1/*
2 CObjects are marked Pending Deprecation as of Python 2.7.
3 The full schedule for 2.x is as follows:
4 - CObjects are marked Pending Deprecation in Python 2.7.
5 - CObjects will be marked Deprecated in Python 2.8
6 (if there is one).
7 - CObjects will be removed in Python 2.9 (if there is one).
8
9 Additionally, for the Python 3.x series:
10 - CObjects were marked Deprecated in Python 3.1.
11 - CObjects will be removed in Python 3.2.
12
13 You should switch all use of CObjects to capsules. Capsules
14 have a safer and more consistent API. For more information,
15 see Include/pycapsule.h, or read the "Capsules" topic in
16 the "Python/C API Reference Manual".
17
18 Python 2.7 no longer uses CObjects itself; all objects which
19 were formerly CObjects are now capsules. Note that this change
20 does not by itself break binary compatibility with extensions
21 built for previous versions of Python--PyCObject_AsVoidPtr()
22 has been changed to also understand capsules.
23
24*/
25
26/* original file header comment follows: */
27
28/* C objects to be exported from one extension module to another.
29
30 C objects are used for communication between extension modules.
31 They provide a way for an extension module to export a C interface
32 to other extension modules, so that extension modules can use the
33 Python import mechanism to link to one another.
34
35*/
36
37#ifndef Py_COBJECT_H
38#define Py_COBJECT_H
39#ifdef __cplusplus
40extern "C" {
41#endif
42
43PyAPI_DATA(PyTypeObject) PyCObject_Type;
44
45#define PyCObject_Check(op) (Py_TYPE(op) == &PyCObject_Type)
46
47/* Create a PyCObject from a pointer to a C object and an optional
48 destructor function. If the second argument is non-null, then it
49 will be called with the first argument if and when the PyCObject is
50 destroyed.
51
52*/
53PyAPI_FUNC(PyObject *) PyCObject_FromVoidPtr(
54 void *cobj, void (*destruct)(void*));
55
56
57/* Create a PyCObject from a pointer to a C object, a description object,
58 and an optional destructor function. If the third argument is non-null,
59 then it will be called with the first and second arguments if and when
60 the PyCObject is destroyed.
61*/
62PyAPI_FUNC(PyObject *) PyCObject_FromVoidPtrAndDesc(
63 void *cobj, void *desc, void (*destruct)(void*,void*));
64
65/* Retrieve a pointer to a C object from a PyCObject. */
66PyAPI_FUNC(void *) PyCObject_AsVoidPtr(PyObject *);
67
68/* Retrieve a pointer to a description object from a PyCObject. */
69PyAPI_FUNC(void *) PyCObject_GetDesc(PyObject *);
70
71/* Import a pointer to a C object from a module using a PyCObject. */
72PyAPI_FUNC(void *) PyCObject_Import(char *module_name, char *cobject_name);
73
74/* Modify a C object. Fails (==0) if object has a destructor. */
75PyAPI_FUNC(int) PyCObject_SetVoidPtr(PyObject *self, void *cobj);
76
77
78typedef struct {
79 PyObject_HEAD
80 void *cobject;
81 void *desc;
82 void (*destructor)(void *);
83} PyCObject;
84
85
86#ifdef __cplusplus
87}
88#endif
89#endif /* !Py_COBJECT_H */
90