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