You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
sip4-tqt/doc/html/_sources/embedding.txt

63 lines
2.3 KiB

Using the C API when Embedding
==============================
The :ref:`C API <ref-c-api>` is intended to be called from handwritten code in
SIP generated modules. However it is also often necessary to call it from C or
C++ applications that embed the Python interpreter and need to pass C or C++
instances between the application and the interpreter.
The API is exported by the SIP module as a ``sipAPIDef`` data structure
containing a set of function pointers. The data structure is defined in the
SIP header file ``sip.h``. The data structure is wrapped as a Python
``PyCObject`` object and is referenced by the name ``_C_API`` in the SIP
module dictionary.
Each member of the data structure is a pointer to one of the functions of the
SIP API. The name of the member can be derived from the function name by
replacing the ``sip`` prefix with ``api`` and converting each word in the
name to lower case and preceding it with an underscore. For example:
``sipExportSymbol`` becomes ``api_export_symbol``
``sipWrapperCheck`` becomes ``api_wrapper_check``
Note that the type objects that SIP generates for a wrapped module (see
:ref:`ref-type-structures`, :ref:`ref-enum-type-objects` and
:ref:`ref-exception-objects`) cannot be refered to directly and must be
obtained using the :cfunc:`sipFindType()` function. Of course, the
corresponding modules must already have been imported into the interpreter.
The following code fragment shows how to get a pointer to the ``sipAPIDef``
data structure::
#include <sip.h>
const sipAPIDef *get_sip_api()
{
PyObject *sip_module;
PyObject *sip_module_dict;
PyObject *c_api;
/* Import the SIP module. */
sip_module = PyImport_ImportModule("sip");
if (sip_module == NULL)
return NULL;
/* Get the module's dictionary. */
sip_module_dict = PyModule_GetDict(sip_module);
/* Get the "_C_API" attribute. */
c_api = PyDict_GetItemString(sip_module_dict, "_C_API");
if (c_api == NULL)
return NULL;
/* Sanity check that it is the right type. */
if (!PyCObject_Check(c_api))
return NULL;
/* Get the actual pointer from the object. */
return (const sipAPIDef *)PyCObject_AsVoidPtr(c_api);
}