Capsules
********

Consulte Providing a C API for an Extension Module para obter mais
informações sobre o uso desses objetos.

Novo na versão 3.1.

PyCapsule

   This subtype of "PyObject" represents an opaque value, useful for C
   extension modules who 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.

PyCapsule_Destructor

   O tipo de um retorno de chamada destruidor para uma cápsula.
   Definido como:

      typedef void (*PyCapsule_Destructor)(PyObject *);

   Veja "PyCapsule_New()" para a semântica dos retornos de chamada
   PyCapsule_Destructor.

int PyCapsule_CheckExact(PyObject *p)

   Retorna true se seu argumento é um "PyCapsule".

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

   Cria um "PyCapsule" que encapsula o *ponteiro*. O argumento
   *pointer* pode não ser "NULL".

   Em caso de falha, define uma exceção e retorna "NULL".

   A string *name* pode ser "NULL" ou um ponteiro para uma string C
   válida. Se não for "NULL", essa string deverá sobreviver à cápsula.
   (Embora seja permitido liberá-lo dentro do *descructor*.)

   Se o argumento *destructor* não for "NULL", ele será chamado com a
   cápsula como argumento quando for destruído.

   Se esta cápsula for armazenada como um atributo de um módulo, o
   *name* deve ser especificado como "modulename.attributename". Isso
   permitirá que outros módulos importem a cápsula usando
   "PyCapsule_Import()".

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

   Recupera o *pointer* armazenado na cápsula. Em caso de falha,
   define uma exceção e retorna "NULL".

   O parâmetro *name* deve ser comparado exatamente com o nome
   armazenado na cápsula. Se o nome armazenado na cápsula for "NULL",
   o *name* passado também deve ser "NULL". Python usa a função C
   "strcmp()" para comparar nomes de cápsulas.

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)

   Retorna o destruidor atual armazenado na cápsula. Em caso de falha,
   define uma exceção e retorna "NULL".

   É legal para uma cápsula ter um destruidor "NULL". Isso torna um
   código de retorno "NULL" um tanto ambíguo; use
   "PyCapsule_IsValid()" ou "PyErr_Occurred()" para desambiguar.

void* PyCapsule_GetContext(PyObject *capsule)

   Retorna o contexto atual armazenado na cápsula. Em caso de falha,
   define uma exceção e retorna "NULL".

   É legal para uma cápsula ter um contexto "NULL". Isso torna um
   código de retorno "NULL" um tanto ambíguo; use
   "PyCapsule_IsValid()" ou "PyErr_Occurred()" para desambiguar.

const char* PyCapsule_GetName(PyObject *capsule)

   Retorna o nome atual armazenado na cápsula. Em caso de falha,
   define uma exceção e retorna "NULL".

   É legal para uma cápsula ter um nome "NULL". Isso torna um código
   de retorno "NULL" um tanto ambíguo; use "PyCapsule_IsValid()" ou
   "PyErr_Occurred()" para desambiguar.

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

   Importa um ponteiro para um objeto C de um atributo capsule em um
   módulo. O parâmetro *name* deve especificar o nome completo do
   atributo, como em "module.attribute". O *nome* armazenado na
   cápsula deve corresponder exatamente a essa sequência. Se
   *no_block* for verdadeiro, importa o módulo sem bloquear (usando
   "PyImport_ImportModuleNoBlock()"). Se *no_block* for falso, importa
   o módulo convencionalmente (usando "PyImport_ImportModule()").

   Retorna o ponteiro interno *pointer* da cápsula com sucesso. Em
   caso de falha, define uma exceção e retorna "NULL".

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

   Determina se *capsule* é ou não uma cápsula válida. Uma cápsula
   válida é diferente de "NULL", passa "PyCapsule_CheckExact()",
   possui um ponteiro diferente de "NULL" armazenado e seu nome
   interno corresponde ao parâmetro *name*. (Consulte
   "PyCapsule_GetPointer()" para obter informações sobre como os nomes
   das cápsulas são comparados.)

   Em outras palavras, se "PyCapsule_IsValid()" retornar um valor
   verdadeiro, as chamadas para qualquer um dos acessadores (qualquer
   função que comece com "PyCapsule_Get()") terão êxito garantido.

   Retorna um valor diferente de zero se o objeto for válido e
   corresponder ao nome passado. Retorna "0" caso contrário. Esta
   função não falhará.

int PyCapsule_SetContext(PyObject *capsule, void *context)

   Define o ponteiro de contexto dentro de *capsule* para *context*.

   Retorna "0" em caso de sucesso. Retorna diferente de zero e define
   uma exceção em caso de falha.

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)

   Define o destrutor dentro de *capsule* para *destructor*.

   Retorna "0" em caso de sucesso. Retorna diferente de zero e define
   uma exceção em caso de falha.

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

   Define o nome dentro de *capsule* como *name*. Se não for "NULL", o
   nome deve sobreviver à cápsula. Se o *name* anterior armazenado na
   cápsula não era "NULL", nenhuma tentativa será feita para
   liberá-lo.

   Retorna "0" em caso de sucesso. Retorna diferente de zero e define
   uma exceção em caso de falha.

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

   Define o ponteiro nulo dentro de *capsule* para *pointer*. O
   ponteiro não pode ser "NULL".

   Retorna "0" em caso de sucesso. Retorna diferente de zero e define
   uma exceção em caso de falha.
