Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1 | .. highlightlang:: c |
| 2 | |
| 3 | .. _cobjects: |
| 4 | |
| 5 | CObjects |
| 6 | -------- |
| 7 | |
| 8 | .. index:: object: CObject |
| 9 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 10 | |
Benjamin Peterson | b173f78 | 2009-05-05 22:31:58 +0000 | [diff] [blame] | 11 | .. warning:: |
| 12 | |
| 13 | The CObject API is deprecated as of Python 3.1. Please switch to the new |
| 14 | :ref:`capsules` API. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 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. |