Georg Brandl | f684272 | 2008-01-19 22:08:21 +0000 | [diff] [blame] | 1 | .. highlightlang:: c |
| 2 | |
| 3 | .. _cobjects: |
| 4 | |
| 5 | CObjects |
| 6 | -------- |
| 7 | |
| 8 | .. index:: object: CObject |
| 9 | |
Georg Brandl | f684272 | 2008-01-19 22:08:21 +0000 | [diff] [blame] | 10 | |
Larry Hastings | 402b73f | 2010-03-25 00:54:54 +0000 | [diff] [blame] | 11 | .. warning:: |
| 12 | |
| 13 | The CObject API is deprecated as of Python 2.7. Please switch to the new |
| 14 | :ref:`capsules` API. |
Georg Brandl | f684272 | 2008-01-19 22:08:21 +0000 | [diff] [blame] | 15 | |
Sandro Tosi | 98ed08f | 2012-01-14 16:42:02 +0100 | [diff] [blame] | 16 | .. c:type:: PyCObject |
Georg Brandl | f684272 | 2008-01-19 22:08:21 +0000 | [diff] [blame] | 17 | |
Sandro Tosi | 98ed08f | 2012-01-14 16:42:02 +0100 | [diff] [blame] | 18 | This subtype of :c:type:`PyObject` represents an opaque value, useful for C |
| 19 | extension modules who need to pass an opaque value (as a :c:type:`void\*` |
Georg Brandl | f684272 | 2008-01-19 22:08:21 +0000 | [diff] [blame] | 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 | |
Sandro Tosi | 98ed08f | 2012-01-14 16:42:02 +0100 | [diff] [blame] | 26 | .. c:function:: int PyCObject_Check(PyObject *p) |
Georg Brandl | f684272 | 2008-01-19 22:08:21 +0000 | [diff] [blame] | 27 | |
Sandro Tosi | 98ed08f | 2012-01-14 16:42:02 +0100 | [diff] [blame] | 28 | Return true if its argument is a :c:type:`PyCObject`. |
Georg Brandl | f684272 | 2008-01-19 22:08:21 +0000 | [diff] [blame] | 29 | |
| 30 | |
Sandro Tosi | 98ed08f | 2012-01-14 16:42:02 +0100 | [diff] [blame] | 31 | .. c:function:: PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *)) |
Georg Brandl | f684272 | 2008-01-19 22:08:21 +0000 | [diff] [blame] | 32 | |
Sandro Tosi | 98ed08f | 2012-01-14 16:42:02 +0100 | [diff] [blame] | 33 | Create a :c:type:`PyCObject` from the ``void *`` *cobj*. The *destr* function |
Georg Brandl | f684272 | 2008-01-19 22:08:21 +0000 | [diff] [blame] | 34 | will be called when the object is reclaimed, unless it is *NULL*. |
| 35 | |
| 36 | |
Sandro Tosi | 98ed08f | 2012-01-14 16:42:02 +0100 | [diff] [blame] | 37 | .. c:function:: PyObject* PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *)) |
Georg Brandl | f684272 | 2008-01-19 22:08:21 +0000 | [diff] [blame] | 38 | |
Sandro Tosi | 98ed08f | 2012-01-14 16:42:02 +0100 | [diff] [blame] | 39 | Create a :c:type:`PyCObject` from the :c:type:`void \*` *cobj*. The *destr* |
Georg Brandl | f684272 | 2008-01-19 22:08:21 +0000 | [diff] [blame] | 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 | |
Sandro Tosi | 98ed08f | 2012-01-14 16:42:02 +0100 | [diff] [blame] | 44 | .. c:function:: void* PyCObject_AsVoidPtr(PyObject* self) |
Georg Brandl | f684272 | 2008-01-19 22:08:21 +0000 | [diff] [blame] | 45 | |
Sandro Tosi | 98ed08f | 2012-01-14 16:42:02 +0100 | [diff] [blame] | 46 | Return the object :c:type:`void \*` that the :c:type:`PyCObject` *self* was |
Georg Brandl | f684272 | 2008-01-19 22:08:21 +0000 | [diff] [blame] | 47 | created with. |
| 48 | |
| 49 | |
Sandro Tosi | 98ed08f | 2012-01-14 16:42:02 +0100 | [diff] [blame] | 50 | .. c:function:: void* PyCObject_GetDesc(PyObject* self) |
Georg Brandl | f684272 | 2008-01-19 22:08:21 +0000 | [diff] [blame] | 51 | |
Sandro Tosi | 98ed08f | 2012-01-14 16:42:02 +0100 | [diff] [blame] | 52 | Return the description :c:type:`void \*` that the :c:type:`PyCObject` *self* was |
Georg Brandl | f684272 | 2008-01-19 22:08:21 +0000 | [diff] [blame] | 53 | created with. |
| 54 | |
| 55 | |
Sandro Tosi | 98ed08f | 2012-01-14 16:42:02 +0100 | [diff] [blame] | 56 | .. c:function:: int PyCObject_SetVoidPtr(PyObject* self, void* cobj) |
Georg Brandl | f684272 | 2008-01-19 22:08:21 +0000 | [diff] [blame] | 57 | |
Sandro Tosi | 98ed08f | 2012-01-14 16:42:02 +0100 | [diff] [blame] | 58 | Set the void pointer inside *self* to *cobj*. The :c:type:`PyCObject` must not |
Georg Brandl | f684272 | 2008-01-19 22:08:21 +0000 | [diff] [blame] | 59 | have an associated destructor. Return true on success, false on failure. |