docs/reference/glib/gvariant-varargs.xml

   1 <?xml version='1.0' encoding='utf-8'?>
   2
   3 <refentry id='gvariant-format-strings'>
   4  <refmeta>
   5   <refentrytitle>GVariant Format Strings</refentrytitle>
   6  </refmeta>
   7
   8  <refsect1>
   9   <title>Variable Argument Conversions</title>
  10
  11   <para>
  12    This page attempts to document how to perform variable argument conversions with GVariant.
  13   </para>
  14   <para>
  15    Conversions occur according to format strings.  A format string is a two-way mapping between a single
  16    <link linkend='GVariant'>GVariant</link> value and one or more C values.
  17   </para>
  18   <para>
  19    A conversion from C values into a <link linkend='GVariant'>GVariant</link> value is made using the
  20    <link linkend='g-variant-new'><function>g_variant_new()</function></link> function.  A conversion from a
  21    <link linkend='GVariant'>GVariant</link> into C values is made using the
  22    <link linkend='g-variant-get'><function>g_variant_get()</function></link> function.
  23   </para>
  24  </refsect1>
  25
  26  <refsect1>
  27   <title>Syntax</title>
  28
  29   <para>
  30    This section exhaustively describes all possibilities for GVariant format strings.  There are no valid forms of
  31    format strings other than those described here.  Please note that the format string syntax is likely to expand in the
  32    future.
  33   </para>
  34   <para>
  35    Valid format strings have one of the following forms:
  36   </para>
  37   <itemizedlist>
  38    <listitem>
  39     <para>any type string</para>
  40    </listitem>
  41    <listitem>
  42     <para>
  43      a type string prefixed with a '<literal>@</literal>'
  44     </para>
  45    </listitem>
  46    <listitem>
  47     <para>
  48      '<literal>&amp;s</literal>' '<literal>&amp;o</literal>', '<literal>&amp;g</literal>', '<literal>^as</literal>',
  49      '<literal>^a&amp;s</literal>', '<literal>^ay</literal>', '<literal>^&amp;ay</literal>', '<literal>^aay</literal>'
  50      or '<literal>^a&amp;ay</literal>'.
  51     </para>
  52    </listitem>
  53    <listitem>
  54     <para>
  55      any format string, prefixed with an '<literal>m</literal>'
  56     </para>
  57    </listitem>
  58    <listitem>
  59     <para>
  60      a sequence of zero or more format strings strings, concatenated and enclosed in parentheses
  61     </para>
  62    </listitem>
  63    <listitem>
  64     <para>
  65      an opening brace, followed by two format strings, followed by a closing brace (subject to the constraint that the
  66      first format string correspond to a type valid for use as the key type of a dictionary)
  67     </para>
  68    </listitem>
  69   </itemizedlist>
  70  </refsect1>
  71  <refsect1>
  72   <title>Symbols</title>
  73
  74    <para>
  75     The following table describes the rough meaning of symbols that may appear inside a GVariant format string.  Each
  76     symbol is described in detail in its own section, including usage examples.
  77   </para>
  78
  79   <informaltable>
  80    <tgroup cols='2'>
  81     <colspec colname='col_0'/>
  82     <colspec colname='col_1'/>
  83     <tbody>
  84
  85      <row rowsep='1'>
  86       <entry colsep='1' rowsep='1'>
  87        <para>
  88         <emphasis role='strong'>Symbol</emphasis>
  89        </para>
  90       </entry>
  91       <entry colsep='1' rowsep='1'>
  92        <para>
  93          <emphasis role='strong'>Meaning</emphasis>
  94        </para>
  95       </entry>
  96      </row>
  97
  98      <row rowsep='1'>
  99       <entry colsep='1' rowsep='1'>
 100        <para>
 101         <emphasis role='strong'>
 102          <literal>b</literal>, <literal>y</literal>, <literal>n</literal>, <literal>q</literal>, <literal>i</literal>,
 103          <literal>u</literal>, <literal>x</literal>, <literal>t</literal>, <literal>h</literal>, <literal>d</literal>
 104         </emphasis>
 105        </para>
 106       </entry>
 107       <entry colsep='1' rowsep='1'>
 108        <para>
 109         Used for building or deconstructing boolean, byte and numeric types.  See
 110         <link linkend='gvariant-format-strings-numeric-types'>Numeric Types</link> below.
 111        </para>
 112       </entry>
 113      </row>
 114
 115      <row rowsep='1'>
 116       <entry colsep='1' rowsep='1'>
 117        <para>
 118         <emphasis role='strong'>
 119          <literal>s</literal>, <literal>o</literal>, <literal>g</literal>
 120         </emphasis>
 121        </para>
 122       </entry>
 123       <entry colsep='1' rowsep='1'>
 124        <para>
 125         Used for building or deconstructing string types.  See
 126         <link linkend='gvariant-format-strings-strings'>Strings</link> below.
 127        </para>
 128       </entry>
 129      </row>
 130
 131      <row rowsep='1'>
 132       <entry colsep='1' rowsep='1'>
 133        <para>
 134         <emphasis role='strong'><literal>v</literal></emphasis>
 135        </para>
 136       </entry>
 137       <entry colsep='1' rowsep='1'>
 138        <para>
 139         Used for building or deconstructing variant types.  See
 140         <link linkend='gvariant-format-strings-variants'>Variants</link> below.
 141        </para>
 142       </entry>
 143      </row>
 144
 145      <row rowsep='1'>
 146       <entry colsep='1' rowsep='1'>
 147        <para>
 148         <emphasis role='strong'>
 149          <literal>a</literal>
 150         </emphasis>
 151        </para>
 152       </entry>
 153       <entry colsep='1' rowsep='1'>
 154        <para>
 155         Used for building or deconstructing arrays.  See
 156         <link linkend='gvariant-format-strings-arrays'>Arrays</link> below.
 157        </para>
 158       </entry>
 159      </row>
 160
 161      <row rowsep='1'>
 162       <entry colsep='1' rowsep='1'>
 163        <para>
 164         <emphasis role='strong'>
 165          <literal>m</literal>
 166         </emphasis>
 167        </para>
 168       </entry>
 169       <entry colsep='1' rowsep='1'>
 170        <para>
 171          Used for building or deconstructing maybe types.  See
 172          <link linkend='gvariant-format-strings-maybe-types'>Maybe Types</link> below.
 173        </para>
 174       </entry>
 175      </row>
 176
 177      <row rowsep='1'>
 178       <entry colsep='1' rowsep='1'>
 179        <para>
 180         <emphasis role='strong'>
 181          <literal>()</literal>
 182         </emphasis>
 183        </para>
 184       </entry>
 185       <entry colsep='1' rowsep='1'>
 186        <para>
 187          Used for building or deconstructing tuples.  See
 188          <link linkend='gvariant-format-strings-tuples'>Tuples</link> below.
 189        </para>
 190       </entry>
 191      </row>
 192
 193      <row rowsep='1'>
 194       <entry colsep='1' rowsep='1'>
 195        <para>
 196         <emphasis role='strong'>
 197          <literal>{}</literal>
 198         </emphasis>
 199        </para>
 200       </entry>
 201       <entry colsep='1' rowsep='1'>
 202        <para>
 203         Used for building or deconstructing dictionary entries. See
 204         <link linkend='gvariant-format-strings-dictionaries'>Dictionaries</link> below.
 205        </para>
 206       </entry>
 207      </row>
 208
 209      <row rowsep='1'>
 210       <entry colsep='1' rowsep='1'>
 211        <para>
 212         <emphasis role='strong'>
 213          <literal>@</literal>
 214         </emphasis>
 215        </para>
 216       </entry>
 217       <entry colsep='1' rowsep='1'>
 218        <para>
 219         Used as a prefix on a GVariant type string (not format string).  Denotes that a pointer to a
 220         <link linkend='GVariant'>GVariant</link> should be used in place of the normal C type or types.  For
 221         <link linkend='g-variant-new'><function>g_variant_new()</function></link> this means that you must pass a
 222         non-<link linkend='NULL--CAPS'><literal>NULL</literal></link> <code>(<link linkend='GVariant'>GVariant</link>
 223         *)</code>; if it is a floating reference, ownership will be taken, as
 224         if by using <link linkend="g-variant-ref-sink"><function>g_variant_ref_sink()</function></link>.
 225         For <link linkend='g-variant-get'><function>g_variant_get()</function></link> this means that you
 226         must pass a pointer to a <code>(<link linkend='GVariant'>GVariant</link> *)</code> for the value to be returned
 227         by reference or <link linkend='NULL--CAPS'><literal>NULL</literal></link> to ignore the value.  See
 228         <link linkend='gvariant-format-strings-gvariant'><code>GVariant *</code></link> below.
 229        </para>
 230       </entry>
 231      </row>
 232
 233      <row rowsep='1'>
 234       <entry colsep='1' rowsep='1'>
 235        <para>
 236         <emphasis role='strong'>
 237          <literal>*</literal>, <literal>?</literal>, <literal>r</literal>
 238         </emphasis>
 239        </para>
 240       </entry>
 241       <entry colsep='1' rowsep='1'>
 242        <para>
 243         Exactly equivalent to <literal>@*</literal>, <literal>@?</literal> and <literal>@r</literal>.  Provided only for
 244         completeness so that all GVariant type strings can be used also as format strings.  See <link
 245         linkend='gvariant-format-strings-gvariant'><code>GVariant *</code></link> below.
 246        </para>
 247       </entry>
 248      </row>
 249
 250      <row rowsep='1'>
 251       <entry colsep='1' rowsep='1'>
 252        <para>
 253         <emphasis role='strong'><literal>&amp;</literal></emphasis>
 254        </para>
 255       </entry>
 256       <entry colsep='1' rowsep='1'>
 257        <para>
 258         Used as a prefix on a GVariant type string (not format string).  Denotes that a C pointer to serialised data
 259         should be used in place of the normal C type.  See
 260         <link linkend='gvariant-format-strings-pointers'>Pointers</link> below.
 261        </para>
 262       </entry>
 263      </row>
 264
 265      <row rowsep='1'>
 266       <entry colsep='1' rowsep='1'>
 267        <para>
 268         <emphasis role='strong'><literal>^</literal></emphasis>
 269        </para>
 270       </entry>
 271       <entry colsep='1' rowsep='1'>
 272        <para>
 273         Used as a prefix on some specific types of format strings.  See
 274         <link linkend='gvariant-format-strings-convenience'>Convenience Conversions</link> below.
 275        </para>
 276       </entry>
 277      </row>
 278     </tbody>
 279    </tgroup>
 280   </informaltable>
 281
 282
 283   <refsect2 id='gvariant-format-strings-numeric-types'>
 284    <title>Numeric Types</title>
 285    <para>
 286     <emphasis role='strong'>
 287      Characters: <literal>b</literal>, <literal>y</literal>, <literal>n</literal>, <literal>q</literal>,
 288      <literal>i</literal>, <literal>u</literal>, <literal>x</literal>, <literal>t</literal>, <literal>h</literal>,
 289      <literal>d</literal>
 290     </emphasis>
 291    </para>
 292
 293    <para>
 294     Variable argument conversions from numeric types work in the most obvious way possible.  Upon encountering one of
 295     these characters, <link linkend='g-variant-new'><function>g_variant_new()</function></link> takes the equivalent C
 296     type as an argument.  <link linkend='g-variant-get'><function>g_variant_get()</function></link> takes a pointer to
 297     the equivalent C type (or <link linkend='NULL--CAPS'><literal>NULL</literal></link> to ignore the value).
 298    </para>
 299
 300    <para>
 301     The equivalent C types are as follows:
 302    </para>
 303
 304    <informaltable>
 305     <tgroup cols='2'>
 306      <colspec colname='col_0'/><colspec colname='col_1'/>
 307      <tbody>
 308       <row rowsep='1'>
 309        <entry colsep='1' rowsep='1'>
 310         <para>
 311           <emphasis role='strong'>Character</emphasis>
 312         </para>
 313        </entry>
 314        <entry colsep='1' rowsep='1'>
 315         <para>
 316           <emphasis role='strong'>Equivalent C type</emphasis>
 317         </para>
 318        </entry>
 319       </row>
 320       <row rowsep='1'>
 321        <entry colsep='1' rowsep='1'>
 322         <para>
 323          <emphasis role='strong'>
 324           <literal>b</literal>
 325          </emphasis>
 326         </para>
 327        </entry>
 328        <entry colsep='1' rowsep='1'>
 329         <para>
 330          <link linkend='gboolean'><type>gboolean</type></link>
 331         </para>
 332        </entry>
 333       </row>
 334       <row rowsep='1'>
 335        <entry colsep='1' rowsep='1'>
 336         <para>
 337          <emphasis role='strong'>
 338           <literal>y</literal>
 339          </emphasis>
 340         </para>
 341        </entry>
 342        <entry colsep='1' rowsep='1'>
 343         <para>
 344          <link linkend='guchar'><type>guchar</type></link>
 345         </para>
 346        </entry>
 347       </row>
 348       <row rowsep='1'>
 349        <entry colsep='1' rowsep='1'>
 350         <para>
 351          <emphasis role='strong'>
 352           <literal>n</literal>
 353          </emphasis>
 354         </para>
 355        </entry>
 356        <entry colsep='1' rowsep='1'>
 357         <para>
 358          <link linkend='gint16'><type>gint16</type></link>
 359         </para>
 360        </entry>
 361       </row>
 362       <row rowsep='1'>
 363        <entry colsep='1' rowsep='1'>
 364         <para>
 365          <emphasis role='strong'>
 366           <literal>q</literal>
 367          </emphasis>
 368         </para>
 369        </entry>
 370        <entry colsep='1' rowsep='1'>
 371         <para>
 372          <link linkend='guint16'><type>guint16</type></link>
 373         </para>
 374        </entry>
 375       </row>
 376       <row rowsep='1'>
 377        <entry colsep='1' rowsep='1'>
 378         <para>
 379          <emphasis role='strong'>
 380           <literal>i</literal>
 381          </emphasis>
 382         </para>
 383        </entry>
 384        <entry colsep='1' rowsep='1'>
 385         <para>
 386          <link linkend='gint32'><type>gint32</type></link>
 387         </para>
 388        </entry>
 389       </row>
 390       <row rowsep='1'>
 391        <entry colsep='1' rowsep='1'>
 392         <para>
 393          <emphasis role='strong'>
 394           <literal>u</literal>
 395          </emphasis>
 396         </para>
 397        </entry>
 398        <entry colsep='1' rowsep='1'>
 399         <para>
 400          <link linkend='guint32'><type>guint32</type></link>
 401         </para>
 402        </entry>
 403       </row>
 404       <row rowsep='1'>
 405        <entry colsep='1' rowsep='1'>
 406         <para>
 407          <emphasis role='strong'>
 408           <literal>x</literal>
 409          </emphasis>
 410         </para>
 411        </entry>
 412        <entry colsep='1' rowsep='1'>
 413         <para>
 414          <link linkend='gint64'><type>gint64</type></link>
 415         </para>
 416        </entry>
 417       </row>
 418       <row rowsep='1'>
 419        <entry colsep='1' rowsep='1'>
 420         <para>
 421          <emphasis role='strong'>
 422           <literal>t</literal>
 423          </emphasis>
 424         </para>
 425        </entry>
 426        <entry colsep='1' rowsep='1'>
 427         <para>
 428          <link linkend='guint64'><type>guint64</type></link>
 429         </para>
 430        </entry>
 431       </row>
 432       <row rowsep='1'>
 433        <entry colsep='1' rowsep='1'>
 434         <para>
 435          <emphasis role='strong'>
 436           <literal>h</literal>
 437          </emphasis>
 438         </para>
 439        </entry>
 440        <entry colsep='1' rowsep='1'>
 441         <para>
 442          <link linkend='gint32'><type>gint32</type></link>
 443         </para>
 444        </entry>
 445       </row>
 446       <row rowsep='1'>
 447        <entry colsep='1' rowsep='1'>
 448         <para>
 449          <emphasis role='strong'>
 450           <literal>d</literal>
 451          </emphasis>
 452         </para>
 453        </entry>
 454        <entry colsep='1' rowsep='1'>
 455         <para>
 456          <link linkend='gdouble'><type>gdouble</type></link>
 457         </para>
 458        </entry>
 459       </row>
 460      </tbody>
 461     </tgroup>
 462    </informaltable>
 463
 464    <para>
 465     Note that in C, small integer types in variable argument lists are promoted up to <link
 466     linkend='gint'><type>int</type></link> or <link linkend='guint'><type>unsigned int</type></link> as appropriate, and
 467     read back accordingly.  <link linkend='gint'><type>int</type></link> is 32 bits on every platform on which GLib is
 468     currently suported.  This means that you can use C expressions of type <link linkend='gint'><type>int</type></link>
 469     with <link linkend='g-variant-new'><function>g_variant_new()</function></link> and format characters
 470     '<literal>b</literal>', '<literal>y</literal>', '<literal>n</literal>', '<literal>q</literal>',
 471     '<literal>i</literal>', '<literal>u</literal>' and '<literal>h</literal>'.  Specifically, you can use integer
 472     literals with these characters.
 473    </para>
 474
 475    <para>
 476     When using the '<literal>x</literal>' and '<literal>t</literal>' characters, you must ensure that the value that you
 477     provide is 64 bit.  This means that you should use a cast or make use of the
 478     <link linkend='G-GINT64-CONSTANT--CAPS'><literal>G_GINT64_CONSTANT</literal></link> or
 479     <link linkend='G-GUINT64-CONSTANT--CAPS'><literal>G_GUINT64_CONSTANT</literal></link> macros.
 480    </para>
 481
 482    <para>
 483     No type promotion occurs when using <link linkend='g-variant-get'><function>g_variant_get()</function></link> since
 484     it operates with pointers.  The pointers must always point to a memory region of exactly the correct size.
 485    </para>
 486
 487    <refsect3>
 488     <title>Examples</title>
 489     <informalexample><programlisting>
 490 <![CDATA[GVariant *value1, *value2, *value3, *value4;
 491
 492 value1 = g_variant_new ("y", 200);
 493 value2 = g_variant_new ("b", TRUE);
 494 value3 = g_variant_new ("d", 37.5):
 495 value4 = g_variant_new ("x", G_GINT64_CONSTANT (998877665544332211));
 496
 497 {
 498   gdouble floating;
 499   gboolean truth;
 500   gint64 bignum;
 501
 502
 503   g_variant_get (value1, "y", NULL);      /* ignore the value. */
 504   g_variant_get (value2, "b", &truth);
 505   g_variant_get (value3, "d", &floating);
 506   g_variant_get (value4, "x", &bignum);
 507 }]]></programlisting></informalexample>
 508    </refsect3>
 509   </refsect2>
 510
 511   <refsect2 id='gvariant-format-strings-strings'>
 512    <title>Strings</title>
 513    <para>
 514     <emphasis role='strong'>
 515      Characters: <literal>s</literal>, <literal>o</literal>, <literal>g</literal>
 516     </emphasis>
 517    </para>
 518
 519    <para>
 520     String conversions occur to and from standard nul-terminated C strings.  Upon encountering an
 521     '<literal>s</literal>', '<literal>o</literal>' or '<literal>g</literal>' in a format string,
 522     <link linkend='g-variant-new'><function>g_variant_new()</function></link> takes a <code>(const
 523     <link linkend='gchar'>gchar</link> *)</code> and makes a copy of it.
 524     <link linkend='NULL--CAPS'><literal>NULL</literal></link> is not a valid string.  If the '<literal>o</literal>' or
 525     '<literal>g</literal>' characters are used, care must be taken to ensure that the passed string is a valid DBus
 526     object path or DBus type signature, respectively.
 527    </para>
 528    <para>
 529     Upon encounting '<literal>s</literal>', '<literal>o</literal>' or '<literal>g</literal>', <link
 530     linkend='g-variant-get'><function>g_variant_get()</function></link> takes a pointer to a
 531     <code>(<link linkend='gchar'>gchar</link> *)</code> (ie: <code>(<link linkend='gchar'>gchar</link> **)</code>) and
 532     sets it to a newly-allocated copy of the string.  It is appropriate to free this copy using
 533     <link linkend='g-free'><function>g_free()</function></link>.
 534     <link linkend='NULL--CAPS'><literal>NULL</literal></link> may also be passed to indicate that the value of the
 535     string should be ignored (in which case no copy is made).
 536    </para>
 537
 538    <refsect3>
 539     <title>Examples</title>
 540     <informalexample><programlisting>
 541 <![CDATA[GVariant *value1, *value2, *value3;
 542
 543 value1 = g_variant_new ("s", "hello world!");
 544 value2 = g_variant_new ("o", "/must/be/a/valid/path");
 545 value3 = g_variant_new ("g", "iias");
 546
 547 #if 0
 548   g_variant_new ("s", NULL);      /* not valid: NULL is not a string. */
 549 #endif
 550
 551 {
 552   gchar *result;
 553
 554   g_variant_get (value1, "s", &result);
 555   g_print ("It was '%s'\n", result);
 556   g_free (result);
 557 }]]></programlisting></informalexample>
 558    </refsect3>
 559   </refsect2>
 560
 561   <refsect2 id='gvariant-format-strings-variants'>
 562    <title>Variants</title>
 563    <para>
 564     <emphasis role='strong'>
 565      Characters: <literal>v</literal>
 566     </emphasis>
 567    </para>
 568
 569    <para>
 570     Upon encountering a '<literal>v</literal>',
 571     <link linkend='g-variant-new'><function>g_variant_new()</function></link> takes a <code>(<link
 572     linkend='GVariant'>GVariant</link> *)</code>.  The value of the
 573     <link linkend='GVariant'><type>GVariant</type></link> is used as the contents of the variant value.
 574    </para>
 575    <para>
 576     Upon encountering a '<literal>v</literal>', <link
 577     linkend='g-variant-get'><function>g_variant_get()</function></link> takes a pointer to a
 578     <code>(<link linkend='GVariant'>GVariant</link> *)</code> (ie: <code>(<link linkend='GVariant'>GVariant</link> **)
 579     </code>).  It is set to a new reference to a <link linkend='GVariant'><type>GVariant</type></link> instance
 580     containing the contents of the variant value.  It is appropriate to free this reference using
 581     <link linkend='g-variant-unref'><function>g_variant_unref()</function></link>.
 582     <link linkend='NULL--CAPS'><literal>NULL</literal></link> may also be passed to indicate that the value should be
 583     ignored (in which case no new reference is created).
 584    </para>
 585
 586    <refsect3>
 587     <title>Examples</title>
 588     <informalexample><programlisting>
 589 <![CDATA[GVariant *x, *y;
 590
 591 /* the following two lines are equivalent: */
 592 x = g_variant_new ("v", y);
 593 x = g_variant_new_variant (y);
 594
 595 /* as are these: */
 596 g_variant_get (x, "v", &y);
 597 y = g_variant_get_variant (x);]]></programlisting></informalexample>
 598    </refsect3>
 599   </refsect2>
 600
 601
 602   <refsect2 id='gvariant-format-strings-arrays'>
 603    <title>Arrays</title>
 604    <para>
 605     <emphasis role='strong'>
 606      Characters: <literal>a</literal>
 607     </emphasis>
 608    </para>
 609
 610    <para>
 611     Upon encountering an '<literal>a</literal>' character followed by a type string,
 612     <link linkend='g-variant-new'><function>g_variant_new()</function></link> will take a
 613     <code>(<link linkend='GVariantBuilder'>GVariantBuilder</link> *)</code> that has been created as an array builder
 614     for an array of the type given in the type string.  The builder will have
 615     <link linkend='g-variant-builder-end'><function>g_variant_builder_end()</function></link> called on it and the
 616     result will be used as the value.  As a special exception, if the given type string is a definite type, then
 617     <link linkend='NULL--CAPS'><literal>NULL</literal></link> may be given to mean an empty array of that type.
 618    </para>
 619
 620    <para>
 621     Upon encountering an '<literal>a</literal>' character followed by a type string,
 622     <link linkend='g-variant-get'><function>g_variant_get()</function></link> will take a pointer to a
 623     <code>(<link linkend='GVariantIter'>GVariantIter</link> *)</code> (ie:
 624     <code>(<link linkend='GVariantIter'>GVariantIter</link> **)</code>).
 625     A new heap-allocated iterator is created and returned, initialised for iterating over the elements of the array.
 626     This iterator should be freed when you are done with it, using
 627     <link linkend='g-variant-iter-free'><function>g_variant_iter_free()</function></link>.
 628     <link linkend='NULL--CAPS'><literal>NULL</literal></link> may also be given to indicate that the value of the array
 629     should be ignored.
 630    </para>
 631
 632    <refsect3>
 633     <title>Examples</title>
 634     <informalexample><programlisting>
 635 <![CDATA[GVariantBuilder *builder;
 636 GVariant *value;
 637
 638 builder = g_variant_builder_new (G_VARIANT_TYPE ("as"));
 639 g_variant_builder_add (builder, "s", "when");
 640 g_variant_builder_add (builder, "s", "in");
 641 g_variant_builder_add (builder, "s", "the");
 642 g_variant_builder_add (builder, "s", "course");
 643 value = g_variant_new ("as", builder);
 644 g_variant_builder_unref (builder);
 645
 646 {
 647   GVariantIter *iter;
 648   gchar *str;
 649
 650   g_variant_get (value, "as", &iter);
 651   while (g_variant_iter_loop (iter, "s", &str))
 652     g_print ("%s\n", str);
 653   g_variant_iter_free (iter);
 654 }
 655
 656 g_variant_unref (value);]]></programlisting></informalexample>
 657    </refsect3>
 658   </refsect2>
 659
 660   <refsect2 id='gvariant-format-strings-maybe-types'>
 661    <title>Maybe Types</title>
 662    <para>
 663     <emphasis role='strong'>
 664      Characters: <literal>m</literal>
 665     </emphasis>
 666    </para>
 667    <para>
 668     Maybe types are handled in two separate ways depending on the format string that follows the
 669     '<literal>m</literal>'.  The method that is used currently depends entirely on the character immediately following the
 670     '<literal>m</literal>'.
 671    </para>
 672
 673    <para>
 674     The first way is used with format strings starting with '<literal>s</literal>', '<literal>o</literal>',
 675     '<literal>g</literal>', '<literal>v</literal>', '<literal>@</literal>', '<literal>*</literal>',
 676     '<literal>?</literal>', '<literal>r</literal>', '<literal>&amp;</literal>', or '<literal>^</literal>'.  In all of
 677     these cases, for non-maybe types, <link linkend='g-variant-new'><function>g_variant_new()</function></link> takes
 678     a pointer to a non-<link linkend='NULL--CAPS'><literal>NULL</literal></link> value and
 679     <link linkend='g-variant-get'><function>g_variant_get()</function></link> returns (by reference) a
 680     non-<link linkend='NULL--CAPS'><literal>NULL</literal></link> pointer.  When any of these format strings are
 681     prefixed with an '<literal>m</literal>', the type of arguments that are collected does not change in any way, but
 682     <link linkend='NULL--CAPS'><literal>NULL</literal></link> becomes a permissable value, to indicate the Nothing case.
 683    </para>
 684    <para>
 685     Note that the "special exception" introduced in the array section for constructing empty arrays is ignored
 686     here.  Using a <literal>NULL</literal> pointer with the format string '<literal>mas</literal>' constructs
 687     the Nothing value -- not an empty array.
 688    </para>
 689    <para>
 690     The second way is used with all other format strings.  For
 691     <link linkend='g-variant-new'><function>g_variant_new()</function></link> an additional
 692     <link linkend='gboolean'><type>gboolean</type></link> argument is collected and for
 693     <link linkend='g-variant-get'><function>g_variant_get()</function></link> an additional
 694     <code>(<link linkend='gboolean'>gboolean</link> *)</code>.  Following this argument, the arguments that are normally
 695     collected for the equivalent non-maybe type will be collected.
 696    </para>
 697    <para>
 698     If <link linkend='FALSE--CAPS'><literal>FALSE</literal></link> is given to
 699     <link linkend='g-variant-new'><function>g_variant_new()</function></link> then the Nothing value is constructed and
 700     the collected arguments are ignored.  Otherwise (if <link linkend='TRUE--CAPS'><literal>TRUE</literal></link> was
 701     given), the arguments are used in the normal way to create the Just value.
 702    </para>
 703    <para>
 704     If <link linkend='NULL--CAPS'><literal>NULL</literal></link> is given to
 705     <link linkend='g-variant-get'><function>g_variant_get()</function></link> then the value is ignored.  If a
 706     non-<link linkend='NULL--CAPS'><literal>NULL</literal></link> pointer is given then it is used to return by reference
 707     whether the value was Just.  In the case that the value was Just, the
 708     <link linkend='gboolean'><type>gboolean</type></link> will be set to
 709     <link linkend='TRUE--CAPS'><literal>TRUE</literal></link> and the value will be stored in the arguments in the usual
 710     way.  In the case that the value was Nothing, the <link linkend='gboolean'><type>gboolean</type></link> will be set to
 711     <link linkend='FALSE--CAPS'><literal>FALSE</literal></link> and the arguments will be collected in the normal way
 712     but have their values set to binary zero.
 713    </para>
 714
 715    <refsect3>
 716     <title>Examples</title>
 717     <informalexample><programlisting>
 718 <![CDATA[GVariant *value1, *value2, *value3, *value4, *value5, *value6;
 719 value1 = g_variant_new ("ms", "Hello world");
 720 value2 = g_variant_new ("ms", NULL);
 721 value3 = g_variant_new ("(m(ii)s)", TRUE, 123, 456, "Done");
 722 value4 = g_variant_new ("(m(ii)s)", FALSE, -1, -1, "Done");          /* both '-1' are ignored. */
 723 value5 = g_variant_new ("(m@(ii)s)", NULL, "Done");
 724
 725 {
 726   GVariant *contents;
 727   const gchar *cstr;
 728   gboolean just;
 729   gint32 x, y;
 730   gchar *str;
 731
 732   g_variant_get (value1, "ms", &str);
 733   if (str != NULL)
 734     g_print ("str: %s\n", str);
 735   else
 736     g_print ("it was null\n");
 737   g_free (str);
 738
 739
 740   g_variant_get (value2, "m&s", &cstr);
 741   if (cstr != NULL)
 742     g_print ("str: %s\n", cstr);
 743   else
 744     g_print ("it was null\n");
 745   /* don't free 'cstr' */
 746
 747
 748   /* NULL passed for the gboolean *, but two 'gint32 *' still collected */
 749   g_variant_get (value3, "(m(ii)s)", NULL, NULL, NULL, &str);
 750   g_print ("string is %s\n", str);
 751   g_free (str);
 752
 753   /* note: &s used, so g_free() not needed */
 754   g_variant_get (value4, "(m(ii)&s)", &just, &x, &y, &cstr);
 755   if (just)
 756     g_print ("it was (%d, %d)\n", x, y);
 757   else
 758     g_print ("it was null\n");
 759   g_print ("string is %s\n", cstr);
 760   /* don't free 'cstr' */
 761
 762
 763   g_variant_get (value5, "(m*s)", &contents, NULL); /* ignore the string. */
 764   if (contents != NULL)
 765     {
 766       g_variant_get (contents, "(ii)", &x, &y);
 767       g_print ("it was (%d, %d)\n", x, y);
 768       g_variant_unref (contents);
 769     }
 770   else
 771     g_print ("it was null\n");
 772 }]]></programlisting></informalexample>
 773    </refsect3>
 774   </refsect2>
 775
 776   <refsect2 id='gvariant-format-strings-tuples'>
 777    <title>Tuples</title>
 778    <para>
 779     <emphasis role='strong'>
 780      Characters: <code>()</code>
 781     </emphasis>
 782    </para>
 783
 784    <para>
 785     Tuples are handled by handling each item in the tuple, in sequence.  Each item is handled in the usual way.
 786    </para>
 787
 788    <refsect3>
 789     <title>Examples</title>
 790     <informalexample><programlisting>
 791 <![CDATA[GVariant *value1, *value2;
 792
 793 value1 = g_variant_new ("(s(ii))", "Hello", 55, 77);
 794 value2 = g_variant_new ("()");
 795
 796 {
 797   gchar *string;
 798   gint x, y;
 799
 800   g_variant_get (value1, "(s(ii))", &string, &x, &y);
 801   g_print ("%s, %d, %d\n", string, x, y);
 802   g_free (string);
 803
 804   g_variant_get (value2, "()");   /* do nothing... */
 805 }]]></programlisting></informalexample>
 806    </refsect3>
 807   </refsect2>
 808
 809   <refsect2 id='gvariant-format-strings-dictionaries'>
 810    <title>Dictionaries</title>
 811    <para>
 812     <emphasis role='strong'>
 813      Characters: <code>{}</code>
 814     </emphasis>
 815    </para>
 816
 817    <para>
 818     Dictionary entries are handled by handling first the key, then the value.  Each is handled in the usual way.
 819    </para>
 820
 821    <refsect3>
 822     <title>Examples</title>
 823     <informalexample><programlisting>
 824 <![CDATA[GVariantBuilder *b;
 825 GVariant *dict;
 826
 827 b = g_variant_builder_new (G_VARIANT_TYPE ("a{sv}"));
 828 g_variant_builder_add (b, "{sv}", "name", g_variant_new_string ("foo"));
 829 g_variant_builder_add (b, "{sv}", "timeout", g_variant_new_int32 (10));
 830 dict = g_variant_builder_end (b);]]></programlisting></informalexample>
 831    </refsect3>
 832   </refsect2>
 833
 834   <refsect2 id='gvariant-format-strings-gvariant'>
 835    <title>GVariant *</title>
 836    <para>
 837     <emphasis role='strong'>
 838      Characters: <literal>@</literal>, <literal>*</literal>, <literal>?</literal>, <literal>r</literal>
 839     </emphasis>
 840
 841    </para>
 842    <para>
 843     Upon encountering a '<literal>@</literal>' in front of a type string,
 844     <link linkend='g-variant-new'><function>g_variant_new()</function></link> takes a
 845     non-<link linkend='NULL--CAPS'><literal>NULL</literal></link> pointer to a
 846     <link linkend='GVariant'><type>GVariant</type></link> and uses its value directly instead of collecting arguments to
 847     create the value.  The provided <link linkend='GVariant'><type>GVariant</type></link> must have a type that matches the
 848     type string following the '<literal>@</literal>'.  '<literal>*</literal>' is
 849     the same as '<literal>@*</literal>' (ie: take a <link linkend='GVariant'><type>GVariant</type></link> of any type).
 850     '<literal>?</literal>' is the same as '<literal>@?</literal>' (ie: take a
 851     <link linkend='GVariant'><type>GVariant</type></link> of any basic type).  '<literal>r</literal>' is the same as
 852     '<literal>@r</literal>' (ie: take a <link linkend='GVariant'><type>GVariant</type></link> of any tuple type).
 853    </para>
 854    <para>
 855     Upon encountering a '<literal>@</literal>' in front of a type string,
 856     <link linkend='g-variant-get'><function>g_variant_get()</function></link>
 857     takes a pointer to a <code>(<link linkend='GVariant'>GVariant</link> *)</code> (ie: a
 858     <code>(<link linkend='GVariant'>GVariant</link> **)</code>) and sets it to a new reference to a
 859     <link linkend='GVariant'><type>GVariant</type></link> containing the value (instead of deconstructing the value into
 860     C types in the usual way).  <link linkend='NULL--CAPS'><literal>NULL</literal></link> can be given to ignore the
 861     value.  '<literal>*</literal>', '<literal>?</literal>' and '<literal>r</literal>' are handled in a way analogous to
 862     what is stated above.
 863    </para>
 864    <para>
 865     You can always use '<literal>*</literal>' as an alternative to '<literal>?</literal>', '<literal>r</literal>' or any
 866     use of '<literal>@</literal>'.  Using the other characters where possible is recommended, however, due to the
 867     improvements in type safety and code self-documentation.
 868    </para>
 869
 870    <refsect3>
 871     <title>Examples</title>
 872     <informalexample><programlisting>
 873 <![CDATA[GVariant *value1, *value2;
 874
 875 value1 = g_variant_new ("(i@ii)", 44, g_variant_new_int32 (55), 66);
 876
 877 /* note: consumes floating reference count on 'value1' */
 878 value2 = g_variant_new ("(@(iii)*)", value1, g_variant_new_string ("foo"));
 879
 880 {
 881   const gchar *string;
 882   GVariant *tmp;
 883   gsize length;
 884   gint x, y, z;
 885
 886   g_variant_get (value2, "((iii)*)", &x, &y, &z, &tmp);
 887   string = g_variant_get_string (tmp, &length);
 888   g_print ("it is %d %d %d %s (length=%d)\n", x, y, z, string, (int) length);
 889   g_variant_unref (tmp);
 890
 891   /* quick way to skip all the values in a tuple */
 892   g_variant_get (value2, "(rs)", NULL, &string); /* or "(@(iii)s)" */
 893   g_print ("i only got the string: %s\n", string);
 894   g_free (string);
 895 }]]></programlisting></informalexample>
 896    </refsect3>
 897   </refsect2>
 898
 899   <refsect2 id='gvariant-format-strings-pointers'>
 900    <title>Pointers</title>
 901    <para>
 902     <emphasis role='strong'>
 903      Characters: <code>&amp;</code>
 904     </emphasis>
 905    </para>
 906
 907    <para>
 908     The '<code>&amp;</code>' character is used to indicate that serialised data should be directly exchanged via a
 909     pointer.
 910    </para>
 911    <para>
 912     Currently, the only use for this character is when it is applied to a string (ie: '<literal>&amp;s</literal>',
 913     '<literal>&amp;o</literal>' or '<code>&amp;g</code>').  For
 914     <link linkend='g-variant-new'><function>g_variant_new()</function></link> this has absolutely no effect.  The string
 915     is collected and duplicated normally.  For <link linkend='g-variant-get'><function>g_variant_get()</function></link>
 916     it means that instead of creating a newly allocated copy of the string, a pointer to the serialised data is
 917     returned.  This pointer should not be freed.  Validity checks are performed to ensure that the string data will
 918     always be properly nul-terminated.
 919    </para>
 920
 921    <refsect3>
 922     <title>Examples</title>
 923     <informalexample><programlisting>
 924 <![CDATA[{
 925   const gchar *str;
 926   GVariant *value;
 927
 928   value = g_variant_new ("&s", "hello world");
 929   str = g_variant_get ("&s", &str);
 930   g_print ("string is: %s\n", str);
 931   /* no need to free str */
 932 }]]></programlisting></informalexample>
 933    </refsect3>
 934   </refsect2>
 935
 936   <refsect2 id='gvariant-format-strings-convenience'>
 937    <title>Convenience Conversions</title>
 938    <para>
 939     <emphasis role='strong'>
 940      Characters: <literal>^</literal>
 941     </emphasis>
 942    </para>
 943
 944    <para>
 945     The '<literal>^</literal>' character currently supports conversion to and from bytestrings or to and from arrays
 946     of strings or bytestrings.  It has a number of forms.
 947    </para>
 948
 949    <para>
 950     In all forms, when used with <link linkend='g-variant-new'><function>g_variant_new()</function></link> one
 951     pointer value is collected from the variable arguments and passed to a function (as given in the table below).
 952     The result of that function is used as the value for this position.  When used with
 953     <link linkend='g-variant-get'><function>g_variant_get()</function></link> one pointer value is produced by using
 954     the function (given in the table) and returned by reference.
 955    </para>
 956
 957    <informaltable>
 958     <tgroup cols='2'>
 959      <colspec colname='col_0'/>
 960      <colspec colname='col_1'/>
 961      <colspec colname='col_2'/>
 962      <tbody>
 963
 964       <row rowsep='1'>
 965        <entry colsep='1' rowsep='1'>
 966         <para>
 967          <emphasis role='strong'>Conversion</emphasis>
 968         </para>
 969        </entry>
 970        <entry colsep='1' rowsep='1'>
 971         <para>
 972           <emphasis role='strong'>
 973             Used with <link linkend='g-variant-new'><function>g_variant_new()</function></link>
 974           </emphasis>
 975         </para>
 976        </entry>
 977        <entry colsep='1' rowsep='1'>
 978         <para>
 979           <emphasis role='strong'>
 980             Used with <link linkend='g-variant-get'><function>g_variant_get()</function></link>
 981           </emphasis>
 982         </para>
 983        </entry>
 984       </row>
 985
 986       <row rowsep='1'>
 987        <entry colsep='1' rowsep='1'>
 988         <para>
 989          <emphasis role='strong'>
 990           <literal>^as</literal>
 991          </emphasis>
 992         </para>
 993        </entry>
 994        <entry colsep='1' rowsep='1' morerows='1'>
 995         <para>
 996          equivalent to <link linkend='g-variant-new-strv'><function>g_variant_new_strv()</function></link>
 997         </para>
 998        </entry>
 999        <entry colsep='1' rowsep='1'>
1000         <para>
1001          equivalent to <link linkend='g-variant-dup-strv'><function>g_variant_dup_strv()</function></link>
1002         </para>
1003        </entry>
1004       </row>
1005
1006       <row rowsep='1'>
1007        <entry colsep='1' rowsep='1'>
1008         <para>
1009          <emphasis role='strong'>
1010           <literal>^a&amp;s</literal>
1011          </emphasis>
1012         </para>
1013        </entry>
1014        <entry colsep='1' rowsep='1'>
1015         <para>
1016          equivalent to <link linkend='g-variant-get-strv'><function>g_variant_get_strv()</function></link>
1017         </para>
1018        </entry>
1019       </row>
1020
1021       <row rowsep='1'>
1022        <entry colsep='1' rowsep='1'>
1023         <para>
1024          <emphasis role='strong'>
1025           <literal>^ay</literal>
1026          </emphasis>
1027         </para>
1028        </entry>
1029        <entry colsep='1' rowsep='1' morerows='1'>
1030         <para>
1031          equivalent to <link linkend='g-variant-new-bytestring'><function>g_variant_new_bytestring()</function></link>
1032         </para>
1033        </entry>
1034        <entry colsep='1' rowsep='1'>
1035         <para>
1036          equivalent to <link linkend='g-variant-dup-bytestring'><function>g_variant_dup_bytestring()</function></link>
1037         </para>
1038        </entry>
1039       </row>
1040
1041       <row rowsep='1'>
1042        <entry colsep='1' rowsep='1'>
1043         <para>
1044          <emphasis role='strong'>
1045           <literal>^&amp;ay</literal>
1046          </emphasis>
1047         </para>
1048        </entry>
1049        <entry colsep='1' rowsep='1'>
1050         <para>
1051          equivalent to <link linkend='g-variant-get-bytestring'><function>g_variant_get_bytestring()</function></link>
1052         </para>
1053        </entry>
1054       </row>
1055
1056       <row rowsep='1'>
1057        <entry colsep='1' rowsep='1'>
1058         <para>
1059          <emphasis role='strong'>
1060           <literal>^aay</literal>
1061          </emphasis>
1062         </para>
1063        </entry>
1064        <entry colsep='1' rowsep='1' morerows='1'>
1065         <para>
1066          equivalent to <link linkend='g-variant-new-bytestring-array'><function>g_variant_new_bytestring_array()</function></link>
1067         </para>
1068        </entry>
1069        <entry colsep='1' rowsep='1'>
1070         <para>
1071          equivalent to <link linkend='g-variant-dup-bytestring-array'><function>g_variant_dup_bytestring_array()</function></link>
1072         </para>
1073        </entry>
1074       </row>
1075
1076       <row rowsep='1'>
1077        <entry colsep='1' rowsep='1'>
1078         <para>
1079          <emphasis role='strong'>
1080           <literal>^a&amp;ay</literal>
1081          </emphasis>
1082         </para>
1083        </entry>
1084        <entry colsep='1' rowsep='1'>
1085         <para>
1086          equivalent to <link linkend='g-variant-get-bytestring-array'><function>g_variant_get_bytestring_array()</function></link>
1087         </para>
1088        </entry>
1089       </row>
1090
1091      </tbody>
1092     </tgroup>
1093    </informaltable>
1094   </refsect2>
1095  </refsect1>
1096 </refentry>