You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
2166 lines
145 KiB
2166 lines
145 KiB
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml"> |
|
<head> |
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
|
|
|
<title>C API for Handwritten Code — SIP 4.10.5 Reference Guide</title> |
|
<link rel="stylesheet" href="_static/default.css" type="text/css" /> |
|
<link rel="stylesheet" href="_static/pygments.css" type="text/css" /> |
|
<script type="text/javascript"> |
|
var DOCUMENTATION_OPTIONS = { |
|
URL_ROOT: '#', |
|
VERSION: '4.10.5', |
|
COLLAPSE_MODINDEX: false, |
|
FILE_SUFFIX: '.html', |
|
HAS_SOURCE: true |
|
}; |
|
</script> |
|
<script type="text/javascript" src="_static/jquery.js"></script> |
|
<script type="text/javascript" src="_static/doctools.js"></script> |
|
<link rel="top" title="SIP 4.10.5 Reference Guide" href="index.html" /> |
|
<link rel="next" title="Using the C API when Embedding" href="embedding.html" /> |
|
<link rel="prev" title="Annotations" href="annotations.html" /> |
|
</head> |
|
<body> |
|
<div class="related"> |
|
<h3>Navigation</h3> |
|
<ul> |
|
<li class="right" style="margin-right: 10px"> |
|
<a href="genindex.html" title="General Index" |
|
accesskey="I">index</a></li> |
|
<li class="right" > |
|
<a href="modindex.html" title="Global Module Index" |
|
accesskey="M">modules</a> |</li> |
|
<li class="right" > |
|
<a href="embedding.html" title="Using the C API when Embedding" |
|
accesskey="N">next</a> |</li> |
|
<li class="right" > |
|
<a href="annotations.html" title="Annotations" |
|
accesskey="P">previous</a> |</li> |
|
<li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> |
|
</ul> |
|
</div> |
|
|
|
<div class="document"> |
|
<div class="documentwrapper"> |
|
<div class="bodywrapper"> |
|
<div class="body"> |
|
|
|
<div class="section" id="c-api-for-handwritten-code"> |
|
<span id="ref-c-api"></span><h1>C API for Handwritten Code<a class="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> |
|
<dl class="cmacro"> |
|
<dt id="SIP_API_MAJOR_NR"> |
|
<tt class="descname">SIP_API_MAJOR_NR</tt><a class="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> |
|
|
|
<dl class="cmacro"> |
|
<dt id="SIP_API_MINOR_NR"> |
|
<tt class="descname">SIP_API_MINOR_NR</tt><a class="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> |
|
|
|
<dl class="cmacro"> |
|
<dt id="SIP_BLOCK_THREADS"> |
|
<tt class="descname">SIP_BLOCK_THREADS</tt><a class="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 |
|
<a title="SIP_UNBLOCK_THREADS" class="reference internal" href="#SIP_UNBLOCK_THREADS"><tt class="xref docutils literal"><span class="pre">SIP_UNBLOCK_THREADS</span></tt></a> at the same lexical scope.</dd></dl> |
|
|
|
<dl class="cmacro"> |
|
<dt id="SIP_NO_CONVERTORS"> |
|
<tt class="descname">SIP_NO_CONVERTORS</tt><a class="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 |
|
type’s <a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a>.</dd></dl> |
|
|
|
<dl class="cmacro"> |
|
<dt id="SIP_NOT_NONE"> |
|
<tt class="descname">SIP_NOT_NONE</tt><a class="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 <tt class="docutils literal"><span class="pre">Py_None</span></tt>.</dd></dl> |
|
|
|
<dl class="cmacro"> |
|
<dt id="SIP_PROTECTED_IS_PUBLIC"> |
|
<tt class="descname">SIP_PROTECTED_IS_PUBLIC</tt><a class="headerlink" href="#SIP_PROTECTED_IS_PUBLIC" title="Permalink to this definition">¶</a></dt> |
|
<dd><p> |
|
<span class="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 |
|
<tt class="docutils literal"><span class="pre">protected</span></tt> redefined as <tt class="docutils literal"><span class="pre">public</span></tt>. This allows handwritten code to |
|
determine if the generated helper functions for accessing protected C++ |
|
functions are available (see <a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a>).</p> |
|
</dd></dl> |
|
|
|
<dl class="cmacro"> |
|
<dt id="SIP_SSIZE_T"> |
|
<tt class="descname">SIP_SSIZE_T</tt><a class="headerlink" href="#SIP_SSIZE_T" title="Permalink to this definition">¶</a></dt> |
|
<dd>This is a C preprocessor macro that is defined as <tt class="docutils literal"><span class="pre">Py_ssize_t</span></tt> for Python |
|
v2.5 and later, and as <tt class="docutils literal"><span class="pre">int</span></tt> for earlier versions of Python. It makes it |
|
easier to write PEP 353 compliant handwritten code.</dd></dl> |
|
|
|
<dl class="cmacro"> |
|
<dt id="SIP_UNBLOCK_THREADS"> |
|
<tt class="descname">SIP_UNBLOCK_THREADS</tt><a class="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 |
|
<a title="SIP_BLOCK_THREADS" class="reference internal" href="#SIP_BLOCK_THREADS"><tt class="xref docutils literal"><span class="pre">SIP_BLOCK_THREADS</span></tt></a>.</dd></dl> |
|
|
|
<dl class="cmacro"> |
|
<dt id="SIP_VERSION"> |
|
<tt class="descname">SIP_VERSION</tt><a class="headerlink" href="#SIP_VERSION" title="Permalink to this definition">¶</a></dt> |
|
<dd>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 |
|
<tt class="docutils literal"><span class="pre">0x040000</span></tt>).</dd></dl> |
|
|
|
<dl class="cmacro"> |
|
<dt id="SIP_VERSION_STR"> |
|
<tt class="descname">SIP_VERSION_STR</tt><a class="headerlink" href="#SIP_VERSION_STR" title="Permalink to this definition">¶</a></dt> |
|
<dd>This is a C preprocessor symbol that defines the SIP version number |
|
represented as a string. For development snapshots it will start with |
|
<tt class="docutils literal"><span class="pre">snapshot-</span></tt>.</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipBadCallableArg"> |
|
sipErrorState <tt class="descname">sipBadCallableArg</tt><big>(</big>int<em> arg_nr</em>, PyObject<em> *arg</em><big>)</big><a class="headerlink" href="#sipBadCallableArg" title="Permalink to this definition">¶</a></dt> |
|
<dd><p> |
|
<span class="versionmodified">New in version 4.10.</span></p> |
|
<p>This is called from <a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="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 |
|
<a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a> does additional type checking of the supplied |
|
arguments.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<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> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the value that should be assigned to <tt class="docutils literal"><span class="pre">sipError</span></tt>.</p> |
|
</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipBadCatcherResult"> |
|
void <tt class="descname">sipBadCatcherResult</tt><big>(</big>PyObject<em> *method</em><big>)</big><a class="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 <a class="reference external" href="directives.html#directive-%VirtualCatcherCode"><tt class="xref docutils literal"><span class="pre">%VirtualCatcherCode</span></tt></a> |
|
directive.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>method</em> – the Python method and would normally be the supplied <tt class="docutils literal"><span class="pre">sipMethod</span></tt>.</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipBadLengthForSlice"> |
|
void <tt class="descname">sipBadLengthForSlice</tt><big>(</big><a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> seqlen</em>, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> slicelen</em><big>)</big><a class="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 <tt class="xref docutils literal"><span class="pre">__setitem__()</span></tt> methods.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="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> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipBuildResult"> |
|
PyObject *<tt class="descname">sipBuildResult</tt><big>(</big>int<em> *iserr</em>, const char<em> *format</em>, ...<big>)</big><a class="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 <tt class="xref docutils literal"><span class="pre">Py_BuildValue()</span></tt> function.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>iserr</em> – if this is not <tt class="docutils literal"><span class="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> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">If there was an error then <tt class="docutils literal"><span class="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 |
|
to be passed.</p> |
|
<dl class="docutils"> |
|
<dt><tt class="docutils literal"><span class="pre">a</span></tt> (string) [char]</dt> |
|
<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">char</span></tt> to a Python v2 or v3 string object.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">b</span></tt> (boolean) [int]</dt> |
|
<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">int</span></tt> to a Python boolean.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">c</span></tt> (string/bytes) [char]</dt> |
|
<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">char</span></tt> to a Python v2 string object or a Python v3 |
|
bytes object.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">d</span></tt> (float) [double]</dt> |
|
<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">double</span></tt> to a Python floating point number.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">e</span></tt> (integer) [enum]</dt> |
|
<dd>Convert an anonymous C/C++ <tt class="docutils literal"><span class="pre">enum</span></tt> to a Python integer.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">f</span></tt> (float) [float]</dt> |
|
<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">float</span></tt> to a Python floating point number.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">g</span></tt> (string/bytes) [char *, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T"><tt class="xref docutils literal"><span class="pre">SIP_SSIZE_T</span></tt></a>]</dt> |
|
<dd>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 <tt class="docutils literal"><span class="pre">NULL</span></tt> then the |
|
length is ignored and the result is <tt class="docutils literal"><span class="pre">Py_None</span></tt>.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">h</span></tt> (integer) [short]</dt> |
|
<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">short</span></tt> to a Python integer.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">i</span></tt> (integer) [int]</dt> |
|
<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">int</span></tt> to a Python integer.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">l</span></tt> (long) [long]</dt> |
|
<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">long</span></tt> to a Python integer.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">m</span></tt> (long) [unsigned long]</dt> |
|
<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span></tt> to a Python long.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">n</span></tt> (long) [long long]</dt> |
|
<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">long</span> <span class="pre">long</span></tt> to a Python long.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">o</span></tt> (long) [unsigned long long]</dt> |
|
<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></tt> to a Python long.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">r</span></tt> (wrapped instance) [<em>type</em> *, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T"><tt class="xref docutils literal"><span class="pre">SIP_SSIZE_T</span></tt></a>, const <tt class="xref docutils literal"><span class="pre">sipTypeDef</span></tt> *]</dt> |
|
<dd>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.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">s</span></tt> (string/bytes) [char *]</dt> |
|
<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">'\0'</span></tt> terminated string to a Python v2 string object |
|
or a Python v3 bytes object. If the string pointer is <tt class="docutils literal"><span class="pre">NULL</span></tt> then |
|
the result is <tt class="docutils literal"><span class="pre">Py_None</span></tt>.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">t</span></tt> (long) [unsigned short]</dt> |
|
<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">short</span></tt> to a Python long.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">u</span></tt> (long) [unsigned int]</dt> |
|
<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">int</span></tt> to a Python long.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">w</span></tt> (unicode/string) [wchar_t]</dt> |
|
<dd>Convert a C/C++ wide character to a Python v2 unicode object or a |
|
Python v3 string object.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">x</span></tt> (unicode/string) [wchar_t *]</dt> |
|
<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">L'\0'</span></tt> terminated wide character string to a Python |
|
v2 unicode object or a Python v3 string object. If the string pointer |
|
is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the result is <tt class="docutils literal"><span class="pre">Py_None</span></tt>.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">A</span></tt> (string) [char *]</dt> |
|
<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">'\0'</span></tt> terminated string to a Python v2 or v3 string |
|
object. If the string pointer is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the result is |
|
<tt class="docutils literal"><span class="pre">Py_None</span></tt>.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">B</span></tt> (wrapped instance) [<em>type</em> *, <a title="sipWrapperType" class="reference internal" href="#sipWrapperType"><tt class="xref docutils literal"><span class="pre">sipWrapperType</span></tt></a> *, PyObject *]</dt> |
|
<dd><p class="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 <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> argument. If it is <tt class="docutils literal"><span class="pre">NULL</span></tt> and the instance has |
|
already been wrapped then the ownership is unchanged. If it is |
|
<tt class="docutils literal"><span class="pre">NULL</span></tt> or <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership will be with Python. Otherwise |
|
ownership will be with C/C++ and the instance associated with the |
|
<tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> argument. The Python class is influenced by any |
|
applicable <a class="reference external" href="directives.html#directive-%ConvertToSubClassCode"><tt class="xref docutils literal"><span class="pre">%ConvertToSubClassCode</span></tt></a> code.</p> |
|
<div class="last admonition note"> |
|
<p class="first admonition-title">Note</p> |
|
<p class="last">This is deprecated from SIP v4.8. Instead you should use <tt class="docutils literal"><span class="pre">N</span></tt>.</p> |
|
</div> |
|
</dd> |
|
<dt><tt class="docutils literal"><span class="pre">C</span></tt> (wrapped instance) [<em>type</em> *, <a title="sipWrapperType" class="reference internal" href="#sipWrapperType"><tt class="xref docutils literal"><span class="pre">sipWrapperType</span></tt></a> *, PyObject *]</dt> |
|
<dd><p class="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 <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> argument. If it is <tt class="docutils literal"><span class="pre">NULL</span></tt> and the instance has |
|
already been wrapped then the ownership is unchanged. If it is |
|
<tt class="docutils literal"><span class="pre">NULL</span></tt> and the instance is newly wrapped then ownership will be with |
|
C/C++. If it is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership is transferred to Python |
|
via a call to <a title="sipTransferBack" class="reference internal" href="#sipTransferBack"><tt class="xref docutils literal"><span class="pre">sipTransferBack()</span></tt></a>. Otherwise ownership is |
|
transferred to C/C++ and the instance associated with the |
|
<tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> argument via a call to <a title="sipTransferTo" class="reference internal" href="#sipTransferTo"><tt class="xref docutils literal"><span class="pre">sipTransferTo()</span></tt></a>. The |
|
Python class is influenced by any applicable |
|
<a class="reference external" href="directives.html#directive-%ConvertToSubClassCode"><tt class="xref docutils literal"><span class="pre">%ConvertToSubClassCode</span></tt></a> code.</p> |
|
<div class="last admonition note"> |
|
<p class="first admonition-title">Note</p> |
|
<p class="last">This is deprecated from SIP v4.8. Instead you should use <tt class="docutils literal"><span class="pre">D</span></tt>.</p> |
|
</div> |
|
</dd> |
|
<dt><tt class="docutils literal"><span class="pre">D</span></tt> (wrapped instance) [<em>type</em> *, const <tt class="xref docutils literal"><span class="pre">sipTypeDef</span></tt> *, PyObject *]</dt> |
|
<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 <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> argument. If it is <tt class="docutils literal"><span class="pre">NULL</span></tt> and the |
|
instance has already been wrapped then the ownership is unchanged. If |
|
it is <tt class="docutils literal"><span class="pre">NULL</span></tt> and the instance is newly wrapped then ownership will be |
|
with C/C++. If it is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership is transferred to |
|
Python via a call to <a title="sipTransferBack" class="reference internal" href="#sipTransferBack"><tt class="xref docutils literal"><span class="pre">sipTransferBack()</span></tt></a>. Otherwise ownership |
|
is transferred to C/C++ and the instance associated with the |
|
<tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> argument via a call to <a title="sipTransferTo" class="reference internal" href="#sipTransferTo"><tt class="xref docutils literal"><span class="pre">sipTransferTo()</span></tt></a>. The |
|
Python class is influenced by any applicable |
|
<a class="reference external" href="directives.html#directive-%ConvertToSubClassCode"><tt class="xref docutils literal"><span class="pre">%ConvertToSubClassCode</span></tt></a> code.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">E</span></tt> (wrapped enum) [enum, PyTypeObject *]</dt> |
|
<dd><p class="first">Convert a named C/C++ <tt class="docutils literal"><span class="pre">enum</span></tt> to an instance of the corresponding |
|
Python named enum type.</p> |
|
<div class="last admonition note"> |
|
<p class="first admonition-title">Note</p> |
|
<p class="last">This is deprecated from SIP v4.8. Instead you should use <tt class="docutils literal"><span class="pre">F</span></tt>.</p> |
|
</div> |
|
</dd> |
|
<dt><tt class="docutils literal"><span class="pre">F</span></tt> (wrapped enum) [enum, <tt class="xref docutils literal"><span class="pre">sipTypeDef</span></tt> *]</dt> |
|
<dd>Convert a named C/C++ <tt class="docutils literal"><span class="pre">enum</span></tt> to an instance of the corresponding |
|
Python named enum type.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">G</span></tt> (unicode) [wchar_t *, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T"><tt class="xref docutils literal"><span class="pre">SIP_SSIZE_T</span></tt></a>]</dt> |
|
<dd>Convert a C/C++ wide character array and its length to a Python unicode |
|
object. If the array is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the length is ignored and the |
|
result is <tt class="docutils literal"><span class="pre">Py_None</span></tt>.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">N</span></tt> (wrapped instance) [<em>type</em> *, <tt class="xref docutils literal"><span class="pre">sipTypeDef</span></tt> *, PyObject *]</dt> |
|
<dd>Convert a new C structure, C++ class or mapped type instance to a |
|
Python object. Ownership of the instance is determined by the |
|
<tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> argument. If it is <tt class="docutils literal"><span class="pre">NULL</span></tt> and the instance has |
|
already been wrapped then the ownership is unchanged. If it is |
|
<tt class="docutils literal"><span class="pre">NULL</span></tt> or <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership will be with Python. Otherwise |
|
ownership will be with C/C++ and the instance associated with the |
|
<tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> argument. The Python class is influenced by any |
|
applicable <a class="reference external" href="directives.html#directive-%ConvertToSubClassCode"><tt class="xref docutils literal"><span class="pre">%ConvertToSubClassCode</span></tt></a> code.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">R</span></tt> (object) [PyObject *]</dt> |
|
<dd>The result is value passed without any conversions. The reference |
|
count is unaffected, i.e. a reference is taken.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">S</span></tt> (object) [PyObject *]</dt> |
|
<dd>The result is value passed without any conversions. The reference |
|
count is incremented.</dd> |
|
<dt><tt class="docutils literal"><span class="pre">V</span></tt> (sip.voidptr) [void *]</dt> |
|
<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">void</span> <span class="pre">*</span></tt> Python <a title="sip.voidptr" class="reference external" href="python_api.html#sip.voidptr"><tt class="xref docutils literal"><span class="pre">sip.voidptr</span></tt></a> object.</dd> |
|
</dl> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipCallMethod"> |
|
PyObject *<tt class="descname">sipCallMethod</tt><big>(</big>int<em> *iserr</em>, PyObject<em> *method</em>, const char<em> *format</em>, ...<big>)</big><a class="headerlink" href="#sipCallMethod" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>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 |
|
<tt class="xref docutils literal"><span class="pre">PyObject_CallObject()</span></tt> function.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>iserr</em> – if this is not <tt class="docutils literal"><span class="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 <a title="sipBuildResult" class="reference internal" href="#sipBuildResult"><tt class="xref docutils literal"><span class="pre">sipBuildResult()</span></tt></a>).</li> |
|
</ul> |
|
</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">If there was an error then <tt class="docutils literal"><span class="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 |
|
<a class="reference external" href="directives.html#directive-%VirtualCatcherCode"><tt class="xref docutils literal"><span class="pre">%VirtualCatcherCode</span></tt></a> directive with method being the supplied |
|
<tt class="docutils literal"><span class="pre">sipMethod</span></tt>.</p> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipCanConvertToEnum"> |
|
int <tt class="descname">sipCanConvertToEnum</tt><big>(</big>PyObject<em> *obj</em>, const sipTypeDef<em> *td</em><big>)</big><a class="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> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>obj</em> – the Python object.</li> |
|
<li><em>td</em> – the enum’s <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a>.</li> |
|
</ul> |
|
</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">a non-zero value if the object can be converted.</p> |
|
</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipCanConvertToInstance"> |
|
int <tt class="descname">sipCanConvertToInstance</tt><big>(</big>PyObject<em> *obj</em>, <a title="sipWrapperType" class="reference internal" href="#sipWrapperType">sipWrapperType</a><em> *type</em>, int<em> flags</em><big>)</big><a class="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 |
|
structure or C++ class.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>obj</em> – the Python object.</li> |
|
<li><em>type</em> – the C/C++ type’s <a class="reference internal" href="#ref-type-objects"><em>generated type object</em></a>.</li> |
|
<li><em>flags</em> – any combination of the <a title="SIP_NOT_NONE" class="reference internal" href="#SIP_NOT_NONE"><tt class="xref docutils literal"><span class="pre">SIP_NOT_NONE</span></tt></a> and |
|
<a title="SIP_NO_CONVERTORS" class="reference internal" href="#SIP_NO_CONVERTORS"><tt class="xref docutils literal"><span class="pre">SIP_NO_CONVERTORS</span></tt></a> flags.</li> |
|
</ul> |
|
</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">a non-zero value if the object can be converted.</p> |
|
</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
<div class="admonition note"> |
|
<p class="first admonition-title">Note</p> |
|
<p class="last">This is deprecated from SIP v4.8. Instead you should use |
|
<a title="sipCanConvertToType" class="reference internal" href="#sipCanConvertToType"><tt class="xref docutils literal"><span class="pre">sipCanConvertToType()</span></tt></a>.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipCanConvertToMappedType"> |
|
int <tt class="descname">sipCanConvertToMappedType</tt><big>(</big>PyObject<em> *obj</em>, const sipMappedType<em> *mt</em>, int<em> flags</em><big>)</big><a class="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> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>obj</em> – the Python object.</li> |
|
<li><em>mt</em> – the opaque structure returned by <a title="sipFindMappedType" class="reference internal" href="#sipFindMappedType"><tt class="xref docutils literal"><span class="pre">sipFindMappedType()</span></tt></a>.</li> |
|
<li><em>flags</em> – this may be the <a title="SIP_NOT_NONE" class="reference internal" href="#SIP_NOT_NONE"><tt class="xref docutils literal"><span class="pre">SIP_NOT_NONE</span></tt></a> flag.</li> |
|
</ul> |
|
</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">a non-zero value if the object can be converted.</p> |
|
</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
<div class="admonition note"> |
|
<p class="first admonition-title">Note</p> |
|
<p class="last">This is deprecated from SIP v4.8. Instead you should use |
|
<a title="sipCanConvertToType" class="reference internal" href="#sipCanConvertToType"><tt class="xref docutils literal"><span class="pre">sipCanConvertToType()</span></tt></a>.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipCanConvertToType"> |
|
int <tt class="descname">sipCanConvertToType</tt><big>(</big>PyObject<em> *obj</em>, const sipTypeDef<em> *td</em>, int<em> flags</em><big>)</big><a class="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 |
|
structure, C++ class or mapped type.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>obj</em> – the Python object.</li> |
|
<li><em>td</em> – the C/C++ type’s <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a>.</li> |
|
<li><em>flags</em> – any combination of the <a title="SIP_NOT_NONE" class="reference internal" href="#SIP_NOT_NONE"><tt class="xref docutils literal"><span class="pre">SIP_NOT_NONE</span></tt></a> and |
|
<a title="SIP_NO_CONVERTORS" class="reference internal" href="#SIP_NO_CONVERTORS"><tt class="xref docutils literal"><span class="pre">SIP_NO_CONVERTORS</span></tt></a> flags.</li> |
|
</ul> |
|
</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">a non-zero value if the object can be converted.</p> |
|
</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipClassName"> |
|
PyObject *<tt class="descname">sipClassName</tt><big>(</big>PyObject<em> *obj</em><big>)</big><a class="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 |
|
comes with a reference.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>obj</em> – the wrapped instance.</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the name of the instance’s class.</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
<div class="admonition note"> |
|
<p class="first admonition-title">Note</p> |
|
<p>This is deprecated from SIP v4.8. Instead you should use the |
|
following:</p> |
|
<div class="last highlight-python"><pre>PyString_FromString(obj->ob_type->tp_name)</pre> |
|
</div> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipConvertFromConstVoidPtr"> |
|
PyObject *<tt class="descname">sipConvertFromConstVoidPtr</tt><big>(</big>const void<em> *cpp</em><big>)</big><a class="headerlink" href="#sipConvertFromConstVoidPtr" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This creates a <a title="sip.voidptr" class="reference external" href="python_api.html#sip.voidptr"><tt class="xref docutils literal"><span class="pre">sip.voidptr</span></tt></a> object for a memory address. The |
|
object will not be writeable and has no associated size.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>cpp</em> – the memory address.</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the <a title="sip.voidptr" class="reference external" href="python_api.html#sip.voidptr"><tt class="xref docutils literal"><span class="pre">sip.voidptr</span></tt></a> object.</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipConvertFromConstVoidPtrAndSize"> |
|
PyObject *<tt class="descname">sipConvertFromConstVoidPtrAndSize</tt><big>(</big>const void<em> *cpp</em>, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> size</em><big>)</big><a class="headerlink" href="#sipConvertFromConstVoidPtrAndSize" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This creates a <a title="sip.voidptr" class="reference external" href="python_api.html#sip.voidptr"><tt class="xref docutils literal"><span class="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> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>cpp</em> – the memory address.</li> |
|
<li><em>size</em> – the size associated with the address.</li> |
|
</ul> |
|
</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the <a title="sip.voidptr" class="reference external" href="python_api.html#sip.voidptr"><tt class="xref docutils literal"><span class="pre">sip.voidptr</span></tt></a> object.</p> |
|
</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipConvertFromEnum"> |
|
PyObject *<tt class="descname">sipConvertFromEnum</tt><big>(</big>int<em> eval</em>, const sipTypeDef<em> *td</em><big>)</big><a class="headerlink" href="#sipConvertFromEnum" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This converts a named C/C++ <tt class="docutils literal"><span class="pre">enum</span></tt> to an instance of the corresponding |
|
generated Python type.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>eval</em> – the enumerated value to convert.</li> |
|
<li><em>td</em> – the enum’s <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a>.</li> |
|
</ul> |
|
</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the Python object.</p> |
|
</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipConvertFromInstance"> |
|
PyObject *<tt class="descname">sipConvertFromInstance</tt><big>(</big>void<em> *cpp</em>, <a title="sipWrapperType" class="reference internal" href="#sipWrapperType">sipWrapperType</a><em> *type</em>, PyObject<em> *transferObj</em><big>)</big><a class="headerlink" href="#sipConvertFromInstance" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This converts a C structure or a C++ class instance to an instance of the |
|
corresponding generated Python type.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>cpp</em> – the C/C++ instance.</li> |
|
<li><em>type</em> – the type’s <a class="reference internal" href="#ref-type-objects"><em>generated type object</em></a>.</li> |
|
<li><em>transferObj</em> – this controls the ownership of the returned value.</li> |
|
</ul> |
|
</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the Python object.</p> |
|
</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
<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 <tt class="docutils literal"><span class="pre">NULL</span></tt> and the instance has already been wrapped then |
|
the ownership is unchanged.</p> |
|
<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">NULL</span></tt> and the instance is newly wrapped then |
|
ownership will be with C/C++.</p> |
|
<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership is transferred to Python via |
|
a call to <a title="sipTransferBack" class="reference internal" href="#sipTransferBack"><tt class="xref docutils literal"><span class="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 <a title="sipTransferTo" class="reference internal" href="#sipTransferTo"><tt class="xref docutils literal"><span class="pre">sipTransferTo()</span></tt></a>.</p> |
|
<p>The Python type is influenced by any applicable |
|
<a class="reference external" href="directives.html#directive-%ConvertToSubClassCode"><tt class="xref docutils literal"><span class="pre">%ConvertToSubClassCode</span></tt></a> code.</p> |
|
<div class="admonition note"> |
|
<p class="first admonition-title">Note</p> |
|
<p class="last">This is deprecated from SIP v4.8. Instead you should use |
|
<a title="sipConvertFromType" class="reference internal" href="#sipConvertFromType"><tt class="xref docutils literal"><span class="pre">sipConvertFromType()</span></tt></a>.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipConvertFromMappedType"> |
|
PyObject *<tt class="descname">sipConvertFromMappedType</tt><big>(</big>void<em> *cpp</em>, const sipMappedType<em> *mt</em>, PyObject<em> *transferObj</em><big>)</big><a class="headerlink" href="#sipConvertFromMappedType" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This converts a C structure or a C++ class instance wrapped as a mapped |
|
type to an instance of the corresponding generated Python type.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>cpp</em> – the C/C++ instance.</li> |
|
<li><em>mt</em> – the opaque structure returned by <a title="sipFindMappedType" class="reference internal" href="#sipFindMappedType"><tt class="xref docutils literal"><span class="pre">sipFindMappedType()</span></tt></a>.</li> |
|
<li><em>transferObj</em> – this controls the ownership of the returned value.</li> |
|
</ul> |
|
</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the Python object.</p> |
|
</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the ownership is unchanged.</p> |
|
<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership is transferred to Python |
|
via a call to <a title="sipTransferBack" class="reference internal" href="#sipTransferBack"><tt class="xref docutils literal"><span class="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 <a title="sipTransferTo" class="reference internal" href="#sipTransferTo"><tt class="xref docutils literal"><span class="pre">sipTransferTo()</span></tt></a>.</p> |
|
<div class="admonition note"> |
|
<p class="first admonition-title">Note</p> |
|
<p class="last">This is deprecated from SIP v4.8. Instead you should use |
|
<a title="sipConvertFromType" class="reference internal" href="#sipConvertFromType"><tt class="xref docutils literal"><span class="pre">sipConvertFromType()</span></tt></a>.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipConvertFromNamedEnum"> |
|
PyObject *<tt class="descname">sipConvertFromNamedEnum</tt><big>(</big>int<em> eval</em>, PyTypeObject<em> *type</em><big>)</big><a class="headerlink" href="#sipConvertFromNamedEnum" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This converts a named C/C++ <tt class="docutils literal"><span class="pre">enum</span></tt> to an instance of the corresponding |
|
generated Python type.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>eval</em> – the enumerated value to convert.</li> |
|
<li><em>type</em> – the enum’s <a class="reference internal" href="#ref-type-objects"><em>generated type object</em></a>.</li> |
|
</ul> |
|
</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the Python object.</p> |
|
</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
<div class="admonition note"> |
|
<p class="first admonition-title">Note</p> |
|
<p class="last">This is deprecated from SIP v4.8. Instead you should use |
|
<a title="sipConvertFromEnum" class="reference internal" href="#sipConvertFromEnum"><tt class="xref docutils literal"><span class="pre">sipConvertFromEnum()</span></tt></a>.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipConvertFromNewInstance"> |
|
PyObject *<tt class="descname">sipConvertFromNewInstance</tt><big>(</big>void<em> *cpp</em>, <a title="sipWrapperType" class="reference internal" href="#sipWrapperType">sipWrapperType</a><em> *type</em>, PyObject<em> *transferObj</em><big>)</big><a class="headerlink" href="#sipConvertFromNewInstance" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This converts a new C structure or a C++ class instance to an instance of |
|
the corresponding generated Python type.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>cpp</em> – the C/C++ instance.</li> |
|
<li><em>type</em> – the type’s <a class="reference internal" href="#ref-type-objects"><em>generated type object</em></a>.</li> |
|
<li><em>transferObj</em> – this controls the ownership of the returned value.</li> |
|
</ul> |
|
</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the Python object.</p> |
|
</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">NULL</span></tt> or <tt class="docutils literal"><span class="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 |
|
<a class="reference external" href="directives.html#directive-%ConvertToSubClassCode"><tt class="xref docutils literal"><span class="pre">%ConvertToSubClassCode</span></tt></a> code.</p> |
|
<div class="admonition note"> |
|
<p class="first admonition-title">Note</p> |
|
<p class="last">This is deprecated from SIP v4.8. Instead you should use |
|
<a title="sipConvertFromNewType" class="reference internal" href="#sipConvertFromNewType"><tt class="xref docutils literal"><span class="pre">sipConvertFromNewType()</span></tt></a>.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipConvertFromNewType"> |
|
PyObject *<tt class="descname">sipConvertFromNewType</tt><big>(</big>void<em> *cpp</em>, const sipTypeDef<em> *td</em>, PyObject<em> *transferObj</em><big>)</big><a class="headerlink" href="#sipConvertFromNewType" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This converts a new C structure or a C++ class instance to an instance of |
|
the corresponding generated Python type.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>cpp</em> – the C/C++ instance.</li> |
|
<li><em>td</em> – the type’s <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a>.</li> |
|
<li><em>transferObj</em> – this controls the ownership of the returned value.</li> |
|
</ul> |
|
</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the Python object.</p> |
|
</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">NULL</span></tt> or <tt class="docutils literal"><span class="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 |
|
<a class="reference external" href="directives.html#directive-%ConvertToSubClassCode"><tt class="xref docutils literal"><span class="pre">%ConvertToSubClassCode</span></tt></a> code.</p> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipConvertFromSequenceIndex"> |
|
<a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a> <tt class="descname">sipConvertFromSequenceIndex</tt><big>(</big><a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> idx</em>, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> len</em><big>)</big><a class="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 |
|
exception raised.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>idx</em> – the sequence index.</li> |
|
<li><em>len</em> – the length of the sequence.</li> |
|
</ul> |
|
</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the unsigned array index.</p> |
|
</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipConvertFromSliceObject"> |
|
int <tt class="descname">sipConvertFromSliceObject</tt><big>(</big>PyObject<em> *slice</em>, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> length</em>, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> *start</em>, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> *stop</em>, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> *step</em>, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> *slicelength</em><big>)</big><a class="headerlink" href="#sipConvertFromSliceObject" title="Permalink to this definition">¶</a></dt> |
|
<dd>This is a thin wrapper around the Python <tt class="xref docutils literal"><span class="pre">PySlice_GetIndicesEx()</span></tt> |
|
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.</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipConvertFromType"> |
|
PyObject *<tt class="descname">sipConvertFromType</tt><big>(</big>void<em> *cpp</em>, const sipTypeDef<em> *td</em>, PyObject<em> *transferObj</em><big>)</big><a class="headerlink" href="#sipConvertFromType" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This converts a C structure or a C++ class instance to an instance of the |
|
corresponding generated Python type.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>cpp</em> – the C/C++ instance.</li> |
|
<li><em>td</em> – the type’s <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a>.</li> |
|
<li><em>transferObj</em> – this controls the ownership of the returned value.</li> |
|
</ul> |
|
</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the Python object.</p> |
|
</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
<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 <tt class="docutils literal"><span class="pre">NULL</span></tt> and the instance has already been wrapped then |
|
the ownership is unchanged.</p> |
|
<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">NULL</span></tt> and the instance is newly wrapped then |
|
ownership will be with C/C++.</p> |
|
<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership is transferred to Python via |
|
a call to <a title="sipTransferBack" class="reference internal" href="#sipTransferBack"><tt class="xref docutils literal"><span class="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 <a title="sipTransferTo" class="reference internal" href="#sipTransferTo"><tt class="xref docutils literal"><span class="pre">sipTransferTo()</span></tt></a>.</p> |
|
<p>The Python class is influenced by any applicable |
|
<a class="reference external" href="directives.html#directive-%ConvertToSubClassCode"><tt class="xref docutils literal"><span class="pre">%ConvertToSubClassCode</span></tt></a> code.</p> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipConvertFromVoidPtr"> |
|
PyObject *<tt class="descname">sipConvertFromVoidPtr</tt><big>(</big>void<em> *cpp</em><big>)</big><a class="headerlink" href="#sipConvertFromVoidPtr" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This creates a <a title="sip.voidptr" class="reference external" href="python_api.html#sip.voidptr"><tt class="xref docutils literal"><span class="pre">sip.voidptr</span></tt></a> object for a memory address. The |
|
object will be writeable but has no associated size.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>cpp</em> – the memory address.</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the <a title="sip.voidptr" class="reference external" href="python_api.html#sip.voidptr"><tt class="xref docutils literal"><span class="pre">sip.voidptr</span></tt></a> object.</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipConvertFromVoidPtrAndSize"> |
|
PyObject *<tt class="descname">sipConvertFromVoidPtrAndSize</tt><big>(</big>void<em> *cpp</em>, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> size</em><big>)</big><a class="headerlink" href="#sipConvertFromVoidPtrAndSize" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This creates a <a title="sip.voidptr" class="reference external" href="python_api.html#sip.voidptr"><tt class="xref docutils literal"><span class="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> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>cpp</em> – the memory address.</li> |
|
<li><em>size</em> – the size associated with the address.</li> |
|
</ul> |
|
</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the <a title="sip.voidptr" class="reference external" href="python_api.html#sip.voidptr"><tt class="xref docutils literal"><span class="pre">sip.voidptr</span></tt></a> object.</p> |
|
</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipConvertToInstance"> |
|
void *<tt class="descname">sipConvertToInstance</tt><big>(</big>PyObject<em> *obj</em>, <a title="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><a class="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 <a title="sipCanConvertToInstance" class="reference internal" href="#sipCanConvertToInstance"><tt class="xref docutils literal"><span class="pre">sipCanConvertToInstance()</span></tt></a> has |
|
been successful.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>obj</em> – the Python object.</li> |
|
<li><em>type</em> – the type’s <a class="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 <a title="SIP_NOT_NONE" class="reference internal" href="#SIP_NOT_NONE"><tt class="xref docutils literal"><span class="pre">SIP_NOT_NONE</span></tt></a> and |
|
<a title="SIP_NO_CONVERTORS" class="reference internal" href="#SIP_NO_CONVERTORS"><tt class="xref docutils literal"><span class="pre">SIP_NO_CONVERTORS</span></tt></a> flags.</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> |
|
</ul> |
|
</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the C/C++ instance.</p> |
|
</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the ownership is unchanged.</p> |
|
<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership is transferred to Python via |
|
a call to <a title="sipTransferBack" class="reference internal" href="#sipTransferBack"><tt class="xref docutils literal"><span class="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 <a title="sipTransferTo" class="reference internal" href="#sipTransferTo"><tt class="xref docutils literal"><span class="pre">sipTransferTo()</span></tt></a>.</p> |
|
<p>If <em>state</em> is not <tt class="docutils literal"><span class="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 <a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a>. The calling code must then release |
|
the value at some point to prevent a memory leak by calling |
|
<a title="sipReleaseInstance" class="reference internal" href="#sipReleaseInstance"><tt class="xref docutils literal"><span class="pre">sipReleaseInstance()</span></tt></a>.</p> |
|
<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> |
|
<div class="admonition note"> |
|
<p class="first admonition-title">Note</p> |
|
<p class="last">This is deprecated from SIP v4.8. Instead you should use |
|
<a title="sipConvertToType" class="reference internal" href="#sipConvertToType"><tt class="xref docutils literal"><span class="pre">sipConvertToType()</span></tt></a>.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipConvertToMappedType"> |
|
void *<tt class="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><a class="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 |
|
<a title="sipCanConvertToMappedType" class="reference internal" href="#sipCanConvertToMappedType"><tt class="xref docutils literal"><span class="pre">sipCanConvertToMappedType()</span></tt></a> has been successful.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>obj</em> – the Python object.</li> |
|
<li><em>mt</em> – the opaque structure returned by <a title="sipFindMappedType" class="reference internal" href="#sipFindMappedType"><tt class="xref docutils literal"><span class="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 <a title="SIP_NOT_NONE" class="reference internal" href="#SIP_NOT_NONE"><tt class="xref docutils literal"><span class="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> |
|
</ul> |
|
</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the C/C++ instance.</p> |
|
</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the ownership is unchanged.</p> |
|
<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership is transferred to Python via |
|
a call to <a title="sipTransferBack" class="reference internal" href="#sipTransferBack"><tt class="xref docutils literal"><span class="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 <a title="sipTransferTo" class="reference internal" href="#sipTransferTo"><tt class="xref docutils literal"><span class="pre">sipTransferTo()</span></tt></a>.</p> |
|
<p>If <em>state</em> is not <tt class="docutils literal"><span class="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 <a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a>. The calling code must then release |
|
the value at some point to prevent a memory leak by calling |
|
<a title="sipReleaseMappedType" class="reference internal" href="#sipReleaseMappedType"><tt class="xref docutils literal"><span class="pre">sipReleaseMappedType()</span></tt></a>.</p> |
|
<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> |
|
<div class="admonition note"> |
|
<p class="first admonition-title">Note</p> |
|
<p class="last">This is deprecated from SIP v4.8. Instead you should use |
|
<a title="sipConvertToType" class="reference internal" href="#sipConvertToType"><tt class="xref docutils literal"><span class="pre">sipConvertToType()</span></tt></a></p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipConvertToType"> |
|
void *<tt class="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><a class="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 <a title="sipCanConvertToType" class="reference internal" href="#sipCanConvertToType"><tt class="xref docutils literal"><span class="pre">sipCanConvertToType()</span></tt></a> |
|
has been successful.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>obj</em> – the Python object.</li> |
|
<li><em>td</em> – the type’s <a class="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 <a title="SIP_NOT_NONE" class="reference internal" href="#SIP_NOT_NONE"><tt class="xref docutils literal"><span class="pre">SIP_NOT_NONE</span></tt></a> and |
|
<a title="SIP_NO_CONVERTORS" class="reference internal" href="#SIP_NO_CONVERTORS"><tt class="xref docutils literal"><span class="pre">SIP_NO_CONVERTORS</span></tt></a> flags.</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> |
|
</ul> |
|
</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the C/C++ instance.</p> |
|
</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the ownership is unchanged. If it is |
|
<tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership is transferred to Python via a call to |
|
<a title="sipTransferBack" class="reference internal" href="#sipTransferBack"><tt class="xref docutils literal"><span class="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 <a title="sipTransferTo" class="reference internal" href="#sipTransferTo"><tt class="xref docutils literal"><span class="pre">sipTransferTo()</span></tt></a>.</p> |
|
<p>If <em>state</em> is not <tt class="docutils literal"><span class="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 <a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a>. The calling code must then release |
|
the value at some point to prevent a memory leak by calling |
|
<a title="sipReleaseType" class="reference internal" href="#sipReleaseType"><tt class="xref docutils literal"><span class="pre">sipReleaseType()</span></tt></a>.</p> |
|
<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> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipConvertToVoidPtr"> |
|
void *<tt class="descname">sipConvertToVoidPtr</tt><big>(</big>PyObject<em> *obj</em><big>)</big><a class="headerlink" href="#sipConvertToVoidPtr" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This converts a Python object to a memory address. |
|
<tt class="xref docutils literal"><span class="pre">PyErr_Occurred()</span></tt> must be used to determine if the conversion was |
|
successful.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>obj</em> – the Python object which may be <tt class="docutils literal"><span class="pre">Py_None</span></tt>, a <a title="sip.voidptr" class="reference external" href="python_api.html#sip.voidptr"><tt class="xref docutils literal"><span class="pre">sip.voidptr</span></tt></a> or a |
|
<tt class="xref docutils literal"><span class="pre">PyCObject</span></tt>.</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the memory address.</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipExportSymbol"> |
|
int <tt class="descname">sipExportSymbol</tt><big>(</big>const char<em> *name</em>, void<em> *sym</em><big>)</big><a class="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 <a title="sipImportSymbol" class="reference internal" href="#sipImportSymbol"><tt class="xref docutils literal"><span class="pre">sipImportSymbol()</span></tt></a>, by |
|
another module.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>name</em> – the name of the symbol.</li> |
|
<li><em>sym</em> – the value of the symbol.</li> |
|
</ul> |
|
</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="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> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipFindClass"> |
|
<a title="sipWrapperType" class="reference internal" href="#sipWrapperType">sipWrapperType</a> *<tt class="descname">sipFindClass</tt><big>(</big>const char<em> *type</em><big>)</big><a class="headerlink" href="#sipFindClass" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This returns a pointer to the <a class="reference internal" href="#ref-type-objects"><em>generated type object |
|
</em></a> corresponding to a C/C++ type.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>type</em> – the C/C++ declaration of the type.</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the generated type object. This will not change and may be saved in a |
|
static cache. <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned if the C/C++ type doesn’t exist.</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
<div class="admonition note"> |
|
<p class="first admonition-title">Note</p> |
|
<p class="last">This is deprecated from SIP v4.8. Instead you should use |
|
<a title="sipFindType" class="reference internal" href="#sipFindType"><tt class="xref docutils literal"><span class="pre">sipFindType()</span></tt></a>.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipFindMappedType"> |
|
const sipMappedType *<tt class="descname">sipFindMappedType</tt><big>(</big>const char<em> *type</em><big>)</big><a class="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> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>type</em> – the C/C++ declaration of the type.</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the opaque structure. This will not change and may be saved in a |
|
static cache. <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned if the C/C++ type doesn’t exist.</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
<div class="admonition note"> |
|
<p class="first admonition-title">Note</p> |
|
<p class="last">This is deprecated from SIP v4.8. Instead you should use |
|
<a title="sipFindType" class="reference internal" href="#sipFindType"><tt class="xref docutils literal"><span class="pre">sipFindType()</span></tt></a>.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipFindNamedEnum"> |
|
PyTypeObject *<tt class="descname">sipFindNamedEnum</tt><big>(</big>const char<em> *type</em><big>)</big><a class="headerlink" href="#sipFindNamedEnum" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This returns a pointer to the <a class="reference internal" href="#ref-enum-type-objects"><em>generated Python type object</em></a> corresponding to a named C/C++ enum.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>type</em> – the C/C++ declaration of the enum.</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the generated Python type object. This will not change and may be |
|
saved in a static cache. <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned if the C/C++ enum |
|
doesn’t exist.</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
<div class="admonition note"> |
|
<p class="first admonition-title">Note</p> |
|
<p class="last">This is deprecated from SIP v4.8. Instead you should use |
|
<a title="sipFindType" class="reference internal" href="#sipFindType"><tt class="xref docutils literal"><span class="pre">sipFindType()</span></tt></a>.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipFindType"> |
|
const sipTypeDef *<tt class="descname">sipFindType</tt><big>(</big>const char<em> *type</em><big>)</big><a class="headerlink" href="#sipFindType" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This returns a pointer to the <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a> corresponding to a C/C++ type.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>type</em> – the C/C++ declaration of the type.</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the generated type structure. This will not change and may be saved in |
|
a static cache. <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned if the C/C++ type doesn’t exist.</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipForceConvertToInstance"> |
|
void *<tt class="descname">sipForceConvertToInstance</tt><big>(</big>PyObject<em> *obj</em>, <a title="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><a class="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 <a title="sipCanConvertToInstance" class="reference internal" href="#sipCanConvertToInstance"><tt class="xref docutils literal"><span class="pre">sipCanConvertToInstance()</span></tt></a> and, if it is successfull, |
|
calling <a title="sipConvertToInstance" class="reference internal" href="#sipConvertToInstance"><tt class="xref docutils literal"><span class="pre">sipConvertToInstance()</span></tt></a>.</p> |
|
<p>See <a title="sipConvertToInstance" class="reference internal" href="#sipConvertToInstance"><tt class="xref docutils literal"><span class="pre">sipConvertToInstance()</span></tt></a> for a full description of the |
|
arguments.</p> |
|
<div class="admonition note"> |
|
<p class="first admonition-title">Note</p> |
|
<p class="last">This is deprecated from SIP v4.8. Instead you should use |
|
<a title="sipForceConvertToType" class="reference internal" href="#sipForceConvertToType"><tt class="xref docutils literal"><span class="pre">sipForceConvertToType()</span></tt></a>.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipForceConvertToMappedType"> |
|
void *<tt class="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><a class="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 |
|
<a title="sipCanConvertToMappedType" class="reference internal" href="#sipCanConvertToMappedType"><tt class="xref docutils literal"><span class="pre">sipCanConvertToMappedType()</span></tt></a> and, if it is successfull, calling |
|
<a title="sipConvertToMappedType" class="reference internal" href="#sipConvertToMappedType"><tt class="xref docutils literal"><span class="pre">sipConvertToMappedType()</span></tt></a>.</p> |
|
<p>See <a title="sipConvertToMappedType" class="reference internal" href="#sipConvertToMappedType"><tt class="xref docutils literal"><span class="pre">sipConvertToMappedType()</span></tt></a> for a full description of the |
|
arguments.</p> |
|
<div class="admonition note"> |
|
<p class="first admonition-title">Note</p> |
|
<p class="last">This is deprecated from SIP v4.8. Instead you should use |
|
<a title="sipForceConvertToType" class="reference internal" href="#sipForceConvertToType"><tt class="xref docutils literal"><span class="pre">sipForceConvertToType()</span></tt></a>.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipForceConvertToType"> |
|
void *<tt class="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><a class="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 <a title="sipCanConvertToType" class="reference internal" href="#sipCanConvertToType"><tt class="xref docutils literal"><span class="pre">sipCanConvertToType()</span></tt></a> and, if it is |
|
successfull, calling <a title="sipConvertToType" class="reference internal" href="#sipConvertToType"><tt class="xref docutils literal"><span class="pre">sipConvertToType()</span></tt></a>.</p> |
|
<p>See <a title="sipConvertToType" class="reference internal" href="#sipConvertToType"><tt class="xref docutils literal"><span class="pre">sipConvertToType()</span></tt></a> for a full description of the arguments.</p> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipFree"> |
|
void <tt class="descname">sipFree</tt><big>(</big>void<em> *mem</em><big>)</big><a class="headerlink" href="#sipFree" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This returns an area of memory allocated by <a title="sipMalloc" class="reference internal" href="#sipMalloc"><tt class="xref docutils literal"><span class="pre">sipMalloc()</span></tt></a> to the |
|
heap.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>mem</em> – the memory address.</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipGetPyObject"> |
|
PyObject *<tt class="descname">sipGetPyObject</tt><big>(</big>void<em> *cppptr</em>, const sipTypeDef<em> *td</em><big>)</big><a class="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 |
|
C++ class instance.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>cppptr</em> – the pointer to the C/C++ instance.</li> |
|
<li><em>td</em> – the <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a> corresponding |
|
to the C/C++ type.</li> |
|
</ul> |
|
</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the Python object or <tt class="docutils literal"><span class="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> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipGetState"> |
|
int <tt class="descname">sipGetState</tt><big>(</big>PyObject<em> *transferObj</em><big>)</big><a class="headerlink" href="#sipGetState" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>The <a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a> directive requires that the provided |
|
code returns an <tt class="docutils literal"><span class="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 |
|
when the converted value is a temporary.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>transferObj</em> – the object that describes the requested transfer of ownership.</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the state of the converted value.</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipGetWrapper"> |
|
PyObject *<tt class="descname">sipGetWrapper</tt><big>(</big>void<em> *cppptr</em>, <a title="sipWrapperType" class="reference internal" href="#sipWrapperType">sipWrapperType</a><em> *type</em><big>)</big><a class="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 |
|
structure or C++ class instance.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>cppptr</em> – the pointer to the C/C++ instance.</li> |
|
<li><em>type</em> – the <a class="reference internal" href="#ref-type-objects"><em>generated type object</em></a> corresponding to |
|
the C/C++ type.</li> |
|
</ul> |
|
</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the Python object or <tt class="docutils literal"><span class="pre">NULL</span></tt> (and no exception is raised) if the |
|
C/C++ instance hasn’t been wrapped.</p> |
|
</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
<div class="admonition note"> |
|
<p class="first admonition-title">Note</p> |
|
<p class="last">This is deprecated from SIP v4.8. Instead you should use |
|
<a title="sipGetPyObject" class="reference internal" href="#sipGetPyObject"><tt class="xref docutils literal"><span class="pre">sipGetPyObject()</span></tt></a>.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipImportSymbol"> |
|
void *<tt class="descname">sipImportSymbol</tt><big>(</big>const char<em> *name</em><big>)</big><a class="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 <a title="sipExportSymbol" class="reference internal" href="#sipExportSymbol"><tt class="xref docutils literal"><span class="pre">sipExportSymbol()</span></tt></a>, by |
|
another module.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>name</em> – the name of the symbol.</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the value of the symbol. <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned if there is no such |
|
symbol.</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
</dd></dl> |
|
|
|
<dl class="ctype"> |
|
<dt id="sipIntTypeClassMap"> |
|
<tt class="descname">sipIntTypeClassMap</tt><a class="headerlink" href="#sipIntTypeClassMap" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This C structure is used with <a title="sipMapIntToClass" class="reference internal" href="#sipMapIntToClass"><tt class="xref docutils literal"><span class="pre">sipMapIntToClass()</span></tt></a> to define a |
|
mapping between integer based RTTI and <a class="reference internal" href="#ref-type-objects"><em>generated type objects</em></a>. The structure elements are as follows.</p> |
|
<dl class="cmember"> |
|
<dt id="typeInt"> |
|
int <tt class="descname">typeInt</tt><a class="headerlink" href="#typeInt" title="Permalink to this definition">¶</a></dt> |
|
<dd>The integer RTTI.</dd></dl> |
|
|
|
<dl class="cmember"> |
|
<dt> |
|
<tt class="descname">sipWrapperType **pyType.</tt></dt> |
|
<dd>A pointer to the corresponding generated type object.</dd></dl> |
|
|
|
<div class="admonition note"> |
|
<p class="first admonition-title">Note</p> |
|
<p class="last">This is deprecated from SIP v4.8.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipIsAPIEnabled"> |
|
int <tt class="descname">sipIsAPIEnabled</tt><big>(</big>const char<em> *name</em>, int<em> from</em>, int<em> to</em><big>)</big><a class="headerlink" href="#sipIsAPIEnabled" title="Permalink to this definition">¶</a></dt> |
|
<dd><p> |
|
<span class="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 <a class="reference external" href="using.html#ref-incompat-apis"><em>Managing Incompatible APIs</em></a> for more detail.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<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> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">a non-zero value if the API is enabled.</p> |
|
</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipLong_AsUnsignedLong"> |
|
unsigned long <tt class="descname">sipLong_AsUnsignedLong</tt><big>(</big>PyObject<em> *obj</em><big>)</big><a class="headerlink" href="#sipLong_AsUnsignedLong" title="Permalink to this definition">¶</a></dt> |
|
<dd>This function is a thin wrapper around <tt class="xref docutils literal"><span class="pre">PyLong_AsUnsignedLong()</span></tt> |
|
that works around a bug in Python v2.3.x and earlier when converting |
|
integer objects.</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipMalloc"> |
|
void *<tt class="descname">sipMalloc</tt><big>(</big>size_t<em> nbytes</em><big>)</big><a class="headerlink" href="#sipMalloc" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This allocates an area of memory on the heap using the Python |
|
<tt class="xref docutils literal"><span class="pre">PyMem_Malloc()</span></tt> function. The memory is freed by calling |
|
<a title="sipFree" class="reference internal" href="#sipFree"><tt class="xref docutils literal"><span class="pre">sipFree()</span></tt></a>.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>nbytes</em> – the number of bytes to allocate.</td> |
|
</tr> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the memory address. If there was an error then <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned |
|
and a Python exception raised.</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipMapIntToClass"> |
|
<a title="sipWrapperType" class="reference internal" href="#sipWrapperType">sipWrapperType</a> *<tt class="descname">sipMapIntToClass</tt><big>(</big>int<em> type</em>, const <a title="sipIntTypeClassMap" class="reference internal" href="#sipIntTypeClassMap">sipIntTypeClassMap</a><em> *map</em>, int<em> maplen</em><big>)</big><a class="headerlink" href="#sipMapIntToClass" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This can be used in <a class="reference external" href="directives.html#directive-%ConvertToSubClassCode"><tt class="xref docutils literal"><span class="pre">%ConvertToSubClassCode</span></tt></a> code as a |
|
convenient way of converting integer based RTTI to the corresponding |
|
<a class="reference internal" href="#ref-type-objects"><em>generated type object</em></a>.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>type</em> – the integer RTTI.</li> |
|
<li><em>map</em> – the table of known RTTI and the corresponding type objects (see |
|
<a title="sipIntTypeClassMap" class="reference internal" href="#sipIntTypeClassMap"><tt class="xref docutils literal"><span class="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> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the corresponding type object, or <tt class="docutils literal"><span class="pre">NULL</span></tt> if <em>type</em> wasn’t in <em>map</em>.</p> |
|
</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
<div class="admonition note"> |
|
<p class="first admonition-title">Note</p> |
|
<p class="last">This is deprecated from SIP v4.8.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|
<dt id="sipMapStringToClass"> |
|
<a title="sipWrapperType" class="reference internal" href="#sipWrapperType">sipWrapperType</a> *<tt class="descname">sipMapStringToClass</tt><big>(</big>char<em> *type</em>, const <a title="sipStringTypeClassMap" class="reference internal" href="#sipStringTypeClassMap">sipStringTypeClassMap</a><em> *map</em>, int<em> maplen</em><big>)</big><a class="headerlink" href="#sipMapStringToClass" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This can be used in <a class="reference external" href="directives.html#directive-%ConvertToSubClassCode"><tt class="xref docutils literal"><span class="pre">%ConvertToSubClassCode</span></tt></a> code as a |
|
convenient way of converting <tt class="docutils literal"><span class="pre">'\0'</span></tt> terminated string based RTTI to the |
|
corresponding <a class="reference internal" href="#ref-type-objects"><em>generated type object</em></a>.</p> |
|
<table class="docutils field-list" frame="void" rules="none"> |
|
<col class="field-name" /> |
|
<col class="field-body" /> |
|
<tbody valign="top"> |
|
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> |
|
<li><em>type</em> – the string RTTI.</li> |
|
<li><em>map</em> – the table of known RTTI and the corresponding type objects (see |
|
<a title="sipStringTypeClassMap" class="reference internal" href="#sipStringTypeClassMap"><tt class="xref docutils literal"><span class="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> |
|
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the corresponding type object, or <tt class="docutils literal"><span class="pre">NULL</span></tt> if <em>type</em> wasn’t in <em>map</em>.</p> |
|
</td> |
|
</tr> |
|
</tbody> |
|
</table> |
|
<div class="admonition note"> |
|
<p class="first admonition-title">Note</p> |
|
<p class="last">This is deprecated from SIP v4.8.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="cfunction"> |
|