膠囊

請參閱 為擴充套件模組提供 C API 以獲取有關使用這些物件的更多資訊。

3.1 版本中新增。

type PyCapsule

此 PyObject 的子型別表示一個不透明的值，對於需要透過 Python 程式碼將不透明值（作為 void* 指標）傳遞給其他 C 程式碼的 C 擴充套件模組非常有用。它通常用於使一個模組中定義的 C 函式指標可用於其他模組，因此可以使用常規的匯入機制來訪問動態載入模組中定義的 C API。

type PyCapsule_Destructor

穩定 ABI 的一部分。

膠囊的解構函式回撥的型別。定義為

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)

返回值：新引用。 穩定 ABI 的一部分。

建立一個封裝 pointer 的 PyCapsule。pointer 引數不能為 NULL。

如果失敗，則設定一個異常並返回 NULL。

name 字串可以為 NULL 或指向有效 C 字串的指標。如果非 NULL，則此字串必須在膠囊的生命週期內有效。（儘管允許在 destructor 中釋放它。）

如果 destructor 引數不是 NULL，則會在銷燬時使用膠囊作為其引數呼叫它。

如果此膠囊將儲存為模組的屬性，則 name 應指定為 modulename.attributename。這將使其他模組可以使用 PyCapsule_Import() 匯入膠囊。

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

穩定 ABI 的一部分。

檢索儲存在膠囊中的 pointer。如果失敗，則設定一個異常並返回 NULL。

name 引數必須與儲存在膠囊中的名稱完全匹配。如果儲存在膠囊中的名稱是 NULL，則傳入的 name 也必須是 NULL。Python 使用 C 函式 strcmp() 比較膠囊名稱。

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)

穩定 ABI 的一部分。

返回當前儲存在膠囊中的解構函式。如果失敗，則設定一個異常並返回 NULL。

膠囊具有 NULL 解構函式是合法的。這使得 NULL 返回程式碼有些模稜兩可；使用 PyCapsule_IsValid() 或 PyErr_Occurred() 來消除歧義。

void *PyCapsule_GetContext(PyObject *capsule)

穩定 ABI 的一部分。

返回當前儲存在膠囊中的上下文。如果失敗，則設定一個異常並返回 NULL。

膠囊具有 NULL 上下文是合法的。這使得 NULL 返回程式碼有些模稜兩可；使用 PyCapsule_IsValid() 或 PyErr_Occurred() 來消除歧義。

const char *PyCapsule_GetName(PyObject *capsule)

穩定 ABI 的一部分。

返回當前儲存在膠囊中的名稱。如果失敗，則設定一個異常並返回 NULL。

膠囊具有 NULL 名稱是合法的。這使得 NULL 返回程式碼有些模稜兩可；使用 PyCapsule_IsValid() 或 PyErr_Occurred() 來消除歧義。

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

穩定 ABI 的一部分。

從模組中的膠囊屬性匯入指向 C 物件的指標。name 引數應指定屬性的完整名稱，如 module.attribute。儲存在膠囊中的 name 必須與此字串完全匹配。

成功時返回膠囊的內部 pointer。如果失敗，則設定一個異常並返回 NULL。

在 3.3 版本中更改：no_block 不再起作用。

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

穩定 ABI 的一部分。

確定 capsule 是否為有效的膠囊 (capsule)。有效的膠囊是非 NULL，透過 PyCapsule_CheckExact() 檢查，內部儲存了非 NULL 指標，並且其內部名稱與 name 引數匹配。（有關膠囊名稱如何比較的資訊，請參閱 PyCapsule_GetPointer()。）

換句話說，如果 PyCapsule_IsValid() 返回真值，則保證對任何訪問器（任何以 PyCapsule_Get 開頭的函式）的呼叫都會成功。

如果物件有效且與傳入的名稱匹配，則返回非零值。否則返回 0。此函式不會失敗。

int PyCapsule_SetContext(PyObject *capsule, void *context)

穩定 ABI 的一部分。

將 capsule 內部的上下文指標設定為 context。

成功時返回 0。失敗時返回非零值並設定異常。

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)

穩定 ABI 的一部分。

將 capsule 內部的解構函式設定為 destructor。

成功時返回 0。失敗時返回非零值並設定異常。

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

穩定 ABI 的一部分。

將 capsule 內部的名稱設定為 name。如果非 NULL，則名稱的生命週期必須長於膠囊。如果膠囊中儲存的先前的 name 不是 NULL，則不會嘗試釋放它。

成功時返回 0。失敗時返回非零值並設定異常。

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

穩定 ABI 的一部分。

將 capsule 內部的 void 指標設定為 pointer。指標不能為 NULL。

成功時返回 0。失敗時返回非零值並設定異常。