Capsules

有关使用这些对象的更多信息，请参考为扩展模块提供 C API。

2.7 版的新Function。

• PyCapsule

  • PyObject的子类型表示不透明值，对于需要pass Python 代码将不透明值(作为void*指针)pass Python 代码传递给其他 C 代码的 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封装* pointer *。 * pointer 参数不能为 NULL *。

失败时，设置一个异常并返回* NULL *。

• name 字符串可以是 NULL 或指向有效 C 字符串的指针。如果不是 NULL ，则此字符串必须比胶囊有效。 (尽管可以在 destructor *内部释放它.)

如果* destructor 参数不是 NULL *，则销毁它时将以胶囊作为参数来调用它。

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

• void * PyCapsule_GetPointer(PyObject *capsule ，const char name *)
  • 检索存储在胶囊中的“指针”。失败时，设置一个异常并返回* NULL *。

• name 参数必须与存储在胶囊中的名称精确比较。如果存储在胶囊中的名称为 NULL ，则传入的名称也必须为 NULL *。 Python 使用 C 函数strcmp()比较胶囊名称。

• PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *胶囊)
  • 返回存储在胶囊中的当前析构函数。失败时，设置一个异常并返回* NULL *。

胶囊具有* NULL 析构函数是合法的。这使 NULL *返回代码有些含糊；使用PyCapsule_IsValid()或PyErr_Occurred()消除歧义。

• 无效* PyCapsule_GetContext(PyObject *胶囊)
  • 返回存储在胶囊中的当前上下文。失败时，设置一个异常并返回* 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 *)
  • 从模块的胶囊属性导入指向 C 对象的指针。 * name 参数应指定属性的全名，如module.attribute所示。储存在胶囊中的 name 必须与该字符串完全匹配。如果 no_block 为 true，则导入模块时不要阻塞(使用PyImport_ImportModuleNoBlock())。如果 no_block *为 false，则按常规导入模块(使用PyImport_ImportModule())。

成功返回胶囊的内部指针。失败时，设置一个异常并返回* NULL *。

• int PyCapsule_IsValid(PyObject *capsule ，const char name *)
  • 确定* capsule 是否为有效胶囊。有效胶囊是非 NULL ，传递PyCapsule_CheckExact()，并且其中存储了非 NULL 指针，并且其内部名称与 name *参数匹配。 (有关如何比较胶囊名称的信息，请参见PyCapsule_GetPointer()。)

换句话说，如果PyCapsule_IsValid()返回的是真值，则可以保证对任何访问器(以PyCapsule_Get()开头的任何函数)的调用都能成功。

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

• 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 *，则不try释放它。

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

• int PyCapsule_SetPointer(PyObject *capsule ，void pointer *)
  • 将* capsule 内部的 void 指针设置为 pointer 。指针可能不是 NULL *。

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