Doc/c-api/cobject.rst

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