Imported Upstream version 1.49.1
[platform/upstream/gobject-introspection.git] / docs / reference / html / gi-GIFieldInfo.html
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5 <title>GIFieldInfo: GObject Introspection Reference Manual</title>
6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
7 <link rel="home" href="index.html" title="GObject Introspection Reference Manual">
8 <link rel="up" href="ch01.html" title="GIRepository">
9 <link rel="prev" href="gi-GIConstantInfo.html" title="GIConstantInfo">
10 <link rel="next" href="gi-GIPropertyInfo.html" title="GIPropertyInfo">
11 <meta name="generator" content="GTK-Doc V1.25.1 (XML mode)">
12 <link rel="stylesheet" href="style.css" type="text/css">
13 </head>
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="5"><tr valign="middle">
16 <td width="100%" align="left" class="shortcuts">
17 <a href="#" class="shortcut">Top</a><span id="nav_description">  <span class="dim">|</span> 
18                   <a href="#gi-GIFieldInfo.description" class="shortcut">Description</a></span>
19 </td>
20 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
21 <td><a accesskey="u" href="ch01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
22 <td><a accesskey="p" href="gi-GIConstantInfo.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
23 <td><a accesskey="n" href="gi-GIPropertyInfo.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
24 </tr></table>
25 <div class="refentry">
26 <a name="gi-GIFieldInfo"></a><div class="titlepage"></div>
27 <div class="refnamediv"><table width="100%"><tr>
28 <td valign="top">
29 <h2><span class="refentrytitle"><a name="gi-GIFieldInfo.top_of_page"></a>GIFieldInfo</span></h2>
30 <p>GIFieldInfo — Struct representing a struct or union field</p>
31 </td>
32 <td class="gallery_image" valign="top" align="right"></td>
33 </tr></table></div>
34 <div class="refsect1">
35 <a name="gi-GIFieldInfo.functions"></a><h2>Functions</h2>
36 <div class="informaltable"><table class="informaltable" width="100%" border="0">
37 <colgroup>
38 <col width="150px" class="functions_return">
39 <col class="functions_name">
40 </colgroup>
41 <tbody>
42 <tr>
43 <td class="define_keyword">#define</td>
44 <td class="function_name">
45 <a class="link" href="gi-GIFieldInfo.html#GI-IS-FIELD-INFO:CAPS" title="GI_IS_FIELD_INFO()">GI_IS_FIELD_INFO</a><span class="c_punctuation">()</span>
46 </td>
47 </tr>
48 <tr>
49 <td class="function_type">
50 <span class="returnvalue">gboolean</span>
51 </td>
52 <td class="function_name">
53 <a class="link" href="gi-GIFieldInfo.html#g-field-info-get-field" title="g_field_info_get_field ()">g_field_info_get_field</a> <span class="c_punctuation">()</span>
54 </td>
55 </tr>
56 <tr>
57 <td class="function_type">
58 <span class="returnvalue">gboolean</span>
59 </td>
60 <td class="function_name">
61 <a class="link" href="gi-GIFieldInfo.html#g-field-info-set-field" title="g_field_info_set_field ()">g_field_info_set_field</a> <span class="c_punctuation">()</span>
62 </td>
63 </tr>
64 <tr>
65 <td class="function_type">
66 <a class="link" href="gi-GIFieldInfo.html#GIFieldInfoFlags" title="enum GIFieldInfoFlags"><span class="returnvalue">GIFieldInfoFlags</span></a>
67 </td>
68 <td class="function_name">
69 <a class="link" href="gi-GIFieldInfo.html#g-field-info-get-flags" title="g_field_info_get_flags ()">g_field_info_get_flags</a> <span class="c_punctuation">()</span>
70 </td>
71 </tr>
72 <tr>
73 <td class="function_type">
74 <span class="returnvalue">gint</span>
75 </td>
76 <td class="function_name">
77 <a class="link" href="gi-GIFieldInfo.html#g-field-info-get-offset" title="g_field_info_get_offset ()">g_field_info_get_offset</a> <span class="c_punctuation">()</span>
78 </td>
79 </tr>
80 <tr>
81 <td class="function_type">
82 <span class="returnvalue">gint</span>
83 </td>
84 <td class="function_name">
85 <a class="link" href="gi-GIFieldInfo.html#g-field-info-get-size" title="g_field_info_get_size ()">g_field_info_get_size</a> <span class="c_punctuation">()</span>
86 </td>
87 </tr>
88 <tr>
89 <td class="function_type">
90 <a class="link" href="gi-GITypeInfo.html#GITypeInfo" title="GITypeInfo"><span class="returnvalue">GITypeInfo</span></a> *
91 </td>
92 <td class="function_name">
93 <a class="link" href="gi-GIFieldInfo.html#g-field-info-get-type" title="g_field_info_get_type ()">g_field_info_get_type</a> <span class="c_punctuation">()</span>
94 </td>
95 </tr>
96 </tbody>
97 </table></div>
98 </div>
99 <div class="refsect1">
100 <a name="gi-GIFieldInfo.other"></a><h2>Types and Values</h2>
101 <div class="informaltable"><table class="informaltable" width="100%" border="0">
102 <colgroup>
103 <col width="150px" class="name">
104 <col class="description">
105 </colgroup>
106 <tbody>
107 <tr>
108 <td class="typedef_keyword">typedef</td>
109 <td class="function_name"><a class="link" href="gi-GIFieldInfo.html#GIFieldInfo" title="GIFieldInfo">GIFieldInfo</a></td>
110 </tr>
111 <tr>
112 <td class="datatype_keyword">enum</td>
113 <td class="function_name"><a class="link" href="gi-GIFieldInfo.html#GIFieldInfoFlags" title="enum GIFieldInfoFlags">GIFieldInfoFlags</a></td>
114 </tr>
115 </tbody>
116 </table></div>
117 </div>
118 <div class="refsect1">
119 <a name="gi-GIFieldInfo.description"></a><h2>Description</h2>
120 <p>A GIFieldInfo struct represents a field of a struct (see <a class="link" href="gi-GIStructInfo.html#GIStructInfo" title="GIStructInfo"><span class="type">GIStructInfo</span></a>),
121 union (see <a class="link" href="gi-GIUnionInfo.html#GIUnionInfo" title="GIUnionInfo"><span class="type">GIUnionInfo</span></a>) or an object (see <a class="link" href="gi-GIObjectInfo.html#GIObjectInfo" title="GIObjectInfo"><span class="type">GIObjectInfo</span></a>). The GIFieldInfo
122 is fetched by calling <a class="link" href="gi-GIStructInfo.html#g-struct-info-get-field" title="g_struct_info_get_field ()"><code class="function">g_struct_info_get_field()</code></a>, <a class="link" href="gi-GIUnionInfo.html#g-union-info-get-field" title="g_union_info_get_field ()"><code class="function">g_union_info_get_field()</code></a>
123 or <a class="link" href="gi-GIObjectInfo.html#g-object-info-get-field" title="g_object_info_get_field ()"><code class="function">g_object_info_get_field()</code></a>.
124 A field has a size, type and a struct offset asssociated and a set of flags,
125 which is currently <a class="link" href="gi-GIFieldInfo.html#GI-FIELD-IS-READABLE:CAPS"><span class="type">GI_FIELD_IS_READABLE</span></a> or <a class="link" href="gi-GIFieldInfo.html#GI-FIELD-IS-WRITABLE:CAPS"><span class="type">GI_FIELD_IS_WRITABLE</span></a>.</p>
126 <div class="refsect1">
127 <a name="gi-gifieldinfo.struct-hierarchy"></a><h2>Struct hierarchy</h2>
128 <pre class="synopsis">
129   <a class="link" href="gi-GIBaseInfo.html" title="GIBaseInfo">GIBaseInfo</a>
130    +----GIFieldInfo
131 </pre>
132 </div>
133 </div>
134 <div class="refsect1">
135 <a name="gi-GIFieldInfo.functions_details"></a><h2>Functions</h2>
136 <div class="refsect2">
137 <a name="GI-IS-FIELD-INFO:CAPS"></a><h3>GI_IS_FIELD_INFO()</h3>
138 <pre class="programlisting">#define             GI_IS_FIELD_INFO(info)</pre>
139 <p>Checks if <em class="parameter"><code>info</code></em>
140  is a <a class="link" href="gi-GIFieldInfo.html#GIFieldInfo" title="GIFieldInfo"><span class="type">GIFieldInfo</span></a>.</p>
141 <div class="refsect3">
142 <a name="GI-IS-FIELD-INFO.parameters"></a><h4>Parameters</h4>
143 <div class="informaltable"><table class="informaltable" width="100%" border="0">
144 <colgroup>
145 <col width="150px" class="parameters_name">
146 <col class="parameters_description">
147 <col width="200px" class="parameters_annotations">
148 </colgroup>
149 <tbody><tr>
150 <td class="parameter_name"><p>info</p></td>
151 <td class="parameter_description"><p>an info structure</p></td>
152 <td class="parameter_annotations"> </td>
153 </tr></tbody>
154 </table></div>
155 </div>
156 </div>
157 <hr>
158 <div class="refsect2">
159 <a name="g-field-info-get-field"></a><h3>g_field_info_get_field ()</h3>
160 <pre class="programlisting"><span class="returnvalue">gboolean</span>
161 g_field_info_get_field (<em class="parameter"><code><a class="link" href="gi-GIFieldInfo.html#GIFieldInfo" title="GIFieldInfo"><span class="type">GIFieldInfo</span></a> *field_info</code></em>,
162                         <em class="parameter"><code><span class="type">gpointer</span> mem</code></em>,
163                         <em class="parameter"><code><a class="link" href="gi-common-types.html#GIArgument" title="GIArgument"><span class="type">GIArgument</span></a> *value</code></em>);</pre>
164 <p>Reads a field identified by a <a class="link" href="gi-GIFieldInfo.html#GIFieldInfo" title="GIFieldInfo"><span class="type">GIFieldInfo</span></a> from a C structure or
165 union.  This only handles fields of simple C types. It will fail
166 for a field of a composite type like a nested structure or union
167 even if that is actually readable.</p>
168 <p><span class="annotation">[<acronym title="Exposed in C code, not necessarily available in other languages."><span class="acronym">skip</span></acronym>]</span></p>
169 <div class="refsect3">
170 <a name="g-field-info-get-field.parameters"></a><h4>Parameters</h4>
171 <div class="informaltable"><table class="informaltable" width="100%" border="0">
172 <colgroup>
173 <col width="150px" class="parameters_name">
174 <col class="parameters_description">
175 <col width="200px" class="parameters_annotations">
176 </colgroup>
177 <tbody>
178 <tr>
179 <td class="parameter_name"><p>field_info</p></td>
180 <td class="parameter_description"><p>a <a class="link" href="gi-GIFieldInfo.html#GIFieldInfo" title="GIFieldInfo"><span class="type">GIFieldInfo</span></a></p></td>
181 <td class="parameter_annotations"> </td>
182 </tr>
183 <tr>
184 <td class="parameter_name"><p>mem</p></td>
185 <td class="parameter_description"><p>pointer to a block of memory representing a C structure or union</p></td>
186 <td class="parameter_annotations"> </td>
187 </tr>
188 <tr>
189 <td class="parameter_name"><p>value</p></td>
190 <td class="parameter_description"><p>a <a class="link" href="gi-common-types.html#GIArgument" title="GIArgument"><span class="type">GIArgument</span></a> into which to store the value retrieved</p></td>
191 <td class="parameter_annotations"> </td>
192 </tr>
193 </tbody>
194 </table></div>
195 </div>
196 <div class="refsect3">
197 <a name="g-field-info-get-field.returns"></a><h4>Returns</h4>
198 <p> <code class="literal">TRUE</code> if reading the field succeeded, otherwise <code class="literal">FALSE</code></p>
199 </div>
200 </div>
201 <hr>
202 <div class="refsect2">
203 <a name="g-field-info-set-field"></a><h3>g_field_info_set_field ()</h3>
204 <pre class="programlisting"><span class="returnvalue">gboolean</span>
205 g_field_info_set_field (<em class="parameter"><code><a class="link" href="gi-GIFieldInfo.html#GIFieldInfo" title="GIFieldInfo"><span class="type">GIFieldInfo</span></a> *field_info</code></em>,
206                         <em class="parameter"><code><span class="type">gpointer</span> mem</code></em>,
207                         <em class="parameter"><code>const <a class="link" href="gi-common-types.html#GIArgument" title="GIArgument"><span class="type">GIArgument</span></a> *value</code></em>);</pre>
208 <p>Writes a field identified by a <a class="link" href="gi-GIFieldInfo.html#GIFieldInfo" title="GIFieldInfo"><span class="type">GIFieldInfo</span></a> to a C structure or
209 union.  This only handles fields of simple C types. It will fail
210 for a field of a composite type like a nested structure or union
211 even if that is actually writable. Note also that that it will refuse
212 to write fields where memory management would by required. A field
213 with a type such as 'char *' must be set with a setter function.</p>
214 <p><span class="annotation">[<acronym title="Exposed in C code, not necessarily available in other languages."><span class="acronym">skip</span></acronym>]</span></p>
215 <div class="refsect3">
216 <a name="g-field-info-set-field.parameters"></a><h4>Parameters</h4>
217 <div class="informaltable"><table class="informaltable" width="100%" border="0">
218 <colgroup>
219 <col width="150px" class="parameters_name">
220 <col class="parameters_description">
221 <col width="200px" class="parameters_annotations">
222 </colgroup>
223 <tbody>
224 <tr>
225 <td class="parameter_name"><p>field_info</p></td>
226 <td class="parameter_description"><p>a <a class="link" href="gi-GIFieldInfo.html#GIFieldInfo" title="GIFieldInfo"><span class="type">GIFieldInfo</span></a></p></td>
227 <td class="parameter_annotations"> </td>
228 </tr>
229 <tr>
230 <td class="parameter_name"><p>mem</p></td>
231 <td class="parameter_description"><p>pointer to a block of memory representing a C structure or union</p></td>
232 <td class="parameter_annotations"> </td>
233 </tr>
234 <tr>
235 <td class="parameter_name"><p>value</p></td>
236 <td class="parameter_description"><p>a <a class="link" href="gi-common-types.html#GIArgument" title="GIArgument"><span class="type">GIArgument</span></a> holding the value to store</p></td>
237 <td class="parameter_annotations"> </td>
238 </tr>
239 </tbody>
240 </table></div>
241 </div>
242 <div class="refsect3">
243 <a name="g-field-info-set-field.returns"></a><h4>Returns</h4>
244 <p> <code class="literal">TRUE</code> if writing the field succeeded, otherwise <code class="literal">FALSE</code></p>
245 </div>
246 </div>
247 <hr>
248 <div class="refsect2">
249 <a name="g-field-info-get-flags"></a><h3>g_field_info_get_flags ()</h3>
250 <pre class="programlisting"><a class="link" href="gi-GIFieldInfo.html#GIFieldInfoFlags" title="enum GIFieldInfoFlags"><span class="returnvalue">GIFieldInfoFlags</span></a>
251 g_field_info_get_flags (<em class="parameter"><code><a class="link" href="gi-GIFieldInfo.html#GIFieldInfo" title="GIFieldInfo"><span class="type">GIFieldInfo</span></a> *info</code></em>);</pre>
252 <p>Obtain the flags for this <a class="link" href="gi-GIFieldInfo.html#GIFieldInfo" title="GIFieldInfo"><span class="type">GIFieldInfo</span></a>. See <a class="link" href="gi-GIFieldInfo.html#GIFieldInfoFlags" title="enum GIFieldInfoFlags"><span class="type">GIFieldInfoFlags</span></a> for possible
253 flag values.</p>
254 <div class="refsect3">
255 <a name="g-field-info-get-flags.parameters"></a><h4>Parameters</h4>
256 <div class="informaltable"><table class="informaltable" width="100%" border="0">
257 <colgroup>
258 <col width="150px" class="parameters_name">
259 <col class="parameters_description">
260 <col width="200px" class="parameters_annotations">
261 </colgroup>
262 <tbody><tr>
263 <td class="parameter_name"><p>info</p></td>
264 <td class="parameter_description"><p>a <a class="link" href="gi-GIFieldInfo.html#GIFieldInfo" title="GIFieldInfo"><span class="type">GIFieldInfo</span></a></p></td>
265 <td class="parameter_annotations"> </td>
266 </tr></tbody>
267 </table></div>
268 </div>
269 <div class="refsect3">
270 <a name="g-field-info-get-flags.returns"></a><h4>Returns</h4>
271 <p> the flags</p>
272 </div>
273 </div>
274 <hr>
275 <div class="refsect2">
276 <a name="g-field-info-get-offset"></a><h3>g_field_info_get_offset ()</h3>
277 <pre class="programlisting"><span class="returnvalue">gint</span>
278 g_field_info_get_offset (<em class="parameter"><code><a class="link" href="gi-GIFieldInfo.html#GIFieldInfo" title="GIFieldInfo"><span class="type">GIFieldInfo</span></a> *info</code></em>);</pre>
279 <p>Obtain the offset in bits of the field member, this is relative
280 to the beginning of the struct or union.</p>
281 <div class="refsect3">
282 <a name="g-field-info-get-offset.parameters"></a><h4>Parameters</h4>
283 <div class="informaltable"><table class="informaltable" width="100%" border="0">
284 <colgroup>
285 <col width="150px" class="parameters_name">
286 <col class="parameters_description">
287 <col width="200px" class="parameters_annotations">
288 </colgroup>
289 <tbody><tr>
290 <td class="parameter_name"><p>info</p></td>
291 <td class="parameter_description"><p>a <a class="link" href="gi-GIFieldInfo.html#GIFieldInfo" title="GIFieldInfo"><span class="type">GIFieldInfo</span></a></p></td>
292 <td class="parameter_annotations"> </td>
293 </tr></tbody>
294 </table></div>
295 </div>
296 <div class="refsect3">
297 <a name="g-field-info-get-offset.returns"></a><h4>Returns</h4>
298 <p> the field offset</p>
299 </div>
300 </div>
301 <hr>
302 <div class="refsect2">
303 <a name="g-field-info-get-size"></a><h3>g_field_info_get_size ()</h3>
304 <pre class="programlisting"><span class="returnvalue">gint</span>
305 g_field_info_get_size (<em class="parameter"><code><a class="link" href="gi-GIFieldInfo.html#GIFieldInfo" title="GIFieldInfo"><span class="type">GIFieldInfo</span></a> *info</code></em>);</pre>
306 <p>Obtain the size in bits of the field member, this is how
307 much space you need to allocate to store the field.</p>
308 <div class="refsect3">
309 <a name="g-field-info-get-size.parameters"></a><h4>Parameters</h4>
310 <div class="informaltable"><table class="informaltable" width="100%" border="0">
311 <colgroup>
312 <col width="150px" class="parameters_name">
313 <col class="parameters_description">
314 <col width="200px" class="parameters_annotations">
315 </colgroup>
316 <tbody><tr>
317 <td class="parameter_name"><p>info</p></td>
318 <td class="parameter_description"><p>a <a class="link" href="gi-GIFieldInfo.html#GIFieldInfo" title="GIFieldInfo"><span class="type">GIFieldInfo</span></a></p></td>
319 <td class="parameter_annotations"> </td>
320 </tr></tbody>
321 </table></div>
322 </div>
323 <div class="refsect3">
324 <a name="g-field-info-get-size.returns"></a><h4>Returns</h4>
325 <p> the field size</p>
326 </div>
327 </div>
328 <hr>
329 <div class="refsect2">
330 <a name="g-field-info-get-type"></a><h3>g_field_info_get_type ()</h3>
331 <pre class="programlisting"><a class="link" href="gi-GITypeInfo.html#GITypeInfo" title="GITypeInfo"><span class="returnvalue">GITypeInfo</span></a> *
332 g_field_info_get_type (<em class="parameter"><code><a class="link" href="gi-GIFieldInfo.html#GIFieldInfo" title="GIFieldInfo"><span class="type">GIFieldInfo</span></a> *info</code></em>);</pre>
333 <p>Obtain the type of a field as a <a class="link" href="gi-GITypeInfo.html#GITypeInfo" title="GITypeInfo"><span class="type">GITypeInfo</span></a>.</p>
334 <div class="refsect3">
335 <a name="g-field-info-get-type.parameters"></a><h4>Parameters</h4>
336 <div class="informaltable"><table class="informaltable" width="100%" border="0">
337 <colgroup>
338 <col width="150px" class="parameters_name">
339 <col class="parameters_description">
340 <col width="200px" class="parameters_annotations">
341 </colgroup>
342 <tbody><tr>
343 <td class="parameter_name"><p>info</p></td>
344 <td class="parameter_description"><p>a <a class="link" href="gi-GIFieldInfo.html#GIFieldInfo" title="GIFieldInfo"><span class="type">GIFieldInfo</span></a></p></td>
345 <td class="parameter_annotations"> </td>
346 </tr></tbody>
347 </table></div>
348 </div>
349 <div class="refsect3">
350 <a name="g-field-info-get-type.returns"></a><h4>Returns</h4>
351 <p> the <a class="link" href="gi-GITypeInfo.html#GITypeInfo" title="GITypeInfo"><span class="type">GITypeInfo</span></a>. Free the struct by calling
352 <a class="link" href="gi-GIBaseInfo.html#g-base-info-unref" title="g_base_info_unref ()"><code class="function">g_base_info_unref()</code></a> when done. </p>
353 <p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p>
354 </div>
355 </div>
356 </div>
357 <div class="refsect1">
358 <a name="gi-GIFieldInfo.other_details"></a><h2>Types and Values</h2>
359 <div class="refsect2">
360 <a name="GIFieldInfo"></a><h3>GIFieldInfo</h3>
361 <pre class="programlisting">typedef GIBaseInfo GIFieldInfo;
362 </pre>
363 <p>Represents a field of a <a class="link" href="gi-GIStructInfo.html#GIStructInfo" title="GIStructInfo"><span class="type">GIStructInfo</span></a> or a <a class="link" href="gi-GIUnionInfo.html#GIUnionInfo" title="GIUnionInfo"><span class="type">GIUnionInfo</span></a>.</p>
364 </div>
365 <hr>
366 <div class="refsect2">
367 <a name="GIFieldInfoFlags"></a><h3>enum GIFieldInfoFlags</h3>
368 <p>Flags for a <a class="link" href="gi-GIFieldInfo.html#GIFieldInfo" title="GIFieldInfo"><span class="type">GIFieldInfo</span></a>.</p>
369 <div class="refsect3">
370 <a name="GIFieldInfoFlags.members"></a><h4>Members</h4>
371 <div class="informaltable"><table class="informaltable" width="100%" border="0">
372 <colgroup>
373 <col width="300px" class="enum_members_name">
374 <col class="enum_members_description">
375 <col width="200px" class="enum_members_annotations">
376 </colgroup>
377 <tbody>
378 <tr>
379 <td class="enum_member_name"><p><a name="GI-FIELD-IS-READABLE:CAPS"></a>GI_FIELD_IS_READABLE</p></td>
380 <td class="enum_member_description">
381 <p>field is readable.</p>
382 </td>
383 <td class="enum_member_annotations"> </td>
384 </tr>
385 <tr>
386 <td class="enum_member_name"><p><a name="GI-FIELD-IS-WRITABLE:CAPS"></a>GI_FIELD_IS_WRITABLE</p></td>
387 <td class="enum_member_description">
388 <p>field is writable.</p>
389 </td>
390 <td class="enum_member_annotations"> </td>
391 </tr>
392 </tbody>
393 </table></div>
394 </div>
395 </div>
396 </div>
397 </div>
398 <div class="footer">
399 <hr>Generated by GTK-Doc V1.25.1</div>
400 </body>
401 </html>