AppPkg/Applications/Python/Python-2.7.2/Include/cobject.h

   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
  40 extern "C" {
  41 #endif
  42
  43 PyAPI_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 */
  53 PyAPI_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 */
  62 PyAPI_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. */
  66 PyAPI_FUNC(void *) PyCObject_AsVoidPtr(PyObject *);
  67
  68 /* Retrieve a pointer to a description object from a PyCObject. */
  69 PyAPI_FUNC(void *) PyCObject_GetDesc(PyObject *);
  70
  71 /* Import a pointer to a C object from a module using a PyCObject. */
  72 PyAPI_FUNC(void *) PyCObject_Import(char *module_name, char *cobject_name);
  73
  74 /* Modify a C object. Fails (==0) if object has a destructor. */
  75 PyAPI_FUNC(int) PyCObject_SetVoidPtr(PyObject *self, void *cobj);
  76
  77
  78 typedef 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 */