Capsules

参照 为扩展模块提供C API 有关使用这些对象的详细信息。

3.1 新版功能.

type PyCapsule

这种亚型 PyObject 表示不透明值，对于需要传递不透明值（作为 void* 指针）通过python代码到其他C代码。它通常用于使一个模块中定义的C函数指针对其他模块可用，因此常规导入机制可以用于访问动态加载模块中定义的C API。

type PyCapsule_Destructor

Capsules的析构函数回调类型。定义为：

typedef void (*PyCapsule_Destructor)(PyObject *);

见 PyCapsule_New() 对于pycapsule析构函数回调的语义。

int PyCapsule_CheckExact(PyObject *p)

如果其参数为 PyCapsule 。此功能总是成功的。

PyObject *PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)

Return value: New reference.

创建一个 PyCapsule 封装 指针 . 这个 指针 参数不能是 NULL .

失败时，设置异常并返回 NULL .

这个 name 字符串可以是 NULL 或者指向有效C字符串的指针。如果非-``NULL`，则此字符串必须比胶囊长。（尽管允许在 析构函数 ）

如果 析构函数 论点不是 NULL ，当它被销毁时，将以胶囊作为参数调用它。

如果此Capsules将作为模块的属性存储，则 name 应指定为 modulename.attributename . 这将使其他模块能够使用 PyCapsule_Import() .

void *PyCapsule_GetPointer(PyObject *capsule, const char *name)

检索 指针 储存在胶囊中。失败时，设置异常并返回 NULL .

这个 name 参数必须与存储在胶囊中的名称完全比较。如果存储在胶囊中的名称是 NULL , the name 还必须 NULL . python使用c函数 strcmp() 比较胶囊名称。

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)

返回存储在胶囊中的当前析构函数。失败时，设置异常并返回 NULL .

胶囊有一个 NULL 析构函数。这使得 NULL 返回代码有点模糊；使用 PyCapsule_IsValid() 或 PyErr_Occurred() 消除歧义。

void *PyCapsule_GetContext(PyObject *capsule)

返回存储在胶囊中的当前上下文。失败时，设置异常并返回 NULL .

胶囊有一个 NULL 上下文。这使得 NULL 返回代码有点模糊；使用 PyCapsule_IsValid() 或 PyErr_Occurred() 消除歧义。

const char *PyCapsule_GetName(PyObject *capsule)

返回存储在胶囊中的当前名称。失败时，设置异常并返回 NULL .

胶囊有一个 NULL 姓名。这使得 NULL 返回代码有点模糊；使用 PyCapsule_IsValid() 或 PyErr_Occurred() 消除歧义。

void *PyCapsule_Import(const char *name, int no_block)

从模块中的Capsules属性导入指向C对象的指针。这个 name 参数应指定属性的全名，如 module.attribute . 这个 name 存储在Capsules中的必须与此字符串完全匹配。如果 no_block 为真，导入模块时不阻塞（使用 PyImport_ImportModuleNoBlock() ）如果 no_block 为false，常规导入模块（使用 PyImport_ImportModule() ）

返回胶囊内部 指针 论成功。失败时，设置异常并返回 NULL .

int PyCapsule_IsValid(PyObject *capsule, const char *name)

确定是否 胶囊 是有效的胶囊。有效的胶囊是非-``空'，通过 :c:func:`PyCapsule_CheckExact ，中存储了一个非“NULL”指针，其内部名称与 name 参数。（见 PyCapsule_GetPointer() 有关如何比较胶囊名称的信息。）

换句话说，如果 PyCapsule_IsValid() 返回一个真值，调用任何访问器（以 PyCapsule_Get() ）一定会成功。

如果对象有效并且与传入的名称匹配，则返回非零值。返回 0 否则。此功能不会失败。

int PyCapsule_SetContext(PyObject *capsule, void *context)

在内部设置上下文指针 Capsules 到 context .

返回 0 论成功。返回非零并在失败时设置异常。

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)

在内部设置析构函数 Capsules 到 析构函数 .

返回 0 论成功。返回非零并在失败时设置异常。

int PyCapsule_SetName(PyObject *capsule, const char *name)

在内部设置名称 胶囊 到 name . 如果非-NULL`，则该名称必须比胶囊长。如果上一个 *name* 储存在胶囊中的不是 ``NULL ，没有试图释放它。

返回 0 论成功。返回非零并在失败时设置异常。

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

在内部设置空指针 胶囊 到 指针 . 指针可能不是 NULL .

返回 0 论成功。返回非零并在失败时设置异常。