blob: 1a61175fe22643a13bb6d0402879ca2130d172d9 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
<!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>Using the C API when Embedding — 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="Python API for Applications" href="python_api.html" />
<link rel="prev" title="C API for Handwritten Code" href="c_api.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="python_api.html" title="Python API for Applications"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="c_api.html" title="C API for Handwritten Code"
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="using-the-c-api-when-embedding">
<h1>Using the C API when Embedding<a class="headerlink" href="#using-the-c-api-when-embedding" title="Permalink to this headline">ΒΆ</a></h1>
<p>The <a class="reference external" href="c_api.html#ref-c-api"><em>C API</em></a> is intended to be called from handwritten code in
SIP generated modules. However it is also often necessary to call it from C or
C++ applications that embed the Python interpreter and need to pass C or C++
instances between the application and the interpreter.</p>
<p>The API is exported by the SIP module as a <tt class="docutils literal"><span class="pre">sipAPIDef</span></tt> data structure
containing a set of function pointers. The data structure is defined in the
SIP header file <tt class="docutils literal"><span class="pre">sip.h</span></tt>. The data structure is wrapped as a Python
<tt class="docutils literal"><span class="pre">PyCObject</span></tt> object and is referenced by the name <tt class="docutils literal"><span class="pre">_C_API</span></tt> in the SIP
module dictionary.</p>
<p>Each member of the data structure is a pointer to one of the functions of the
SIP API. The name of the member can be derived from the function name by
replacing the <tt class="docutils literal"><span class="pre">sip</span></tt> prefix with <tt class="docutils literal"><span class="pre">api</span></tt> and converting each word in the
name to lower case and preceding it with an underscore. For example:</p>
<blockquote>
<p><tt class="docutils literal"><span class="pre">sipExportSymbol</span></tt> becomes <tt class="docutils literal"><span class="pre">api_export_symbol</span></tt></p>
<p><tt class="docutils literal"><span class="pre">sipWrapperCheck</span></tt> becomes <tt class="docutils literal"><span class="pre">api_wrapper_check</span></tt></p>
</blockquote>
<p>Note that the type objects that SIP generates for a wrapped module (see
<a class="reference external" href="c_api.html#ref-type-structures"><em>Generated Type Structures</em></a>, <a class="reference external" href="c_api.html#ref-enum-type-objects"><em>Generated Named Enum Type Objects</em></a> and
<a class="reference external" href="c_api.html#ref-exception-objects"><em>Generated Exception Objects</em></a>) cannot be refered to directly and must be
obtained using the <a title="sipFindType" class="reference external" href="c_api.html#sipFindType"><tt class="xref docutils literal"><span class="pre">sipFindType()</span></tt></a> function. Of course, the
corresponding modules must already have been imported into the interpreter.</p>
<p>The following code fragment shows how to get a pointer to the <tt class="docutils literal"><span class="pre">sipAPIDef</span></tt>
data structure:</p>
<div class="highlight-python"><pre>#include <sip.h>
const sipAPIDef *get_sip_api()
{
PyObject *sip_module;
PyObject *sip_module_dict;
PyObject *c_api;
/* Import the SIP module. */
sip_module = PyImport_ImportModule("sip");
if (sip_module == NULL)
return NULL;
/* Get the module's dictionary. */
sip_module_dict = PyModule_GetDict(sip_module);
/* Get the "_C_API" attribute. */
c_api = PyDict_GetItemString(sip_module_dict, "_C_API");
if (c_api == NULL)
return NULL;
/* Sanity check that it is the right type. */
if (!PyCObject_Check(c_api))
return NULL;
/* Get the actual pointer from the object. */
return (const sipAPIDef *)PyCObject_AsVoidPtr(c_api);
}</pre>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="c_api.html"
title="previous chapter">C API for Handwritten Code</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="python_api.html"
title="next chapter">Python API for Applications</a></p>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="modindex.html" title="Global Module Index"
>modules</a> |</li>
<li class="right" >
<a href="python_api.html" title="Python API for Applications"
>next</a> |</li>
<li class="right" >
<a href="c_api.html" title="C API for Handwritten Code"
>previous</a> |</li>
<li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2010 Riverbank Computing Limited.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4.
</div>
</body>
</html>
|
