From 6c4cc3653e8dd7668295f3e659b7eb4dc571b67c Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Tue, 22 Nov 2011 02:59:34 -0600 Subject: Initial import of SIP4 for Qt3 --- doc/html/c_api.html | 2166 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 2166 insertions(+) create mode 100644 doc/html/c_api.html (limited to 'doc/html/c_api.html') diff --git a/doc/html/c_api.html b/doc/html/c_api.html new file mode 100644 index 0000000..b761f8a --- /dev/null +++ b/doc/html/c_api.html @@ -0,0 +1,2166 @@ + + + + + + + C API for Handwritten Code — SIP 4.10.5 Reference Guide + + + + + + + + + + +
+

Navigation

+ +
+ +
+
+
+
+ +
+

C API for Handwritten Code

+

In this section we describe the API that can be used by handwritten code in +specification files.

+
+
+SIP_API_MAJOR_NR
+
This is a C preprocessor symbol that defines the major number of the SIP +API. Its value is a number. There is no direct relationship between this +and the SIP version number.
+ +
+
+SIP_API_MINOR_NR
+
This is a C preprocessor symbol that defines the minor number of the SIP +API. Its value is a number. There is no direct relationship between this +and the SIP version number.
+ +
+
+SIP_BLOCK_THREADS
+
This is a C preprocessor macro that will make sure the Python Global +Interpreter Lock (GIL) is acquired. Python API calls must only be made +when the GIL has been acquired. There must be a corresponding +SIP_UNBLOCK_THREADS at the same lexical scope.
+ +
+
+SIP_NO_CONVERTORS
+
This is a flag used by various type convertors that suppresses the use of a +type’s %ConvertToTypeCode.
+ +
+
+SIP_NOT_NONE
+
This is a flag used by various type convertors that causes the conversion +to fail if the Python object being converted is Py_None.
+ +
+
+SIP_PROTECTED_IS_PUBLIC
+

+New in version 4.10.

+

This is a C preprocessor macro that is set automatically by the build +system to specify that the generated code is being compiled with +protected redefined as public. This allows handwritten code to +determine if the generated helper functions for accessing protected C++ +functions are available (see %MethodCode).

+
+ +
+
+SIP_SSIZE_T
+
This is a C preprocessor macro that is defined as Py_ssize_t for Python +v2.5 and later, and as int for earlier versions of Python. It makes it +easier to write PEP 353 compliant handwritten code.
+ +
+
+SIP_UNBLOCK_THREADS
+
This is a C preprocessor macro that will restore the Python Global +Interpreter Lock (GIL) to the state it was prior to the corresponding +SIP_BLOCK_THREADS.
+ +
+
+SIP_VERSION
+
This is a C preprocessor symbol that defines the SIP version number +represented as a 3 part hexadecimal number (e.g. v4.0.0 is represented as +0x040000).
+ +
+
+SIP_VERSION_STR
+
This is a C preprocessor symbol that defines the SIP version number +represented as a string. For development snapshots it will start with +snapshot-.
+ +
+
+sipErrorState sipBadCallableArg(int arg_nr, PyObject *arg)
+

+New in version 4.10.

+

This is called from %MethodCode to raise a Python exception +when an argument to a function, a C++ constructor or method is found to +have an unexpected type. This should be used when the +%MethodCode does additional type checking of the supplied +arguments.

+ +++ + + + + + +
Parameters:
    +
  • arg_nr – the number of the argument. Arguments are numbered from 0 but are +numbered from 1 in the detail of the exception.
    • +
  • arg – the argument.
    • +
+
Returns:

the value that should be assigned to sipError.

+
+
+ +
+
+void sipBadCatcherResult(PyObject *method)
+

This raises a Python exception when the result of a Python reimplementation +of a C++ method doesn’t have the expected type. It is normally called by +handwritten code specified with the %VirtualCatcherCode +directive.

+ +++ + + + +
Parameter:method – the Python method and would normally be the supplied sipMethod.
+
+ +
+
+void sipBadLengthForSlice(SIP_SSIZE_T seqlen, SIP_SSIZE_T slicelen)
+

This raises a Python exception when the length of a slice object is +inappropriate for a sequence-like object. It is normally called by +handwritten code specified for __setitem__() methods.

+ +++ + + + +
Parameters:
    +
  • seqlen – the length of the sequence.
    • +
  • slicelen – the length of the slice.
    • +
+
+
+ +
+
+PyObject *sipBuildResult(int *iserr, const char *format, ...)
+

This creates a Python object based on a format string and associated +values in a similar way to the Python Py_BuildValue() function.

+ +++ + + + + + +
Parameters:
    +
  • iserr – if this is not NULL then the location it points to is set to a +non-zero value.
    • +
  • format – the string of format characters.
    • +
+
Returns:

If there was an error then NULL is returned and a Python exception +is raised.

+
+

If the format string begins and ends with parentheses then a tuple of +objects is created. If it contains more than one format character then +parentheses must be specified.

+

In the following description the first letter is the format character, the +entry in parentheses is the Python object type that the format character +will create, and the entry in brackets are the types of the C/C++ values +to be passed.

+
+
a (string) [char]
+
Convert a C/C++ char to a Python v2 or v3 string object.
+
b (boolean) [int]
+
Convert a C/C++ int to a Python boolean.
+
c (string/bytes) [char]
+
Convert a C/C++ char to a Python v2 string object or a Python v3 +bytes object.
+
d (float) [double]
+
Convert a C/C++ double to a Python floating point number.
+
e (integer) [enum]
+
Convert an anonymous C/C++ enum to a Python integer.
+
f (float) [float]
+
Convert a C/C++ float to a Python floating point number.
+
g (string/bytes) [char *, SIP_SSIZE_T]
+
Convert a C/C++ character array and its length to a Python v2 string +object or a Python v3 bytes object. If the array is NULL then the +length is ignored and the result is Py_None.
+
h (integer) [short]
+
Convert a C/C++ short to a Python integer.
+
i (integer) [int]
+
Convert a C/C++ int to a Python integer.
+
l (long) [long]
+
Convert a C/C++ long to a Python integer.
+
m (long) [unsigned long]
+
Convert a C/C++ unsigned long to a Python long.
+
n (long) [long long]
+
Convert a C/C++ long long to a Python long.
+
o (long) [unsigned long long]
+
Convert a C/C++ unsigned long long to a Python long.
+
r (wrapped instance) [type *, SIP_SSIZE_T, const sipTypeDef *]
+
Convert an array of C structures, C++ classes or mapped type instances +to a Python tuple. Note that copies of the array elements are made.
+
s (string/bytes) [char *]
+
Convert a C/C++ '\0' terminated string to a Python v2 string object +or a Python v3 bytes object. If the string pointer is NULL then +the result is Py_None.
+
t (long) [unsigned short]
+
Convert a C/C++ unsigned short to a Python long.
+
u (long) [unsigned int]
+
Convert a C/C++ unsigned int to a Python long.
+
w (unicode/string) [wchar_t]
+
Convert a C/C++ wide character to a Python v2 unicode object or a +Python v3 string object.
+
x (unicode/string) [wchar_t *]
+
Convert a C/C++ L'\0' terminated wide character string to a Python +v2 unicode object or a Python v3 string object. If the string pointer +is NULL then the result is Py_None.
+
A (string) [char *]
+
Convert a C/C++ '\0' terminated string to a Python v2 or v3 string +object. If the string pointer is NULL then the result is +Py_None.
+
B (wrapped instance) [type *, sipWrapperType *, PyObject *]
+

Convert a new C structure or a new C++ class instance to a Python class +instance object. Ownership of the structure or instance is determined +by the PyObject * argument. If it is NULL and the instance has +already been wrapped then the ownership is unchanged. If it is +NULL or Py_None then ownership will be with Python. Otherwise +ownership will be with C/C++ and the instance associated with the +PyObject * argument. The Python class is influenced by any +applicable %ConvertToSubClassCode code.

+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use N.

+
+
+
C (wrapped instance) [type *, sipWrapperType *, PyObject *]
+

Convert a C structure or a C++ class instance to a Python class +instance object. If the structure or class instance has already been +wrapped then the result is a new reference to the existing class +instance object. Ownership of the structure or instance is determined +by the PyObject * argument. If it is NULL and the instance has +already been wrapped then the ownership is unchanged. If it is +NULL and the instance is newly wrapped then ownership will be with +C/C++. If it is Py_None then ownership is transferred to Python +via a call to sipTransferBack(). Otherwise ownership is +transferred to C/C++ and the instance associated with the +PyObject * argument via a call to sipTransferTo(). The +Python class is influenced by any applicable +%ConvertToSubClassCode code.

+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use D.

+
+
+
D (wrapped instance) [type *, const sipTypeDef *, PyObject *]
+
Convert a C structure, C++ class or mapped type instance to a Python +object. If the instance has already been wrapped then the result is a +new reference to the existing object. Ownership of the instance is +determined by the PyObject * argument. If it is NULL and the +instance has already been wrapped then the ownership is unchanged. If +it is NULL and the instance is newly wrapped then ownership will be +with C/C++. If it is Py_None then ownership is transferred to +Python via a call to sipTransferBack(). Otherwise ownership +is transferred to C/C++ and the instance associated with the +PyObject * argument via a call to sipTransferTo(). The +Python class is influenced by any applicable +%ConvertToSubClassCode code.
+
E (wrapped enum) [enum, PyTypeObject *]
+

Convert a named C/C++ enum to an instance of the corresponding +Python named enum type.

+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use F.

+
+
+
F (wrapped enum) [enum, sipTypeDef *]
+
Convert a named C/C++ enum to an instance of the corresponding +Python named enum type.
+
G (unicode) [wchar_t *, SIP_SSIZE_T]
+
Convert a C/C++ wide character array and its length to a Python unicode +object. If the array is NULL then the length is ignored and the +result is Py_None.
+
N (wrapped instance) [type *, sipTypeDef *, PyObject *]
+
Convert a new C structure, C++ class or mapped type instance to a +Python object. Ownership of the instance is determined by the +PyObject * argument. If it is NULL and the instance has +already been wrapped then the ownership is unchanged. If it is +NULL or Py_None then ownership will be with Python. Otherwise +ownership will be with C/C++ and the instance associated with the +PyObject * argument. The Python class is influenced by any +applicable %ConvertToSubClassCode code.
+
R (object) [PyObject *]
+
The result is value passed without any conversions. The reference +count is unaffected, i.e. a reference is taken.
+
S (object) [PyObject *]
+
The result is value passed without any conversions. The reference +count is incremented.
+
V (sip.voidptr) [void *]
+
Convert a C/C++ void * Python sip.voidptr object.
+
+
+ +
+
+PyObject *sipCallMethod(int *iserr, PyObject *method, const char *format, ...)
+

This calls a Python method passing a tuple of arguments based on a format +string and associated values in a similar way to the Python +PyObject_CallObject() function.

+ +++ + + + + + +
Parameters:
    +
  • iserr – if this is not NULL then the location it points to is set to a +non-zero value if there was an error.
    • +
  • method – the Python bound method to call.
    • +
  • format – the string of format characters (see sipBuildResult()).
    • +
+
Returns:

If there was an error then NULL is returned and a Python exception +is raised.

+
+

It is normally called by handwritten code specified with the +%VirtualCatcherCode directive with method being the supplied +sipMethod.

+
+ +
+
+int sipCanConvertToEnum(PyObject *obj, const sipTypeDef *td)
+

This checks if a Python object can be converted to a named enum.

+ +++ + + + + + +
Parameters: +
Returns:

a non-zero value if the object can be converted.

+
+
+ +
+
+int sipCanConvertToInstance(PyObject *obj, sipWrapperType *type, int flags)
+

This checks if a Python object can be converted to an instance of a C +structure or C++ class.

+ +++ + + + + + +
Parameters: +
Returns:

a non-zero value if the object can be converted.

+
+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use +sipCanConvertToType().

+
+
+ +
+
+int sipCanConvertToMappedType(PyObject *obj, const sipMappedType *mt, int flags)
+

This checks if a Python object can be converted to an instance of a C +structure or C++ class which has been implemented as a mapped type.

+ +++ + + + + + +
Parameters: +
Returns:

a non-zero value if the object can be converted.

+
+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use +sipCanConvertToType().

+
+
+ +
+
+int sipCanConvertToType(PyObject *obj, const sipTypeDef *td, int flags)
+

This checks if a Python object can be converted to an instance of a C +structure, C++ class or mapped type.

+ +++ + + + + + +
Parameters: +
Returns:

a non-zero value if the object can be converted.

+
+
+ +
+
+PyObject *sipClassName(PyObject *obj)
+

This gets the class name of a wrapped instance as a Python string. It +comes with a reference.

+ +++ + + + + + +
Parameter:obj – the wrapped instance.
Returns:the name of the instance’s class.
+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use the +following:

+
PyString_FromString(obj->ob_type->tp_name)
+
+
+
+ +
+
+PyObject *sipConvertFromConstVoidPtr(const void *cpp)
+

This creates a sip.voidptr object for a memory address. The +object will not be writeable and has no associated size.

+ +++ + + + + + +
Parameter:cpp – the memory address.
Returns:the sip.voidptr object.
+
+ +
+
+PyObject *sipConvertFromConstVoidPtrAndSize(const void *cpp, SIP_SSIZE_T size)
+

This creates a sip.voidptr object for a memory address. The +object will not be writeable and can be used as an immutable buffer object.

+ +++ + + + + + +
Parameters:
    +
  • cpp – the memory address.
    • +
  • size – the size associated with the address.
    • +
+
Returns:

the sip.voidptr object.

+
+
+ +
+
+PyObject *sipConvertFromEnum(int eval, const sipTypeDef *td)
+

This converts a named C/C++ enum to an instance of the corresponding +generated Python type.

+ +++ + + + + + +
Parameters: +
Returns:

the Python object.

+
+
+ +
+
+PyObject *sipConvertFromInstance(void *cpp, sipWrapperType *type, PyObject *transferObj)
+

This converts a C structure or a C++ class instance to an instance of the +corresponding generated Python type.

+ +++ + + + + + +
Parameters:
    +
  • cpp – the C/C++ instance.
    • +
  • type – the type’s generated type object.
    • +
  • transferObj – this controls the ownership of the returned value.
    • +
+
Returns:

the Python object.

+
+

If the C/C++ instance has already been wrapped then the result is a +new reference to the existing class instance object.

+

If transferObj is NULL and the instance has already been wrapped then +the ownership is unchanged.

+

If transferObj is NULL and the instance is newly wrapped then +ownership will be with C/C++.

+

If transferObj is Py_None then ownership is transferred to Python via +a call to sipTransferBack().

+

Otherwise ownership is transferred to C/C++ and the instance associated +with transferObj via a call to sipTransferTo().

+

The Python type is influenced by any applicable +%ConvertToSubClassCode code.

+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use +sipConvertFromType().

+
+
+ +
+
+PyObject *sipConvertFromMappedType(void *cpp, const sipMappedType *mt, PyObject *transferObj)
+

This converts a C structure or a C++ class instance wrapped as a mapped +type to an instance of the corresponding generated Python type.

+ +++ + + + + + +
Parameters:
    +
  • cpp – the C/C++ instance.
    • +
  • mt – the opaque structure returned by sipFindMappedType().
    • +
  • transferObj – this controls the ownership of the returned value.
    • +
+
Returns:

the Python object.

+
+

If transferObj is NULL then the ownership is unchanged.

+

If transferObj is Py_None then ownership is transferred to Python +via a call to sipTransferBack().

+

Otherwise ownership is transferred to C/C++ and the instance associated +with transferObj argument via a call to sipTransferTo().

+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use +sipConvertFromType().

+
+
+ +
+
+PyObject *sipConvertFromNamedEnum(int eval, PyTypeObject *type)
+

This converts a named C/C++ enum to an instance of the corresponding +generated Python type.

+ +++ + + + + + +
Parameters: +
Returns:

the Python object.

+
+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use +sipConvertFromEnum().

+
+
+ +
+
+PyObject *sipConvertFromNewInstance(void *cpp, sipWrapperType *type, PyObject *transferObj)
+

This converts a new C structure or a C++ class instance to an instance of +the corresponding generated Python type.

+ +++ + + + + + +
Parameters:
    +
  • cpp – the C/C++ instance.
    • +
  • type – the type’s generated type object.
    • +
  • transferObj – this controls the ownership of the returned value.
    • +
+
Returns:

the Python object.

+
+

If transferObj is NULL or Py_None then ownership will be with +Python.

+

Otherwise ownership will be with C/C++ and the instance associated with +transferObj.

+

The Python type is influenced by any applicable +%ConvertToSubClassCode code.

+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use +sipConvertFromNewType().

+
+
+ +
+
+PyObject *sipConvertFromNewType(void *cpp, const sipTypeDef *td, PyObject *transferObj)
+

This converts a new C structure or a C++ class instance to an instance of +the corresponding generated Python type.

+ +++ + + + + + +
Parameters:
    +
  • cpp – the C/C++ instance.
    • +
  • td – the type’s generated type structure.
    • +
  • transferObj – this controls the ownership of the returned value.
    • +
+
Returns:

the Python object.

+
+

If transferObj is NULL or Py_None then ownership will be with +Python.

+

Otherwise ownership will be with C/C++ and the instance associated with +transferObj.

+

The Python type is influenced by any applicable +%ConvertToSubClassCode code.

+
+ +
+
+SIP_SSIZE_T sipConvertFromSequenceIndex(SIP_SSIZE_T idx, SIP_SSIZE_T len)
+

This converts a Python sequence index (i.e. where a negative value refers +to the offset from the end of the sequence) to a C/C++ array index. If the +index was out of range then a negative value is returned and a Python +exception raised.

+ +++ + + + + + +
Parameters:
    +
  • idx – the sequence index.
    • +
  • len – the length of the sequence.
    • +
+
Returns:

the unsigned array index.

+
+
+ +
+
+int sipConvertFromSliceObject(PyObject *slice, SIP_SSIZE_T length, SIP_SSIZE_T *start, SIP_SSIZE_T *stop, SIP_SSIZE_T *step, SIP_SSIZE_T *slicelength)
+
This is a thin wrapper around the Python PySlice_GetIndicesEx() +function provided to make it easier to write handwritten code that is +compatible with SIP v3.x and versions of Python earlier that v2.3.
+ +
+
+PyObject *sipConvertFromType(void *cpp, const sipTypeDef *td, PyObject *transferObj)
+

This converts a C structure or a C++ class instance to an instance of the +corresponding generated Python type.

+ +++ + + + + + +
Parameters:
    +
  • cpp – the C/C++ instance.
    • +
  • td – the type’s generated type structure.
    • +
  • transferObj – this controls the ownership of the returned value.
    • +
+
Returns:

the Python object.

+
+

If the C/C++ instance has already been wrapped then the result is a new +reference to the existing object.

+

If transferObj is NULL and the instance has already been wrapped then +the ownership is unchanged.

+

If transferObj is NULL and the instance is newly wrapped then +ownership will be with C/C++.

+

If transferObj is Py_None then ownership is transferred to Python via +a call to sipTransferBack().

+

Otherwise ownership is transferred to C/C++ and the instance associated +with transferObj via a call to sipTransferTo().

+

The Python class is influenced by any applicable +%ConvertToSubClassCode code.

+
+ +
+
+PyObject *sipConvertFromVoidPtr(void *cpp)
+

This creates a sip.voidptr object for a memory address. The +object will be writeable but has no associated size.

+ +++ + + + + + +
Parameter:cpp – the memory address.
Returns:the sip.voidptr object.
+
+ +
+
+PyObject *sipConvertFromVoidPtrAndSize(void *cpp, SIP_SSIZE_T size)
+

This creates a sip.voidptr object for a memory address. The +object will be writeable and can be used as a mutable buffer object.

+ +++ + + + + + +
Parameters:
    +
  • cpp – the memory address.
    • +
  • size – the size associated with the address.
    • +
+
Returns:

the sip.voidptr object.

+
+
+ +
+
+void *sipConvertToInstance(PyObject *obj, sipWrapperType *type, PyObject *transferObj, int flags, int *state, int *iserr)
+

This converts a Python object to an instance of a C structure or C++ class +assuming that a previous call to sipCanConvertToInstance() has +been successful.

+ +++ + + + + + +
Parameters:
    +
  • obj – the Python object.
    • +
  • type – the type’s generated type object.
    • +
  • transferObj – this controls any ownership changes to obj.
    • +
  • flags – any combination of the SIP_NOT_NONE and +SIP_NO_CONVERTORS flags.
    • +
  • state – the state of the returned C/C++ instance is returned via this pointer.
    • +
  • iserr – the error flag is passed and updated via this pointer.
    • +
+
Returns:

the C/C++ instance.

+
+

If transferObj is NULL then the ownership is unchanged.

+

If transferObj is Py_None then ownership is transferred to Python via +a call to sipTransferBack().

+

Otherwise ownership is transferred to C/C++ and obj associated with +transferObj via a call to sipTransferTo().

+

If state is not NULL then the location it points to is set to +describe the state of the returned C/C++ instance and is the value returned +by any %ConvertToTypeCode. The calling code must then release +the value at some point to prevent a memory leak by calling +sipReleaseInstance().

+

If there is an error then the location iserr points to is set to a +non-zero value. If it was initially a non-zero value then the conversion +isn’t attempted in the first place. (This allows several calls to be made +that share the same error flag so that it only needs to be tested once +rather than after each call.)

+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use +sipConvertToType().

+
+
+ +
+
+void *sipConvertToMappedType(PyObject *obj, const sipMappedType *mt, PyObject *transferObj, int flags, int *state, int *iserr)
+

This converts a Python object to an instance of a C structure or C++ +class that is implemented as a mapped type assuming that a previous call to +sipCanConvertToMappedType() has been successful.

+ +++ + + + + + +
Parameters:
    +
  • obj – the Python object.
    • +
  • mt – the opaque structure returned by sipFindMappedType().
    • +
  • transferObj – this controls any ownership changes to obj.
    • +
  • flags – this may be the SIP_NOT_NONE flag.
    • +
  • state – the state of the returned C/C++ instance is returned via this pointer.
    • +
  • iserr – the error flag is passed and updated via this pointer.
    • +
+
Returns:

the C/C++ instance.

+
+

If transferObj is NULL then the ownership is unchanged.

+

If transferObj is Py_None then ownership is transferred to Python via +a call to sipTransferBack().

+

Otherwise ownership is transferred to C/C++ and obj associated with +transferObj via a call to sipTransferTo().

+

If state is not NULL then the location it points to is set to +describe the state of the returned C/C++ instance and is the value returned +by any %ConvertToTypeCode. The calling code must then release +the value at some point to prevent a memory leak by calling +sipReleaseMappedType().

+

If there is an error then the location iserr points to is set to a +non-zero value. If it was initially a non-zero value then the conversion +isn’t attempted in the first place. (This allows several calls to be made +that share the same error flag so that it only needs to be tested once +rather than after each call.)

+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use +sipConvertToType()

+
+
+ +
+
+void *sipConvertToType(PyObject *obj, const sipTypeDef *td, PyObject *transferObj, int flags, int *state, int *iserr)
+

This converts a Python object to an instance of a C structure, C++ class or +mapped type assuming that a previous call to sipCanConvertToType() +has been successful.

+ +++ + + + + + +
Parameters:
    +
  • obj – the Python object.
    • +
  • td – the type’s generated type structure.
    • +
  • transferObj – this controls any ownership changes to obj.
    • +
  • flags – any combination of the SIP_NOT_NONE and +SIP_NO_CONVERTORS flags.
    • +
  • state – the state of the returned C/C++ instance is returned via this pointer.
    • +
  • iserr – the error flag is passed and updated via this pointer.
    • +
+
Returns:

the C/C++ instance.

+
+

If transferObj is NULL then the ownership is unchanged. If it is +Py_None then ownership is transferred to Python via a call to +sipTransferBack().

+

Otherwise ownership is transferred to C/C++ and obj associated with +transferObj via a call to sipTransferTo().

+

If state is not NULL then the location it points to is set to +describe the state of the returned C/C++ instance and is the value returned +by any %ConvertToTypeCode. The calling code must then release +the value at some point to prevent a memory leak by calling +sipReleaseType().

+

If there is an error then the location iserr points to is set to a +non-zero value. If it was initially a non-zero value then the conversion +isn’t attempted in the first place. (This allows several calls to be made +that share the same error flag so that it only needs to be tested once +rather than after each call.)

+
+ +
+
+void *sipConvertToVoidPtr(PyObject *obj)
+

This converts a Python object to a memory address. +PyErr_Occurred() must be used to determine if the conversion was +successful.

+ +++ + + + + + +
Parameter:obj – the Python object which may be Py_None, a sip.voidptr or a +PyCObject.
Returns:the memory address.
+
+ +
+
+int sipExportSymbol(const char *name, void *sym)
+

Python does not allow extension modules to directly access symbols in +another extension module. This exports a symbol, referenced by a name, +that can subsequently be imported, using sipImportSymbol(), by +another module.

+ +++ + + + + + +
Parameters:
    +
  • name – the name of the symbol.
    • +
  • sym – the value of the symbol.
    • +
+
Returns:

0 if there was no error. A negative value is returned if name is +already associated with a symbol or there was some other error.

+
+
+ +
+
+sipWrapperType *sipFindClass(const char *type)
+

This returns a pointer to the generated type object + corresponding to a C/C++ type.

+ +++ + + + + + +
Parameter:type – the C/C++ declaration of the type.
Returns:the generated type object. This will not change and may be saved in a +static cache. NULL is returned if the C/C++ type doesn’t exist.
+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use +sipFindType().

+
+
+ +
+
+const sipMappedType *sipFindMappedType(const char *type)
+

This returns a pointer to an opaque structure describing a mapped type.

+ +++ + + + + + +
Parameter:type – the C/C++ declaration of the type.
Returns:the opaque structure. This will not change and may be saved in a +static cache. NULL is returned if the C/C++ type doesn’t exist.
+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use +sipFindType().

+
+
+ +
+
+PyTypeObject *sipFindNamedEnum(const char *type)
+

This returns a pointer to the generated Python type object corresponding to a named C/C++ enum.

+ +++ + + + + + +
Parameter:type – the C/C++ declaration of the enum.
Returns:the generated Python type object. This will not change and may be +saved in a static cache. NULL is returned if the C/C++ enum +doesn’t exist.
+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use +sipFindType().

+
+
+ +
+
+const sipTypeDef *sipFindType(const char *type)
+

This returns a pointer to the generated type structure corresponding to a C/C++ type.

+ +++ + + + + + +
Parameter:type – the C/C++ declaration of the type.
Returns:the generated type structure. This will not change and may be saved in +a static cache. NULL is returned if the C/C++ type doesn’t exist.
+
+ +
+
+void *sipForceConvertToInstance(PyObject *obj, sipWrapperType *type, PyObject *transferObj, int flags, int *state, int *iserr)
+

This converts a Python object to an instance of a C structure or C++ class +by calling sipCanConvertToInstance() and, if it is successfull, +calling sipConvertToInstance().

+

See sipConvertToInstance() for a full description of the +arguments.

+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use +sipForceConvertToType().

+
+
+ +
+
+void *sipForceConvertToMappedType(PyObject *obj, const sipMappedType *mt, PyObject *transferObj, int flags, int *state, int *iserr)
+

This converts a Python object to an instance of a C structure or C++ class +which has been implemented as a mapped type by calling +sipCanConvertToMappedType() and, if it is successfull, calling +sipConvertToMappedType().

+

See sipConvertToMappedType() for a full description of the +arguments.

+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use +sipForceConvertToType().

+
+
+ +
+
+void *sipForceConvertToType(PyObject *obj, const sipTypeDef *td, PyObject *transferObj, int flags, int *state, int *iserr)
+

This converts a Python object to an instance of a C structure, C++ class or +mapped type by calling sipCanConvertToType() and, if it is +successfull, calling sipConvertToType().

+

See sipConvertToType() for a full description of the arguments.

+
+ +
+
+void sipFree(void *mem)
+

This returns an area of memory allocated by sipMalloc() to the +heap.

+ +++ + + + +
Parameter:mem – the memory address.
+
+ +
+
+PyObject *sipGetPyObject(void *cppptr, const sipTypeDef *td)
+

This returns a borrowed reference to the Python object for a C structure or +C++ class instance.

+ +++ + + + + + +
Parameters:
    +
  • cppptr – the pointer to the C/C++ instance.
    • +
  • td – the generated type structure corresponding +to the C/C++ type.
    • +
+
Returns:

the Python object or NULL (and no exception is raised) if the +C/C++ instance hasn’t been wrapped.

+
+
+ +
+
+int sipGetState(PyObject *transferObj)
+

The %ConvertToTypeCode directive requires that the provided +code returns an int describing the state of the converted value. The +state usually depends on any transfers of ownership that have been +requested. This is a convenience function that returns the correct state +when the converted value is a temporary.

+ +++ + + + + + +
Parameter:transferObj – the object that describes the requested transfer of ownership.
Returns:the state of the converted value.
+
+ +
+
+PyObject *sipGetWrapper(void *cppptr, sipWrapperType *type)
+

This returns a borrowed reference to the wrapped instance object for a C +structure or C++ class instance.

+ +++ + + + + + +
Parameters:
    +
  • cppptr – the pointer to the C/C++ instance.
    • +
  • type – the generated type object corresponding to +the C/C++ type.
    • +
+
Returns:

the Python object or NULL (and no exception is raised) if the +C/C++ instance hasn’t been wrapped.

+
+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use +sipGetPyObject().

+
+
+ +
+
+void *sipImportSymbol(const char *name)
+

Python does not allow extension modules to directly access symbols in +another extension module. This imports a symbol, referenced by a name, +that has previously been exported, using sipExportSymbol(), by +another module.

+ +++ + + + + + +
Parameter:name – the name of the symbol.
Returns:the value of the symbol. NULL is returned if there is no such +symbol.
+
+ +
+
+sipIntTypeClassMap
+

This C structure is used with sipMapIntToClass() to define a +mapping between integer based RTTI and generated type objects. The structure elements are as follows.

+
+
+int typeInt
+
The integer RTTI.
+ +
+
+sipWrapperType **pyType.
+
A pointer to the corresponding generated type object.
+ +
+

Note

+

This is deprecated from SIP v4.8.

+
+
+ +
+
+int sipIsAPIEnabled(const char *name, int from, int to)
+

+New in version 4.9.

+

This checks to see if the current version number of an API falls within a +given range. See Managing Incompatible APIs for more detail.

+ +++ + + + + + +
Parameters:
    +
  • name – the name of the API.
    • +
  • from – the lower bound of the range. For the API to be enabled its version +number must be greater than or equal to from. If from is 0 then +this check isn’t made.
    • +
  • to – the upper bound of the range. For the API to be enabled its version +number must be less than to. If to is 0 then this check isn’t +made.
    • +
+
Returns:

a non-zero value if the API is enabled.

+
+
+ +
+
+unsigned long sipLong_AsUnsignedLong(PyObject *obj)
+
This function is a thin wrapper around PyLong_AsUnsignedLong() +that works around a bug in Python v2.3.x and earlier when converting +integer objects.
+ +
+
+void *sipMalloc(size_t nbytes)
+

This allocates an area of memory on the heap using the Python +PyMem_Malloc() function. The memory is freed by calling +sipFree().

+ +++ + + + + + +
Parameter:nbytes – the number of bytes to allocate.
Returns:the memory address. If there was an error then NULL is returned +and a Python exception raised.
+
+ +
+
+sipWrapperType *sipMapIntToClass(int type, const sipIntTypeClassMap *map, int maplen)
+

This can be used in %ConvertToSubClassCode code as a +convenient way of converting integer based RTTI to the corresponding +generated type object.

+ +++ + + + + + +
Parameters:
    +
  • type – the integer RTTI.
    • +
  • map – the table of known RTTI and the corresponding type objects (see +sipIntTypeClassMap). The entries in the table must be sorted +in ascending order of RTTI.
    • +
  • maplen – the number of entries in the table.
    • +
+
Returns:

the corresponding type object, or NULL if type wasn’t in map.

+
+
+

Note

+

This is deprecated from SIP v4.8.

+
+
+ +
+
+sipWrapperType *sipMapStringToClass(char *type, const sipStringTypeClassMap *map, int maplen)
+

This can be used in %ConvertToSubClassCode code as a +convenient way of converting '\0' terminated string based RTTI to the +corresponding generated type object.

+ +++ + + + + + +
Parameters:
    +
  • type – the string RTTI.
    • +
  • map – the table of known RTTI and the corresponding type objects (see +sipStringTypeClassMap). The entries in the table must be +sorted in ascending order of RTTI.
    • +
  • maplen – the number of entries in the table.
    • +
+
Returns:

the corresponding type object, or NULL if type wasn’t in map.

+
+
+

Note

+

This is deprecated from SIP v4.8.

+
+
+ +
+
+int sipParseResult(int *iserr, PyObject *method, PyObject *result, const char *format, ...)
+

This converts a Python object (usually returned by a method) to C/C++ based +on a format string and associated values in a similar way to the Python +PyArg_ParseTuple() function.

+ +++ + + + + + +
Parameters:
    +
  • iserr – if this is not NULL then the location it points to is set to a +non-zero value if there was an error.
    • +
  • method – the Python method that returned result.
    • +
  • result – the Python object returned by method.
    • +
  • format – the format string.
    • +
+
Returns:

0 if there was no error. Otherwise a negative value is returned, and +an exception raised.

+
+

This is normally called by handwritten code specified with the +%VirtualCatcherCode directive with method being the supplied +sipMethod and result being the value returned by +sipCallMethod().

+

If format begins and ends with parentheses then result must be a Python +tuple and the rest of format is applied to the tuple contents.

+

In the following description the first letter is the format character, the +entry in parentheses is the Python object type that the format character +will convert, and the entry in brackets are the types of the C/C++ values +to be passed.

+
+
ae (object) [char *]
+
Convert a Python string-like object of length 1 to a C/C++ char +according to the encoding e. e can either be A for ASCII, +L for Latin-1, or 8 for UTF-8. For Python v2 the object may be +either a string or a unicode object that can be encoded. For Python v3 +the object may either be a bytes object or a string object that can be +encoded. An object that supports the buffer protocol may also be used.
+
b (integer) [bool *]
+
Convert a Python integer to a C/C++ bool.
+
c (string/bytes) [char *]
+
Convert a Python v2 string object or a Python v3 bytes object of length +1 to a C/C++ char.
+
d (float) [double *]
+
Convert a Python floating point number to a C/C++ double.
+
e (integer) [enum *]
+
Convert a Python integer to an anonymous C/C++ enum.
+
f (float) [float *]
+
Convert a Python floating point number to a C/C++ float.
+
g (string/bytes) [const char **, SIP_SSIZE_T *]
+
Convert a Python v2 string object or a Python v3 bytes object to a +C/C++ character array and its length. If the Python object is +Py_None then the array and length are NULL and zero +respectively.
+
h (integer) [short *]
+
Convert a Python integer to a C/C++ short.
+
i (integer) [int *]
+
Convert a Python integer to a C/C++ int.
+
l (long) [long *]
+
Convert a Python long to a C/C++ long.
+
m (long) [unsigned long *]
+
Convert a Python long to a C/C++ unsigned long.
+
n (long) [long long *]
+
Convert a Python long to a C/C++ long long.
+
o (long) [unsigned long long *]
+
Convert a Python long to a C/C++ unsigned long long.
+
s (string/bytes) [const char **]
+

Convert a Python v2 string object or a Python v3 bytes object to a +C/C++ '\0' terminated string. If the Python object is Py_None +then the string is NULL.

+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use B.

+
+
+
t (long) [unsigned short *]
+
Convert a Python long to a C/C++ unsigned short.
+
u (long) [unsigned int *]
+
Convert a Python long to a C/C++ unsigned int.
+
w (unicode/string) [wchar_t *]
+
Convert a Python v2 string or unicode object or a Python v3 string +object of length 1 to a C/C++ wide character.
+
x (unicode/string) [wchar_t **]
+
Convert a Python v2 string or unicode object or a Python v3 string +object to a C/C++ L'\0' terminated wide character string. If the +Python object is Py_None then the string is NULL.
+
Ae (object) [int, const char **]
+
Convert a Python string-like object to a C/C++ '\0' terminated +string according to the encoding e. e can either be A for +ASCII, L for Latin-1, or 8 for UTF-8. If the Python object is +Py_None then the string is NULL. The integer uniquely +identifies the object in the context defined by the S format +character and allows an extra reference to the object to be kept to +ensure that the string remains valid. For Python v2 the object may be +either a string or a unicode object that can be encoded. For Python v3 +the object may either be a bytes object or a string object that can be +encoded. An object that supports the buffer protocol may also be used.
+
B (string/bytes) [int, const char **]
+
Convert a Python v2 string object or a Python v3 bytes object to a +C/C++ '\0' terminated string. If the Python object is Py_None +then the string is NULL. The integer uniquely identifies the +object in the context defined by the S format character and allows +an extra reference to the object to be kept to ensure that the string +remains valid.
+
Cf (wrapped class) [sipWrapperType *, int *, void **]
+

Convert a Python object to a C structure or a C++ class instance and +return its state as described in sipConvertToInstance(). +f is a combination of the following flags encoded as an ASCII +character by adding 0 to the combined value:

+
+

0x01 disallows the conversion of Py_None to NULL

+
+
0x02 implements the Factory and TransferBack
+
annotations
+
0x04 suppresses the return of the state of the returned C/C++
+
instance. Note that the int * used to return the state is +not passed if this flag is specified.
+
+
+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use Hf.

+
+
+
Df (wrapped instance) [const sipTypeDef *, int *, void **]
+

Convert a Python object to a C structure, C++ class or mapped type +instance and return its state as described in +sipConvertToType(). f is a combination of the following +flags encoded as an ASCII character by adding 0 to the combined +value:

+
+

0x01 disallows the conversion of Py_None to NULL

+
+
0x02 implements the Factory and TransferBack
+
annotations
+
0x04 suppresses the return of the state of the returned C/C++
+
instance. Note that the int * used to return the state is +not passed if this flag is specified.
+
+
+
+

Note

+

This is deprecated from SIP v4.10.1. Instead you should use +Hf.

+
+
+
E (wrapped enum) [PyTypeObject *, enum *]
+

Convert a Python named enum type to the corresponding C/C++ enum.

+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use F.

+
+
+
F (wrapped enum) [sipTypeDef *, enum *]
+
Convert a Python named enum type to the corresponding C/C++ enum.
+
G (unicode/string) [wchar_t **, SIP_SSIZE_T *]
+
Convert a Python v2 string or unicode object or a Python v3 string +object to a C/C++ wide character array and its length. If the Python +object is Py_None then the array and length are NULL and zero +respectively.
+
Hf (wrapped instance) [const sipTypeDef *, int *, void **]
+

Convert a Python object to a C structure, C++ class or mapped type +instance as described in sipConvertToType(). f is a +combination of the following flags encoded as an ASCII character by +adding 0 to the combined value:

+
+

0x01 disallows the conversion of Py_None to NULL

+
+
0x02 implements the Factory and TransferBack
+
annotations
+
+

0x04 returns a copy of the C/C++ instance.

+
+
+
N (object) [PyTypeObject *, :PyObject **]
+
A Python object is checked to see if it is a certain type and then +returned without any conversions. The reference count is incremented. +The Python object may be Py_None.
+
O (object) [PyObject **]
+
A Python object is returned without any conversions. The reference +count is incremented.
+
S [sipSimpleWrapper *]
+
This format character, if used, must be the first. It is used with +other format characters to define a context and doesn’t itself convert +an argument.
+
T (object) [PyTypeObject *, PyObject **]
+
A Python object is checked to see if it is a certain type and then +returned without any conversions. The reference count is incremented. +The Python object may not be Py_None.
+
V (sip.voidptr) [void *]
+
Convert a Python sip.voidptr object to a C/C++ void *.
+
Z (object) []
+
Check that a Python object is Py_None. No value is returned.
+
+
+ +
+
+int sipRegisterAttributeGetter(const sipTypeDef *td, sipAttrGetterFunc getter)
+

This registers a handler that will called just before SIP needs to get an +attribute from a wrapped type’s dictionary for the first time. The handler +must then populate the type’s dictionary with any lazy attributes.

+ +++ + + + + + +
Parameters:
    +
  • td – the optional generated type structure that +determines which types the handler will be called for.
    • +
  • getter – the handler function.
    • +
+
Returns:

0 if there was no error, otherwise -1 is returned.

+
+

If td is not NULL then the handler will only be called for types with +that type or that are sub-classed from it. Otherwise the handler will be +called for all types.

+

A handler has the following signature.

+

int handler(const sipTypeDef *td, PyObject *dict)

+
+

td is the generated type definition of the type whose dictionary is +to be populated.

+

dict is the dictionary to be populated.

+

0 if there was no error, otherwise -1 is returned.

+
+

See the section Lazy Type Attributes for more details.

+
+ +
+
+int sipRegisterPyType(PyTypeObject *type)
+

This registers a Python type object that can be used as the meta-type or +super-type of a wrapped C++ type.

+ +++ + + + + + +
Parameter:type – the type object.
Returns:0 if there was no error, otherwise -1 is returned.
+

See the section Types and Meta-types for more details.

+
+ +
+
+void sipReleaseInstance(void *cpp, sipWrapperType *type, int state)
+

This destroys a wrapped C/C++ instance if it was a temporary instance. It +is called after a call to either sipConvertToInstance() or +sipForceConvertToInstance().

+ +++ + + + +
Parameters:
    +
  • cpp – the C/C++ instance.
    • +
  • type – the type’s generated type object.
    • +
  • state – describes the state of the C/C++ instance.
    • +
+
+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use +sipReleaseType().

+
+
+ +
+
+void sipReleaseMappedType(void *cpp, const sipMappedType *mt, int state)
+

This destroys a wrapped C/C++ mapped type if it was a temporary instance. +It is called after a call to either sipConvertToMappedType() or +sipForceConvertToMappedType().

+ +++ + + + +
Parameters:
    +
  • cpp – the C/C++ instance.
    • +
  • mt – the opaque structure returned by sipFindMappedType().
    • +
  • state – describes the state of the C/C++ instance.
    • +
+
+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use +sipReleaseType().

+
+
+ +
+
+void sipReleaseType(void *cpp, const sipTypeDef *td, int state)
+

This destroys a wrapped C/C++ or mapped type instance if it was a temporary +instance. It is called after a call to either sipConvertToType() +or sipForceConvertToType().

+ +++ + + + +
Parameters:
    +
  • cpp – the C/C++ instance.
    • +
  • td – the type’s generated type structure.
    • +
  • state – describes the state of the C/C++ instance.
    • +
+
+
+ +
+
+const char *sipResolveTypedef(const char *name)
+

This returns the value of a C/C++ typedef.

+ +++ + + + + + +
Parameter:name – the name of the typedef.
Returns:the value of the typedef or NULL if there was no such typedef.
+
+ +
+
+sipSimpleWrapper
+

This is a C structure that represents a Python wrapped instance whose type +is sip.simplewrapper. It is an extension of the PyObject +structure and so may be safely cast to it.

+
+
+PyObject *user
+
This can be used for any purpose by handwritten code and will +automatically be garbage collected at the appropriate time.
+ +
+ +
+
+PyTypeObject *sipSimpleWrapper_Type
+
This is the type of a sipSimpleWrapper structure and is the C +implementation of sip.simplewrapper. It may be safely cast to +sipWrapperType.
+ +
+
+sipStringTypeClassMap
+

This C structure is used with sipMapStringToClass() to define a +mapping between '\0' terminated string based RTTI and +Generated Type Objects. The structure elements are as follows.

+
+
+char *typeString
+
The '\0' terminated string RTTI.
+ +
+
+sipWrapperType **pyType.
+
A pointer to the corresponding generated type object.
+ +
+

Note

+

This is deprecated from SIP v4.8.

+
+
+ +
+
+void sipTransferBack(PyObject *obj)
+

This transfers ownership of a Python wrapped instance to Python (see +Ownership of Objects).

+ +++ + + + +
Parameter:obj – the wrapped instance.
+

In addition, any association of the instance with regard to the cyclic +garbage collector with another instance is removed.

+
+ +
+
+void sipTransferBreak(PyObject *obj)
+

Any association of a Python wrapped instance with regard to the cyclic +garbage collector with another instance is removed. Ownership of the +instance should be with C++.

+ +++ + + + +
Parameter:obj – the wrapped instance.
+
+ +
+
+void sipTransferTo(PyObject *obj, PyObject *owner)
+

This transfers ownership of a Python wrapped instance to C++ (see +Ownership of Objects).

+ +++ + + + +
Parameters:
    +
  • obj – the wrapped instance.
    • +
  • owner – an optional wrapped instance that obj becomes associated with with +regard to the cyclic garbage collector. If owner is NULL then no +such association is made. If owner is the same value as obj then +any reference cycles involving obj can never be detected or broken by +the cyclic garbage collector. Responsibility for calling the C++ +instance’s destructor is always transfered to C++.
    • +
+
+
+ +
+
+PyTypeObject *sipTypeAsPyTypeObject(sipTypeDef *td)
+

This returns a pointer to the Python type object that SIP creates for a +generated type structure.

+ +++ + + + + + +
Parameter:td – the type structure.
Returns:the Python type object. If the type structure refers to a mapped type +then NULL will be returned.
+

If the type structure refers to a C structure or C++ class then the +Python type object may be safely cast to a sipWrapperType.

+
+ +
+
+const sipTypeDef *sipTypeFromPyTypeObject(PyTypeObject *py_type)
+

This returns the generated type structure for +a Python type object.

+ +++ + + + + + +
Parameter:py_type – the Python type object.
Returns:the type structure or NULL if the Python type object doesn’t +correspond to a type structure.
+
+ +
+
+int sipTypeIsClass(sipTypeDef *td)
+

This checks if a generated type structure +refers to a C structure or C++ class.

+ +++ + + + + + +
Parameter:td – the type structure.
Returns:a non-zero value if the type structure refers to a structure or class.
+
+ +
+
+int sipTypeIsEnum(sipTypeDef *td)
+

This checks if a generated type structure +refers to a named enum.

+ +++ + + + + + +
Parameter:td – the type structure.
Returns:a non-zero value if the type structure refers to an enum.
+
+ +
+
+int sipTypeIsMapped(sipTypeDef *td)
+

This checks if a generated type structure +refers to a mapped type.

+ +++ + + + + + +
Parameter:td – the type structure.
Returns:a non-zero value if the type structure refers to a mapped type.
+
+ +
+
+int sipTypeIsNamespace(sipTypeDef *td)
+

This checks if a generated type structure +refers to a C++ namespace.

+ +++ + + + + + +
Parameter:td – the type structure.
Returns:a non-zero value if the type structure refers to a namespace.
+
+ +
+
+const char *sipTypeName(const sipTypeDef *td)
+

This returns the C/C++ name of a wrapped type.

+ +++ + + + + + +
Parameter:td – the type’s generated type structure.
Returns:the name of the C/C++ type.
+
+ +
+
+const sipTypeDef *sipTypeScope(const sipTypeDef *td)
+

This returns the generated type structure of +the enclosing scope of another generated type structure.

+ +++ + + + + + +
Parameter:td – the type structure.
Returns:the type structure of the scope or NULL if the type has no scope.
+
+ +
+
+PyTypeObject *sipVoidPtr_Type
+
This is the type of a PyObject structure that is used to wrap a +void *.
+ +
+
+sipWrapper
+
This is a C structure that represents a Python wrapped instance whose type +is sip.wrapper. It is an extension of the +sipSimpleWrapper and PyObject structures and so may be safely +cast to both.
+ +
+
+int sipWrapper_Check(PyObject *obj)
+

This checks if a Python object is a wrapped instance.

+ +++ + + + + + +
Parameter:obj – the Python object.
Returns:a non-zero value if the Python object is a wrapped instance.
+
+

Note

+

This is deprecated from SIP v4.8. Instead you should use the +following:

+
PyObject_TypeCheck(obj, sipWrapper_Type)
+
+
+
+
+ +
+
+PyTypeObject *sipWrapper_Type
+
This is the type of a sipWrapper structure and is the C +implementation of sip.wrapper. It may be safely cast to +sipWrapperType.
+ +
+
+sipWrapperType
+
This is a C structure that represents a SIP generated type object. It is +an extension of the PyTypeObject structure (which is itself an +extension of the PyObject structure) and so may be safely cast to +PyTypeObject (and PyObject).
+ +
+
+PyTypeObject *sipWrapperType_Type
+
This is the type of a sipWrapperType structure and is the C +implementation of sip.wrappertype.
+ +
+

Generated Type Structures

+

SIP generates an opaque type structure for each C structure, C++ class, C++ +namespace, named enum or mapped type being wrapped. These are +sipTypeDef structures and are used extensively by the SIP API.

+

The names of these structure are prefixed by sipType_.

+

For those structures that correspond to C structures, C++ classes, C++ +namespaces or named enums the remaining part of the name is the fully +qualified name of the structure, class, namespace or enum name. Any :: +scope separators are replaced by an underscore. For example, the type object +for class Klass is sipType_Klass.

+

For those structure that correspond to mapped types the remaining part of the +name is generated by SIP. The only way for handwritten code to obtain a +pointer to a structure for a mapped type is to use sipFindType().

+

The type structures of all imported types are available to handwritten code.

+
+
+

Generated Type Objects

+

SIP generates a sipWrapperType type object for each C structure or +C++ class being wrapped.

+

These objects are named with the structure or class name prefixed by +sipClass_. For example, the type object for class Klass is +sipClass_Klass.

+
+

Note

+

Using these names is deprecated from SIP v4.8. Instead use the +corresponding generated type structure (see Generated Type Structures) and +sipTypeAsPyTypeObject().

+
+
+
+

Generated Named Enum Type Objects

+

SIP generates a type object for each named enum being wrapped. These are +PyTypeObject structures. (Anonymous enums are wrapped as Python integers.)

+

These objects are named with the fully qualified enum name (i.e. including any +enclosing scope) prefixed by sipEnum_. For example, the type object for +enum Enum defined in class Klass is sipEnum_Klass_Enum.

+
+

Note

+

Using these names is deprecated from SIP v4.8. Instead use the +corresponding generated type structure (see Generated Type Structures) and +sipTypeAsPyTypeObject().

+
+
+
+

Generated Derived Classes

+

For most C++ classes being wrapped SIP generates a derived class with the same +name prefixed by sip. For example, the derived class for class Klass +is sipKlass.

+

If a C++ class doesn’t have any virtual or protected methods in it or any of +it’s super-class hierarchy, or does not emit any Qt signals, then a derived +class is not generated.

+

Most of the time handwritten code should ignore the derived classes. The only +exception is that handwritten constructor code specified using the +%MethodCode directive should call the derived class’s constructor +(which has the same C++ signature) rather then the wrapped class’s constructor.

+
+
+

Generated Exception Objects

+

SIP generates a Python object for each exception defined with the +%Exception directive.

+

These objects are named with the fully qualified exception name (i.e. including +any enclosing scope) prefixed by sipException_. For example, the type +object for enum Except defined in class Klass is +sipException_Klass_Except.

+

The objects of all imported exceptions are available to handwritten code.

+
+
+ + +
+
+
+
+
+

Table Of Contents

+ + +

Previous topic

+

Annotations

+

Next topic

+

Using the C API when Embedding

+ + +
+
+
+
+
+

Navigation

+ +
+
+ © Copyright 2010 Riverbank Computing Limited. + Created using Sphinx 0.6.4. +
+ + \ No newline at end of file -- cgit v1.2.3