Capsules

有关使用这些对象的详细信息,请参阅Providing a C API for an Extension Module

PyCapsule

PyObject的子类型表示一个不透明值,对于需要通过Python代码向其他C代码传递不透明值(作为void*指针)的C扩展模块非常有用。它通常用于使一个模块中定义的C函数指针可用于其他模块,因此常规导入机制可用于访问在动态加载的模块中定义的C API。

PyCapsule_Destructor

一个胶囊的析构函数回调的类型。定义为:

typedef void (*PyCapsule_Destructor)(PyObject *);

有关PyCapsule_Destructor回调的语义,请参见PyCapsule_New()

int PyCapsule_CheckExact(PyObject *p)

如果其参数为PyCapsule,则返回true。

PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
返回值:新引用。

创建封装指针PyCapsule指针参数可能不是NULL

失败时,设置异常并返回NULL

名称字符串可以是NULL或指向有效C字符串的指针。如果非NULL,则此字符串必须比胶囊更长。(虽然允许在析构函数中释放它)。

如果destructor参数不是NULL,那么当它被销毁时,它将以capsule作为其参数来调用。

如果此胶囊将作为模块的属性存储,则名称应指定为modulename.attributename这将使其他模块使用PyCapsule_Import()导入胶囊。

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

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

名称参数必须与存储在胶囊中的名称完全相同。如果存储在胶囊中的名称为NULL,则传递的名称也必须为NULLPython使用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)

从模块中的capsule属性导入指​​向C对象的指针。name参数应指定属性的全名,如module.attribute中所示。存储在胶囊中的名称必须与此字符串完全匹配。如果no_block为true,则导入模块而不阻塞(使用PyImport_ImportModuleNoBlock())。如果no_block为false,则以常规方式导入模块(使用PyImport_ImportModule())。

成功后返回胶囊的内部指针失败时,设置异常并返回NULL但是,如果PyCapsule_Import()导入模块失败,no_block为true,则不会设置异常。

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中的上下文指针设置为上下文

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

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)

capsule内的析构函数设置为析构函数

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

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

capsule中的名称设为名称如果非NULL,则名称必须比胶囊更长。如果存储在胶囊中的上一个名称不是NULL,则不尝试释放它。

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

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

capsule中的void指针设置为指针指针不能为NULL

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