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()
。
- 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,则传递的名称也必须为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)¶ 从模块中的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。返回非零值,并在失败时设置异常。