/Doc/c-api/cobject.rst

 1.. highlightlang:: c
 2
 3.. _cobjects:
 4
 5CObjects
 6--------
 7
 8.. index:: object: CObject
 9
10Refer 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.