胶囊

参考为扩展模块提供C API 有关使用这些物体的更多信息.

PyCapsule

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

PyCapsule_Destructor

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

typedef void (*PyCapsule_Destructor)(PyObject *);

请参阅PyCapsule_New()了解PyCapsule_Destructorcallbacks.

int PyCapsule_CheckExact（ PyObject  *p的语义

如果它的参数是PyCapsule.

PyObject * PyCapsule_New（无效 *pointer，const char  *name，PyCapsule_Destructor  destructor）

Return value: New reference.

创建一个 PyCapsule封装pointer。pointer争论可能不是NULL.

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

name字符串可以是NULL或指向有效C字符串的指针。Ifnon – NULL，这个字符串必须比胶囊寿命长。（虽然允许把它放在destructor.)

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

如果这个胶囊被存储为模块的属性，name应该被指定为modulename.attributename。这将使其他模块能够使用PyCapsule_Import().

void * PyCapsule_GetPointer（的PyObject  *capsule，const char  *name）

找回pointer存储在胶囊中。失败时，设置异常并返回NULL.

name参数必须与存储在胶囊中的名称完全比较。如果存储在胶囊中的名称是NULL，name传入也必须NULL。Python使用C函数strcmp()来比较capsulenames.

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）

从模块中的capsule属性导入指​​向C对象的指针。name参数应指定属性的全名，如module.attribute。存储在胶囊中的name必须与此字符串完全匹配。如果no_block为真，则导入模块而不阻塞（使用PyImport_ImportModuleNoBlock()）是合法的。如果no_block是假的，按常规导入模块（使用PyImport_ImportModule()).

成功后回收胶囊的内部pointer。失败时，设置一个异常并返回NULL.

int PyCapsule_IsValid（ PyObject  *capsule，const char  *name）

确定capsule是否是有效的胶囊。一个有效的胶囊是非 – NULL，通过PyCapsule_CheckExact()，有一个非NULL指针，其内部名称与name参数。（看到PyCapsule_GetPointer()有关如何比较胶囊名称的信息。）

换句话说，如果PyCapsule_IsValid()返回一个真值，调用任何一个评估者（任何以开头的函数）PyCapsule_Get()保证成功.

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

int PyCapsule_SetContext（ PyObject  *capsule，void  *context）

将上下文指针设置在capsule中context.

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

int PyCapsule_SetDestructor（ PyObject  *capsule，PyCapsule_Destructor  destructor）

将析构函数设置在capsule中destructor.

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

int PyCapsule_SetName（ PyObject  *capsule，const char  *name）

将capsule中的名称设置为name。如果不是NULL，这个名字必须比胶囊好。如果先前存放在胶囊中的name不是NULL，则不会试图释放它.

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

int PyCapsule_SetPointer（的PyObject  *capsule，无效 *pointer）

将void指针设置在capsule至 pointer。指针可能不是NULL.

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