膠囊?
有關(guān)使用這些對象的更多信息請參閱 給擴展模塊提供C API。
3.1 新版功能.
-
PyCapsule? 這個
PyObject的子類型代表著一個任意值，當(dāng)需要通過 Python 代碼將任意值（以void*指針的形式）從 C 擴展模塊傳遞給其他 C 代碼時非常有用。它通常用于將指向一個模塊中定義的 C 語言函數(shù)指針傳遞給其他模塊，以便可以從那里調(diào)用它們。這允許通過正常的模塊導(dǎo)入機制訪問動態(tài)加載的模塊中的 C API。
-
PyCapsule_Destructor? 這種類型的一個析構(gòu)器返回一個膠囊，定義如下：
typedef void (*PyCapsule_Destructor)(PyObject *);
參閱
PyCapsule_New()來獲取 PyCapsule_Destructor 返回值的語義。
-
PyObject*
PyCapsule_New(void?*pointer, const char?*name, PyCapsule_Destructor?destructor)? - Return value: New reference.
創(chuàng)建一個封裝了 pointer 的
PyCapsule。 pointer 參考可以不為NULL。在失敗時設(shè)置一個異常并返回
NULL。字符串 name 可以是
NULL或是一個指向有效的 C 字符串的指針。 如果不為NULL，則此字符串必須比 capsule 長（雖然也允許在 destructor 中釋放它。）如果 destructor 參數(shù)不為
NULL，則當(dāng)它被銷毀時將附帶 capsule 作為參數(shù)來調(diào)用。如果此 capsule 將被保存為一個模塊的屬性，則 name 應(yīng)當(dāng)被指定為
modulename.attributename。 這將允許其他模塊使用PyCapsule_Import()來導(dǎo)入此 capsule。
-
void*
PyCapsule_GetPointer(PyObject?*capsule, const char?*name)? 提取保存在 capsule 中的 pointer。 在失敗時設(shè)置一個異常并返回
NULL。name 形參必須與保存在 capsule 中的名稱進行精確比較。 如果保存在 capsule 中的名稱為
NULL，則傳入的 name 也必須為NULL。 Python 會使用 C 函數(shù)strcmp()來比較 capsule 名稱。
-
PyCapsule_Destructor
PyCapsule_GetDestructor(PyObject?*capsule)? 返回保存為 capsule 中的當(dāng)前析構(gòu)器。 在失敗時設(shè)置一個異常并返回
NULL。具有
NULL析構(gòu)器是合法的。 這會使得NULL返回值有些歧義；請使用PyCapsule_IsValid()或PyErr_Occurred()來消除歧義。
-
void*
PyCapsule_GetContext(PyObject?*capsule)? 返回保存在 capsule 中的當(dāng)前上下文。 在失敗時設(shè)置一個異常并返回
NULL。capsule 具有
NULL上下文是全法的。 這會使得NULL返回碼有些歧義；請使用PyCapsule_IsValid()或PyErr_Occurred()來消除歧義。
-
const char*
PyCapsule_GetName(PyObject?*capsule)? 返回保存在 capsule 中的當(dāng)前名稱。 在失敗時設(shè)置一個異常并返回
NULL。capsule 具有
NULL名稱是合法的。 這會使得NULL返回碼有些歧義；請使用PyCapsule_IsValid()或PyErr_Occurred()來消除歧義。
-
void*
PyCapsule_Import(const char?*name, int?no_block)? 從一個模塊的 capsule 屬性導(dǎo)入指向 C 對象的指針。 name 形參應(yīng)當(dāng)指定屬性的完整名稱，與
module.attribute中的一致。 保存在 capsule 中的 name 必須完全匹配此字符串。 如果 no_block 為真值，則以無阻塞模式導(dǎo)入模塊 (使用PyImport_ImportModuleNoBlock())。 如果 no_block 為假值，則以傳統(tǒng)模式導(dǎo)入模塊 (使用PyImport_ImportModule())。成功時返回 capsule 的內(nèi)部 指針。 在失敗時設(shè)置一個異常并返回
NULL。
-
int
PyCapsule_IsValid(PyObject?*capsule, const char?*name)? 確定 capsule 是否是一個有效的。 有效的 capsule 必須不為
NULL，傳遞PyCapsule_CheckExact()，在其中存儲一個不為NULL的指針，并且其內(nèi)部名稱與 name 形參相匹配。 （請參閱PyCapsule_GetPointer()了解如何對 capsule 名稱進行比較的有關(guān)信息。）換句話說，如果
PyCapsule_IsValid()返回真值，則任何對訪問器（以PyCapsule_Get()開頭的任何函數(shù)）的調(diào)用都保證會成功。如果對象有效并且匹配傳入的名稱則返回非零值。 否則返回
0。 此函數(shù)一定不會失敗。
-
int
PyCapsule_SetContext(PyObject?*capsule, void?*context)? 將 capsule 內(nèi)部的上下文指針設(shè)為 context。
成功時返回
0。 失敗時返回非零值并設(shè)置一個異常。
-
int
PyCapsule_SetDestructor(PyObject?*capsule, PyCapsule_Destructor?destructor)? 將 capsule 內(nèi)部的析構(gòu)器設(shè)為 destructor。
成功時返回
0。 失敗時返回非零值并設(shè)置一個異常。