膠囊?

有關使用這些對象的更多信息請參閱 給擴展模塊提供C API。

3.1 新版功能.

PyCapsule?

這個 PyObject 的子類型代表著一個任意值，當需要通過 Python 代碼將任意值（以 void* 指針的形式）從 C 擴展模塊傳遞給其他 C 代碼時非常有用。它通常用于將指向一個模塊中定義的 C 語言函數指針傳遞給其他模塊，以便可以從那里調用它們。這允許通過正常的模塊導入機制訪問動態加載的模塊中的 C API。

PyCapsule_Destructor?

這種類型的一個析構器返回一個膠囊，定義如下：

typedef void (*PyCapsule_Destructor)(PyObject *);

參閱 PyCapsule_New() 來獲取 PyCapsule_Destructor 返回值的語義。

int PyCapsule_CheckExact(PyObject?*p)?

如果參數是一個 PyCapsule 則返回 True

PyObject* PyCapsule_New(void?*pointer, const char?*name, PyCapsule_Destructor?destructor)?
Return value: New reference.

創建一個封裝了 pointer 的 PyCapsule。 pointer 參考可以不為 NULL。

在失敗時設置一個異常并返回 NULL。

字符串 name 可以是 NULL 或是一個指向有效的 C 字符串的指針。 如果不為 NULL，則此字符串必須比 capsule 長（雖然也允許在 destructor 中釋放它。）

如果 destructor 參數不為 NULL，則當它被銷毀時將附帶 capsule 作為參數來調用。

如果此 capsule 將被保存為一個模塊的屬性，則 name 應當被指定為 modulename.attributename。 這將允許其他模塊使用 PyCapsule_Import() 來導入此 capsule。

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

提取保存在 capsule 中的 pointer。 在失敗時設置一個異常并返回 NULL。

name 形參必須與保存在 capsule 中的名稱進行精確比較。 如果保存在 capsule 中的名稱為 NULL，則傳入的 name 也必須為 NULL。 Python 會使用 C 函數 strcmp() 來比較 capsule 名稱。

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject?*capsule)?

返回保存為 capsule 中的當前析構器。 在失敗時設置一個異常并返回 NULL。

具有 NULL 析構器是合法的。 這會使得 NULL 返回值有些歧義；請使用 PyCapsule_IsValid() 或 PyErr_Occurred() 來消除歧義。

void* PyCapsule_GetContext(PyObject?*capsule)?

返回保存在 capsule 中的當前上下文。 在失敗時設置一個異常并返回 NULL。

capsule 具有 NULL 上下文是全法的。 這會使得 NULL 返回碼有些歧義；請使用 PyCapsule_IsValid() 或 PyErr_Occurred() 來消除歧義。

const char* PyCapsule_GetName(PyObject?*capsule)?

返回保存在 capsule 中的當前名稱。 在失敗時設置一個異常并返回 NULL。

capsule 具有 NULL 名稱是合法的。 這會使得 NULL 返回碼有些歧義；請使用 PyCapsule_IsValid() 或 PyErr_Occurred() 來消除歧義。

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

從一個模塊的 capsule 屬性導入指向 C 對象的指針。 name 形參應當指定屬性的完整名稱，與 module.attribute 中的一致。 保存在 capsule 中的 name 必須完全匹配此字符串。 如果 no_block 為真值，則以無阻塞模式導入模塊 (使用 PyImport_ImportModuleNoBlock())。 如果 no_block 為假值，則以傳統模式導入模塊 (使用 PyImport_ImportModule())。

成功時返回 capsule 的內部 指針。 在失敗時設置一個異常并返回 NULL。

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

確定 capsule 是否是一個有效的。 有效的 capsule 必須不為 NULL，傳遞 PyCapsule_CheckExact()，在其中存儲一個不為 NULL 的指針，并且其內部名稱與 name 形參相匹配。 （請參閱 PyCapsule_GetPointer() 了解如何對 capsule 名稱進行比較的有關信息。）

換句話說，如果 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，則名稱的存在期必須比 capsule 更長。 如果之前保存在 capsule 中的 name 不為 NULL，則不會嘗試釋放它。

成功時返回 0。 失敗時返回非零值并設置一個異常。

int PyCapsule_SetPointer(PyObject?*capsule, void?*pointer)?

將 capsule 內部的空指針設為 pointer。 指針不可為 NULL。

成功時返回 0。 失敗時返回非零值并設置一個異常。