# カプセル

using-capsules 以下のオブジェクトを使う方法については 拡張モジュールに C API を提供する を参照してください。

Added in version 3.1.

type PyCapsule

  This subtype of `PyObject` represents an opaque value, useful for C extension modules which need to pass an opaque value (as a void* pointer) through Python code to other C code. It is often used to make a C function pointer defined in one module available to other modules, so the regular import mechanism can be used to access C APIs defined in dynamically loaded modules.

PyTypeObject PyCapsule_Type
  次に属します: Stable ABI.

  The type object corresponding to capsule objects. This is the same object as `types.CapsuleType` in the Python layer.

type PyCapsule_Destructor
  次に属します: Stable ABI.

  カプセルに対するデストラクタコールバック型. 次のように定義されます:

      typedef void (*PyCapsule_Destructor)(PyObject *);

  PyCapsule_Destructor コールバックの動作については `PyCapsule_New()` を参照してください。

int PyCapsule_CheckExact(PyObject *p)
  Thread safety: Atomic.

  引数が `PyCapsule` の場合に真を返します。この関数は常に成功します。

PyObject *PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
  戻り値: 新しい参照。 次に属します: Stable ABI. Thread safety: Atomic.

  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)
  次に属します: Stable ABI. Thread safety: Safe to call without external synchronization on distinct objects.

  カプセルに保存されている pointer を取り出します。失敗した場合は例外を設定して `NULL` を返します。

  The name parameter must compare exactly to the name stored in the capsule. If the name stored in the capsule is `NULL`, the name passed in must also be `NULL`. Python uses the C function `strcmp()` to compare capsule names.

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)
  次に属します: Stable ABI. Thread safety: Safe to call without external synchronization on distinct objects.

  カプセルに保存されている現在のデストラクタを返します。失敗した場合、例外を設定して `NULL` を返します。

  カプセルは `NULL` をデストラクタとして持つことができます。従って、戻り値の `NULL` がエラーを指してない可能性があります。 `PyCapsule_IsValid()` か `PyErr_Occurred()` を利用して確認してください。

void *PyCapsule_GetContext(PyObject *capsule)
  次に属します: Stable ABI. Thread safety: Safe to call without external synchronization on distinct objects.

  カプセルに保存されている現在のコンテキスト(context)を返します。失敗した場合、例外を設定して `NULL` を返します。

  カプセルは `NULL` をコンテキストとして持つことができます。従って、戻り値の `NULL` がエラーを指してない可能性があります。 `PyCapsule_IsValid()` か `PyErr_Occurred()` を利用して確認してください。

const char *PyCapsule_GetName(PyObject *capsule)
  次に属します: Stable ABI. Thread safety: Safe to call without external synchronization on distinct objects.

  カプセルに保存されている現在の name を返します。失敗した場合、例外を設定して `NULL` を返します。

  カプセルは `NULL` を name として持つことができます。従って、戻り値の `NULL` がエラーを指してない可能性があります。 `PyCapsule_IsValid()` か `PyErr_Occurred()` を利用して確認してください。

void *PyCapsule_Import(const char *name, int no_block)
  次に属します: Stable ABI. Thread safety: Safe to call from multiple threads with external synchronization only.

  Import a pointer to a C object from a capsule attribute in a module. The name parameter should specify the full name to the attribute, as in `module.attribute`. The name stored in the capsule must match this string exactly.

  This function splits name on the `.` character, and imports the first element. It then processes further elements using attribute lookups.

  成功した場合、カプセルの内部 ポインタ を返します。失敗した場合、例外を設定して `NULL` を返します。

  注釈

  If name points to an attribute of some submodule or subpackage, this submodule or subpackage must be previously imported using other means (for example, by using `PyImport_ImportModule()`) for the attribute lookups to succeed.

  バージョン 3.3 で変更: no_block has no effect anymore.

int PyCapsule_IsValid(PyObject *capsule, const char *name)
  次に属します: Stable ABI. Thread safety: Safe to call without external synchronization on distinct objects.

  capsule が有効なカプセルであるかどうかをチェックします。有効な capsule は、非 `NULL` で、 `PyCapsule_CheckExact()` をパスし、非 `NULL` なポインタを格納していて、内部の name が引数 name とマッチします。 (name の比較方法については `PyCapsule_GetPointer()` を参照)

  In other words, if `PyCapsule_IsValid()` returns a true value, calls to any of the accessors (any function starting with `PyCapsule_Get`) are guaranteed to succeed.

  オブジェクトが有効で name がマッチした場合に非 `0` を、それ以外の場合に `0` を返します。この関数は絶対に失敗しません。

int PyCapsule_SetContext(PyObject *capsule, void *context)
  次に属します: Stable ABI. Thread safety: Safe to call without external synchronization on distinct objects.

  capsule 内部のコンテキストポインタを context に設定します。

  成功したら `0` を、失敗したら例外を設定して非 `0` を返します。

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
  次に属します: Stable ABI. Thread safety: Safe to call without external synchronization on distinct objects.

  capsule 内部のデストラクタを destructor に設定します。

  成功したら `0` を、失敗したら例外を設定して非 `0` を返します。

int PyCapsule_SetName(PyObject *capsule, const char *name)
  次に属します: Stable ABI. Thread safety: Safe to call without external synchronization on distinct objects.

  capsule 内部の name を name に設定します。name が非 `NULL` のとき、それは capsule よりも長い寿命を持つ必要があります。もしすでに capsule に非 `NULL` の name が保存されていた場合、それに対する解放は行われません。

  成功したら `0` を、失敗したら例外を設定して非 `0` を返します。

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
  次に属します: Stable ABI. Thread safety: Safe to call without external synchronization on distinct objects.

  capsule 内部のポインタを pointer に設定します。pointer は `NULL` であってはなりません。

  成功したら `0` を、失敗したら例外を設定して非 `0` を返します。