1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5 <title>GObject Introspection Reference Manual: girffi</title>
6 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
7 <link rel="home" href="index.html" title="GObject Introspection Reference Manual">
8 <link rel="up" href="ch03.html" title="TODO">
9 <link rel="prev" href="ch03.html" title="TODO">
10 <link rel="next" href="gi-gir-reference.html" title="The GIR XML format">
11 <meta name="generator" content="GTK-Doc V1.19.1 (XML mode)">
12 <link rel="stylesheet" href="style.css" type="text/css">
14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle">
16 <td width="100%" align="left">
17 <a href="#" class="shortcut">Top</a>
19 <a href="#gi-girffi.description" class="shortcut">Description</a>
21 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
22 <td><a accesskey="u" href="ch03.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
23 <td><a accesskey="p" href="ch03.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
24 <td><a accesskey="n" href="gi-gir-reference.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
26 <div class="refentry">
27 <a name="gi-girffi"></a><div class="titlepage"></div>
28 <div class="refnamediv"><table width="100%"><tr>
30 <h2><span class="refentrytitle"><a name="gi-girffi.top_of_page"></a>girffi</span></h2>
33 <td valign="top" align="right"></td>
35 <div class="refsynopsisdiv">
36 <a name="gi-girffi.synopsis"></a><h2>Synopsis</h2>
37 <pre class="synopsis"><span class="returnvalue">void</span> (<a class="link" href="gi-girffi.html#GIFFIClosureCallback" title="GIFFIClosureCallback ()">*GIFFIClosureCallback</a>) (<em class="parameter"><code><span class="type">ffi_cif</span> *Param1</code></em>,
38 <em class="parameter"><code><span class="type">void</span> *Param2</code></em>,
39 <em class="parameter"><code><span class="type">void</span> **Param3</code></em>,
40 <em class="parameter"><code><span class="type">void</span> *Param4</code></em>);
41 struct <a class="link" href="gi-girffi.html#GIFunctionInvoker" title="struct GIFunctionInvoker">GIFunctionInvoker</a>;
42 typedef <a class="link" href="gi-girffi.html#GIFFIReturnValue" title="GIFFIReturnValue">GIFFIReturnValue</a>;
43 <span class="returnvalue">ffi_type</span> * <a class="link" href="gi-girffi.html#gi-type-tag-get-ffi-type" title="gi_type_tag_get_ffi_type ()">gi_type_tag_get_ffi_type</a> (<em class="parameter"><code><a class="link" href="gi-common-types.html#GITypeTag" title="enum GITypeTag"><span class="type">GITypeTag</span></a> type_tag</code></em>,
44 <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> is_pointer</code></em>);
45 <span class="returnvalue">ffi_type</span> * <a class="link" href="gi-girffi.html#g-type-info-get-ffi-type" title="g_type_info_get_ffi_type ()">g_type_info_get_ffi_type</a> (<em class="parameter"><code><a class="link" href="gi-GITypeInfo.html#GITypeInfo" title="GITypeInfo"><span class="type">GITypeInfo</span></a> *info</code></em>);
46 <span class="returnvalue">void</span> <a class="link" href="gi-girffi.html#gi-type-info-extract-ffi-return-value" title="gi_type_info_extract_ffi_return_value ()">gi_type_info_extract_ffi_return_value</a>
47 (<em class="parameter"><code><a class="link" href="gi-GITypeInfo.html#GITypeInfo" title="GITypeInfo"><span class="type">GITypeInfo</span></a> *return_info</code></em>,
48 <em class="parameter"><code><a class="link" href="gi-girffi.html#GIFFIReturnValue" title="GIFFIReturnValue"><span class="type">GIFFIReturnValue</span></a> *ffi_value</code></em>,
49 <em class="parameter"><code><a class="link" href="gi-common-types.html#GIArgument" title="union GIArgument"><span class="type">GIArgument</span></a> *arg</code></em>);
50 <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> <a class="link" href="gi-girffi.html#g-function-info-prep-invoker" title="g_function_info_prep_invoker ()">g_function_info_prep_invoker</a> (<em class="parameter"><code><a class="link" href="gi-GIFunctionInfo.html#GIFunctionInfo" title="GIFunctionInfo"><span class="type">GIFunctionInfo</span></a> *info</code></em>,
51 <em class="parameter"><code><a class="link" href="gi-girffi.html#GIFunctionInvoker" title="struct GIFunctionInvoker"><span class="type">GIFunctionInvoker</span></a> *invoker</code></em>,
52 <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);
53 <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> <a class="link" href="gi-girffi.html#g-function-invoker-new-for-address" title="g_function_invoker_new_for_address ()">g_function_invoker_new_for_address</a> (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> addr</code></em>,
54 <em class="parameter"><code><a class="link" href="gi-GICallableInfo.html#GICallableInfo" title="GICallableInfo"><span class="type">GICallableInfo</span></a> *info</code></em>,
55 <em class="parameter"><code><a class="link" href="gi-girffi.html#GIFunctionInvoker" title="struct GIFunctionInvoker"><span class="type">GIFunctionInvoker</span></a> *invoker</code></em>,
56 <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);
57 <span class="returnvalue">void</span> <a class="link" href="gi-girffi.html#g-function-invoker-destroy" title="g_function_invoker_destroy ()">g_function_invoker_destroy</a> (<em class="parameter"><code><a class="link" href="gi-girffi.html#GIFunctionInvoker" title="struct GIFunctionInvoker"><span class="type">GIFunctionInvoker</span></a> *invoker</code></em>);
58 <span class="returnvalue">ffi_closure</span> * <a class="link" href="gi-girffi.html#g-callable-info-prepare-closure" title="g_callable_info_prepare_closure ()">g_callable_info_prepare_closure</a> (<em class="parameter"><code><a class="link" href="gi-GICallableInfo.html#GICallableInfo" title="GICallableInfo"><span class="type">GICallableInfo</span></a> *callable_info</code></em>,
59 <em class="parameter"><code><span class="type">ffi_cif</span> *cif</code></em>,
60 <em class="parameter"><code><a class="link" href="gi-girffi.html#GIFFIClosureCallback" title="GIFFIClosureCallback ()"><span class="type">GIFFIClosureCallback</span></a> callback</code></em>,
61 <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
62 <span class="returnvalue">void</span> <a class="link" href="gi-girffi.html#g-callable-info-free-closure" title="g_callable_info_free_closure ()">g_callable_info_free_closure</a> (<em class="parameter"><code><a class="link" href="gi-GICallableInfo.html#GICallableInfo" title="GICallableInfo"><span class="type">GICallableInfo</span></a> *callable_info</code></em>,
63 <em class="parameter"><code><span class="type">ffi_closure</span> *closure</code></em>);
66 <div class="refsect1">
67 <a name="gi-girffi.description"></a><h2>Description</h2>
72 <div class="refsect1">
73 <a name="gi-girffi.details"></a><h2>Details</h2>
74 <div class="refsect2">
75 <a name="GIFFIClosureCallback"></a><h3>GIFFIClosureCallback ()</h3>
76 <pre class="programlisting"><span class="returnvalue">void</span> (*GIFFIClosureCallback) (<em class="parameter"><code><span class="type">ffi_cif</span> *Param1</code></em>,
77 <em class="parameter"><code><span class="type">void</span> *Param2</code></em>,
78 <em class="parameter"><code><span class="type">void</span> **Param3</code></em>,
79 <em class="parameter"><code><span class="type">void</span> *Param4</code></em>);</pre>
83 <div class="variablelist"><table border="0" class="variablelist">
85 <col align="left" valign="top">
90 <td><p><span class="term"><em class="parameter"><code>Param1</code></em> :</span></p></td>
94 <td><p><span class="term"><em class="parameter"><code>Param2</code></em> :</span></p></td>
98 <td><p><span class="term"><em class="parameter"><code>Param3</code></em> :</span></p></td>
102 <td><p><span class="term"><em class="parameter"><code>Param4</code></em> :</span></p></td>
109 <div class="refsect2">
110 <a name="GIFunctionInvoker"></a><h3>struct GIFunctionInvoker</h3>
111 <pre class="programlisting">struct GIFunctionInvoker {
113 gpointer native_address;
119 <div class="variablelist"><table border="0" class="variablelist">
121 <col align="left" valign="top">
126 <td><p><span class="term"><span class="type">ffi_cif</span> <em class="structfield"><code><a name="GIFunctionInvoker.cif"></a>cif</code></em>;</span></p></td>
130 <td><p><span class="term"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> <em class="structfield"><code><a name="GIFunctionInvoker.native-address"></a>native_address</code></em>;</span></p></td>
131 <td>the native address</td>
137 <div class="refsect2">
138 <a name="GIFFIReturnValue"></a><h3>GIFFIReturnValue</h3>
139 <pre class="programlisting">typedef GIArgument GIFFIReturnValue;
146 <div class="refsect2">
147 <a name="gi-type-tag-get-ffi-type"></a><h3>gi_type_tag_get_ffi_type ()</h3>
148 <pre class="programlisting"><span class="returnvalue">ffi_type</span> * gi_type_tag_get_ffi_type (<em class="parameter"><code><a class="link" href="gi-common-types.html#GITypeTag" title="enum GITypeTag"><span class="type">GITypeTag</span></a> type_tag</code></em>,
149 <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> is_pointer</code></em>);</pre>
153 <div class="variablelist"><table border="0" class="variablelist">
155 <col align="left" valign="top">
160 <td><p><span class="term"><em class="parameter"><code>type_tag</code></em> :</span></p></td>
161 <td>A <a class="link" href="gi-common-types.html#GITypeTag" title="enum GITypeTag"><span class="type">GITypeTag</span></a>
165 <td><p><span class="term"><em class="parameter"><code>is_pointer</code></em> :</span></p></td>
166 <td>Whether or not this is a pointer type</td>
169 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
170 <td>A <span class="type">ffi_type</span> corresponding to the platform default C ABI for <em class="parameter"><code>tag</code></em> and <em class="parameter"><code>is_pointer</code></em>.</td>
176 <div class="refsect2">
177 <a name="g-type-info-get-ffi-type"></a><h3>g_type_info_get_ffi_type ()</h3>
178 <pre class="programlisting"><span class="returnvalue">ffi_type</span> * g_type_info_get_ffi_type (<em class="parameter"><code><a class="link" href="gi-GITypeInfo.html#GITypeInfo" title="GITypeInfo"><span class="type">GITypeInfo</span></a> *info</code></em>);</pre>
182 <div class="variablelist"><table border="0" class="variablelist">
184 <col align="left" valign="top">
189 <td><p><span class="term"><em class="parameter"><code>info</code></em> :</span></p></td>
190 <td>A <a class="link" href="gi-GITypeInfo.html#GITypeInfo" title="GITypeInfo"><span class="type">GITypeInfo</span></a>
194 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
195 <td>A <span class="type">ffi_type</span> corresponding to the platform default C ABI for <em class="parameter"><code>info</code></em>.</td>
201 <div class="refsect2">
202 <a name="gi-type-info-extract-ffi-return-value"></a><h3>gi_type_info_extract_ffi_return_value ()</h3>
203 <pre class="programlisting"><span class="returnvalue">void</span> gi_type_info_extract_ffi_return_value
204 (<em class="parameter"><code><a class="link" href="gi-GITypeInfo.html#GITypeInfo" title="GITypeInfo"><span class="type">GITypeInfo</span></a> *return_info</code></em>,
205 <em class="parameter"><code><a class="link" href="gi-girffi.html#GIFFIReturnValue" title="GIFFIReturnValue"><span class="type">GIFFIReturnValue</span></a> *ffi_value</code></em>,
206 <em class="parameter"><code><a class="link" href="gi-common-types.html#GIArgument" title="union GIArgument"><span class="type">GIArgument</span></a> *arg</code></em>);</pre>
208 Extract the correct bits from an ffi_arg return value into
209 GIArgument: https://bugzilla.gnome.org/show_bug.cgi?id=665152
212 Also see <span class="citerefentry"><span class="refentrytitle">ffi_call</span>(3)</span>
213 - the storage requirements for return values are "special".
215 <div class="variablelist"><table border="0" class="variablelist">
217 <col align="left" valign="top">
222 <td><p><span class="term"><em class="parameter"><code>return_info</code></em> :</span></p></td>
226 <td><p><span class="term"><em class="parameter"><code>ffi_value</code></em> :</span></p></td>
230 <td><p><span class="term"><em class="parameter"><code>arg</code></em> :</span></p></td>
231 <td>TODO. <span class="annotation">[<acronym title="Out parameter, where caller must allocate storage."><span class="acronym">out caller-allocates</span></acronym>]</span>
238 <div class="refsect2">
239 <a name="g-function-info-prep-invoker"></a><h3>g_function_info_prep_invoker ()</h3>
240 <pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> g_function_info_prep_invoker (<em class="parameter"><code><a class="link" href="gi-GIFunctionInfo.html#GIFunctionInfo" title="GIFunctionInfo"><span class="type">GIFunctionInfo</span></a> *info</code></em>,
241 <em class="parameter"><code><a class="link" href="gi-girffi.html#GIFunctionInvoker" title="struct GIFunctionInvoker"><span class="type">GIFunctionInvoker</span></a> *invoker</code></em>,
242 <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre>
244 Initialize the caller-allocated <em class="parameter"><code>invoker</code></em> structure with a cache
245 of information needed to invoke the C function corresponding to
246 <em class="parameter"><code>info</code></em> with the platform's default ABI.
249 A primary intent of this function is that a dynamic structure allocated
250 by a language binding could contain a <a class="link" href="gi-girffi.html#GIFunctionInvoker" title="struct GIFunctionInvoker"><span class="type">GIFunctionInvoker</span></a> structure
251 inside the binding's function mapping.
253 <div class="variablelist"><table border="0" class="variablelist">
255 <col align="left" valign="top">
260 <td><p><span class="term"><em class="parameter"><code>info</code></em> :</span></p></td>
261 <td>A <a class="link" href="gi-GIFunctionInfo.html#GIFunctionInfo" title="GIFunctionInfo"><span class="type">GIFunctionInfo</span></a>
265 <td><p><span class="term"><em class="parameter"><code>invoker</code></em> :</span></p></td>
266 <td>Output invoker structure</td>
269 <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
270 <td>A <a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a>
274 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
276 <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> on success, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> otherwise with <em class="parameter"><code>error</code></em> set.</td>
282 <div class="refsect2">
283 <a name="g-function-invoker-new-for-address"></a><h3>g_function_invoker_new_for_address ()</h3>
284 <pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> g_function_invoker_new_for_address (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> addr</code></em>,
285 <em class="parameter"><code><a class="link" href="gi-GICallableInfo.html#GICallableInfo" title="GICallableInfo"><span class="type">GICallableInfo</span></a> *info</code></em>,
286 <em class="parameter"><code><a class="link" href="gi-girffi.html#GIFunctionInvoker" title="struct GIFunctionInvoker"><span class="type">GIFunctionInvoker</span></a> *invoker</code></em>,
287 <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre>
289 Initialize the caller-allocated <em class="parameter"><code>invoker</code></em> structure with a cache
290 of information needed to invoke the C function corresponding to
291 <em class="parameter"><code>info</code></em> with the platform's default ABI.
294 A primary intent of this function is that a dynamic structure allocated
295 by a language binding could contain a <a class="link" href="gi-girffi.html#GIFunctionInvoker" title="struct GIFunctionInvoker"><span class="type">GIFunctionInvoker</span></a> structure
296 inside the binding's function mapping.
298 <div class="variablelist"><table border="0" class="variablelist">
300 <col align="left" valign="top">
305 <td><p><span class="term"><em class="parameter"><code>addr</code></em> :</span></p></td>
309 <td><p><span class="term"><em class="parameter"><code>info</code></em> :</span></p></td>
310 <td>A <a class="link" href="gi-GICallableInfo.html#GICallableInfo" title="GICallableInfo"><span class="type">GICallableInfo</span></a>
314 <td><p><span class="term"><em class="parameter"><code>invoker</code></em> :</span></p></td>
315 <td>Output invoker structure</td>
318 <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
319 <td>A <a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a>
323 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
325 <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> on success, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> otherwise with <em class="parameter"><code>error</code></em> set.</td>
331 <div class="refsect2">
332 <a name="g-function-invoker-destroy"></a><h3>g_function_invoker_destroy ()</h3>
333 <pre class="programlisting"><span class="returnvalue">void</span> g_function_invoker_destroy (<em class="parameter"><code><a class="link" href="gi-girffi.html#GIFunctionInvoker" title="struct GIFunctionInvoker"><span class="type">GIFunctionInvoker</span></a> *invoker</code></em>);</pre>
335 Release all resources allocated for the internals of <em class="parameter"><code>invoker</code></em>; callers
336 are responsible for freeing any resources allocated for the structure
339 <div class="variablelist"><table border="0" class="variablelist">
341 <col align="left" valign="top">
345 <td><p><span class="term"><em class="parameter"><code>invoker</code></em> :</span></p></td>
346 <td>A <a class="link" href="gi-girffi.html#GIFunctionInvoker" title="struct GIFunctionInvoker"><span class="type">GIFunctionInvoker</span></a>
352 <div class="refsect2">
353 <a name="g-callable-info-prepare-closure"></a><h3>g_callable_info_prepare_closure ()</h3>
354 <pre class="programlisting"><span class="returnvalue">ffi_closure</span> * g_callable_info_prepare_closure (<em class="parameter"><code><a class="link" href="gi-GICallableInfo.html#GICallableInfo" title="GICallableInfo"><span class="type">GICallableInfo</span></a> *callable_info</code></em>,
355 <em class="parameter"><code><span class="type">ffi_cif</span> *cif</code></em>,
356 <em class="parameter"><code><a class="link" href="gi-girffi.html#GIFFIClosureCallback" title="GIFFIClosureCallback ()"><span class="type">GIFFIClosureCallback</span></a> callback</code></em>,
357 <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
359 Prepares a callback for ffi invocation.
361 <div class="variablelist"><table border="0" class="variablelist">
363 <col align="left" valign="top">
368 <td><p><span class="term"><em class="parameter"><code>callable_info</code></em> :</span></p></td>
369 <td>a callable info from a typelib</td>
372 <td><p><span class="term"><em class="parameter"><code>cif</code></em> :</span></p></td>
373 <td>a ffi_cif structure</td>
376 <td><p><span class="term"><em class="parameter"><code>callback</code></em> :</span></p></td>
377 <td>the ffi callback</td>
380 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
381 <td>data to be passed into the callback</td>
384 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
385 <td>the ffi_closure or NULL on error. The return value
386 should be freed by calling <a class="link" href="gi-girffi.html#g-callable-info-free-closure" title="g_callable_info_free_closure ()"><code class="function">g_callable_info_free_closure()</code></a>.</td>
392 <div class="refsect2">
393 <a name="g-callable-info-free-closure"></a><h3>g_callable_info_free_closure ()</h3>
394 <pre class="programlisting"><span class="returnvalue">void</span> g_callable_info_free_closure (<em class="parameter"><code><a class="link" href="gi-GICallableInfo.html#GICallableInfo" title="GICallableInfo"><span class="type">GICallableInfo</span></a> *callable_info</code></em>,
395 <em class="parameter"><code><span class="type">ffi_closure</span> *closure</code></em>);</pre>
397 Frees a ffi_closure returned from <a class="link" href="gi-girffi.html#g-callable-info-prepare-closure" title="g_callable_info_prepare_closure ()"><code class="function">g_callable_info_prepare_closure()</code></a>
399 <div class="variablelist"><table border="0" class="variablelist">
401 <col align="left" valign="top">
406 <td><p><span class="term"><em class="parameter"><code>callable_info</code></em> :</span></p></td>
407 <td>a callable info from a typelib</td>
410 <td><p><span class="term"><em class="parameter"><code>closure</code></em> :</span></p></td>
420 Generated by GTK-Doc V1.19.1</div>