<spanid="ref-c-api"></span><h1>C API for Handwritten Code<aclass="headerlink"href="#c-api-for-handwritten-code"title="Permalink to this headline">¶</a></h1>
<p>In this section we describe the API that can be used by handwritten code in
specification files.</p>
<dlclass="cmacro">
<dtid="SIP_API_MAJOR_NR">
<ttclass="descname">SIP_API_MAJOR_NR</tt><aclass="headerlink"href="#SIP_API_MAJOR_NR"title="Permalink to this definition">¶</a></dt>
<dd>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.</dd></dl>
<dlclass="cmacro">
<dtid="SIP_API_MINOR_NR">
<ttclass="descname">SIP_API_MINOR_NR</tt><aclass="headerlink"href="#SIP_API_MINOR_NR"title="Permalink to this definition">¶</a></dt>
<dd>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.</dd></dl>
<dlclass="cmacro">
<dtid="SIP_BLOCK_THREADS">
<ttclass="descname">SIP_BLOCK_THREADS</tt><aclass="headerlink"href="#SIP_BLOCK_THREADS"title="Permalink to this definition">¶</a></dt>
<dd>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
<atitle="SIP_UNBLOCK_THREADS"class="reference internal"href="#SIP_UNBLOCK_THREADS"><ttclass="xref docutils literal"><spanclass="pre">SIP_UNBLOCK_THREADS</span></tt></a> at the same lexical scope.</dd></dl>
<dlclass="cmacro">
<dtid="SIP_NO_CONVERTORS">
<ttclass="descname">SIP_NO_CONVERTORS</tt><aclass="headerlink"href="#SIP_NO_CONVERTORS"title="Permalink to this definition">¶</a></dt>
<dd>This is a flag used by various type convertors that suppresses the use of a
<ttclass="descname">SIP_NOT_NONE</tt><aclass="headerlink"href="#SIP_NOT_NONE"title="Permalink to this definition">¶</a></dt>
<dd>This is a flag used by various type convertors that causes the conversion
to fail if the Python object being converted is <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt>.</dd></dl>
<dlclass="cmacro">
<dtid="SIP_PROTECTED_IS_PUBLIC">
<ttclass="descname">SIP_PROTECTED_IS_PUBLIC</tt><aclass="headerlink"href="#SIP_PROTECTED_IS_PUBLIC"title="Permalink to this definition">¶</a></dt>
<dd><p>
<spanclass="versionmodified">New in version 4.10.</span></p>
<p>This is a C preprocessor macro that is set automatically by the build
system to specify that the generated code is being compiled with
<ttclass="docutils literal"><spanclass="pre">protected</span></tt> redefined as <ttclass="docutils literal"><spanclass="pre">public</span></tt>. This allows handwritten code to
determine if the generated helper functions for accessing protected C++
functions are available (see <aclass="reference external"href="directives.html#directive-%MethodCode"><ttclass="xref docutils literal"><spanclass="pre">%MethodCode</span></tt></a>).</p>
</dd></dl>
<dlclass="cmacro">
<dtid="SIP_SSIZE_T">
<ttclass="descname">SIP_SSIZE_T</tt><aclass="headerlink"href="#SIP_SSIZE_T"title="Permalink to this definition">¶</a></dt>
<dd>This is a C preprocessor macro that is defined as <ttclass="docutils literal"><spanclass="pre">Py_ssize_t</span></tt> for Python
v2.5 and later, and as <ttclass="docutils literal"><spanclass="pre">int</span></tt> for earlier versions of Python. It makes it
easier to write PEP 353 compliant handwritten code.</dd></dl>
<dlclass="cmacro">
<dtid="SIP_UNBLOCK_THREADS">
<ttclass="descname">SIP_UNBLOCK_THREADS</tt><aclass="headerlink"href="#SIP_UNBLOCK_THREADS"title="Permalink to this definition">¶</a></dt>
<dd>This is a C preprocessor macro that will restore the Python Global
Interpreter Lock (GIL) to the state it was prior to the corresponding
sipErrorState <ttclass="descname">sipBadCallableArg</tt><big>(</big>int<em> arg_nr</em>, PyObject<em> *arg</em><big>)</big><aclass="headerlink"href="#sipBadCallableArg"title="Permalink to this definition">¶</a></dt>
<dd><p>
<spanclass="versionmodified">New in version 4.10.</span></p>
<p>This is called from <aclass="reference external"href="directives.html#directive-%MethodCode"><ttclass="xref docutils literal"><spanclass="pre">%MethodCode</span></tt></a> 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
<aclass="reference external"href="directives.html#directive-%MethodCode"><ttclass="xref docutils literal"><spanclass="pre">%MethodCode</span></tt></a> does additional type checking of the supplied
<li><em>arg_nr</em>– the number of the argument. Arguments are numbered from 0 but are
numbered from 1 in the detail of the exception.</li>
<li><em>arg</em>– the argument.</li>
</ul>
</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body"><pclass="first last">the value that should be assigned to <ttclass="docutils literal"><spanclass="pre">sipError</span></tt>.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="cfunction">
<dtid="sipBadCatcherResult">
void <ttclass="descname">sipBadCatcherResult</tt><big>(</big>PyObject<em> *method</em><big>)</big><aclass="headerlink"href="#sipBadCatcherResult"title="Permalink to this definition">¶</a></dt>
<dd><p>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 <aclass="reference external"href="directives.html#directive-%VirtualCatcherCode"><ttclass="xref docutils literal"><spanclass="pre">%VirtualCatcherCode</span></tt></a>
<trclass="field"><thclass="field-name">Parameter:</th><tdclass="field-body"><em>method</em>– the Python method and would normally be the supplied <ttclass="docutils literal"><spanclass="pre">sipMethod</span></tt>.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="cfunction">
<dtid="sipBadLengthForSlice">
void <ttclass="descname">sipBadLengthForSlice</tt><big>(</big><atitle="SIP_SSIZE_T"class="reference internal"href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> seqlen</em>, <atitle="SIP_SSIZE_T"class="reference internal"href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> slicelen</em><big>)</big><aclass="headerlink"href="#sipBadLengthForSlice"title="Permalink to this definition">¶</a></dt>
<dd><p>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 <ttclass="xref docutils literal"><spanclass="pre">__setitem__()</span></tt> methods.</p>
<trclass="field"><thclass="field-name">Parameters:</th><tdclass="field-body"><ulclass="first last simple">
<li><em>seqlen</em>– the length of the sequence.</li>
<li><em>slicelen</em>– the length of the slice.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="cfunction">
<dtid="sipBuildResult">
PyObject *<ttclass="descname">sipBuildResult</tt><big>(</big>int<em> *iserr</em>, const char<em> *format</em>, ...<big>)</big><aclass="headerlink"href="#sipBuildResult"title="Permalink to this definition">¶</a></dt>
<dd><p>This creates a Python object based on a format string and associated
values in a similar way to the Python <ttclass="xref docutils literal"><spanclass="pre">Py_BuildValue()</span></tt> function.</p>
<li><em>iserr</em>– if this is not <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> then the location it points to is set to a
non-zero value.</li>
<li><em>format</em>– the string of format characters.</li>
</ul>
</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body"><pclass="first last">If there was an error then <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> is returned and a Python exception
is raised.</p>
</td>
</tr>
</tbody>
</table>
<p>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.</p>
<p>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
<dd>Convert a C/C++ <ttclass="docutils literal"><spanclass="pre">long</span><spanclass="pre">long</span></tt> to a Python long.</dd>
<dt><ttclass="docutils literal"><spanclass="pre">o</span></tt> (long) [unsigned long long]</dt>
<dd>Convert a C/C++ <ttclass="docutils literal"><spanclass="pre">unsigned</span><spanclass="pre">long</span><spanclass="pre">long</span></tt> to a Python long.</dd>
is <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> then the result is <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt>.</dd>
<dd><pclass="first">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 <ttclass="docutils literal"><spanclass="pre">PyObject</span><spanclass="pre">*</span></tt> argument. If it is <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> and the instance has
already been wrapped then the ownership is unchanged. If it is
<ttclass="docutils literal"><spanclass="pre">NULL</span></tt> or <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt> then ownership will be with Python. Otherwise
ownership will be with C/C++ and the instance associated with the
<ttclass="docutils literal"><spanclass="pre">PyObject</span><spanclass="pre">*</span></tt> argument. The Python class is influenced by any
<dd><pclass="first">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 <ttclass="docutils literal"><spanclass="pre">PyObject</span><spanclass="pre">*</span></tt> argument. If it is <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> and the instance has
already been wrapped then the ownership is unchanged. If it is
<ttclass="docutils literal"><spanclass="pre">NULL</span></tt> and the instance is newly wrapped then ownership will be with
C/C++. If it is <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt> then ownership is transferred to Python
via a call to <atitle="sipTransferBack"class="reference internal"href="#sipTransferBack"><ttclass="xref docutils literal"><spanclass="pre">sipTransferBack()</span></tt></a>. Otherwise ownership is
transferred to C/C++ and the instance associated with the
<ttclass="docutils literal"><spanclass="pre">PyObject</span><spanclass="pre">*</span></tt> argument via a call to <atitle="sipTransferTo"class="reference internal"href="#sipTransferTo"><ttclass="xref docutils literal"><spanclass="pre">sipTransferTo()</span></tt></a>. The
<dd>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 <ttclass="docutils literal"><spanclass="pre">PyObject</span><spanclass="pre">*</span></tt> argument. If it is <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> and the
instance has already been wrapped then the ownership is unchanged. If
it is <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> and the instance is newly wrapped then ownership will be
with C/C++. If it is <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt> then ownership is transferred to
Python via a call to <atitle="sipTransferBack"class="reference internal"href="#sipTransferBack"><ttclass="xref docutils literal"><spanclass="pre">sipTransferBack()</span></tt></a>. Otherwise ownership
is transferred to C/C++ and the instance associated with the
<ttclass="docutils literal"><spanclass="pre">PyObject</span><spanclass="pre">*</span></tt> argument via a call to <atitle="sipTransferTo"class="reference internal"href="#sipTransferTo"><ttclass="xref docutils literal"><spanclass="pre">sipTransferTo()</span></tt></a>. The
<dd>Convert a new C structure, C++ class or mapped type instance to a
Python object. Ownership of the instance is determined by the
<ttclass="docutils literal"><spanclass="pre">PyObject</span><spanclass="pre">*</span></tt> argument. If it is <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> and the instance has
already been wrapped then the ownership is unchanged. If it is
<ttclass="docutils literal"><spanclass="pre">NULL</span></tt> or <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt> then ownership will be with Python. Otherwise
ownership will be with C/C++ and the instance associated with the
<ttclass="docutils literal"><spanclass="pre">PyObject</span><spanclass="pre">*</span></tt> argument. The Python class is influenced by any
<li><em>iserr</em>– if this is not <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> then the location it points to is set to a
non-zero value if there was an error.</li>
<li><em>method</em>– the Python bound method to call.</li>
<li><em>format</em>– the string of format characters (see <atitle="sipBuildResult"class="reference internal"href="#sipBuildResult"><ttclass="xref docutils literal"><spanclass="pre">sipBuildResult()</span></tt></a>).</li>
</ul>
</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body"><pclass="first last">If there was an error then <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> is returned and a Python exception
is raised.</p>
</td>
</tr>
</tbody>
</table>
<p>It is normally called by handwritten code specified with the
<aclass="reference external"href="directives.html#directive-%VirtualCatcherCode"><ttclass="xref docutils literal"><spanclass="pre">%VirtualCatcherCode</span></tt></a> directive with method being the supplied
int <ttclass="descname">sipCanConvertToEnum</tt><big>(</big>PyObject<em> *obj</em>, const sipTypeDef<em> *td</em><big>)</big><aclass="headerlink"href="#sipCanConvertToEnum"title="Permalink to this definition">¶</a></dt>
<dd><p>This checks if a Python object can be converted to a named enum.</p>
<li><em>td</em>– the enum’s <aclass="reference internal"href="#ref-type-structures"><em>generated type structure</em></a>.</li>
</ul>
</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body"><pclass="first last">a non-zero value if the object can be converted.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="cfunction">
<dtid="sipCanConvertToInstance">
int <ttclass="descname">sipCanConvertToInstance</tt><big>(</big>PyObject<em> *obj</em>, <atitle="sipWrapperType"class="reference internal"href="#sipWrapperType">sipWrapperType</a><em> *type</em>, int<em> flags</em><big>)</big><aclass="headerlink"href="#sipCanConvertToInstance"title="Permalink to this definition">¶</a></dt>
<dd><p>This checks if a Python object can be converted to an instance of a C
<li><em>type</em>– the C/C++ type’s <aclass="reference internal"href="#ref-type-objects"><em>generated type object</em></a>.</li>
<li><em>flags</em>– any combination of the <atitle="SIP_NOT_NONE"class="reference internal"href="#SIP_NOT_NONE"><ttclass="xref docutils literal"><spanclass="pre">SIP_NOT_NONE</span></tt></a> and
int <ttclass="descname">sipCanConvertToMappedType</tt><big>(</big>PyObject<em> *obj</em>, const sipMappedType<em> *mt</em>, int<em> flags</em><big>)</big><aclass="headerlink"href="#sipCanConvertToMappedType"title="Permalink to this definition">¶</a></dt>
<dd><p>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.</p>
<li><em>mt</em>– the opaque structure returned by <atitle="sipFindMappedType"class="reference internal"href="#sipFindMappedType"><ttclass="xref docutils literal"><spanclass="pre">sipFindMappedType()</span></tt></a>.</li>
<li><em>flags</em>– this may be the <atitle="SIP_NOT_NONE"class="reference internal"href="#SIP_NOT_NONE"><ttclass="xref docutils literal"><spanclass="pre">SIP_NOT_NONE</span></tt></a> flag.</li>
</ul>
</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body"><pclass="first last">a non-zero value if the object can be converted.</p>
</td>
</tr>
</tbody>
</table>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">This is deprecated from SIP v4.8. Instead you should use
int <ttclass="descname">sipCanConvertToType</tt><big>(</big>PyObject<em> *obj</em>, const sipTypeDef<em> *td</em>, int<em> flags</em><big>)</big><aclass="headerlink"href="#sipCanConvertToType"title="Permalink to this definition">¶</a></dt>
<dd><p>This checks if a Python object can be converted to an instance of a C
<li><em>td</em>– the C/C++ type’s <aclass="reference internal"href="#ref-type-structures"><em>generated type structure</em></a>.</li>
<li><em>flags</em>– any combination of the <atitle="SIP_NOT_NONE"class="reference internal"href="#SIP_NOT_NONE"><ttclass="xref docutils literal"><spanclass="pre">SIP_NOT_NONE</span></tt></a> and
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body"><pclass="first last">a non-zero value if the object can be converted.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="cfunction">
<dtid="sipClassName">
PyObject *<ttclass="descname">sipClassName</tt><big>(</big>PyObject<em> *obj</em><big>)</big><aclass="headerlink"href="#sipClassName"title="Permalink to this definition">¶</a></dt>
<dd><p>This gets the class name of a wrapped instance as a Python string. It
PyObject *<ttclass="descname">sipConvertFromConstVoidPtr</tt><big>(</big>const void<em> *cpp</em><big>)</big><aclass="headerlink"href="#sipConvertFromConstVoidPtr"title="Permalink to this definition">¶</a></dt>
<dd><p>This creates a <atitle="sip.voidptr"class="reference external"href="python_api.html#sip.voidptr"><ttclass="xref docutils literal"><spanclass="pre">sip.voidptr</span></tt></a> object for a memory address. The
object will not be writeable and has no associated size.</p>
PyObject *<ttclass="descname">sipConvertFromConstVoidPtrAndSize</tt><big>(</big>const void<em> *cpp</em>, <atitle="SIP_SSIZE_T"class="reference internal"href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> size</em><big>)</big><aclass="headerlink"href="#sipConvertFromConstVoidPtrAndSize"title="Permalink to this definition">¶</a></dt>
<dd><p>This creates a <atitle="sip.voidptr"class="reference external"href="python_api.html#sip.voidptr"><ttclass="xref docutils literal"><spanclass="pre">sip.voidptr</span></tt></a> object for a memory address. The
object will not be writeable and can be used as an immutable buffer object.</p>
PyObject *<ttclass="descname">sipConvertFromEnum</tt><big>(</big>int<em> eval</em>, const sipTypeDef<em> *td</em><big>)</big><aclass="headerlink"href="#sipConvertFromEnum"title="Permalink to this definition">¶</a></dt>
<dd><p>This converts a named C/C++ <ttclass="docutils literal"><spanclass="pre">enum</span></tt> to an instance of the corresponding
<p>If the C/C++ instance has already been wrapped then the result is a
new reference to the existing class instance object.</p>
<p>If <em>transferObj</em> is <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> and the instance has already been wrapped then
the ownership is unchanged.</p>
<p>If <em>transferObj</em> is <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> and the instance is newly wrapped then
ownership will be with C/C++.</p>
<p>If <em>transferObj</em> is <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt> then ownership is transferred to Python via
a call to <atitle="sipTransferBack"class="reference internal"href="#sipTransferBack"><ttclass="xref docutils literal"><spanclass="pre">sipTransferBack()</span></tt></a>.</p>
<p>Otherwise ownership is transferred to C/C++ and the instance associated
with <em>transferObj</em> via a call to <atitle="sipTransferTo"class="reference internal"href="#sipTransferTo"><ttclass="xref docutils literal"><spanclass="pre">sipTransferTo()</span></tt></a>.</p>
<p>The Python type is influenced by any applicable
<li><em>mt</em>– the opaque structure returned by <atitle="sipFindMappedType"class="reference internal"href="#sipFindMappedType"><ttclass="xref docutils literal"><spanclass="pre">sipFindMappedType()</span></tt></a>.</li>
<li><em>transferObj</em>– this controls the ownership of the returned value.</li>
<p>If <em>transferObj</em> is <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> then the ownership is unchanged.</p>
<p>If <em>transferObj</em> is <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt> then ownership is transferred to Python
via a call to <atitle="sipTransferBack"class="reference internal"href="#sipTransferBack"><ttclass="xref docutils literal"><spanclass="pre">sipTransferBack()</span></tt></a>.</p>
<p>Otherwise ownership is transferred to C/C++ and the instance associated
with <em>transferObj</em> argument via a call to <atitle="sipTransferTo"class="reference internal"href="#sipTransferTo"><ttclass="xref docutils literal"><spanclass="pre">sipTransferTo()</span></tt></a>.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">This is deprecated from SIP v4.8. Instead you should use
PyObject *<ttclass="descname">sipConvertFromNamedEnum</tt><big>(</big>int<em> eval</em>, PyTypeObject<em> *type</em><big>)</big><aclass="headerlink"href="#sipConvertFromNamedEnum"title="Permalink to this definition">¶</a></dt>
<dd><p>This converts a named C/C++ <ttclass="docutils literal"><spanclass="pre">enum</span></tt> to an instance of the corresponding
<p>If <em>transferObj</em> is <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> or <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt> then ownership will be with
Python.</p>
<p>Otherwise ownership will be with C/C++ and the instance associated with
<em>transferObj</em>.</p>
<p>The Python type is influenced by any applicable
<p>If <em>transferObj</em> is <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> or <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt> then ownership will be with
Python.</p>
<p>Otherwise ownership will be with C/C++ and the instance associated with
<em>transferObj</em>.</p>
<p>The Python type is influenced by any applicable
<atitle="SIP_SSIZE_T"class="reference internal"href="#SIP_SSIZE_T">SIP_SSIZE_T</a><ttclass="descname">sipConvertFromSequenceIndex</tt><big>(</big><atitle="SIP_SSIZE_T"class="reference internal"href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> idx</em>, <atitle="SIP_SSIZE_T"class="reference internal"href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> len</em><big>)</big><aclass="headerlink"href="#sipConvertFromSequenceIndex"title="Permalink to this definition">¶</a></dt>
<dd><p>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
<p>If the C/C++ instance has already been wrapped then the result is a new
reference to the existing object.</p>
<p>If <em>transferObj</em> is <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> and the instance has already been wrapped then
the ownership is unchanged.</p>
<p>If <em>transferObj</em> is <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> and the instance is newly wrapped then
ownership will be with C/C++.</p>
<p>If <em>transferObj</em> is <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt> then ownership is transferred to Python via
a call to <atitle="sipTransferBack"class="reference internal"href="#sipTransferBack"><ttclass="xref docutils literal"><spanclass="pre">sipTransferBack()</span></tt></a>.</p>
<p>Otherwise ownership is transferred to C/C++ and the instance associated
with <em>transferObj</em> via a call to <atitle="sipTransferTo"class="reference internal"href="#sipTransferTo"><ttclass="xref docutils literal"><spanclass="pre">sipTransferTo()</span></tt></a>.</p>
<p>The Python class is influenced by any applicable
PyObject *<ttclass="descname">sipConvertFromVoidPtr</tt><big>(</big>void<em> *cpp</em><big>)</big><aclass="headerlink"href="#sipConvertFromVoidPtr"title="Permalink to this definition">¶</a></dt>
<dd><p>This creates a <atitle="sip.voidptr"class="reference external"href="python_api.html#sip.voidptr"><ttclass="xref docutils literal"><spanclass="pre">sip.voidptr</span></tt></a> object for a memory address. The
object will be writeable but has no associated size.</p>
PyObject *<ttclass="descname">sipConvertFromVoidPtrAndSize</tt><big>(</big>void<em> *cpp</em>, <atitle="SIP_SSIZE_T"class="reference internal"href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> size</em><big>)</big><aclass="headerlink"href="#sipConvertFromVoidPtrAndSize"title="Permalink to this definition">¶</a></dt>
<dd><p>This creates a <atitle="sip.voidptr"class="reference external"href="python_api.html#sip.voidptr"><ttclass="xref docutils literal"><spanclass="pre">sip.voidptr</span></tt></a> object for a memory address. The
object will be writeable and can be used as a mutable buffer object.</p>
void *<ttclass="descname">sipConvertToInstance</tt><big>(</big>PyObject<em> *obj</em>, <atitle="sipWrapperType"class="reference internal"href="#sipWrapperType">sipWrapperType</a><em> *type</em>, PyObject<em> *transferObj</em>, int<em> flags</em>, int<em> *state</em>, int<em> *iserr</em><big>)</big><aclass="headerlink"href="#sipConvertToInstance"title="Permalink to this definition">¶</a></dt>
<dd><p>This converts a Python object to an instance of a C structure or C++ class
assuming that a previous call to <atitle="sipCanConvertToInstance"class="reference internal"href="#sipCanConvertToInstance"><ttclass="xref docutils literal"><spanclass="pre">sipCanConvertToInstance()</span></tt></a> has
<li><em>type</em>– the type’s <aclass="reference internal"href="#ref-type-objects"><em>generated type object</em></a>.</li>
<li><em>transferObj</em>– this controls any ownership changes to <em>obj</em>.</li>
<li><em>flags</em>– any combination of the <atitle="SIP_NOT_NONE"class="reference internal"href="#SIP_NOT_NONE"><ttclass="xref docutils literal"><spanclass="pre">SIP_NOT_NONE</span></tt></a> and
<p>If <em>transferObj</em> is <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> then the ownership is unchanged.</p>
<p>If <em>transferObj</em> is <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt> then ownership is transferred to Python via
a call to <atitle="sipTransferBack"class="reference internal"href="#sipTransferBack"><ttclass="xref docutils literal"><spanclass="pre">sipTransferBack()</span></tt></a>.</p>
<p>Otherwise ownership is transferred to C/C++ and <em>obj</em> associated with
<em>transferObj</em> via a call to <atitle="sipTransferTo"class="reference internal"href="#sipTransferTo"><ttclass="xref docutils literal"><spanclass="pre">sipTransferTo()</span></tt></a>.</p>
<p>If <em>state</em> is not <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> 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 <aclass="reference external"href="directives.html#directive-%ConvertToTypeCode"><ttclass="xref docutils literal"><spanclass="pre">%ConvertToTypeCode</span></tt></a>. The calling code must then release
the value at some point to prevent a memory leak by calling
void *<ttclass="descname">sipConvertToMappedType</tt><big>(</big>PyObject<em> *obj</em>, const sipMappedType<em> *mt</em>, PyObject<em> *transferObj</em>, int<em> flags</em>, int<em> *state</em>, int<em> *iserr</em><big>)</big><aclass="headerlink"href="#sipConvertToMappedType"title="Permalink to this definition">¶</a></dt>
<dd><p>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
<atitle="sipCanConvertToMappedType"class="reference internal"href="#sipCanConvertToMappedType"><ttclass="xref docutils literal"><spanclass="pre">sipCanConvertToMappedType()</span></tt></a> has been successful.</p>
<li><em>mt</em>– the opaque structure returned by <atitle="sipFindMappedType"class="reference internal"href="#sipFindMappedType"><ttclass="xref docutils literal"><spanclass="pre">sipFindMappedType()</span></tt></a>.</li>
<li><em>transferObj</em>– this controls any ownership changes to <em>obj</em>.</li>
<li><em>flags</em>– this may be the <atitle="SIP_NOT_NONE"class="reference internal"href="#SIP_NOT_NONE"><ttclass="xref docutils literal"><spanclass="pre">SIP_NOT_NONE</span></tt></a> flag.</li>
<li><em>state</em>– the state of the returned C/C++ instance is returned via this pointer.</li>
<li><em>iserr</em>– the error flag is passed and updated via this pointer.</li>
<p>If <em>transferObj</em> is <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> then the ownership is unchanged.</p>
<p>If <em>transferObj</em> is <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt> then ownership is transferred to Python via
a call to <atitle="sipTransferBack"class="reference internal"href="#sipTransferBack"><ttclass="xref docutils literal"><spanclass="pre">sipTransferBack()</span></tt></a>.</p>
<p>Otherwise ownership is transferred to C/C++ and <em>obj</em> associated with
<em>transferObj</em> via a call to <atitle="sipTransferTo"class="reference internal"href="#sipTransferTo"><ttclass="xref docutils literal"><spanclass="pre">sipTransferTo()</span></tt></a>.</p>
<p>If <em>state</em> is not <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> 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 <aclass="reference external"href="directives.html#directive-%ConvertToTypeCode"><ttclass="xref docutils literal"><spanclass="pre">%ConvertToTypeCode</span></tt></a>. The calling code must then release
the value at some point to prevent a memory leak by calling
void *<ttclass="descname">sipConvertToType</tt><big>(</big>PyObject<em> *obj</em>, const sipTypeDef<em> *td</em>, PyObject<em> *transferObj</em>, int<em> flags</em>, int<em> *state</em>, int<em> *iserr</em><big>)</big><aclass="headerlink"href="#sipConvertToType"title="Permalink to this definition">¶</a></dt>
<dd><p>This converts a Python object to an instance of a C structure, C++ class or
mapped type assuming that a previous call to <atitle="sipCanConvertToType"class="reference internal"href="#sipCanConvertToType"><ttclass="xref docutils literal"><spanclass="pre">sipCanConvertToType()</span></tt></a>
<li><em>td</em>– the type’s <aclass="reference internal"href="#ref-type-structures"><em>generated type structure</em></a>.</li>
<li><em>transferObj</em>– this controls any ownership changes to <em>obj</em>.</li>
<li><em>flags</em>– any combination of the <atitle="SIP_NOT_NONE"class="reference internal"href="#SIP_NOT_NONE"><ttclass="xref docutils literal"><spanclass="pre">SIP_NOT_NONE</span></tt></a> and
<p>Otherwise ownership is transferred to C/C++ and <em>obj</em> associated with
<em>transferObj</em> via a call to <atitle="sipTransferTo"class="reference internal"href="#sipTransferTo"><ttclass="xref docutils literal"><spanclass="pre">sipTransferTo()</span></tt></a>.</p>
<p>If <em>state</em> is not <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> 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 <aclass="reference external"href="directives.html#directive-%ConvertToTypeCode"><ttclass="xref docutils literal"><spanclass="pre">%ConvertToTypeCode</span></tt></a>. The calling code must then release
the value at some point to prevent a memory leak by calling
<p>If there is an error then the location <em>iserr</em> 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.)</p>
</dd></dl>
<dlclass="cfunction">
<dtid="sipConvertToVoidPtr">
void *<ttclass="descname">sipConvertToVoidPtr</tt><big>(</big>PyObject<em> *obj</em><big>)</big><aclass="headerlink"href="#sipConvertToVoidPtr"title="Permalink to this definition">¶</a></dt>
<dd><p>This converts a Python object to a memory address.
<ttclass="xref docutils literal"><spanclass="pre">PyErr_Occurred()</span></tt> must be used to determine if the conversion was
<trclass="field"><thclass="field-name">Parameter:</th><tdclass="field-body"><em>obj</em>– the Python object which may be <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt>, a <atitle="sip.voidptr"class="reference external"href="python_api.html#sip.voidptr"><ttclass="xref docutils literal"><spanclass="pre">sip.voidptr</span></tt></a> or a
int <ttclass="descname">sipExportSymbol</tt><big>(</big>const char<em> *name</em>, void<em> *sym</em><big>)</big><aclass="headerlink"href="#sipExportSymbol"title="Permalink to this definition">¶</a></dt>
<dd><p>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 <atitle="sipImportSymbol"class="reference internal"href="#sipImportSymbol"><ttclass="xref docutils literal"><spanclass="pre">sipImportSymbol()</span></tt></a>, by
<li><em>name</em>– the name of the symbol.</li>
<li><em>sym</em>– the value of the symbol.</li>
</ul>
</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body"><pclass="first last">0 if there was no error. A negative value is returned if <em>name</em> is
already associated with a symbol or there was some other error.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="cfunction">
<dtid="sipFindClass">
<atitle="sipWrapperType"class="reference internal"href="#sipWrapperType">sipWrapperType</a> *<ttclass="descname">sipFindClass</tt><big>(</big>const char<em> *type</em><big>)</big><aclass="headerlink"href="#sipFindClass"title="Permalink to this definition">¶</a></dt>
<dd><p>This returns a pointer to the <aclass="reference internal"href="#ref-type-objects"><em>generated type object
const sipMappedType *<ttclass="descname">sipFindMappedType</tt><big>(</big>const char<em> *type</em><big>)</big><aclass="headerlink"href="#sipFindMappedType"title="Permalink to this definition">¶</a></dt>
<dd><p>This returns a pointer to an opaque structure describing a mapped type.</p>
PyTypeObject *<ttclass="descname">sipFindNamedEnum</tt><big>(</big>const char<em> *type</em><big>)</big><aclass="headerlink"href="#sipFindNamedEnum"title="Permalink to this definition">¶</a></dt>
<dd><p>This returns a pointer to the <aclass="reference internal"href="#ref-enum-type-objects"><em>generated Python type object</em></a> corresponding to a named C/C++ enum.</p>
const sipTypeDef *<ttclass="descname">sipFindType</tt><big>(</big>const char<em> *type</em><big>)</big><aclass="headerlink"href="#sipFindType"title="Permalink to this definition">¶</a></dt>
<dd><p>This returns a pointer to the <aclass="reference internal"href="#ref-type-structures"><em>generated type structure</em></a> corresponding to a C/C++ type.</p>
<trclass="field"><thclass="field-name">Parameter:</th><tdclass="field-body"><em>type</em>– the C/C++ declaration of the type.</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">the generated type structure. This will not change and may be saved in
a static cache. <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> is returned if the C/C++ type doesn’t exist.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="cfunction">
<dtid="sipForceConvertToInstance">
void *<ttclass="descname">sipForceConvertToInstance</tt><big>(</big>PyObject<em> *obj</em>, <atitle="sipWrapperType"class="reference internal"href="#sipWrapperType">sipWrapperType</a><em> *type</em>, PyObject<em> *transferObj</em>, int<em> flags</em>, int<em> *state</em>, int<em> *iserr</em><big>)</big><aclass="headerlink"href="#sipForceConvertToInstance"title="Permalink to this definition">¶</a></dt>
<dd><p>This converts a Python object to an instance of a C structure or C++ class
by calling <atitle="sipCanConvertToInstance"class="reference internal"href="#sipCanConvertToInstance"><ttclass="xref docutils literal"><spanclass="pre">sipCanConvertToInstance()</span></tt></a> and, if it is successfull,
<p>See <atitle="sipConvertToInstance"class="reference internal"href="#sipConvertToInstance"><ttclass="xref docutils literal"><spanclass="pre">sipConvertToInstance()</span></tt></a> for a full description of the
arguments.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">This is deprecated from SIP v4.8. Instead you should use
void *<ttclass="descname">sipForceConvertToMappedType</tt><big>(</big>PyObject<em> *obj</em>, const sipMappedType<em> *mt</em>, PyObject<em> *transferObj</em>, int<em> flags</em>, int<em> *state</em>, int<em> *iserr</em><big>)</big><aclass="headerlink"href="#sipForceConvertToMappedType"title="Permalink to this definition">¶</a></dt>
<dd><p>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
<atitle="sipCanConvertToMappedType"class="reference internal"href="#sipCanConvertToMappedType"><ttclass="xref docutils literal"><spanclass="pre">sipCanConvertToMappedType()</span></tt></a> and, if it is successfull, calling
<p>See <atitle="sipConvertToMappedType"class="reference internal"href="#sipConvertToMappedType"><ttclass="xref docutils literal"><spanclass="pre">sipConvertToMappedType()</span></tt></a> for a full description of the
arguments.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">This is deprecated from SIP v4.8. Instead you should use
void *<ttclass="descname">sipForceConvertToType</tt><big>(</big>PyObject<em> *obj</em>, const sipTypeDef<em> *td</em>, PyObject<em> *transferObj</em>, int<em> flags</em>, int<em> *state</em>, int<em> *iserr</em><big>)</big><aclass="headerlink"href="#sipForceConvertToType"title="Permalink to this definition">¶</a></dt>
<dd><p>This converts a Python object to an instance of a C structure, C++ class or
mapped type by calling <atitle="sipCanConvertToType"class="reference internal"href="#sipCanConvertToType"><ttclass="xref docutils literal"><spanclass="pre">sipCanConvertToType()</span></tt></a> and, if it is
<p>See <atitle="sipConvertToType"class="reference internal"href="#sipConvertToType"><ttclass="xref docutils literal"><spanclass="pre">sipConvertToType()</span></tt></a> for a full description of the arguments.</p>
</dd></dl>
<dlclass="cfunction">
<dtid="sipFree">
void <ttclass="descname">sipFree</tt><big>(</big>void<em> *mem</em><big>)</big><aclass="headerlink"href="#sipFree"title="Permalink to this definition">¶</a></dt>
<dd><p>This returns an area of memory allocated by <atitle="sipMalloc"class="reference internal"href="#sipMalloc"><ttclass="xref docutils literal"><spanclass="pre">sipMalloc()</span></tt></a> to the
<trclass="field"><thclass="field-name">Parameter:</th><tdclass="field-body"><em>mem</em>– the memory address.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="cfunction">
<dtid="sipGetPyObject">
PyObject *<ttclass="descname">sipGetPyObject</tt><big>(</big>void<em> *cppptr</em>, const sipTypeDef<em> *td</em><big>)</big><aclass="headerlink"href="#sipGetPyObject"title="Permalink to this definition">¶</a></dt>
<dd><p>This returns a borrowed reference to the Python object for a C structure or
<li><em>cppptr</em>– the pointer to the C/C++ instance.</li>
<li><em>td</em>– the <aclass="reference internal"href="#ref-type-structures"><em>generated type structure</em></a> corresponding
to the C/C++ type.</li>
</ul>
</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body"><pclass="first last">the Python object or <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> (and no exception is raised) if the
C/C++ instance hasn’t been wrapped.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="cfunction">
<dtid="sipGetState">
int <ttclass="descname">sipGetState</tt><big>(</big>PyObject<em> *transferObj</em><big>)</big><aclass="headerlink"href="#sipGetState"title="Permalink to this definition">¶</a></dt>
<dd><p>The <aclass="reference external"href="directives.html#directive-%ConvertToTypeCode"><ttclass="xref docutils literal"><spanclass="pre">%ConvertToTypeCode</span></tt></a> directive requires that the provided
code returns an <ttclass="docutils literal"><spanclass="pre">int</span></tt> 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
<trclass="field"><thclass="field-name">Parameter:</th><tdclass="field-body"><em>transferObj</em>– the object that describes the requested transfer of ownership.</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">the state of the converted value.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="cfunction">
<dtid="sipGetWrapper">
PyObject *<ttclass="descname">sipGetWrapper</tt><big>(</big>void<em> *cppptr</em>, <atitle="sipWrapperType"class="reference internal"href="#sipWrapperType">sipWrapperType</a><em> *type</em><big>)</big><aclass="headerlink"href="#sipGetWrapper"title="Permalink to this definition">¶</a></dt>
<dd><p>This returns a borrowed reference to the wrapped instance object for a C
<li><em>cppptr</em>– the pointer to the C/C++ instance.</li>
<li><em>type</em>– the <aclass="reference internal"href="#ref-type-objects"><em>generated type object</em></a> corresponding to
the C/C++ type.</li>
</ul>
</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body"><pclass="first last">the Python object or <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> (and no exception is raised) if the
C/C++ instance hasn’t been wrapped.</p>
</td>
</tr>
</tbody>
</table>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">This is deprecated from SIP v4.8. Instead you should use
void *<ttclass="descname">sipImportSymbol</tt><big>(</big>const char<em> *name</em><big>)</big><aclass="headerlink"href="#sipImportSymbol"title="Permalink to this definition">¶</a></dt>
<dd><p>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 <atitle="sipExportSymbol"class="reference internal"href="#sipExportSymbol"><ttclass="xref docutils literal"><spanclass="pre">sipExportSymbol()</span></tt></a>, by
<trclass="field"><thclass="field-name">Parameter:</th><tdclass="field-body"><em>name</em>– the name of the symbol.</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">the value of the symbol. <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> is returned if there is no such
symbol.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="ctype">
<dtid="sipIntTypeClassMap">
<ttclass="descname">sipIntTypeClassMap</tt><aclass="headerlink"href="#sipIntTypeClassMap"title="Permalink to this definition">¶</a></dt>
<dd><p>This C structure is used with <atitle="sipMapIntToClass"class="reference internal"href="#sipMapIntToClass"><ttclass="xref docutils literal"><spanclass="pre">sipMapIntToClass()</span></tt></a> to define a
mapping between integer based RTTI and <aclass="reference internal"href="#ref-type-objects"><em>generated type objects</em></a>. The structure elements are as follows.</p>
<dlclass="cmember">
<dtid="typeInt">
int <ttclass="descname">typeInt</tt><aclass="headerlink"href="#typeInt"title="Permalink to this definition">¶</a></dt>
<dd>A pointer to the corresponding generated type object.</dd></dl>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">This is deprecated from SIP v4.8.</p>
</div>
</dd></dl>
<dlclass="cfunction">
<dtid="sipIsAPIEnabled">
int <ttclass="descname">sipIsAPIEnabled</tt><big>(</big>const char<em> *name</em>, int<em> from</em>, int<em> to</em><big>)</big><aclass="headerlink"href="#sipIsAPIEnabled"title="Permalink to this definition">¶</a></dt>
<dd><p>
<spanclass="versionmodified">New in version 4.9.</span></p>
<p>This checks to see if the current version number of an API falls within a
given range. See <aclass="reference external"href="using.html#ref-incompat-apis"><em>Managing Incompatible APIs</em></a> for more detail.</p>
<li><em>name</em>– the name of the API.</li>
<li><em>from</em>– the lower bound of the range. For the API to be enabled its version
number must be greater than or equal to <em>from</em>. If <em>from</em> is 0 then
this check isn’t made.</li>
<li><em>to</em>– the upper bound of the range. For the API to be enabled its version
number must be less than <em>to</em>. If <em>to</em> is 0 then this check isn’t
made.</li>
</ul>
</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body"><pclass="first last">a non-zero value if the API is enabled.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="cfunction">
<dtid="sipLong_AsUnsignedLong">
unsigned long <ttclass="descname">sipLong_AsUnsignedLong</tt><big>(</big>PyObject<em> *obj</em><big>)</big><aclass="headerlink"href="#sipLong_AsUnsignedLong"title="Permalink to this definition">¶</a></dt>
<dd>This function is a thin wrapper around <ttclass="xref docutils literal"><spanclass="pre">PyLong_AsUnsignedLong()</span></tt>
that works around a bug in Python v2.3.x and earlier when converting
integer objects.</dd></dl>
<dlclass="cfunction">
<dtid="sipMalloc">
void *<ttclass="descname">sipMalloc</tt><big>(</big>size_t<em> nbytes</em><big>)</big><aclass="headerlink"href="#sipMalloc"title="Permalink to this definition">¶</a></dt>
<dd><p>This allocates an area of memory on the heap using the Python
<ttclass="xref docutils literal"><spanclass="pre">PyMem_Malloc()</span></tt> function. The memory is freed by calling
<trclass="field"><thclass="field-name">Parameter:</th><tdclass="field-body"><em>nbytes</em>– the number of bytes to allocate.</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">the memory address. If there was an error then <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> is returned
and a Python exception raised.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="cfunction">
<dtid="sipMapIntToClass">
<atitle="sipWrapperType"class="reference internal"href="#sipWrapperType">sipWrapperType</a> *<ttclass="descname">sipMapIntToClass</tt><big>(</big>int<em> type</em>, const <atitle="sipIntTypeClassMap"class="reference internal"href="#sipIntTypeClassMap">sipIntTypeClassMap</a><em> *map</em>, int<em> maplen</em><big>)</big><aclass="headerlink"href="#sipMapIntToClass"title="Permalink to this definition">¶</a></dt>
<dd><p>This can be used in <aclass="reference external"href="directives.html#directive-%ConvertToSubClassCode"><ttclass="xref docutils literal"><spanclass="pre">%ConvertToSubClassCode</span></tt></a> code as a
convenient way of converting integer based RTTI to the corresponding
<aclass="reference internal"href="#ref-type-objects"><em>generated type object</em></a>.</p>
<li><em>map</em>– the table of known RTTI and the corresponding type objects (see
<atitle="sipIntTypeClassMap"class="reference internal"href="#sipIntTypeClassMap"><ttclass="xref docutils literal"><spanclass="pre">sipIntTypeClassMap</span></tt></a>). The entries in the table must be sorted
in ascending order of RTTI.</li>
<li><em>maplen</em>– the number of entries in the table.</li>
</ul>
</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body"><pclass="first last">the corresponding type object, or <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> if <em>type</em> wasn’t in <em>map</em>.</p>
</td>
</tr>
</tbody>
</table>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">This is deprecated from SIP v4.8.</p>
</div>
</dd></dl>
<dlclass="cfunction">
<dtid="sipMapStringToClass">
<atitle="sipWrapperType"class="reference internal"href="#sipWrapperType">sipWrapperType</a> *<ttclass="descname">sipMapStringToClass</tt><big>(</big>char<em> *type</em>, const <atitle="sipStringTypeClassMap"class="reference internal"href="#sipStringTypeClassMap">sipStringTypeClassMap</a><em> *map</em>, int<em> maplen</em><big>)</big><aclass="headerlink"href="#sipMapStringToClass"title="Permalink to this definition">¶</a></dt>
<dd><p>This can be used in <aclass="reference external"href="directives.html#directive-%ConvertToSubClassCode"><ttclass="xref docutils literal"><spanclass="pre">%ConvertToSubClassCode</span></tt></a> code as a
convenient way of converting <ttclass="docutils literal"><spanclass="pre">'\0'</span></tt> terminated string based RTTI to the
corresponding <aclass="reference internal"href="#ref-type-objects"><em>generated type object</em></a>.</p>
<li><em>map</em>– the table of known RTTI and the corresponding type objects (see
<atitle="sipStringTypeClassMap"class="reference internal"href="#sipStringTypeClassMap"><ttclass="xref docutils literal"><spanclass="pre">sipStringTypeClassMap</span></tt></a>). The entries in the table must be
sorted in ascending order of RTTI.</li>
<li><em>maplen</em>– the number of entries in the table.</li>
</ul>
</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body"><pclass="first last">the corresponding type object, or <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> if <em>type</em> wasn’t in <em>map</em>.</p>
</td>
</tr>
</tbody>
</table>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">This is deprecated from SIP v4.8.</p>
</div>
</dd></dl>
<dlclass="cfunction">
<dtid="sipParseResult">
int <ttclass="descname">sipParseResult</tt><big>(</big>int<em> *iserr</em>, PyObject<em> *method</em>, PyObject<em> *result</em>, const char<em> *format</em>, ...<big>)</big><aclass="headerlink"href="#sipParseResult"title="Permalink to this definition">¶</a></dt>
<dd><p>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
<li><em>iserr</em>– if this is not <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> then the location it points to is set to a
non-zero value if there was an error.</li>
<li><em>method</em>– the Python method that returned <em>result</em>.</li>
<li><em>result</em>– the Python object returned by <em>method</em>.</li>
<li><em>format</em>– the format string.</li>
</ul>
</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body"><pclass="first last">0 if there was no error. Otherwise a negative value is returned, and
an exception raised.</p>
</td>
</tr>
</tbody>
</table>
<p>This is normally called by handwritten code specified with the
<aclass="reference external"href="directives.html#directive-%VirtualCatcherCode"><ttclass="xref docutils literal"><spanclass="pre">%VirtualCatcherCode</span></tt></a> directive with <em>method</em> being the supplied
<ttclass="docutils literal"><spanclass="pre">sipMethod</span></tt> and <em>result</em> being the value returned by
<dd>Convert a Python string-like object of length 1 to a C/C++ <ttclass="docutils literal"><spanclass="pre">char</span></tt>
according to the encoding <ttclass="docutils literal"><spanclass="pre">e</span></tt>. <ttclass="docutils literal"><spanclass="pre">e</span></tt> can either be <ttclass="docutils literal"><spanclass="pre">A</span></tt> for ASCII,
<ttclass="docutils literal"><spanclass="pre">L</span></tt> for Latin-1, or <ttclass="docutils literal"><spanclass="pre">8</span></tt> for UTF-8. For Python v2 the object may be
<dd>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
<ttclass="docutils literal"><spanclass="pre">Py_None</span></tt> then the array and length are <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> and zero
<dd>Convert a Python long to a C/C++ <ttclass="docutils literal"><spanclass="pre">long</span></tt>.</dd>
<dt><ttclass="docutils literal"><spanclass="pre">m</span></tt> (long) [unsigned long *]</dt>
<dd>Convert a Python long to a C/C++ <ttclass="docutils literal"><spanclass="pre">unsigned</span><spanclass="pre">long</span></tt>.</dd>
<dt><ttclass="docutils literal"><spanclass="pre">n</span></tt> (long) [long long *]</dt>
<dd>Convert a Python long to a C/C++ <ttclass="docutils literal"><spanclass="pre">long</span><spanclass="pre">long</span></tt>.</dd>
<dt><ttclass="docutils literal"><spanclass="pre">o</span></tt> (long) [unsigned long long *]</dt>
<dd>Convert a Python long to a C/C++ <ttclass="docutils literal"><spanclass="pre">unsigned</span><spanclass="pre">long</span><spanclass="pre">long</span></tt>.</dd>
<dd><pclass="first">Convert a Python v2 string object or a Python v3 bytes object to a
C/C++ <ttclass="docutils literal"><spanclass="pre">'\0'</span></tt> terminated string. If the Python object is <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt>
then the string is <ttclass="docutils literal"><spanclass="pre">NULL</span></tt>.</p>
<divclass="last admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">This is deprecated from SIP v4.8. Instead you should use <ttclass="docutils literal"><spanclass="pre">B</span></tt>.</p>
</div>
</dd>
<dt><ttclass="docutils literal"><spanclass="pre">t</span></tt> (long) [unsigned short *]</dt>
<dd>Convert a Python long to a C/C++ <ttclass="docutils literal"><spanclass="pre">unsigned</span><spanclass="pre">short</span></tt>.</dd>
<dt><ttclass="docutils literal"><spanclass="pre">u</span></tt> (long) [unsigned int *]</dt>
<dd>Convert a Python long to a C/C++ <ttclass="docutils literal"><spanclass="pre">unsigned</span><spanclass="pre">int</span></tt>.</dd>
object to a C/C++ <ttclass="docutils literal"><spanclass="pre">L'\0'</span></tt> terminated wide character string. If the
Python object is <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt> then the string is <ttclass="docutils literal"><spanclass="pre">NULL</span></tt>.</dd>
<dd>Convert a Python string-like object to a C/C++ <ttclass="docutils literal"><spanclass="pre">'\0'</span></tt> terminated
string according to the encoding <ttclass="docutils literal"><spanclass="pre">e</span></tt>. <ttclass="docutils literal"><spanclass="pre">e</span></tt> can either be <ttclass="docutils literal"><spanclass="pre">A</span></tt> for
ASCII, <ttclass="docutils literal"><spanclass="pre">L</span></tt> for Latin-1, or <ttclass="docutils literal"><spanclass="pre">8</span></tt> for UTF-8. If the Python object is
<ttclass="docutils literal"><spanclass="pre">Py_None</span></tt> then the string is <ttclass="docutils literal"><spanclass="pre">NULL</span></tt>. The integer uniquely
identifies the object in the context defined by the <ttclass="docutils literal"><spanclass="pre">S</span></tt> 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
<dd>Convert a Python v2 string object or a Python v3 bytes object to a
C/C++ <ttclass="docutils literal"><spanclass="pre">'\0'</span></tt> terminated string. If the Python object is <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt>
then the string is <ttclass="docutils literal"><spanclass="pre">NULL</span></tt>. The integer uniquely identifies the
object in the context defined by the <ttclass="docutils literal"><spanclass="pre">S</span></tt> format character and allows
an extra reference to the object to be kept to ensure that the string
<dd><pclass="first">Convert a Python object to a C structure or a C++ class instance and
return its state as described in <atitle="sipConvertToInstance"class="reference internal"href="#sipConvertToInstance"><ttclass="xref docutils literal"><spanclass="pre">sipConvertToInstance()</span></tt></a>.
<ttclass="docutils literal"><spanclass="pre">f</span></tt> is a combination of the following flags encoded as an ASCII
character by adding <ttclass="docutils literal"><spanclass="pre">0</span></tt> to the combined value:</p>
<blockquote>
<p>0x01 disallows the conversion of <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt> to <ttclass="docutils literal"><spanclass="pre">NULL</span></tt></p>
<dlclass="docutils">
<dt>0x02 implements the <aclass="reference external"href="annotations.html#fanno-Factory"><ttclass="xref docutils literal"><spanclass="pre">Factory</span></tt></a> and <aclass="reference external"href="annotations.html#fanno-TransferBack"><ttclass="xref docutils literal"><spanclass="pre">TransferBack</span></tt></a></dt>
<dd>annotations</dd>
<dt>0x04 suppresses the return of the state of the returned C/C++</dt>
<dd>instance. Note that the <ttclass="docutils literal"><spanclass="pre">int</span><spanclass="pre">*</span></tt> used to return the state is
not passed if this flag is specified.</dd>
</dl>
</blockquote>
<divclass="last admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">This is deprecated from SIP v4.8. Instead you should use <ttclass="docutils literal"><spanclass="pre">Hf</span></tt>.</p>
<dd><pclass="first">Convert a Python object to a C structure, C++ class or mapped type
instance and return its state as described in
<atitle="sipConvertToType"class="reference internal"href="#sipConvertToType"><ttclass="xref docutils literal"><spanclass="pre">sipConvertToType()</span></tt></a>. <ttclass="docutils literal"><spanclass="pre">f</span></tt> is a combination of the following
flags encoded as an ASCII character by adding <ttclass="docutils literal"><spanclass="pre">0</span></tt> to the combined
value:</p>
<blockquote>
<p>0x01 disallows the conversion of <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt> to <ttclass="docutils literal"><spanclass="pre">NULL</span></tt></p>
<dlclass="docutils">
<dt>0x02 implements the <aclass="reference external"href="annotations.html#fanno-Factory"><ttclass="xref docutils literal"><spanclass="pre">Factory</span></tt></a> and <aclass="reference external"href="annotations.html#fanno-TransferBack"><ttclass="xref docutils literal"><spanclass="pre">TransferBack</span></tt></a></dt>
<dd>annotations</dd>
<dt>0x04 suppresses the return of the state of the returned C/C++</dt>
<dd>instance. Note that the <ttclass="docutils literal"><spanclass="pre">int</span><spanclass="pre">*</span></tt> used to return the state is
not passed if this flag is specified.</dd>
</dl>
</blockquote>
<divclass="last admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">This is deprecated from SIP v4.10.1. Instead you should use
object to a C/C++ wide character array and its length. If the Python
object is <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt> then the array and length are <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> and zero
<dd><pclass="first">Convert a Python object to a C structure, C++ class or mapped type
instance as described in <atitle="sipConvertToType"class="reference internal"href="#sipConvertToType"><ttclass="xref docutils literal"><spanclass="pre">sipConvertToType()</span></tt></a>. <ttclass="docutils literal"><spanclass="pre">f</span></tt> is a
combination of the following flags encoded as an ASCII character by
adding <ttclass="docutils literal"><spanclass="pre">0</span></tt> to the combined value:</p>
<blockquoteclass="last">
<p>0x01 disallows the conversion of <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt> to <ttclass="docutils literal"><spanclass="pre">NULL</span></tt></p>
<dlclass="docutils">
<dt>0x02 implements the <aclass="reference external"href="annotations.html#fanno-Factory"><ttclass="xref docutils literal"><spanclass="pre">Factory</span></tt></a> and <aclass="reference external"href="annotations.html#fanno-TransferBack"><ttclass="xref docutils literal"><spanclass="pre">TransferBack</span></tt></a></dt>
<dd>Convert a Python <atitle="sip.voidptr"class="reference external"href="python_api.html#sip.voidptr"><ttclass="xref docutils literal"><spanclass="pre">sip.voidptr</span></tt></a> object to a C/C++ <ttclass="docutils literal"><spanclass="pre">void</span><spanclass="pre">*</span></tt>.</dd>
<dd>Check that a Python object is <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt>. No value is returned.</dd>
</dl>
</dd></dl>
<dlclass="cfunction">
<dtid="sipRegisterAttributeGetter">
int <ttclass="descname">sipRegisterAttributeGetter</tt><big>(</big>const sipTypeDef<em> *td</em>, sipAttrGetterFunc<em> getter</em><big>)</big><aclass="headerlink"href="#sipRegisterAttributeGetter"title="Permalink to this definition">¶</a></dt>
<dd><p>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.</p>
<p><em>td</em> is the generated type definition of the type whose dictionary is
to be populated.</p>
<p><em>dict</em> is the dictionary to be populated.</p>
<p>0 if there was no error, otherwise -1 is returned.</p>
</blockquote>
<p>See the section <aclass="reference external"href="using.html#ref-lazy-type-attributes"><em>Lazy Type Attributes</em></a> for more details.</p>
</dd></dl>
<dlclass="cfunction">
<dtid="sipRegisterPyType">
int <ttclass="descname">sipRegisterPyType</tt><big>(</big>PyTypeObject<em> *type</em><big>)</big><aclass="headerlink"href="#sipRegisterPyType"title="Permalink to this definition">¶</a></dt>
<dd><p>This registers a Python type object that can be used as the meta-type or
<trclass="field"><thclass="field-name">Parameter:</th><tdclass="field-body"><em>type</em>– the type object.</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">0 if there was no error, otherwise -1 is returned.</td>
</tr>
</tbody>
</table>
<p>See the section <aclass="reference external"href="using.html#ref-types-metatypes"><em>Types and Meta-types</em></a> for more details.</p>
</dd></dl>
<dlclass="cfunction">
<dtid="sipReleaseInstance">
void <ttclass="descname">sipReleaseInstance</tt><big>(</big>void<em> *cpp</em>, <atitle="sipWrapperType"class="reference internal"href="#sipWrapperType">sipWrapperType</a><em> *type</em>, int<em> state</em><big>)</big><aclass="headerlink"href="#sipReleaseInstance"title="Permalink to this definition">¶</a></dt>
<dd><p>This destroys a wrapped C/C++ instance if it was a temporary instance. It
is called after a call to either <atitle="sipConvertToInstance"class="reference internal"href="#sipConvertToInstance"><ttclass="xref docutils literal"><spanclass="pre">sipConvertToInstance()</span></tt></a> or
void <ttclass="descname">sipReleaseMappedType</tt><big>(</big>void<em> *cpp</em>, const sipMappedType<em> *mt</em>, int<em> state</em><big>)</big><aclass="headerlink"href="#sipReleaseMappedType"title="Permalink to this definition">¶</a></dt>
<dd><p>This destroys a wrapped C/C++ mapped type if it was a temporary instance.
It is called after a call to either <atitle="sipConvertToMappedType"class="reference internal"href="#sipConvertToMappedType"><ttclass="xref docutils literal"><spanclass="pre">sipConvertToMappedType()</span></tt></a> or
<trclass="field"><thclass="field-name">Parameters:</th><tdclass="field-body"><ulclass="first last simple">
<li><em>cpp</em>– the C/C++ instance.</li>
<li><em>mt</em>– the opaque structure returned by <atitle="sipFindMappedType"class="reference internal"href="#sipFindMappedType"><ttclass="xref docutils literal"><spanclass="pre">sipFindMappedType()</span></tt></a>.</li>
<li><em>state</em>– describes the state of the C/C++ instance.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">This is deprecated from SIP v4.8. Instead you should use
void <ttclass="descname">sipReleaseType</tt><big>(</big>void<em> *cpp</em>, const sipTypeDef<em> *td</em>, int<em> state</em><big>)</big><aclass="headerlink"href="#sipReleaseType"title="Permalink to this definition">¶</a></dt>
<dd><p>This destroys a wrapped C/C++ or mapped type instance if it was a temporary
instance. It is called after a call to either <atitle="sipConvertToType"class="reference internal"href="#sipConvertToType"><ttclass="xref docutils literal"><spanclass="pre">sipConvertToType()</span></tt></a>
or <atitle="sipForceConvertToType"class="reference internal"href="#sipForceConvertToType"><ttclass="xref docutils literal"><spanclass="pre">sipForceConvertToType()</span></tt></a>.</p>
<trclass="field"><thclass="field-name">Parameters:</th><tdclass="field-body"><ulclass="first last simple">
<li><em>cpp</em>– the C/C++ instance.</li>
<li><em>td</em>– the type’s <aclass="reference internal"href="#ref-type-structures"><em>generated type structure</em></a>.</li>
<li><em>state</em>– describes the state of the C/C++ instance.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="cfunction">
<dtid="sipResolveTypedef">
const char *<ttclass="descname">sipResolveTypedef</tt><big>(</big>const char<em> *name</em><big>)</big><aclass="headerlink"href="#sipResolveTypedef"title="Permalink to this definition">¶</a></dt>
<dd><p>This returns the value of a C/C++ typedef.</p>
<trclass="field"><thclass="field-name">Parameter:</th><tdclass="field-body"><em>name</em>– the name of the typedef.</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">the value of the typedef or <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> if there was no such typedef.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="ctype">
<dtid="sipSimpleWrapper">
<ttclass="descname">sipSimpleWrapper</tt><aclass="headerlink"href="#sipSimpleWrapper"title="Permalink to this definition">¶</a></dt>
<dd><p>This is a C structure that represents a Python wrapped instance whose type
is <ttclass="xref docutils literal"><spanclass="pre">sip.simplewrapper</span></tt>. It is an extension of the <ttclass="docutils literal"><spanclass="pre">PyObject</span></tt>
structure and so may be safely cast to it.</p>
<dlclass="cmember">
<dtid="user">
PyObject *<ttclass="descname">user</tt><aclass="headerlink"href="#user"title="Permalink to this definition">¶</a></dt>
<dd>This can be used for any purpose by handwritten code and will
automatically be garbage collected at the appropriate time.</dd></dl>
</dd></dl>
<dlclass="cvar">
<dtid="sipSimpleWrapper_Type">
PyTypeObject *<ttclass="descname">sipSimpleWrapper_Type</tt><aclass="headerlink"href="#sipSimpleWrapper_Type"title="Permalink to this definition">¶</a></dt>
<dd>This is the type of a <atitle="sipSimpleWrapper"class="reference internal"href="#sipSimpleWrapper"><ttclass="xref docutils literal"><spanclass="pre">sipSimpleWrapper</span></tt></a> structure and is the C
implementation of <ttclass="xref docutils literal"><spanclass="pre">sip.simplewrapper</span></tt>. It may be safely cast to
<ttclass="descname">sipStringTypeClassMap</tt><aclass="headerlink"href="#sipStringTypeClassMap"title="Permalink to this definition">¶</a></dt>
<dd><p>This C structure is used with <atitle="sipMapStringToClass"class="reference internal"href="#sipMapStringToClass"><ttclass="xref docutils literal"><spanclass="pre">sipMapStringToClass()</span></tt></a> to define a
mapping between <ttclass="docutils literal"><spanclass="pre">'\0'</span></tt> terminated string based RTTI and
<aclass="reference internal"href="#ref-type-objects"><em>Generated Type Objects</em></a>. The structure elements are as follows.</p>
<dlclass="cmember">
<dtid="typeString">
char *<ttclass="descname">typeString</tt><aclass="headerlink"href="#typeString"title="Permalink to this definition">¶</a></dt>
<dd>A pointer to the corresponding generated type object.</dd></dl>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">This is deprecated from SIP v4.8.</p>
</div>
</dd></dl>
<dlclass="cfunction">
<dtid="sipTransferBack">
void <ttclass="descname">sipTransferBack</tt><big>(</big>PyObject<em> *obj</em><big>)</big><aclass="headerlink"href="#sipTransferBack"title="Permalink to this definition">¶</a></dt>
<dd><p>This transfers ownership of a Python wrapped instance to Python (see
<aclass="reference external"href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a>).</p>
<trclass="field"><thclass="field-name">Parameter:</th><tdclass="field-body"><em>obj</em>– the wrapped instance.</td>
</tr>
</tbody>
</table>
<p>In addition, any association of the instance with regard to the cyclic
garbage collector with another instance is removed.</p>
</dd></dl>
<dlclass="cfunction">
<dtid="sipTransferBreak">
void <ttclass="descname">sipTransferBreak</tt><big>(</big>PyObject<em> *obj</em><big>)</big><aclass="headerlink"href="#sipTransferBreak"title="Permalink to this definition">¶</a></dt>
<dd><p>Any association of a Python wrapped instance with regard to the cyclic
garbage collector with another instance is removed. Ownership of the
<trclass="field"><thclass="field-name">Parameter:</th><tdclass="field-body"><em>obj</em>– the wrapped instance.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="cfunction">
<dtid="sipTransferTo">
void <ttclass="descname">sipTransferTo</tt><big>(</big>PyObject<em> *obj</em>, PyObject<em> *owner</em><big>)</big><aclass="headerlink"href="#sipTransferTo"title="Permalink to this definition">¶</a></dt>
<dd><p>This transfers ownership of a Python wrapped instance to C++ (see
<aclass="reference external"href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a>).</p>
<trclass="field"><thclass="field-name">Parameters:</th><tdclass="field-body"><ulclass="first last simple">
<li><em>obj</em>– the wrapped instance.</li>
<li><em>owner</em>– an optional wrapped instance that <em>obj</em> becomes associated with with
regard to the cyclic garbage collector. If <em>owner</em> is <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> then no
such association is made. If <em>owner</em> is the same value as <em>obj</em> then
any reference cycles involving <em>obj</em> can never be detected or broken by
the cyclic garbage collector. Responsibility for calling the C++
instance’s destructor is always transfered to C++.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="cfunction">
<dtid="sipTypeAsPyTypeObject">
PyTypeObject *<ttclass="descname">sipTypeAsPyTypeObject</tt><big>(</big>sipTypeDef<em> *td</em><big>)</big><aclass="headerlink"href="#sipTypeAsPyTypeObject"title="Permalink to this definition">¶</a></dt>
<dd><p>This returns a pointer to the Python type object that SIP creates for a
<aclass="reference internal"href="#ref-type-structures"><em>generated type structure</em></a>.</p>
<trclass="field"><thclass="field-name">Parameter:</th><tdclass="field-body"><em>td</em>– the type structure.</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">the Python type object. If the type structure refers to a mapped type
then <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> will be returned.</td>
</tr>
</tbody>
</table>
<p>If the type structure refers to a C structure or C++ class then the
Python type object may be safely cast to a <atitle="sipWrapperType"class="reference internal"href="#sipWrapperType"><ttclass="xref docutils literal"><spanclass="pre">sipWrapperType</span></tt></a>.</p>
</dd></dl>
<dlclass="cfunction">
<dtid="sipTypeFromPyTypeObject">
const sipTypeDef *<ttclass="descname">sipTypeFromPyTypeObject</tt><big>(</big>PyTypeObject<em> *py_type</em><big>)</big><aclass="headerlink"href="#sipTypeFromPyTypeObject"title="Permalink to this definition">¶</a></dt>
<dd><p>This returns the <aclass="reference internal"href="#ref-type-structures"><em>generated type structure</em></a> for
<trclass="field"><thclass="field-name">Parameter:</th><tdclass="field-body"><em>py_type</em>– the Python type object.</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">the type structure or <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> if the Python type object doesn’t
correspond to a type structure.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="cfunction">
<dtid="sipTypeIsClass">
int <ttclass="descname">sipTypeIsClass</tt><big>(</big>sipTypeDef<em> *td</em><big>)</big><aclass="headerlink"href="#sipTypeIsClass"title="Permalink to this definition">¶</a></dt>
<dd><p>This checks if a <aclass="reference internal"href="#ref-type-structures"><em>generated type structure</em></a>
<trclass="field"><thclass="field-name">Parameter:</th><tdclass="field-body"><em>td</em>– the type structure.</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">a non-zero value if the type structure refers to a structure or class.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="cfunction">
<dtid="sipTypeIsEnum">
int <ttclass="descname">sipTypeIsEnum</tt><big>(</big>sipTypeDef<em> *td</em><big>)</big><aclass="headerlink"href="#sipTypeIsEnum"title="Permalink to this definition">¶</a></dt>
<dd><p>This checks if a <aclass="reference internal"href="#ref-type-structures"><em>generated type structure</em></a>
<trclass="field"><thclass="field-name">Parameter:</th><tdclass="field-body"><em>td</em>– the type structure.</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">a non-zero value if the type structure refers to an enum.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="cfunction">
<dtid="sipTypeIsMapped">
int <ttclass="descname">sipTypeIsMapped</tt><big>(</big>sipTypeDef<em> *td</em><big>)</big><aclass="headerlink"href="#sipTypeIsMapped"title="Permalink to this definition">¶</a></dt>
<dd><p>This checks if a <aclass="reference internal"href="#ref-type-structures"><em>generated type structure</em></a>
<trclass="field"><thclass="field-name">Parameter:</th><tdclass="field-body"><em>td</em>– the type structure.</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">a non-zero value if the type structure refers to a mapped type.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="cfunction">
<dtid="sipTypeIsNamespace">
int <ttclass="descname">sipTypeIsNamespace</tt><big>(</big>sipTypeDef<em> *td</em><big>)</big><aclass="headerlink"href="#sipTypeIsNamespace"title="Permalink to this definition">¶</a></dt>
<dd><p>This checks if a <aclass="reference internal"href="#ref-type-structures"><em>generated type structure</em></a>
<trclass="field"><thclass="field-name">Parameter:</th><tdclass="field-body"><em>td</em>– the type structure.</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">a non-zero value if the type structure refers to a namespace.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="cfunction">
<dtid="sipTypeName">
const char *<ttclass="descname">sipTypeName</tt><big>(</big>const sipTypeDef<em> *td</em><big>)</big><aclass="headerlink"href="#sipTypeName"title="Permalink to this definition">¶</a></dt>
<dd><p>This returns the C/C++ name of a wrapped type.</p>
<trclass="field"><thclass="field-name">Parameter:</th><tdclass="field-body"><em>td</em>– the type’s <aclass="reference internal"href="#ref-type-structures"><em>generated type structure</em></a>.</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">the name of the C/C++ type.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="cfunction">
<dtid="sipTypeScope">
const sipTypeDef *<ttclass="descname">sipTypeScope</tt><big>(</big>const sipTypeDef<em> *td</em><big>)</big><aclass="headerlink"href="#sipTypeScope"title="Permalink to this definition">¶</a></dt>
<dd><p>This returns the <aclass="reference internal"href="#ref-type-structures"><em>generated type structure</em></a> of
the enclosing scope of another generated type structure.</p>
<trclass="field"><thclass="field-name">Parameter:</th><tdclass="field-body"><em>td</em>– the type structure.</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">the type structure of the scope or <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> if the type has no scope.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dlclass="cvar">
<dtid="sipVoidPtr_Type">
PyTypeObject *<ttclass="descname">sipVoidPtr_Type</tt><aclass="headerlink"href="#sipVoidPtr_Type"title="Permalink to this definition">¶</a></dt>
<dd>This is the type of a <ttclass="docutils literal"><spanclass="pre">PyObject</span></tt> structure that is used to wrap a
<ttclass="descname">sipWrapper</tt><aclass="headerlink"href="#sipWrapper"title="Permalink to this definition">¶</a></dt>
<dd>This is a C structure that represents a Python wrapped instance whose type
is <atitle="sip.wrapper"class="reference external"href="python_api.html#sip.wrapper"><ttclass="xref docutils literal"><spanclass="pre">sip.wrapper</span></tt></a>. It is an extension of the
<atitle="sipSimpleWrapper"class="reference internal"href="#sipSimpleWrapper"><ttclass="xref docutils literal"><spanclass="pre">sipSimpleWrapper</span></tt></a> and <ttclass="docutils literal"><spanclass="pre">PyObject</span></tt> structures and so may be safely
cast to both.</dd></dl>
<dlclass="cfunction">
<dtid="sipWrapper_Check">
int <ttclass="descname">sipWrapper_Check</tt><big>(</big>PyObject<em> *obj</em><big>)</big><aclass="headerlink"href="#sipWrapper_Check"title="Permalink to this definition">¶</a></dt>
<dd><p>This checks if a Python object is a wrapped instance.</p>
PyTypeObject *<ttclass="descname">sipWrapper_Type</tt><aclass="headerlink"href="#sipWrapper_Type"title="Permalink to this definition">¶</a></dt>
<dd>This is the type of a <atitle="sipWrapper"class="reference internal"href="#sipWrapper"><ttclass="xref docutils literal"><spanclass="pre">sipWrapper</span></tt></a> structure and is the C
implementation of <atitle="sip.wrapper"class="reference external"href="python_api.html#sip.wrapper"><ttclass="xref docutils literal"><spanclass="pre">sip.wrapper</span></tt></a>. It may be safely cast to
PyTypeObject *<ttclass="descname">sipWrapperType_Type</tt><aclass="headerlink"href="#sipWrapperType_Type"title="Permalink to this definition">¶</a></dt>
<dd>This is the type of a <atitle="sipWrapperType"class="reference internal"href="#sipWrapperType"><ttclass="xref docutils literal"><spanclass="pre">sipWrapperType</span></tt></a> structure and is the C
implementation of <atitle="sip.wrappertype"class="reference external"href="python_api.html#sip.wrappertype"><ttclass="xref docutils literal"><spanclass="pre">sip.wrappertype</span></tt></a>.</dd></dl>
<spanid="ref-type-structures"></span><h2>Generated Type Structures<aclass="headerlink"href="#generated-type-structures"title="Permalink to this headline">¶</a></h2>
<p>SIP generates an opaque type structure for each C structure, C++ class, C++
namespace, named enum or mapped type being wrapped. These are
<ttclass="xref docutils literal"><spanclass="pre">sipTypeDef</span></tt> structures and are used extensively by the SIP API.</p>
<p>The names of these structure are prefixed by <ttclass="docutils literal"><spanclass="pre">sipType_</span></tt>.</p>
<p>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 <ttclass="docutils literal"><spanclass="pre">::</span></tt>
scope separators are replaced by an underscore. For example, the type object
for class <ttclass="docutils literal"><spanclass="pre">Klass</span></tt> is <ttclass="docutils literal"><spanclass="pre">sipType_Klass</span></tt>.</p>
<p>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 <atitle="sipFindType"class="reference internal"href="#sipFindType"><ttclass="xref docutils literal"><spanclass="pre">sipFindType()</span></tt></a>.</p>
<p>The type structures of all imported types are available to handwritten code.</p>
</div>
<divclass="section"id="generated-type-objects">
<spanid="ref-type-objects"></span><h2>Generated Type Objects<aclass="headerlink"href="#generated-type-objects"title="Permalink to this headline">¶</a></h2>
<p>SIP generates a <atitle="sipWrapperType"class="reference internal"href="#sipWrapperType"><ttclass="xref docutils literal"><spanclass="pre">sipWrapperType</span></tt></a> type object for each C structure or
C++ class being wrapped.</p>
<p>These objects are named with the structure or class name prefixed by
<ttclass="docutils literal"><spanclass="pre">sipClass_</span></tt>. For example, the type object for class <ttclass="docutils literal"><spanclass="pre">Klass</span></tt> is
<spanid="ref-enum-type-objects"></span><h2>Generated Named Enum Type Objects<aclass="headerlink"href="#generated-named-enum-type-objects"title="Permalink to this headline">¶</a></h2>
<p>SIP generates a type object for each named enum being wrapped. These are
PyTypeObject structures. (Anonymous enums are wrapped as Python integers.)</p>
<p>These objects are named with the fully qualified enum name (i.e. including any
enclosing scope) prefixed by <ttclass="docutils literal"><spanclass="pre">sipEnum_</span></tt>. For example, the type object for
enum <ttclass="docutils literal"><spanclass="pre">Enum</span></tt> defined in class <ttclass="docutils literal"><spanclass="pre">Klass</span></tt> is <ttclass="docutils literal"><spanclass="pre">sipEnum_Klass_Enum</span></tt>.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">Using these names is deprecated from SIP v4.8. Instead use the
corresponding generated type structure (see <aclass="reference internal"href="#ref-type-structures"><em>Generated Type Structures</em></a>) and
<spanid="ref-derived-classes"></span><h2>Generated Derived Classes<aclass="headerlink"href="#generated-derived-classes"title="Permalink to this headline">¶</a></h2>
<p>For most C++ classes being wrapped SIP generates a derived class with the same
name prefixed by <ttclass="docutils literal"><spanclass="pre">sip</span></tt>. For example, the derived class for class <ttclass="docutils literal"><spanclass="pre">Klass</span></tt>
is <ttclass="docutils literal"><spanclass="pre">sipKlass</span></tt>.</p>
<p>If a C++ class doesn’t have any virtual or protected methods in it or any of
<spanid="ref-exception-objects"></span><h2>Generated Exception Objects<aclass="headerlink"href="#generated-exception-objects"title="Permalink to this headline">¶</a></h2>
<p>SIP generates a Python object for each exception defined with the
<p>These objects are named with the fully qualified exception name (i.e. including
any enclosing scope) prefixed by <ttclass="docutils literal"><spanclass="pre">sipException_</span></tt>. For example, the type
object for enum <ttclass="docutils literal"><spanclass="pre">Except</span></tt> defined in class <ttclass="docutils literal"><spanclass="pre">Klass</span></tt> is
