Doc/c-api/cobject.rst

   1 .. highlightlang:: c
   2
   3 .. _cobjects:
   4
   5 CObjects
   6 --------
   7
   8 .. index:: object: CObject
   9
  10 Refer to :ref:`using-cobjects` for more information on using these objects.
  11
  12
  13 .. ctype:: PyCObject
  14
  15    This subtype of :ctype:`PyObject` represents an opaque value, useful for C
  16    extension modules who need to pass an opaque value (as a :ctype:`void\*`
  17    pointer) through Python code to other C code.  It is often used to make a C
  18    function pointer defined in one module available to other modules, so the
  19    regular import mechanism can be used to access C APIs defined in dynamically
  20    loaded modules.
  21
  22
  23 .. cfunction:: int PyCObject_Check(PyObject *p)
  24
  25    Return true if its argument is a :ctype:`PyCObject`.
  26
  27
  28 .. cfunction:: PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *))
  29
  30    Create a :ctype:`PyCObject` from the ``void *`` *cobj*.  The *destr* function
  31    will be called when the object is reclaimed, unless it is *NULL*.
  32
  33
  34 .. cfunction:: PyObject* PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *))
  35
  36    Create a :ctype:`PyCObject` from the :ctype:`void \*` *cobj*.  The *destr*
  37    function will be called when the object is reclaimed. The *desc* argument can
  38    be used to pass extra callback data for the destructor function.
  39
  40
  41 .. cfunction:: void* PyCObject_AsVoidPtr(PyObject* self)
  42
  43    Return the object :ctype:`void \*` that the :ctype:`PyCObject` *self* was
  44    created with.
  45
  46
  47 .. cfunction:: void* PyCObject_GetDesc(PyObject* self)
  48
  49    Return the description :ctype:`void \*` that the :ctype:`PyCObject` *self* was
  50    created with.
  51
  52
  53 .. cfunction:: int PyCObject_SetVoidPtr(PyObject* self, void* cobj)
  54
  55    Set the void pointer inside *self* to *cobj*. The :ctype:`PyCObject` must not
  56    have an associated destructor. Return true on success, false on failure.