docs/reference/glib/html/glib-GVariant.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>GVariant</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
   7 <link rel="home" href="index.html" title="GLib Reference Manual">
   8 <link rel="up" href="glib-data-types.html" title="GLib Data Types">
   9 <link rel="prev" href="glib-GVariantType.html" title="GVariantType">
  10 <link rel="next" href="gvariant-format-strings.html" title="GVariant Format Strings">
  11 <meta name="generator" content="GTK-Doc V1.13 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 <link rel="chapter" href="glib.html" title="GLib Overview">
  14 <link rel="chapter" href="glib-fundamentals.html" title="GLib Fundamentals">
  15 <link rel="chapter" href="glib-core.html" title="GLib Core Application Support">
  16 <link rel="chapter" href="glib-utilities.html" title="GLib Utilities">
  17 <link rel="chapter" href="glib-data-types.html" title="GLib Data Types">
  18 <link rel="chapter" href="tools.html" title="GLib Tools">
  19 <link rel="index" href="api-index-full.html" title="Index">
  20 <link rel="index" href="api-index-deprecated.html" title="Index of deprecated symbols">
  21 <link rel="index" href="api-index-2-2.html" title="Index of new symbols in 2.2">
  22 <link rel="index" href="api-index-2-4.html" title="Index of new symbols in 2.4">
  23 <link rel="index" href="api-index-2-6.html" title="Index of new symbols in 2.6">
  24 <link rel="index" href="api-index-2-8.html" title="Index of new symbols in 2.8">
  25 <link rel="index" href="api-index-2-10.html" title="Index of new symbols in 2.10">
  26 <link rel="index" href="api-index-2-12.html" title="Index of new symbols in 2.12">
  27 <link rel="index" href="api-index-2-14.html" title="Index of new symbols in 2.14">
  28 <link rel="index" href="api-index-2-16.html" title="Index of new symbols in 2.16">
  29 <link rel="index" href="api-index-2-18.html" title="Index of new symbols in 2.18">
  30 <link rel="index" href="api-index-2-20.html" title="Index of new symbols in 2.20">
  31 <link rel="index" href="api-index-2-22.html" title="Index of new symbols in 2.22">
  32 <link rel="index" href="api-index-2-24.html" title="Index of new symbols in 2.24">
  33 </head>
  34 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  35 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  36 <tr valign="middle">
  37 <td><a accesskey="p" href="glib-GVariantType.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  38 <td><a accesskey="u" href="glib-data-types.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  39 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  40 <th width="100%" align="center">GLib Reference Manual</th>
  41 <td><a accesskey="n" href="gvariant-format-strings.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  42 </tr>
  43 <tr><td colspan="5" class="shortcuts">
  44 <a href="#glib-GVariant.synopsis" class="shortcut">Top</a>
  45                    |
  46                   <a href="#glib-GVariant.description" class="shortcut">Description</a>
  47 </td></tr>
  48 </table>
  49 <div class="refentry" title="GVariant">
  50 <a name="glib-GVariant"></a><div class="titlepage"></div>
  51 <div class="refnamediv"><table width="100%"><tr>
  52 <td valign="top">
  53 <h2><span class="refentrytitle"><a name="glib-GVariant.top_of_page"></a>GVariant</span></h2>
  54 <p>GVariant — strongly typed value datatype</p>
  55 </td>
  56 <td valign="top" align="right"></td>
  57 </tr></table></div>
  58 <div class="refsynopsisdiv" title="Synopsis">
  59 <a name="glib-GVariant.synopsis"></a><h2>Synopsis</h2>
  60 <pre class="synopsis">
  61 #include &lt;glib.h&gt;
  62
  63                     <a class="link" href="glib-GVariant.html#GVariant" title="GVariant">GVariant</a>;
  64 <span class="returnvalue">void</span>                <a class="link" href="glib-GVariant.html#g-variant-unref" title="g_variant_unref ()">g_variant_unref</a>                     (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
  65 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-ref" title="g_variant_ref ()">g_variant_ref</a>                       (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
  66 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-ref-sink" title="g_variant_ref_sink ()">g_variant_ref_sink</a>                  (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
  67 const <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="returnvalue">GVariantType</span></a> * <a class="link" href="glib-GVariant.html#g-variant-get-type" title="g_variant_get_type ()">g_variant_get_type</a>                 (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
  68 const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       <a class="link" href="glib-GVariant.html#g-variant-get-type-string" title="g_variant_get_type_string ()">g_variant_get_type_string</a>           (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
  69 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-GVariant.html#g-variant-is-of-type" title="g_variant_is_of_type ()">g_variant_is_of_type</a>                (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
  70                                                          const <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="returnvalue">GVariantType</span></a> *type);
  71 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-GVariant.html#g-variant-is-container" title="g_variant_is_container ()">g_variant_is_container</a>              (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
  72
  73 <a class="link" href="glib-GVariant.html#GVariantClass" title="enum GVariantClass"><span class="returnvalue">GVariantClass</span></a>       <a class="link" href="glib-GVariant.html#g-variant-classify" title="g_variant_classify ()">g_variant_classify</a>                  (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
  74 enum                <a class="link" href="glib-GVariant.html#GVariantClass" title="enum GVariantClass">GVariantClass</a>;
  75
  76 <span class="returnvalue">void</span>                <a class="link" href="glib-GVariant.html#g-variant-get" title="g_variant_get ()">g_variant_get</a>                       (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
  77                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *format_string,
  78                                                          ...);
  79 <span class="returnvalue">void</span>                <a class="link" href="glib-GVariant.html#g-variant-get-va" title="g_variant_get_va ()">g_variant_get_va</a>                    (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
  80                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *format_string,
  81                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **endptr,
  82                                                          <span class="returnvalue">va_list</span> *app);
  83 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new" title="g_variant_new ()">g_variant_new</a>                       (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *format_string,
  84                                                          ...);
  85 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new-va" title="g_variant_new_va ()">g_variant_new_va</a>                    (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *format_string,
  86                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **endptr,
  87                                                          <span class="returnvalue">va_list</span> *app);
  88
  89 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new-boolean" title="g_variant_new_boolean ()">g_variant_new_boolean</a>               (<a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> boolean);
  90 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new-byte" title="g_variant_new_byte ()">g_variant_new_byte</a>                  (<a class="link" href="glib-Basic-Types.html#guchar" title="guchar"><span class="returnvalue">guchar</span></a> byte);
  91 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new-int16" title="g_variant_new_int16 ()">g_variant_new_int16</a>                 (<a class="link" href="glib-Basic-Types.html#gint16" title="gint16"><span class="returnvalue">gint16</span></a> int16);
  92 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new-uint16" title="g_variant_new_uint16 ()">g_variant_new_uint16</a>                (<a class="link" href="glib-Basic-Types.html#guint16" title="guint16"><span class="returnvalue">guint16</span></a> uint16);
  93 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new-int32" title="g_variant_new_int32 ()">g_variant_new_int32</a>                 (<a class="link" href="glib-Basic-Types.html#gint32" title="gint32"><span class="returnvalue">gint32</span></a> int32);
  94 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new-uint32" title="g_variant_new_uint32 ()">g_variant_new_uint32</a>                (<a class="link" href="glib-Basic-Types.html#guint32" title="guint32"><span class="returnvalue">guint32</span></a> uint32);
  95 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new-int64" title="g_variant_new_int64 ()">g_variant_new_int64</a>                 (<a class="link" href="glib-Basic-Types.html#gint64" title="gint64"><span class="returnvalue">gint64</span></a> int64);
  96 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new-uint64" title="g_variant_new_uint64 ()">g_variant_new_uint64</a>                (<a class="link" href="glib-Basic-Types.html#guint64" title="guint64"><span class="returnvalue">guint64</span></a> uint64);
  97 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new-handle" title="g_variant_new_handle ()">g_variant_new_handle</a>                (<a class="link" href="glib-Basic-Types.html#gint32" title="gint32"><span class="returnvalue">gint32</span></a> handle);
  98 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new-double" title="g_variant_new_double ()">g_variant_new_double</a>                (<a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="returnvalue">gdouble</span></a> floating);
  99 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new-string" title="g_variant_new_string ()">g_variant_new_string</a>                (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *string);
 100 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new-object-path" title="g_variant_new_object_path ()">g_variant_new_object_path</a>           (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *object_path);
 101 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-GVariant.html#g-variant-is-object-path" title="g_variant_is_object_path ()">g_variant_is_object_path</a>            (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *string);
 102 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new-signature" title="g_variant_new_signature ()">g_variant_new_signature</a>             (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *signature);
 103 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-GVariant.html#g-variant-is-signature" title="g_variant_is_signature ()">g_variant_is_signature</a>              (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *string);
 104 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new-variant" title="g_variant_new_variant ()">g_variant_new_variant</a>               (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
 105 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new-strv" title="g_variant_new_strv ()">g_variant_new_strv</a>                  (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * const *strv,
 106                                                          <a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="returnvalue">gssize</span></a> length);
 107
 108 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-GVariant.html#g-variant-get-boolean" title="g_variant_get_boolean ()">g_variant_get_boolean</a>               (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
 109 <a class="link" href="glib-Basic-Types.html#guchar" title="guchar"><span class="returnvalue">guchar</span></a>              <a class="link" href="glib-GVariant.html#g-variant-get-byte" title="g_variant_get_byte ()">g_variant_get_byte</a>                  (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
 110 <a class="link" href="glib-Basic-Types.html#gint16" title="gint16"><span class="returnvalue">gint16</span></a>              <a class="link" href="glib-GVariant.html#g-variant-get-int16" title="g_variant_get_int16 ()">g_variant_get_int16</a>                 (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
 111 <a class="link" href="glib-Basic-Types.html#guint16" title="guint16"><span class="returnvalue">guint16</span></a>             <a class="link" href="glib-GVariant.html#g-variant-get-uint16" title="g_variant_get_uint16 ()">g_variant_get_uint16</a>                (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
 112 <a class="link" href="glib-Basic-Types.html#gint32" title="gint32"><span class="returnvalue">gint32</span></a>              <a class="link" href="glib-GVariant.html#g-variant-get-int32" title="g_variant_get_int32 ()">g_variant_get_int32</a>                 (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
 113 <a class="link" href="glib-Basic-Types.html#guint32" title="guint32"><span class="returnvalue">guint32</span></a>             <a class="link" href="glib-GVariant.html#g-variant-get-uint32" title="g_variant_get_uint32 ()">g_variant_get_uint32</a>                (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
 114 <a class="link" href="glib-Basic-Types.html#gint64" title="gint64"><span class="returnvalue">gint64</span></a>              <a class="link" href="glib-GVariant.html#g-variant-get-int64" title="g_variant_get_int64 ()">g_variant_get_int64</a>                 (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
 115 <a class="link" href="glib-Basic-Types.html#guint64" title="guint64"><span class="returnvalue">guint64</span></a>             <a class="link" href="glib-GVariant.html#g-variant-get-uint64" title="g_variant_get_uint64 ()">g_variant_get_uint64</a>                (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
 116 <a class="link" href="glib-Basic-Types.html#gint32" title="gint32"><span class="returnvalue">gint32</span></a>              <a class="link" href="glib-GVariant.html#g-variant-get-handle" title="g_variant_get_handle ()">g_variant_get_handle</a>                (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
 117 <a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="returnvalue">gdouble</span></a>             <a class="link" href="glib-GVariant.html#g-variant-get-double" title="g_variant_get_double ()">g_variant_get_double</a>                (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
 118 const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       <a class="link" href="glib-GVariant.html#g-variant-get-string" title="g_variant_get_string ()">g_variant_get_string</a>                (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
 119                                                          <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a> *length);
 120 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-GVariant.html#g-variant-dup-string" title="g_variant_dup_string ()">g_variant_dup_string</a>                (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
 121                                                          <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a> *length);
 122 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-get-variant" title="g_variant_get_variant ()">g_variant_get_variant</a>               (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
 123 const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **      <a class="link" href="glib-GVariant.html#g-variant-get-strv" title="g_variant_get_strv ()">g_variant_get_strv</a>                  (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
 124                                                          <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a> *length);
 125 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **            <a class="link" href="glib-GVariant.html#g-variant-dup-strv" title="g_variant_dup_strv ()">g_variant_dup_strv</a>                  (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
 126                                                          <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a> *length);
 127
 128 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new-maybe" title="g_variant_new_maybe ()">g_variant_new_maybe</a>                 (const <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="returnvalue">GVariantType</span></a> *child_type,
 129                                                          <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *child);
 130 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new-array" title="g_variant_new_array ()">g_variant_new_array</a>                 (const <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="returnvalue">GVariantType</span></a> *child_type,
 131                                                          <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> * const *children,
 132                                                          <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a> n_children);
 133 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new-tuple" title="g_variant_new_tuple ()">g_variant_new_tuple</a>                 (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> * const *children,
 134                                                          <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a> n_children);
 135 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new-dict-entry" title="g_variant_new_dict_entry ()">g_variant_new_dict_entry</a>            (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *key,
 136                                                          <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
 137
 138 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-get-maybe" title="g_variant_get_maybe ()">g_variant_get_maybe</a>                 (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
 139 <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a>               <a class="link" href="glib-GVariant.html#g-variant-n-children" title="g_variant_n_children ()">g_variant_n_children</a>                (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
 140 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-get-child-value" title="g_variant_get_child_value ()">g_variant_get_child_value</a>           (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
 141                                                          <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a> index_);
 142 <span class="returnvalue">void</span>                <a class="link" href="glib-GVariant.html#g-variant-get-child" title="g_variant_get_child ()">g_variant_get_child</a>                 (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
 143                                                          <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a> index_,
 144                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *format_string,
 145                                                          ...);
 146 <a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="returnvalue">gconstpointer</span></a>       <a class="link" href="glib-GVariant.html#g-variant-get-fixed-array" title="g_variant_get_fixed_array ()">g_variant_get_fixed_array</a>           (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
 147                                                          <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a> *n_elements,
 148                                                          <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a> element_size);
 149
 150 <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a>               <a class="link" href="glib-GVariant.html#g-variant-get-size" title="g_variant_get_size ()">g_variant_get_size</a>                  (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
 151 <a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="returnvalue">gconstpointer</span></a>       <a class="link" href="glib-GVariant.html#g-variant-get-data" title="g_variant_get_data ()">g_variant_get_data</a>                  (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
 152 <span class="returnvalue">void</span>                <a class="link" href="glib-GVariant.html#g-variant-store" title="g_variant_store ()">g_variant_store</a>                     (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
 153                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> data);
 154 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new-from-data" title="g_variant_new_from_data ()">g_variant_new_from_data</a>             (const <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="returnvalue">GVariantType</span></a> *type,
 155                                                          <a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="returnvalue">gconstpointer</span></a> data,
 156                                                          <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a> size,
 157                                                          <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> trusted,
 158                                                          <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="returnvalue">GDestroyNotify</span></a> notify,
 159                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> user_data);
 160 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-byteswap" title="g_variant_byteswap ()">g_variant_byteswap</a>                  (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
 161 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-get-normal-form" title="g_variant_get_normal_form ()">g_variant_get_normal_form</a>           (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
 162 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-GVariant.html#g-variant-is-normal-form" title="g_variant_is_normal_form ()">g_variant_is_normal_form</a>            (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
 163
 164 <a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               <a class="link" href="glib-GVariant.html#g-variant-hash" title="g_variant_hash ()">g_variant_hash</a>                      (<a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="returnvalue">gconstpointer</span></a> value);
 165 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-GVariant.html#g-variant-equal" title="g_variant_equal ()">g_variant_equal</a>                     (<a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="returnvalue">gconstpointer</span></a> one,
 166                                                          <a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="returnvalue">gconstpointer</span></a> two);
 167
 168 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-GVariant.html#g-variant-print" title="g_variant_print ()">g_variant_print</a>                     (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
 169                                                          <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> type_annotate);
 170 <a class="link" href="glib-Strings.html#GString" title="GString"><span class="returnvalue">GString</span></a> *           <a class="link" href="glib-GVariant.html#g-variant-print-string" title="g_variant_print_string ()">g_variant_print_string</a>              (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
 171                                                          <a class="link" href="glib-Strings.html#GString" title="GString"><span class="returnvalue">GString</span></a> *string,
 172                                                          <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> type_annotate);
 173
 174                     <a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter">GVariantIter</a>;
 175 <a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="returnvalue">GVariantIter</span></a> *      <a class="link" href="glib-GVariant.html#g-variant-iter-copy" title="g_variant_iter_copy ()">g_variant_iter_copy</a>                 (<a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="returnvalue">GVariantIter</span></a> *iter);
 176 <span class="returnvalue">void</span>                <a class="link" href="glib-GVariant.html#g-variant-iter-free" title="g_variant_iter_free ()">g_variant_iter_free</a>                 (<a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="returnvalue">GVariantIter</span></a> *iter);
 177 <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a>               <a class="link" href="glib-GVariant.html#g-variant-iter-init" title="g_variant_iter_init ()">g_variant_iter_init</a>                 (<a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="returnvalue">GVariantIter</span></a> *iter,
 178                                                          <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
 179 <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a>               <a class="link" href="glib-GVariant.html#g-variant-iter-n-children" title="g_variant_iter_n_children ()">g_variant_iter_n_children</a>           (<a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="returnvalue">GVariantIter</span></a> *iter);
 180 <a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="returnvalue">GVariantIter</span></a> *      <a class="link" href="glib-GVariant.html#g-variant-iter-new" title="g_variant_iter_new ()">g_variant_iter_new</a>                  (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
 181 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-iter-next-value" title="g_variant_iter_next_value ()">g_variant_iter_next_value</a>           (<a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="returnvalue">GVariantIter</span></a> *iter);
 182 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-GVariant.html#g-variant-iter-next" title="g_variant_iter_next ()">g_variant_iter_next</a>                 (<a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="returnvalue">GVariantIter</span></a> *iter,
 183                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *format_string,
 184                                                          ...);
 185 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-GVariant.html#g-variant-iter-loop" title="g_variant_iter_loop ()">g_variant_iter_loop</a>                 (<a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="returnvalue">GVariantIter</span></a> *iter,
 186                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *format_string,
 187                                                          ...);
 188
 189                     <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder">GVariantBuilder</a>;
 190 <span class="returnvalue">void</span>                <a class="link" href="glib-GVariant.html#g-variant-builder-unref" title="g_variant_builder_unref ()">g_variant_builder_unref</a>             (<a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="returnvalue">GVariantBuilder</span></a> *builder);
 191 <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="returnvalue">GVariantBuilder</span></a> *   <a class="link" href="glib-GVariant.html#g-variant-builder-ref" title="g_variant_builder_ref ()">g_variant_builder_ref</a>               (<a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="returnvalue">GVariantBuilder</span></a> *builder);
 192 <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="returnvalue">GVariantBuilder</span></a> *   <a class="link" href="glib-GVariant.html#g-variant-builder-new" title="g_variant_builder_new ()">g_variant_builder_new</a>               (const <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="returnvalue">GVariantType</span></a> *type);
 193 <span class="returnvalue">void</span>                <a class="link" href="glib-GVariant.html#g-variant-builder-init" title="g_variant_builder_init ()">g_variant_builder_init</a>              (<a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="returnvalue">GVariantBuilder</span></a> *builder,
 194                                                          const <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="returnvalue">GVariantType</span></a> *type);
 195 <span class="returnvalue">void</span>                <a class="link" href="glib-GVariant.html#g-variant-builder-clear" title="g_variant_builder_clear ()">g_variant_builder_clear</a>             (<a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="returnvalue">GVariantBuilder</span></a> *builder);
 196 <span class="returnvalue">void</span>                <a class="link" href="glib-GVariant.html#g-variant-builder-add-value" title="g_variant_builder_add_value ()">g_variant_builder_add_value</a>         (<a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="returnvalue">GVariantBuilder</span></a> *builder,
 197                                                          <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);
 198 <span class="returnvalue">void</span>                <a class="link" href="glib-GVariant.html#g-variant-builder-add" title="g_variant_builder_add ()">g_variant_builder_add</a>               (<a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="returnvalue">GVariantBuilder</span></a> *builder,
 199                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *format_string,
 200                                                          ...);
 201 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-builder-end" title="g_variant_builder_end ()">g_variant_builder_end</a>               (<a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="returnvalue">GVariantBuilder</span></a> *builder);
 202 <span class="returnvalue">void</span>                <a class="link" href="glib-GVariant.html#g-variant-builder-open" title="g_variant_builder_open ()">g_variant_builder_open</a>              (<a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="returnvalue">GVariantBuilder</span></a> *builder,
 203                                                          const <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="returnvalue">GVariantType</span></a> *type);
 204 <span class="returnvalue">void</span>                <a class="link" href="glib-GVariant.html#g-variant-builder-close" title="g_variant_builder_close ()">g_variant_builder_close</a>             (<a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="returnvalue">GVariantBuilder</span></a> *builder);
 205
 206 #define             <a class="link" href="glib-GVariant.html#G-VARIANT-PARSE-ERROR:CAPS" title="G_VARIANT_PARSE_ERROR">G_VARIANT_PARSE_ERROR</a>
 207 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-parse" title="g_variant_parse ()">g_variant_parse</a>                     (const <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="returnvalue">GVariantType</span></a> *type,
 208                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *text,
 209                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *limit,
 210                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **endptr,
 211                                                          <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="returnvalue">GError</span></a> **error);
 212 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new-parsed-va" title="g_variant_new_parsed_va ()">g_variant_new_parsed_va</a>             (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *format,
 213                                                          <span class="returnvalue">va_list</span> *app);
 214 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          <a class="link" href="glib-GVariant.html#g-variant-new-parsed" title="g_variant_new_parsed ()">g_variant_new_parsed</a>                (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *format,
 215                                                          ...);
 216 </pre>
 217 </div>
 218 <div class="refsect1" title="Description">
 219 <a name="glib-GVariant.description"></a><h2>Description</h2>
 220 <p>
 221 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is a variant datatype; it stores a value along with
 222 information about the type of that value.  The range of possible
 223 values is determined by the type.  The type system used by <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
 224 is <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="type">GVariantType</span></a>.
 225 </p>
 226 <p>
 227 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instances always have a type and a value (which are given
 228 at construction time).  The type and value of a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
 229 can never change other than by the <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> itself being
 230 destroyed.  A <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> can not contain a pointer.
 231 </p>
 232 <p>
 233 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is reference counted using <a class="link" href="glib-GVariant.html#g-variant-ref" title="g_variant_ref ()"><code class="function">g_variant_ref()</code></a> and
 234 <a class="link" href="glib-GVariant.html#g-variant-unref" title="g_variant_unref ()"><code class="function">g_variant_unref()</code></a>.  <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> also has floating reference counts --
 235 see <a class="link" href="glib-GVariant.html#g-variant-ref-sink" title="g_variant_ref_sink ()"><code class="function">g_variant_ref_sink()</code></a>.
 236 </p>
 237 <p>
 238 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is completely threadsafe.  A <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance can be
 239 concurrently accessed in any way from any number of threads without
 240 problems.
 241 </p>
 242 <p>
 243 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is heavily optimised for dealing with data in serialised
 244 form.  It works particularly well with data located in memory-mapped
 245 files.  It can perform nearly all deserialisation operations in a
 246 small constant time, usually touching only a single memory page.
 247 Serialised <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> data can also be sent over the network.
 248 </p>
 249 <p>
 250 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is largely compatible with DBus.  Almost all types of
 251 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instances can be sent over DBus.  See <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="type">GVariantType</span></a> for
 252 exceptions.
 253 </p>
 254 <p>
 255 For convenience to C programmers, <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> features powerful
 256 varargs-based value construction and destruction.  This feature is
 257 designed to be embedded in other libraries.
 258 </p>
 259 <p>
 260 There is a Python-inspired text language for describing <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
 261 values.  <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> includes a printer for this language and a parser
 262 with type inferencing.
 263 </p>
 264 <p>
 265 </p>
 266 <div class="refsect2" title="Memory Use">
 267 <a name="id816906"></a><h3>Memory Use</h3>
 268 <p>
 269   <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> tries to be quite efficient with respect to memory use.
 270   This section gives a rough idea of how much memory is used by the
 271   current implementation.  The information here is subject to change
 272   in the future.
 273  </p>
 274 <p>
 275   The memory allocated by <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> can be grouped into 4 broad
 276   purposes: memory for serialised data, memory for the type
 277   information cache, buffer management memory and memory for the
 278   <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> structure itself.
 279  </p>
 280 <div class="refsect3" title="Serialised Data Memory">
 281 <a name="id816944"></a><h4>Serialised Data Memory</h4>
 282 <p>
 283    This is the memory that is used for storing GVariant data in
 284    serialised form.  This is what would be sent over the network or
 285    what would end up on disk.
 286   </p>
 287 <p>
 288    The amount of memory required to store a boolean is 1 byte.  16,
 289    32 and 64 bit integers and double precision floating point numbers
 290    use their "natural" size.  Strings (including object path and
 291    signature strings) are stored with a nul terminator, and as such
 292    use the length of the string plus 1 byte.
 293   </p>
 294 <p>
 295    Maybe types use no space at all to represent the null value and
 296    use the same amount of space (sometimes plus one byte) as the
 297    equivalent non-maybe-typed value to represent the non-null case.
 298   </p>
 299 <p>
 300    Arrays use the amount of space required to store each of their
 301    members, concatenated.  Additionally, if the items stored in an
 302    array are not of a fixed-size (ie: strings, other arrays, etc)
 303    then an additional framing offset is stored for each item.  The
 304    size of this offset is either 1, 2 or 4 bytes depending on the
 305    overall size of the container.  Additionally, extra padding bytes
 306    are added as required for alignment of child values.
 307   </p>
 308 <p>
 309    Tuples (including dictionary entries) use the amount of space
 310    required to store each of their members, concatenated, plus one
 311    framing offset (as per arrays) for each non-fixed-sized item in
 312    the tuple, except for the last one.  Additionally, extra padding
 313    bytes are added as required for alignment of child values.
 314   </p>
 315 <p>
 316    Variants use the same amount of space as the item inside of the
 317    variant, plus 1 byte, plus the length of the type string for the
 318    item inside the variant.
 319   </p>
 320 <p>
 321    As an example, consider a dictionary mapping strings to variants.
 322    In the case that the dictionary is empty, 0 bytes are required for
 323    the serialisation.
 324   </p>
 325 <p>
 326    If we add an item "width" that maps to the int32 value of 500 then
 327    we will use 4 byte to store the int32 (so 6 for the variant
 328    containing it) and 6 bytes for the string.  The variant must be
 329    aligned to 8 after the 6 bytes of the string, so that's 2 extra
 330    bytes.  6 (string) + 2 (padding) + 6 (variant) is 14 bytes used
 331    for the dictionary entry.  An additional 1 byte is added to the
 332    array as a framing offset making a total of 15 bytes.
 333   </p>
 334 <p>
 335    If we add another entry, "title" that maps to a nullable string
 336    that happens to have a value of null, then we use 0 bytes for the
 337    null value (and 3 bytes for the variant to contain it along with
 338    its type string) plus 6 bytes for the string.  Again, we need 2
 339    padding bytes.  That makes a total of 6 + 2 + 3 = 11 bytes.
 340   </p>
 341 <p>
 342    We now require extra padding between the two items in the array.
 343    After the 14 bytes of the first item, that's 2 bytes required.  We
 344    now require 2 framing offsets for an extra two bytes.  14 + 2 + 11
 345    + 2 = 29 bytes to encode the entire two-item dictionary.
 346   </p>
 347 </div>
 348 <div class="refsect3" title="Type Information Cache">
 349 <a name="id817012"></a><h4>Type Information Cache</h4>
 350 <p>
 351    For each GVariant type that currently exists in the program a type
 352    information structure is kept in the type information cache.  The
 353    type information structure is required for rapid deserialisation.
 354   </p>
 355 <p>
 356    Continuing with the above example, if a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> exists with the
 357    type "a{sv}" then a type information struct will exist for
 358    "a{sv}", "{sv}", "s", and "v".  Multiple uses of the same type
 359    will share the same type information.  Additionally, all
 360    single-digit types are stored in read-only static memory and do
 361    not contribute to the writable memory footprint of a program using
 362    <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>.
 363   </p>
 364 <p>
 365    Aside from the type information structures stored in read-only
 366    memory, there are two forms of type information.  One is used for
 367    container types where there is a single element type: arrays and
 368    maybe types.  The other is used for container types where there
 369    are multiple element types: tuples and dictionary entries.
 370   </p>
 371 <p>
 372    Array type info structures are 6 * sizeof (void *), plus the
 373    memory required to store the type string itself.  This means that
 374    on 32bit systems, the cache entry for "a{sv}" would require 30
 375    bytes of memory (plus malloc overhead).
 376   </p>
 377 <p>
 378    Tuple type info structures are 6 * sizeof (void *), plus 4 *
 379    sizeof (void *) for each item in the tuple, plus the memory
 380    required to store the type string itself.  A 2-item tuple, for
 381    example, would have a type information structure that consumed
 382    writable memory in the size of 14 * sizeof (void *) (plus type
 383    string)  This means that on 32bit systems, the cache entry for
 384    "{sv}" would require 61 bytes of memory (plus malloc overhead).
 385   </p>
 386 <p>
 387    This means that in total, for our "a{sv}" example, 91 bytes of
 388    type information would be allocated.
 389   </p>
 390 <p>
 391    The type information cache, additionally, uses a <a class="link" href="glib-Hash-Tables.html#GHashTable" title="GHashTable"><span class="type">GHashTable</span></a> to
 392    store and lookup the cached items and stores a pointer to this
 393    hash table in static storage.  The hash table is freed when there
 394    are zero items in the type cache.
 395   </p>
 396 <p>
 397    Although these sizes may seem large it is important to remember
 398    that a program will probably only have a very small number of
 399    different types of values in it and that only one type information
 400    structure is required for many different values of the same type.
 401   </p>
 402 </div>
 403 <div class="refsect3" title="Buffer Management Memory">
 404 <a name="id817087"></a><h4>Buffer Management Memory</h4>
 405 <p>
 406    <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> uses an internal buffer management structure to deal
 407    with the various different possible sources of serialised data
 408    that it uses.  The buffer is responsible for ensuring that the
 409    correct call is made when the data is no longer in use by
 410    <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>.  This may involve a <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a> or a <a class="link" href="glib-Memory-Slices.html#g-slice-free" title="g_slice_free()"><code class="function">g_slice_free()</code></a> or
 411    even <a class="link" href="glib-File-Utilities.html#g-mapped-file-unref" title="g_mapped_file_unref ()"><code class="function">g_mapped_file_unref()</code></a>.
 412   </p>
 413 <p>
 414    One buffer management structure is used for each chunk of
 415    serialised data.  The size of the buffer management structure is 4
 416    * (void *).  On 32bit systems, that's 16 bytes.
 417   </p>
 418 </div>
 419 <div class="refsect3" title="GVariant structure">
 420 <a name="id817149"></a><h4>GVariant structure</h4>
 421 <p>
 422    The size of a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> structure is 6 * (void *).  On 32 bit
 423    systems, that's 24 bytes.
 424   </p>
 425 <p>
 426    <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> structures only exist if they are explicitly created
 427    with API calls.  For example, if a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is constructed out of
 428    serialised data for the example given above (with the dictionary)
 429    then although there are 9 individual values that comprise the
 430    entire dictionary (two keys, two values, two variants containing
 431    the values, two dictionary entries, plus the dictionary itself),
 432    only 1 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance exists -- the one refering to the
 433    dictionary.
 434   </p>
 435 <p>
 436    If calls are made to start accessing the other values then
 437    <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instances will exist for those values only for as long
 438    as they are in use (ie: until you call <a class="link" href="glib-GVariant.html#g-variant-unref" title="g_variant_unref ()"><code class="function">g_variant_unref()</code></a>).  The
 439    type information is shared.  The serialised data and the buffer
 440    management structure for that serialised data is shared by the
 441    child.
 442   </p>
 443 </div>
 444 <div class="refsect3" title="Summary">
 445 <a name="id817219"></a><h4>Summary</h4>
 446 <p>
 447    To put the entire example together, for our dictionary mapping
 448    strings to variants (with two entries, as given above), we are
 449    using 91 bytes of memory for type information, 29 byes of memory
 450    for the serialised data, 16 bytes for buffer management and 24
 451    bytes for the <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance, or a total of 160 bytes, plus
 452    malloc overhead.  If we were to use <a class="link" href="glib-GVariant.html#g-variant-get-child-value" title="g_variant_get_child_value ()"><code class="function">g_variant_get_child_value()</code></a> to
 453    access the two dictionary entries, we would use an additional 48
 454    bytes.  If we were to have other dictionaries of the same type, we
 455    would use more memory for the serialised data and buffer
 456    management for those dictionaries, but the type information would
 457    be shared.
 458   </p>
 459 </div>
 460 </div>
 461 </div>
 462 <div class="refsect1" title="Details">
 463 <a name="glib-GVariant.details"></a><h2>Details</h2>
 464 <div class="refsect2" title="GVariant">
 465 <a name="GVariant"></a><h3>GVariant</h3>
 466 <pre class="programlisting">typedef struct _GVariant GVariant;</pre>
 467 <p>
 468 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is an opaque data structure and can only be accessed
 469 using the following functions.</p>
 470 <p class="since">Since 2.24</p>
 471 </div>
 472 <hr>
 473 <div class="refsect2" title="g_variant_unref ()">
 474 <a name="g-variant-unref"></a><h3>g_variant_unref ()</h3>
 475 <pre class="programlisting"><span class="returnvalue">void</span>                g_variant_unref                     (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
 476 <p>
 477 Decreases the reference count of <em class="parameter"><code>value</code></em>.  When its reference count
 478 drops to 0, the memory used by the variant is freed.</p>
 479 <div class="variablelist"><table border="0">
 480 <col align="left" valign="top">
 481 <tbody><tr>
 482 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
 483 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
 484 </td>
 485 </tr></tbody>
 486 </table></div>
 487 <p class="since">Since 2.24</p>
 488 </div>
 489 <hr>
 490 <div class="refsect2" title="g_variant_ref ()">
 491 <a name="g-variant-ref"></a><h3>g_variant_ref ()</h3>
 492 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_ref                       (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
 493 <p>
 494 Increases the reference count of <em class="parameter"><code>value</code></em>.</p>
 495 <div class="variablelist"><table border="0">
 496 <col align="left" valign="top">
 497 <tbody>
 498 <tr>
 499 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
 500 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
 501 </td>
 502 </tr>
 503 <tr>
 504 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 505 <td> the same <em class="parameter"><code>value</code></em>
 506 </td>
 507 </tr>
 508 </tbody>
 509 </table></div>
 510 <p class="since">Since 2.24</p>
 511 </div>
 512 <hr>
 513 <div class="refsect2" title="g_variant_ref_sink ()">
 514 <a name="g-variant-ref-sink"></a><h3>g_variant_ref_sink ()</h3>
 515 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_ref_sink                  (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
 516 <p>
 517 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> uses a floating reference count system.  All functions with
 518 names starting with <code class="literal">g_variant_new_</code> return floating
 519 references.
 520 </p>
 521 <p>
 522 Calling <a class="link" href="glib-GVariant.html#g-variant-ref-sink" title="g_variant_ref_sink ()"><code class="function">g_variant_ref_sink()</code></a> on a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> with a floating reference
 523 will convert the floating reference into a full reference.  Calling
 524 <a class="link" href="glib-GVariant.html#g-variant-ref-sink" title="g_variant_ref_sink ()"><code class="function">g_variant_ref_sink()</code></a> on a non-floating <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> results in an
 525 additional normal reference being added.
 526 </p>
 527 <p>
 528 In other words, if the <em class="parameter"><code>value</code></em> is floating, then this call "assumes
 529 ownership" of the floating reference, converting it to a normal
 530 reference.  If the <em class="parameter"><code>value</code></em> is not floating, then this call adds a
 531 new normal reference increasing the reference count by one.
 532 </p>
 533 <p>
 534 All calls that result in a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance being inserted into a
 535 container will call <a class="link" href="glib-GVariant.html#g-variant-ref-sink" title="g_variant_ref_sink ()"><code class="function">g_variant_ref_sink()</code></a> on the instance.  This means
 536 that if the value was just created (and has only its floating
 537 reference) then the container will assume sole ownership of the value
 538 at that point and the caller will not need to unreference it.  This
 539 makes certain common styles of programming much easier while still
 540 maintaining normal refcounting semantics in situations where values
 541 are not floating.</p>
 542 <div class="variablelist"><table border="0">
 543 <col align="left" valign="top">
 544 <tbody>
 545 <tr>
 546 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
 547 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
 548 </td>
 549 </tr>
 550 <tr>
 551 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 552 <td> the same <em class="parameter"><code>value</code></em>
 553 </td>
 554 </tr>
 555 </tbody>
 556 </table></div>
 557 <p class="since">Since 2.24</p>
 558 </div>
 559 <hr>
 560 <div class="refsect2" title="g_variant_get_type ()">
 561 <a name="g-variant-get-type"></a><h3>g_variant_get_type ()</h3>
 562 <pre class="programlisting">const <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="returnvalue">GVariantType</span></a> * g_variant_get_type                 (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
 563 <p>
 564 Determines the type of <em class="parameter"><code>value</code></em>.
 565 </p>
 566 <p>
 567 The return value is valid for the lifetime of <em class="parameter"><code>value</code></em> and must not
 568 be freed.</p>
 569 <div class="variablelist"><table border="0">
 570 <col align="left" valign="top">
 571 <tbody>
 572 <tr>
 573 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
 574 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
 575 </td>
 576 </tr>
 577 <tr>
 578 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 579 <td> a <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="type">GVariantType</span></a>
 580 </td>
 581 </tr>
 582 </tbody>
 583 </table></div>
 584 <p class="since">Since 2.24</p>
 585 </div>
 586 <hr>
 587 <div class="refsect2" title="g_variant_get_type_string ()">
 588 <a name="g-variant-get-type-string"></a><h3>g_variant_get_type_string ()</h3>
 589 <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       g_variant_get_type_string           (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
 590 <p>
 591 Returns the type string of <em class="parameter"><code>value</code></em>.  Unlike the result of calling
 592 <a class="link" href="glib-GVariantType.html#g-variant-type-peek-string" title="g_variant_type_peek_string ()"><code class="function">g_variant_type_peek_string()</code></a>, this string is nul-terminated.  This
 593 string belongs to <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> and must not be freed.</p>
 594 <div class="variablelist"><table border="0">
 595 <col align="left" valign="top">
 596 <tbody>
 597 <tr>
 598 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
 599 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
 600 </td>
 601 </tr>
 602 <tr>
 603 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 604 <td> the type string for the type of <em class="parameter"><code>value</code></em>
 605 </td>
 606 </tr>
 607 </tbody>
 608 </table></div>
 609 <p class="since">Since 2.24</p>
 610 </div>
 611 <hr>
 612 <div class="refsect2" title="g_variant_is_of_type ()">
 613 <a name="g-variant-is-of-type"></a><h3>g_variant_is_of_type ()</h3>
 614 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_variant_is_of_type                (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
 615                                                          const <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="returnvalue">GVariantType</span></a> *type);</pre>
 616 <p>
 617 Checks if a value has a type matching the provided type.</p>
 618 <div class="variablelist"><table border="0">
 619 <col align="left" valign="top">
 620 <tbody>
 621 <tr>
 622 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
 623 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
 624 </td>
 625 </tr>
 626 <tr>
 627 <td><p><span class="term"><em class="parameter"><code>type</code></em> :</span></p></td>
 628 <td> a <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="type">GVariantType</span></a>
 629 </td>
 630 </tr>
 631 <tr>
 632 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 633 <td> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the type of <em class="parameter"><code>value</code></em> matches <em class="parameter"><code>type</code></em>
 634 </td>
 635 </tr>
 636 </tbody>
 637 </table></div>
 638 <p class="since">Since 2.24</p>
 639 </div>
 640 <hr>
 641 <div class="refsect2" title="g_variant_is_container ()">
 642 <a name="g-variant-is-container"></a><h3>g_variant_is_container ()</h3>
 643 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_variant_is_container              (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
 644 <p>
 645 Checks if <em class="parameter"><code>value</code></em> is a container.</p>
 646 <div class="variablelist"><table border="0">
 647 <col align="left" valign="top">
 648 <tbody>
 649 <tr>
 650 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
 651 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
 652 </td>
 653 </tr>
 654 <tr>
 655 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 656 <td> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>value</code></em> is a container
 657 </td>
 658 </tr>
 659 </tbody>
 660 </table></div>
 661 </div>
 662 <hr>
 663 <div class="refsect2" title="g_variant_classify ()">
 664 <a name="g-variant-classify"></a><h3>g_variant_classify ()</h3>
 665 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariantClass" title="enum GVariantClass"><span class="returnvalue">GVariantClass</span></a>       g_variant_classify                  (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
 666 <p>
 667 Classifies <em class="parameter"><code>value</code></em> according to its top-level type.</p>
 668 <div class="variablelist"><table border="0">
 669 <col align="left" valign="top">
 670 <tbody>
 671 <tr>
 672 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
 673 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
 674 </td>
 675 </tr>
 676 <tr>
 677 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 678 <td> the <a class="link" href="glib-GVariant.html#GVariantClass" title="enum GVariantClass"><span class="type">GVariantClass</span></a> of <em class="parameter"><code>value</code></em>
 679 </td>
 680 </tr>
 681 </tbody>
 682 </table></div>
 683 <p class="since">Since 2.24</p>
 684 </div>
 685 <hr>
 686 <div class="refsect2" title="enum GVariantClass">
 687 <a name="GVariantClass"></a><h3>enum GVariantClass</h3>
 688 <pre class="programlisting">typedef enum
 689 {
 690   G_VARIANT_CLASS_BOOLEAN       = 'b',
 691   G_VARIANT_CLASS_BYTE          = 'y',
 692   G_VARIANT_CLASS_INT16         = 'n',
 693   G_VARIANT_CLASS_UINT16        = 'q',
 694   G_VARIANT_CLASS_INT32         = 'i',
 695   G_VARIANT_CLASS_UINT32        = 'u',
 696   G_VARIANT_CLASS_INT64         = 'x',
 697   G_VARIANT_CLASS_UINT64        = 't',
 698   G_VARIANT_CLASS_HANDLE        = 'h',
 699   G_VARIANT_CLASS_DOUBLE        = 'd',
 700   G_VARIANT_CLASS_STRING        = 's',
 701   G_VARIANT_CLASS_OBJECT_PATH   = 'o',
 702   G_VARIANT_CLASS_SIGNATURE     = 'g',
 703   G_VARIANT_CLASS_VARIANT       = 'v',
 704   G_VARIANT_CLASS_MAYBE         = 'm',
 705   G_VARIANT_CLASS_ARRAY         = 'a',
 706   G_VARIANT_CLASS_TUPLE         = '(',
 707   G_VARIANT_CLASS_DICT_ENTRY    = '{'
 708 } GVariantClass;
 709 </pre>
 710 <p>
 711 The range of possible top-level types of <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instances.</p>
 712 <div class="variablelist"><table border="0">
 713 <col align="left" valign="top">
 714 <tbody>
 715 <tr>
 716 <td><p><a name="G-VARIANT-CLASS-BOOLEAN:CAPS"></a><span class="term"><code class="literal">G_VARIANT_CLASS_BOOLEAN</code></span></p></td>
 717 <td> The <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is a boolean.
 718 </td>
 719 </tr>
 720 <tr>
 721 <td><p><a name="G-VARIANT-CLASS-BYTE:CAPS"></a><span class="term"><code class="literal">G_VARIANT_CLASS_BYTE</code></span></p></td>
 722 <td> The <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is a byte.
 723 </td>
 724 </tr>
 725 <tr>
 726 <td><p><a name="G-VARIANT-CLASS-INT16:CAPS"></a><span class="term"><code class="literal">G_VARIANT_CLASS_INT16</code></span></p></td>
 727 <td> The <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is a signed 16 bit integer.
 728 </td>
 729 </tr>
 730 <tr>
 731 <td><p><a name="G-VARIANT-CLASS-UINT16:CAPS"></a><span class="term"><code class="literal">G_VARIANT_CLASS_UINT16</code></span></p></td>
 732 <td> The <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is an unsigned 16 bit integer.
 733 </td>
 734 </tr>
 735 <tr>
 736 <td><p><a name="G-VARIANT-CLASS-INT32:CAPS"></a><span class="term"><code class="literal">G_VARIANT_CLASS_INT32</code></span></p></td>
 737 <td> The <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is a signed 32 bit integer.
 738 </td>
 739 </tr>
 740 <tr>
 741 <td><p><a name="G-VARIANT-CLASS-UINT32:CAPS"></a><span class="term"><code class="literal">G_VARIANT_CLASS_UINT32</code></span></p></td>
 742 <td> The <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is an unsigned 32 bit integer.
 743 </td>
 744 </tr>
 745 <tr>
 746 <td><p><a name="G-VARIANT-CLASS-INT64:CAPS"></a><span class="term"><code class="literal">G_VARIANT_CLASS_INT64</code></span></p></td>
 747 <td> The <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is a signed 64 bit integer.
 748 </td>
 749 </tr>
 750 <tr>
 751 <td><p><a name="G-VARIANT-CLASS-UINT64:CAPS"></a><span class="term"><code class="literal">G_VARIANT_CLASS_UINT64</code></span></p></td>
 752 <td> The <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is an unsigned 64 bit integer.
 753 </td>
 754 </tr>
 755 <tr>
 756 <td><p><a name="G-VARIANT-CLASS-HANDLE:CAPS"></a><span class="term"><code class="literal">G_VARIANT_CLASS_HANDLE</code></span></p></td>
 757 <td> The <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is a file handle index.
 758 </td>
 759 </tr>
 760 <tr>
 761 <td><p><a name="G-VARIANT-CLASS-DOUBLE:CAPS"></a><span class="term"><code class="literal">G_VARIANT_CLASS_DOUBLE</code></span></p></td>
 762 <td> The <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is a double precision floating
 763                          point value.
 764 </td>
 765 </tr>
 766 <tr>
 767 <td><p><a name="G-VARIANT-CLASS-STRING:CAPS"></a><span class="term"><code class="literal">G_VARIANT_CLASS_STRING</code></span></p></td>
 768 <td> The <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is a normal string.
 769 </td>
 770 </tr>
 771 <tr>
 772 <td><p><a name="G-VARIANT-CLASS-OBJECT-PATH:CAPS"></a><span class="term"><code class="literal">G_VARIANT_CLASS_OBJECT_PATH</code></span></p></td>
 773 <td> The <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is a DBus object path
 774                               string.
 775 </td>
 776 </tr>
 777 <tr>
 778 <td><p><a name="G-VARIANT-CLASS-SIGNATURE:CAPS"></a><span class="term"><code class="literal">G_VARIANT_CLASS_SIGNATURE</code></span></p></td>
 779 <td> The <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is a DBus signature string.
 780 </td>
 781 </tr>
 782 <tr>
 783 <td><p><a name="G-VARIANT-CLASS-VARIANT:CAPS"></a><span class="term"><code class="literal">G_VARIANT_CLASS_VARIANT</code></span></p></td>
 784 <td> The <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is a variant.
 785 </td>
 786 </tr>
 787 <tr>
 788 <td><p><a name="G-VARIANT-CLASS-MAYBE:CAPS"></a><span class="term"><code class="literal">G_VARIANT_CLASS_MAYBE</code></span></p></td>
 789 <td> The <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is a maybe-typed value.
 790 </td>
 791 </tr>
 792 <tr>
 793 <td><p><a name="G-VARIANT-CLASS-ARRAY:CAPS"></a><span class="term"><code class="literal">G_VARIANT_CLASS_ARRAY</code></span></p></td>
 794 <td> The <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is an array.
 795 </td>
 796 </tr>
 797 <tr>
 798 <td><p><a name="G-VARIANT-CLASS-TUPLE:CAPS"></a><span class="term"><code class="literal">G_VARIANT_CLASS_TUPLE</code></span></p></td>
 799 <td> The <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is a tuple.
 800 </td>
 801 </tr>
 802 <tr>
 803 <td><p><a name="G-VARIANT-CLASS-DICT-ENTRY:CAPS"></a><span class="term"><code class="literal">G_VARIANT_CLASS_DICT_ENTRY</code></span></p></td>
 804 <td> The <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is a dictionary entry.
 805 </td>
 806 </tr>
 807 </tbody>
 808 </table></div>
 809 <p class="since">Since 2.24</p>
 810 </div>
 811 <hr>
 812 <div class="refsect2" title="g_variant_get ()">
 813 <a name="g-variant-get"></a><h3>g_variant_get ()</h3>
 814 <pre class="programlisting"><span class="returnvalue">void</span>                g_variant_get                       (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
 815                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *format_string,
 816                                                          ...);</pre>
 817 <p>
 818 Deconstructs a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance.
 819 </p>
 820 <p>
 821 Think of this function as an analogue to <code class="function">scanf()</code>.
 822 </p>
 823 <p>
 824 The arguments that are expected by this function are entirely
 825 determined by <em class="parameter"><code>format_string</code></em>.  <em class="parameter"><code>format_string</code></em> also restricts the
 826 permissible types of <em class="parameter"><code>value</code></em>.  It is an error to give a value with
 827 an incompatible type.  See the section on <a href="gvariant-format-strings.html">GVariant Format Strings</a>.
 828 Please note that the syntax of the format string is very likely to be
 829 extended in the future.</p>
 830 <div class="variablelist"><table border="0">
 831 <col align="left" valign="top">
 832 <tbody>
 833 <tr>
 834 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
 835 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
 836 </td>
 837 </tr>
 838 <tr>
 839 <td><p><span class="term"><em class="parameter"><code>format_string</code></em> :</span></p></td>
 840 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> format string
 841 </td>
 842 </tr>
 843 <tr>
 844 <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
 845 <td> arguments, as per <em class="parameter"><code>format_string</code></em>
 846 </td>
 847 </tr>
 848 </tbody>
 849 </table></div>
 850 <p class="since">Since 2.24</p>
 851 </div>
 852 <hr>
 853 <div class="refsect2" title="g_variant_get_va ()">
 854 <a name="g-variant-get-va"></a><h3>g_variant_get_va ()</h3>
 855 <pre class="programlisting"><span class="returnvalue">void</span>                g_variant_get_va                    (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
 856                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *format_string,
 857                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **endptr,
 858                                                          <span class="returnvalue">va_list</span> *app);</pre>
 859 <p>
 860 This function is intended to be used by libraries based on <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
 861 that want to provide <a class="link" href="glib-GVariant.html#g-variant-get" title="g_variant_get ()"><code class="function">g_variant_get()</code></a>-like functionality to their
 862 users.
 863 </p>
 864 <p>
 865 The API is more general than <a class="link" href="glib-GVariant.html#g-variant-get" title="g_variant_get ()"><code class="function">g_variant_get()</code></a> to allow a wider range
 866 of possible uses.
 867 </p>
 868 <p>
 869 <em class="parameter"><code>format_string</code></em> must still point to a valid format string, but it only
 870 need to be nul-terminated if <em class="parameter"><code>endptr</code></em> is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.  If <em class="parameter"><code>endptr</code></em> is
 871 non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> then it is updated to point to the first character past the
 872 end of the format string.
 873 </p>
 874 <p>
 875 <em class="parameter"><code>app</code></em> is a pointer to a <span class="type">va_list</span>.  The arguments, according to
 876 <em class="parameter"><code>format_string</code></em>, are collected from this <span class="type">va_list</span> and the list is left
 877 pointing to the argument following the last.
 878 </p>
 879 <p>
 880 These two generalisations allow mixing of multiple calls to
 881 <a class="link" href="glib-GVariant.html#g-variant-new-va" title="g_variant_new_va ()"><code class="function">g_variant_new_va()</code></a> and <a class="link" href="glib-GVariant.html#g-variant-get-va" title="g_variant_get_va ()"><code class="function">g_variant_get_va()</code></a> within a single actual
 882 varargs call by the user.</p>
 883 <div class="variablelist"><table border="0">
 884 <col align="left" valign="top">
 885 <tbody>
 886 <tr>
 887 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
 888 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
 889 </td>
 890 </tr>
 891 <tr>
 892 <td><p><span class="term"><em class="parameter"><code>format_string</code></em> :</span></p></td>
 893 <td> a string that is prefixed with a format string
 894 </td>
 895 </tr>
 896 <tr>
 897 <td><p><span class="term"><em class="parameter"><code>endptr</code></em> :</span></p></td>
 898 <td> location to store the end pointer, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
 899 </td>
 900 </tr>
 901 <tr>
 902 <td><p><span class="term"><em class="parameter"><code>app</code></em> :</span></p></td>
 903 <td> a pointer to a <span class="type">va_list</span>
 904 </td>
 905 </tr>
 906 </tbody>
 907 </table></div>
 908 <p class="since">Since 2.24</p>
 909 </div>
 910 <hr>
 911 <div class="refsect2" title="g_variant_new ()">
 912 <a name="g-variant-new"></a><h3>g_variant_new ()</h3>
 913 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new                       (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *format_string,
 914                                                          ...);</pre>
 915 <p>
 916 Creates a new <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance.
 917 </p>
 918 <p>
 919 Think of this function as an analogue to <a class="link" href="glib-String-Utility-Functions.html#g-strdup-printf" title="g_strdup_printf ()"><code class="function">g_strdup_printf()</code></a>.
 920 </p>
 921 <p>
 922 The type of the created instance and the arguments that are
 923 expected by this function are determined by <em class="parameter"><code>format_string</code></em>.  See the
 924 section on <GTKDOCLINK HREF="gvariant-format-strings">GVariant Format
 925 Strings</GTKDOCLINK>.  Please note that the syntax of the format string is
 926 very likely to be extended in the future.
 927 </p>
 928 <p>
 929 The first character of the format string must not be '*' '?' '@' or
 930 'r'; in essence, a new <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> must always be constructed by this
 931 function (and not merely passed through it unmodified).</p>
 932 <div class="variablelist"><table border="0">
 933 <col align="left" valign="top">
 934 <tbody>
 935 <tr>
 936 <td><p><span class="term"><em class="parameter"><code>format_string</code></em> :</span></p></td>
 937 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> format string
 938 </td>
 939 </tr>
 940 <tr>
 941 <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
 942 <td> arguments, as per <em class="parameter"><code>format_string</code></em>
 943 </td>
 944 </tr>
 945 <tr>
 946 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 947 <td> a new floating <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
 948 </td>
 949 </tr>
 950 </tbody>
 951 </table></div>
 952 <p class="since">Since 2.24</p>
 953 </div>
 954 <hr>
 955 <div class="refsect2" title="g_variant_new_va ()">
 956 <a name="g-variant-new-va"></a><h3>g_variant_new_va ()</h3>
 957 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new_va                    (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *format_string,
 958                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **endptr,
 959                                                          <span class="returnvalue">va_list</span> *app);</pre>
 960 <p>
 961 This function is intended to be used by libraries based on
 962 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> that want to provide <a class="link" href="glib-GVariant.html#g-variant-new" title="g_variant_new ()"><code class="function">g_variant_new()</code></a>-like functionality
 963 to their users.
 964 </p>
 965 <p>
 966 The API is more general than <a class="link" href="glib-GVariant.html#g-variant-new" title="g_variant_new ()"><code class="function">g_variant_new()</code></a> to allow a wider range
 967 of possible uses.
 968 </p>
 969 <p>
 970 <em class="parameter"><code>format_string</code></em> must still point to a valid format string, but it only
 971 needs to be nul-terminated if <em class="parameter"><code>endptr</code></em> is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.  If <em class="parameter"><code>endptr</code></em> is
 972 non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> then it is updated to point to the first character past the
 973 end of the format string.
 974 </p>
 975 <p>
 976 <em class="parameter"><code>app</code></em> is a pointer to a <span class="type">va_list</span>.  The arguments, according to
 977 <em class="parameter"><code>format_string</code></em>, are collected from this <span class="type">va_list</span> and the list is left
 978 pointing to the argument following the last.
 979 </p>
 980 <p>
 981 These two generalisations allow mixing of multiple calls to
 982 <a class="link" href="glib-GVariant.html#g-variant-new-va" title="g_variant_new_va ()"><code class="function">g_variant_new_va()</code></a> and <a class="link" href="glib-GVariant.html#g-variant-get-va" title="g_variant_get_va ()"><code class="function">g_variant_get_va()</code></a> within a single actual
 983 varargs call by the user.
 984 </p>
 985 <p>
 986 The return value will be floating if it was a newly created GVariant
 987 instance (for example, if the format string was "(ii)").  In the case
 988 that the format_string was '*', '?', 'r', or a format starting with
 989 '@' then the collected <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> pointer will be returned unmodified,
 990 without adding any additional references.
 991 </p>
 992 <p>
 993 In order to behave correctly in all cases it is necessary for the
 994 calling function to <a class="link" href="glib-GVariant.html#g-variant-ref-sink" title="g_variant_ref_sink ()"><code class="function">g_variant_ref_sink()</code></a> the return result before
 995 returning control to the user that originally provided the pointer.
 996 At this point, the caller will have their own full reference to the
 997 result.  This can also be done by adding the result to a container,
 998 or by passing it to another <a class="link" href="glib-GVariant.html#g-variant-new" title="g_variant_new ()"><code class="function">g_variant_new()</code></a> call.</p>
 999 <div class="variablelist"><table border="0">
1000 <col align="left" valign="top">
1001 <tbody>
1002 <tr>
1003 <td><p><span class="term"><em class="parameter"><code>format_string</code></em> :</span></p></td>
1004 <td> a string that is prefixed with a format string
1005 </td>
1006 </tr>
1007 <tr>
1008 <td><p><span class="term"><em class="parameter"><code>endptr</code></em> :</span></p></td>
1009 <td> location to store the end pointer, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
1010 </td>
1011 </tr>
1012 <tr>
1013 <td><p><span class="term"><em class="parameter"><code>app</code></em> :</span></p></td>
1014 <td> a pointer to a <span class="type">va_list</span>
1015 </td>
1016 </tr>
1017 <tr>
1018 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1019 <td> a new, usually floating, <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
1020 </td>
1021 </tr>
1022 </tbody>
1023 </table></div>
1024 <p class="since">Since 2.24</p>
1025 </div>
1026 <hr>
1027 <div class="refsect2" title="g_variant_new_boolean ()">
1028 <a name="g-variant-new-boolean"></a><h3>g_variant_new_boolean ()</h3>
1029 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new_boolean               (<a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> boolean);</pre>
1030 <p>
1031 Creates a new boolean <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance -- either <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> or <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a>.</p>
1032 <div class="variablelist"><table border="0">
1033 <col align="left" valign="top">
1034 <tbody>
1035 <tr>
1036 <td><p><span class="term"><em class="parameter"><code>boolean</code></em> :</span></p></td>
1037 <td> a <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> value
1038 </td>
1039 </tr>
1040 <tr>
1041 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1042 <td> a new boolean <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1043 </td>
1044 </tr>
1045 </tbody>
1046 </table></div>
1047 <p class="since">Since 2.24</p>
1048 </div>
1049 <hr>
1050 <div class="refsect2" title="g_variant_new_byte ()">
1051 <a name="g-variant-new-byte"></a><h3>g_variant_new_byte ()</h3>
1052 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new_byte                  (<a class="link" href="glib-Basic-Types.html#guchar" title="guchar"><span class="returnvalue">guchar</span></a> byte);</pre>
1053 <p>
1054 Creates a new byte <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance.</p>
1055 <div class="variablelist"><table border="0">
1056 <col align="left" valign="top">
1057 <tbody>
1058 <tr>
1059 <td><p><span class="term"><em class="parameter"><code>byte</code></em> :</span></p></td>
1060 <td> a <a class="link" href="glib-Basic-Types.html#guint8" title="guint8"><span class="type">guint8</span></a> value
1061 </td>
1062 </tr>
1063 <tr>
1064 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1065 <td> a new byte <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1066 </td>
1067 </tr>
1068 </tbody>
1069 </table></div>
1070 <p class="since">Since 2.24</p>
1071 </div>
1072 <hr>
1073 <div class="refsect2" title="g_variant_new_int16 ()">
1074 <a name="g-variant-new-int16"></a><h3>g_variant_new_int16 ()</h3>
1075 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new_int16                 (<a class="link" href="glib-Basic-Types.html#gint16" title="gint16"><span class="returnvalue">gint16</span></a> int16);</pre>
1076 <p>
1077 Creates a new int16 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance.</p>
1078 <div class="variablelist"><table border="0">
1079 <col align="left" valign="top">
1080 <tbody>
1081 <tr>
1082 <td><p><span class="term"><em class="parameter"><code>int16</code></em> :</span></p></td>
1083 <td> a <a class="link" href="glib-Basic-Types.html#gint16" title="gint16"><span class="type">gint16</span></a> value
1084 </td>
1085 </tr>
1086 <tr>
1087 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1088 <td> a new int16 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1089 </td>
1090 </tr>
1091 </tbody>
1092 </table></div>
1093 <p class="since">Since 2.24</p>
1094 </div>
1095 <hr>
1096 <div class="refsect2" title="g_variant_new_uint16 ()">
1097 <a name="g-variant-new-uint16"></a><h3>g_variant_new_uint16 ()</h3>
1098 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new_uint16                (<a class="link" href="glib-Basic-Types.html#guint16" title="guint16"><span class="returnvalue">guint16</span></a> uint16);</pre>
1099 <p>
1100 Creates a new uint16 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance.</p>
1101 <div class="variablelist"><table border="0">
1102 <col align="left" valign="top">
1103 <tbody>
1104 <tr>
1105 <td><p><span class="term"><em class="parameter"><code>uint16</code></em> :</span></p></td>
1106 <td> a <a class="link" href="glib-Basic-Types.html#guint16" title="guint16"><span class="type">guint16</span></a> value
1107 </td>
1108 </tr>
1109 <tr>
1110 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1111 <td> a new uint16 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1112 </td>
1113 </tr>
1114 </tbody>
1115 </table></div>
1116 <p class="since">Since 2.24</p>
1117 </div>
1118 <hr>
1119 <div class="refsect2" title="g_variant_new_int32 ()">
1120 <a name="g-variant-new-int32"></a><h3>g_variant_new_int32 ()</h3>
1121 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new_int32                 (<a class="link" href="glib-Basic-Types.html#gint32" title="gint32"><span class="returnvalue">gint32</span></a> int32);</pre>
1122 <p>
1123 Creates a new int32 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance.</p>
1124 <div class="variablelist"><table border="0">
1125 <col align="left" valign="top">
1126 <tbody>
1127 <tr>
1128 <td><p><span class="term"><em class="parameter"><code>int32</code></em> :</span></p></td>
1129 <td> a <a class="link" href="glib-Basic-Types.html#gint32" title="gint32"><span class="type">gint32</span></a> value
1130 </td>
1131 </tr>
1132 <tr>
1133 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1134 <td> a new int32 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1135 </td>
1136 </tr>
1137 </tbody>
1138 </table></div>
1139 <p class="since">Since 2.24</p>
1140 </div>
1141 <hr>
1142 <div class="refsect2" title="g_variant_new_uint32 ()">
1143 <a name="g-variant-new-uint32"></a><h3>g_variant_new_uint32 ()</h3>
1144 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new_uint32                (<a class="link" href="glib-Basic-Types.html#guint32" title="guint32"><span class="returnvalue">guint32</span></a> uint32);</pre>
1145 <p>
1146 Creates a new uint32 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance.</p>
1147 <div class="variablelist"><table border="0">
1148 <col align="left" valign="top">
1149 <tbody>
1150 <tr>
1151 <td><p><span class="term"><em class="parameter"><code>uint32</code></em> :</span></p></td>
1152 <td> a <a class="link" href="glib-Basic-Types.html#guint32" title="guint32"><span class="type">guint32</span></a> value
1153 </td>
1154 </tr>
1155 <tr>
1156 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1157 <td> a new uint32 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1158 </td>
1159 </tr>
1160 </tbody>
1161 </table></div>
1162 <p class="since">Since 2.24</p>
1163 </div>
1164 <hr>
1165 <div class="refsect2" title="g_variant_new_int64 ()">
1166 <a name="g-variant-new-int64"></a><h3>g_variant_new_int64 ()</h3>
1167 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new_int64                 (<a class="link" href="glib-Basic-Types.html#gint64" title="gint64"><span class="returnvalue">gint64</span></a> int64);</pre>
1168 <p>
1169 Creates a new int64 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance.</p>
1170 <div class="variablelist"><table border="0">
1171 <col align="left" valign="top">
1172 <tbody>
1173 <tr>
1174 <td><p><span class="term"><em class="parameter"><code>int64</code></em> :</span></p></td>
1175 <td> a <a class="link" href="glib-Basic-Types.html#gint64" title="gint64"><span class="type">gint64</span></a> value
1176 </td>
1177 </tr>
1178 <tr>
1179 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1180 <td> a new int64 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1181 </td>
1182 </tr>
1183 </tbody>
1184 </table></div>
1185 <p class="since">Since 2.24</p>
1186 </div>
1187 <hr>
1188 <div class="refsect2" title="g_variant_new_uint64 ()">
1189 <a name="g-variant-new-uint64"></a><h3>g_variant_new_uint64 ()</h3>
1190 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new_uint64                (<a class="link" href="glib-Basic-Types.html#guint64" title="guint64"><span class="returnvalue">guint64</span></a> uint64);</pre>
1191 <p>
1192 Creates a new uint64 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance.</p>
1193 <div class="variablelist"><table border="0">
1194 <col align="left" valign="top">
1195 <tbody>
1196 <tr>
1197 <td><p><span class="term"><em class="parameter"><code>uint64</code></em> :</span></p></td>
1198 <td> a <a class="link" href="glib-Basic-Types.html#guint64" title="guint64"><span class="type">guint64</span></a> value
1199 </td>
1200 </tr>
1201 <tr>
1202 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1203 <td> a new uint64 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1204 </td>
1205 </tr>
1206 </tbody>
1207 </table></div>
1208 <p class="since">Since 2.24</p>
1209 </div>
1210 <hr>
1211 <div class="refsect2" title="g_variant_new_handle ()">
1212 <a name="g-variant-new-handle"></a><h3>g_variant_new_handle ()</h3>
1213 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new_handle                (<a class="link" href="glib-Basic-Types.html#gint32" title="gint32"><span class="returnvalue">gint32</span></a> handle);</pre>
1214 <p>
1215 Creates a new handle <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance.
1216 </p>
1217 <p>
1218 By convention, handles are indexes into an array of file descriptors
1219 that are sent alongside a DBus message.  If you're not interacting
1220 with DBus, you probably don't need them.</p>
1221 <div class="variablelist"><table border="0">
1222 <col align="left" valign="top">
1223 <tbody>
1224 <tr>
1225 <td><p><span class="term"><em class="parameter"><code>handle</code></em> :</span></p></td>
1226 <td> a <a class="link" href="glib-Basic-Types.html#gint32" title="gint32"><span class="type">gint32</span></a> value
1227 </td>
1228 </tr>
1229 <tr>
1230 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1231 <td> a new handle <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1232 </td>
1233 </tr>
1234 </tbody>
1235 </table></div>
1236 <p class="since">Since 2.24</p>
1237 </div>
1238 <hr>
1239 <div class="refsect2" title="g_variant_new_double ()">
1240 <a name="g-variant-new-double"></a><h3>g_variant_new_double ()</h3>
1241 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new_double                (<a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="returnvalue">gdouble</span></a> floating);</pre>
1242 <p>
1243 Creates a new double <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance.</p>
1244 <div class="variablelist"><table border="0">
1245 <col align="left" valign="top">
1246 <tbody>
1247 <tr>
1248 <td><p><span class="term"><em class="parameter"><code>floating</code></em> :</span></p></td>
1249 <td> a <a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="type">gdouble</span></a> floating point value
1250 </td>
1251 </tr>
1252 <tr>
1253 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1254 <td> a new double <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1255 </td>
1256 </tr>
1257 </tbody>
1258 </table></div>
1259 <p class="since">Since 2.24</p>
1260 </div>
1261 <hr>
1262 <div class="refsect2" title="g_variant_new_string ()">
1263 <a name="g-variant-new-string"></a><h3>g_variant_new_string ()</h3>
1264 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new_string                (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *string);</pre>
1265 <p>
1266 Creates a string <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> with the contents of <em class="parameter"><code>string</code></em>.</p>
1267 <div class="variablelist"><table border="0">
1268 <col align="left" valign="top">
1269 <tbody>
1270 <tr>
1271 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
1272 <td> a normal C nul-terminated string
1273 </td>
1274 </tr>
1275 <tr>
1276 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1277 <td> a new string <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1278 </td>
1279 </tr>
1280 </tbody>
1281 </table></div>
1282 <p class="since">Since 2.24</p>
1283 </div>
1284 <hr>
1285 <div class="refsect2" title="g_variant_new_object_path ()">
1286 <a name="g-variant-new-object-path"></a><h3>g_variant_new_object_path ()</h3>
1287 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new_object_path           (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *object_path);</pre>
1288 <p>
1289 Creates a DBus object path <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> with the contents of <em class="parameter"><code>string</code></em>.
1290 <em class="parameter"><code>string</code></em> must be a valid DBus object path.  Use
1291 <a class="link" href="glib-GVariant.html#g-variant-is-object-path" title="g_variant_is_object_path ()"><code class="function">g_variant_is_object_path()</code></a> if you're not sure.</p>
1292 <div class="variablelist"><table border="0">
1293 <col align="left" valign="top">
1294 <tbody>
1295 <tr>
1296 <td><p><span class="term"><em class="parameter"><code>object_path</code></em> :</span></p></td>
1297 <td> a normal C nul-terminated string
1298 </td>
1299 </tr>
1300 <tr>
1301 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1302 <td> a new object path <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1303 </td>
1304 </tr>
1305 </tbody>
1306 </table></div>
1307 <p class="since">Since 2.24</p>
1308 </div>
1309 <hr>
1310 <div class="refsect2" title="g_variant_is_object_path ()">
1311 <a name="g-variant-is-object-path"></a><h3>g_variant_is_object_path ()</h3>
1312 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_variant_is_object_path            (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *string);</pre>
1313 <p>
1314 Determines if a given string is a valid DBus object path.  You
1315 should ensure that a string is a valid DBus object path before
1316 passing it to <a class="link" href="glib-GVariant.html#g-variant-new-object-path" title="g_variant_new_object_path ()"><code class="function">g_variant_new_object_path()</code></a>.
1317 </p>
1318 <p>
1319 A valid object path starts with '/' followed by zero or more
1320 sequences of characters separated by '/' characters.  Each sequence
1321 must contain only the characters "[A-Z][a-z][0-9]_".  No sequence
1322 (including the one following the final '/' character) may be empty.</p>
1323 <div class="variablelist"><table border="0">
1324 <col align="left" valign="top">
1325 <tbody>
1326 <tr>
1327 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
1328 <td> a normal C nul-terminated string
1329 </td>
1330 </tr>
1331 <tr>
1332 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1333 <td> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>string</code></em> is a DBus object path
1334 </td>
1335 </tr>
1336 </tbody>
1337 </table></div>
1338 <p class="since">Since 2.24</p>
1339 </div>
1340 <hr>
1341 <div class="refsect2" title="g_variant_new_signature ()">
1342 <a name="g-variant-new-signature"></a><h3>g_variant_new_signature ()</h3>
1343 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new_signature             (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *signature);</pre>
1344 <p>
1345 Creates a DBus type signature <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> with the contents of
1346 <em class="parameter"><code>string</code></em>.  <em class="parameter"><code>string</code></em> must be a valid DBus type signature.  Use
1347 <a class="link" href="glib-GVariant.html#g-variant-is-signature" title="g_variant_is_signature ()"><code class="function">g_variant_is_signature()</code></a> if you're not sure.</p>
1348 <div class="variablelist"><table border="0">
1349 <col align="left" valign="top">
1350 <tbody>
1351 <tr>
1352 <td><p><span class="term"><em class="parameter"><code>signature</code></em> :</span></p></td>
1353 <td> a normal C nul-terminated string
1354 </td>
1355 </tr>
1356 <tr>
1357 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1358 <td> a new signature <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1359 </td>
1360 </tr>
1361 </tbody>
1362 </table></div>
1363 <p class="since">Since 2.24</p>
1364 </div>
1365 <hr>
1366 <div class="refsect2" title="g_variant_is_signature ()">
1367 <a name="g-variant-is-signature"></a><h3>g_variant_is_signature ()</h3>
1368 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_variant_is_signature              (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *string);</pre>
1369 <p>
1370 Determines if a given string is a valid DBus type signature.  You
1371 should ensure that a string is a valid DBus object path before
1372 passing it to <a class="link" href="glib-GVariant.html#g-variant-new-signature" title="g_variant_new_signature ()"><code class="function">g_variant_new_signature()</code></a>.
1373 </p>
1374 <p>
1375 DBus type signatures consist of zero or more definite <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="type">GVariantType</span></a>
1376 strings in sequence.</p>
1377 <div class="variablelist"><table border="0">
1378 <col align="left" valign="top">
1379 <tbody>
1380 <tr>
1381 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
1382 <td> a normal C nul-terminated string
1383 </td>
1384 </tr>
1385 <tr>
1386 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1387 <td> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>string</code></em> is a DBus type signature
1388 </td>
1389 </tr>
1390 </tbody>
1391 </table></div>
1392 <p class="since">Since 2.24</p>
1393 </div>
1394 <hr>
1395 <div class="refsect2" title="g_variant_new_variant ()">
1396 <a name="g-variant-new-variant"></a><h3>g_variant_new_variant ()</h3>
1397 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new_variant               (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
1398 <p>
1399 Boxes <em class="parameter"><code>value</code></em>.  The result is a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance representing a
1400 variant containing the original value.</p>
1401 <div class="variablelist"><table border="0">
1402 <col align="left" valign="top">
1403 <tbody>
1404 <tr>
1405 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
1406 <td> a <span class="type">GVariance</span> instance
1407 </td>
1408 </tr>
1409 <tr>
1410 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1411 <td> a new variant <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1412 </td>
1413 </tr>
1414 </tbody>
1415 </table></div>
1416 <p class="since">Since 2.24</p>
1417 </div>
1418 <hr>
1419 <div class="refsect2" title="g_variant_new_strv ()">
1420 <a name="g-variant-new-strv"></a><h3>g_variant_new_strv ()</h3>
1421 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new_strv                  (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * const *strv,
1422                                                          <a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="returnvalue">gssize</span></a> length);</pre>
1423 <p>
1424 Constructs an array of strings <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> from the given array of
1425 strings.
1426 </p>
1427 <p>
1428 If <em class="parameter"><code>length</code></em> is not -1 then it gives the maximum length of <em class="parameter"><code>strv</code></em>.  In
1429 any case, a <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> pointer in <em class="parameter"><code>strv</code></em> is taken as a terminator.</p>
1430 <div class="variablelist"><table border="0">
1431 <col align="left" valign="top">
1432 <tbody>
1433 <tr>
1434 <td><p><span class="term"><em class="parameter"><code>strv</code></em> :</span></p></td>
1435 <td> an array of strings
1436 </td>
1437 </tr>
1438 <tr>
1439 <td><p><span class="term"><em class="parameter"><code>length</code></em> :</span></p></td>
1440 <td> the length of <em class="parameter"><code>strv</code></em>, or -1
1441 </td>
1442 </tr>
1443 <tr>
1444 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1445 <td> a new floating <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1446 </td>
1447 </tr>
1448 </tbody>
1449 </table></div>
1450 <p class="since">Since 2.24</p>
1451 </div>
1452 <hr>
1453 <div class="refsect2" title="g_variant_get_boolean ()">
1454 <a name="g-variant-get-boolean"></a><h3>g_variant_get_boolean ()</h3>
1455 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_variant_get_boolean               (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
1456 <p>
1457 Returns the boolean value of <em class="parameter"><code>value</code></em>.
1458 </p>
1459 <p>
1460 It is an error to call this function with a <em class="parameter"><code>value</code></em> of any type
1461 other than <a class="link" href="glib-GVariantType.html#G-VARIANT-TYPE-BOOLEAN:CAPS" title="G_VARIANT_TYPE_BOOLEAN"><code class="literal">G_VARIANT_TYPE_BOOLEAN</code></a>.</p>
1462 <div class="variablelist"><table border="0">
1463 <col align="left" valign="top">
1464 <tbody>
1465 <tr>
1466 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
1467 <td> a boolean <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1468 </td>
1469 </tr>
1470 <tr>
1471 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1472 <td> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> or <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a>
1473 </td>
1474 </tr>
1475 </tbody>
1476 </table></div>
1477 <p class="since">Since 2.24</p>
1478 </div>
1479 <hr>
1480 <div class="refsect2" title="g_variant_get_byte ()">
1481 <a name="g-variant-get-byte"></a><h3>g_variant_get_byte ()</h3>
1482 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#guchar" title="guchar"><span class="returnvalue">guchar</span></a>              g_variant_get_byte                  (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
1483 <p>
1484 Returns the byte value of <em class="parameter"><code>value</code></em>.
1485 </p>
1486 <p>
1487 It is an error to call this function with a <em class="parameter"><code>value</code></em> of any type
1488 other than <a class="link" href="glib-GVariantType.html#G-VARIANT-TYPE-BYTE:CAPS" title="G_VARIANT_TYPE_BYTE"><code class="literal">G_VARIANT_TYPE_BYTE</code></a>.</p>
1489 <div class="variablelist"><table border="0">
1490 <col align="left" valign="top">
1491 <tbody>
1492 <tr>
1493 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
1494 <td> a byte <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1495 </td>
1496 </tr>
1497 <tr>
1498 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1499 <td> a <a class="link" href="glib-Basic-Types.html#guchar" title="guchar"><span class="type">guchar</span></a>
1500 </td>
1501 </tr>
1502 </tbody>
1503 </table></div>
1504 <p class="since">Since 2.24</p>
1505 </div>
1506 <hr>
1507 <div class="refsect2" title="g_variant_get_int16 ()">
1508 <a name="g-variant-get-int16"></a><h3>g_variant_get_int16 ()</h3>
1509 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint16" title="gint16"><span class="returnvalue">gint16</span></a>              g_variant_get_int16                 (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
1510 <p>
1511 Returns the 16-bit signed integer value of <em class="parameter"><code>value</code></em>.
1512 </p>
1513 <p>
1514 It is an error to call this function with a <em class="parameter"><code>value</code></em> of any type
1515 other than <a class="link" href="glib-GVariantType.html#G-VARIANT-TYPE-INT16:CAPS" title="G_VARIANT_TYPE_INT16"><code class="literal">G_VARIANT_TYPE_INT16</code></a>.</p>
1516 <div class="variablelist"><table border="0">
1517 <col align="left" valign="top">
1518 <tbody>
1519 <tr>
1520 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
1521 <td> a int16 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1522 </td>
1523 </tr>
1524 <tr>
1525 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1526 <td> a <a class="link" href="glib-Basic-Types.html#gint16" title="gint16"><span class="type">gint16</span></a>
1527 </td>
1528 </tr>
1529 </tbody>
1530 </table></div>
1531 <p class="since">Since 2.24</p>
1532 </div>
1533 <hr>
1534 <div class="refsect2" title="g_variant_get_uint16 ()">
1535 <a name="g-variant-get-uint16"></a><h3>g_variant_get_uint16 ()</h3>
1536 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#guint16" title="guint16"><span class="returnvalue">guint16</span></a>             g_variant_get_uint16                (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
1537 <p>
1538 Returns the 16-bit unsigned integer value of <em class="parameter"><code>value</code></em>.
1539 </p>
1540 <p>
1541 It is an error to call this function with a <em class="parameter"><code>value</code></em> of any type
1542 other than <a class="link" href="glib-GVariantType.html#G-VARIANT-TYPE-UINT16:CAPS" title="G_VARIANT_TYPE_UINT16"><code class="literal">G_VARIANT_TYPE_UINT16</code></a>.</p>
1543 <div class="variablelist"><table border="0">
1544 <col align="left" valign="top">
1545 <tbody>
1546 <tr>
1547 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
1548 <td> a uint16 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1549 </td>
1550 </tr>
1551 <tr>
1552 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1553 <td> a <a class="link" href="glib-Basic-Types.html#guint16" title="guint16"><span class="type">guint16</span></a>
1554 </td>
1555 </tr>
1556 </tbody>
1557 </table></div>
1558 <p class="since">Since 2.24</p>
1559 </div>
1560 <hr>
1561 <div class="refsect2" title="g_variant_get_int32 ()">
1562 <a name="g-variant-get-int32"></a><h3>g_variant_get_int32 ()</h3>
1563 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint32" title="gint32"><span class="returnvalue">gint32</span></a>              g_variant_get_int32                 (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
1564 <p>
1565 Returns the 32-bit signed integer value of <em class="parameter"><code>value</code></em>.
1566 </p>
1567 <p>
1568 It is an error to call this function with a <em class="parameter"><code>value</code></em> of any type
1569 other than <a class="link" href="glib-GVariantType.html#G-VARIANT-TYPE-INT32:CAPS" title="G_VARIANT_TYPE_INT32"><code class="literal">G_VARIANT_TYPE_INT32</code></a>.</p>
1570 <div class="variablelist"><table border="0">
1571 <col align="left" valign="top">
1572 <tbody>
1573 <tr>
1574 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
1575 <td> a int32 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1576 </td>
1577 </tr>
1578 <tr>
1579 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1580 <td> a <a class="link" href="glib-Basic-Types.html#gint32" title="gint32"><span class="type">gint32</span></a>
1581 </td>
1582 </tr>
1583 </tbody>
1584 </table></div>
1585 <p class="since">Since 2.24</p>
1586 </div>
1587 <hr>
1588 <div class="refsect2" title="g_variant_get_uint32 ()">
1589 <a name="g-variant-get-uint32"></a><h3>g_variant_get_uint32 ()</h3>
1590 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#guint32" title="guint32"><span class="returnvalue">guint32</span></a>             g_variant_get_uint32                (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
1591 <p>
1592 Returns the 32-bit unsigned integer value of <em class="parameter"><code>value</code></em>.
1593 </p>
1594 <p>
1595 It is an error to call this function with a <em class="parameter"><code>value</code></em> of any type
1596 other than <a class="link" href="glib-GVariantType.html#G-VARIANT-TYPE-UINT32:CAPS" title="G_VARIANT_TYPE_UINT32"><code class="literal">G_VARIANT_TYPE_UINT32</code></a>.</p>
1597 <div class="variablelist"><table border="0">
1598 <col align="left" valign="top">
1599 <tbody>
1600 <tr>
1601 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
1602 <td> a uint32 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1603 </td>
1604 </tr>
1605 <tr>
1606 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1607 <td> a <a class="link" href="glib-Basic-Types.html#guint32" title="guint32"><span class="type">guint32</span></a>
1608 </td>
1609 </tr>
1610 </tbody>
1611 </table></div>
1612 <p class="since">Since 2.24</p>
1613 </div>
1614 <hr>
1615 <div class="refsect2" title="g_variant_get_int64 ()">
1616 <a name="g-variant-get-int64"></a><h3>g_variant_get_int64 ()</h3>
1617 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint64" title="gint64"><span class="returnvalue">gint64</span></a>              g_variant_get_int64                 (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
1618 <p>
1619 Returns the 64-bit signed integer value of <em class="parameter"><code>value</code></em>.
1620 </p>
1621 <p>
1622 It is an error to call this function with a <em class="parameter"><code>value</code></em> of any type
1623 other than <a class="link" href="glib-GVariantType.html#G-VARIANT-TYPE-INT64:CAPS" title="G_VARIANT_TYPE_INT64"><code class="literal">G_VARIANT_TYPE_INT64</code></a>.</p>
1624 <div class="variablelist"><table border="0">
1625 <col align="left" valign="top">
1626 <tbody>
1627 <tr>
1628 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
1629 <td> a int64 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1630 </td>
1631 </tr>
1632 <tr>
1633 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1634 <td> a <a class="link" href="glib-Basic-Types.html#gint64" title="gint64"><span class="type">gint64</span></a>
1635 </td>
1636 </tr>
1637 </tbody>
1638 </table></div>
1639 <p class="since">Since 2.24</p>
1640 </div>
1641 <hr>
1642 <div class="refsect2" title="g_variant_get_uint64 ()">
1643 <a name="g-variant-get-uint64"></a><h3>g_variant_get_uint64 ()</h3>
1644 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#guint64" title="guint64"><span class="returnvalue">guint64</span></a>             g_variant_get_uint64                (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
1645 <p>
1646 Returns the 64-bit unsigned integer value of <em class="parameter"><code>value</code></em>.
1647 </p>
1648 <p>
1649 It is an error to call this function with a <em class="parameter"><code>value</code></em> of any type
1650 other than <a class="link" href="glib-GVariantType.html#G-VARIANT-TYPE-UINT64:CAPS" title="G_VARIANT_TYPE_UINT64"><code class="literal">G_VARIANT_TYPE_UINT64</code></a>.</p>
1651 <div class="variablelist"><table border="0">
1652 <col align="left" valign="top">
1653 <tbody>
1654 <tr>
1655 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
1656 <td> a uint64 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1657 </td>
1658 </tr>
1659 <tr>
1660 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1661 <td> a <a class="link" href="glib-Basic-Types.html#guint64" title="guint64"><span class="type">guint64</span></a>
1662 </td>
1663 </tr>
1664 </tbody>
1665 </table></div>
1666 <p class="since">Since 2.24</p>
1667 </div>
1668 <hr>
1669 <div class="refsect2" title="g_variant_get_handle ()">
1670 <a name="g-variant-get-handle"></a><h3>g_variant_get_handle ()</h3>
1671 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint32" title="gint32"><span class="returnvalue">gint32</span></a>              g_variant_get_handle                (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
1672 <p>
1673 Returns the 32-bit signed integer value of <em class="parameter"><code>value</code></em>.
1674 </p>
1675 <p>
1676 It is an error to call this function with a <em class="parameter"><code>value</code></em> of any type other
1677 than <a class="link" href="glib-GVariantType.html#G-VARIANT-TYPE-HANDLE:CAPS" title="G_VARIANT_TYPE_HANDLE"><code class="literal">G_VARIANT_TYPE_HANDLE</code></a>.
1678 </p>
1679 <p>
1680 By convention, handles are indexes into an array of file descriptors
1681 that are sent alongside a DBus message.  If you're not interacting
1682 with DBus, you probably don't need them.</p>
1683 <div class="variablelist"><table border="0">
1684 <col align="left" valign="top">
1685 <tbody>
1686 <tr>
1687 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
1688 <td> a handle <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1689 </td>
1690 </tr>
1691 <tr>
1692 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1693 <td> a <a class="link" href="glib-Basic-Types.html#gint32" title="gint32"><span class="type">gint32</span></a>
1694 </td>
1695 </tr>
1696 </tbody>
1697 </table></div>
1698 <p class="since">Since 2.24</p>
1699 </div>
1700 <hr>
1701 <div class="refsect2" title="g_variant_get_double ()">
1702 <a name="g-variant-get-double"></a><h3>g_variant_get_double ()</h3>
1703 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="returnvalue">gdouble</span></a>             g_variant_get_double                (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
1704 <p>
1705 Returns the double precision floating point value of <em class="parameter"><code>value</code></em>.
1706 </p>
1707 <p>
1708 It is an error to call this function with a <em class="parameter"><code>value</code></em> of any type
1709 other than <a class="link" href="glib-GVariantType.html#G-VARIANT-TYPE-DOUBLE:CAPS" title="G_VARIANT_TYPE_DOUBLE"><code class="literal">G_VARIANT_TYPE_DOUBLE</code></a>.</p>
1710 <div class="variablelist"><table border="0">
1711 <col align="left" valign="top">
1712 <tbody>
1713 <tr>
1714 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
1715 <td> a double <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1716 </td>
1717 </tr>
1718 <tr>
1719 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1720 <td> a <a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="type">gdouble</span></a>
1721 </td>
1722 </tr>
1723 </tbody>
1724 </table></div>
1725 <p class="since">Since 2.24</p>
1726 </div>
1727 <hr>
1728 <div class="refsect2" title="g_variant_get_string ()">
1729 <a name="g-variant-get-string"></a><h3>g_variant_get_string ()</h3>
1730 <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       g_variant_get_string                (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
1731                                                          <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a> *length);</pre>
1732 <p>
1733 Returns the string value of a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance with a string
1734 type.  This includes the types <a class="link" href="glib-GVariantType.html#G-VARIANT-TYPE-STRING:CAPS" title="G_VARIANT_TYPE_STRING"><code class="literal">G_VARIANT_TYPE_STRING</code></a>,
1735 <a class="link" href="glib-GVariantType.html#G-VARIANT-TYPE-OBJECT-PATH:CAPS" title="G_VARIANT_TYPE_OBJECT_PATH"><code class="literal">G_VARIANT_TYPE_OBJECT_PATH</code></a> and <a class="link" href="glib-GVariantType.html#G-VARIANT-TYPE-SIGNATURE:CAPS" title="G_VARIANT_TYPE_SIGNATURE"><code class="literal">G_VARIANT_TYPE_SIGNATURE</code></a>.
1736 </p>
1737 <p>
1738 If <em class="parameter"><code>length</code></em> is non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> then the length of the string (in bytes) is
1739 returned there.  For trusted values, this information is already
1740 known.  For untrusted values, a <code class="function">strlen()</code> will be performed.
1741 </p>
1742 <p>
1743 It is an error to call this function with a <em class="parameter"><code>value</code></em> of any type
1744 other than those three.
1745 </p>
1746 <p>
1747 The return value remains valid as long as <em class="parameter"><code>value</code></em> exists.</p>
1748 <div class="variablelist"><table border="0">
1749 <col align="left" valign="top">
1750 <tbody>
1751 <tr>
1752 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
1753 <td> a string <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1754 </td>
1755 </tr>
1756 <tr>
1757 <td><p><span class="term"><em class="parameter"><code>length</code></em> :</span></p></td>
1758 <td> a pointer to a <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a>, to store the length
1759 </td>
1760 </tr>
1761 <tr>
1762 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1763 <td> the constant string
1764 </td>
1765 </tr>
1766 </tbody>
1767 </table></div>
1768 <p class="since">Since 2.24</p>
1769 </div>
1770 <hr>
1771 <div class="refsect2" title="g_variant_dup_string ()">
1772 <a name="g-variant-dup-string"></a><h3>g_variant_dup_string ()</h3>
1773 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_variant_dup_string                (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
1774                                                          <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a> *length);</pre>
1775 <p>
1776 Similar to <a class="link" href="glib-GVariant.html#g-variant-get-string" title="g_variant_get_string ()"><code class="function">g_variant_get_string()</code></a> except that instead of returning
1777 a constant string, the string is duplicated.
1778 </p>
1779 <p>
1780 The return value must be freed using <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a>.</p>
1781 <div class="variablelist"><table border="0">
1782 <col align="left" valign="top">
1783 <tbody>
1784 <tr>
1785 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
1786 <td> a string <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
1787 </td>
1788 </tr>
1789 <tr>
1790 <td><p><span class="term"><em class="parameter"><code>length</code></em> :</span></p></td>
1791 <td> a pointer to a <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a>, to store the length
1792 </td>
1793 </tr>
1794 <tr>
1795 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1796 <td> a newly allocated string
1797 </td>
1798 </tr>
1799 </tbody>
1800 </table></div>
1801 <p class="since">Since 2.24</p>
1802 </div>
1803 <hr>
1804 <div class="refsect2" title="g_variant_get_variant ()">
1805 <a name="g-variant-get-variant"></a><h3>g_variant_get_variant ()</h3>
1806 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_get_variant               (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
1807 <p>
1808 Unboxes <em class="parameter"><code>value</code></em>.  The result is the <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance that was
1809 contained in <em class="parameter"><code>value</code></em>.</p>
1810 <div class="variablelist"><table border="0">
1811 <col align="left" valign="top">
1812 <tbody>
1813 <tr>
1814 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
1815 <td> a variant <span class="type">GVariance</span> instance
1816 </td>
1817 </tr>
1818 <tr>
1819 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1820 <td> the item contained in the variant
1821 </td>
1822 </tr>
1823 </tbody>
1824 </table></div>
1825 <p class="since">Since 2.24</p>
1826 </div>
1827 <hr>
1828 <div class="refsect2" title="g_variant_get_strv ()">
1829 <a name="g-variant-get-strv"></a><h3>g_variant_get_strv ()</h3>
1830 <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **      g_variant_get_strv                  (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
1831                                                          <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a> *length);</pre>
1832 <p>
1833 Gets the contents of an array of strings <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>.  This call
1834 makes a shallow copy; the return result should be released with
1835 <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a>, but the individual strings must not be modified.
1836 </p>
1837 <p>
1838 If <em class="parameter"><code>length</code></em> is non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> then the number of elements in the result
1839 is stored there.  In any case, the resulting array will be
1840 <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated.
1841 </p>
1842 <p>
1843 For an empty array, <em class="parameter"><code>length</code></em> will be set to 0 and a pointer to a
1844 <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> pointer will be returned.</p>
1845 <div class="variablelist"><table border="0">
1846 <col align="left" valign="top">
1847 <tbody>
1848 <tr>
1849 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
1850 <td> an array of strings <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
1851 </td>
1852 </tr>
1853 <tr>
1854 <td><p><span class="term"><em class="parameter"><code>length</code></em> :</span></p></td>
1855 <td> the length of the result, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
1856 </td>
1857 </tr>
1858 <tr>
1859 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1860 <td> an array of constant strings
1861 </td>
1862 </tr>
1863 </tbody>
1864 </table></div>
1865 <p class="since">Since 2.24</p>
1866 </div>
1867 <hr>
1868 <div class="refsect2" title="g_variant_dup_strv ()">
1869 <a name="g-variant-dup-strv"></a><h3>g_variant_dup_strv ()</h3>
1870 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **            g_variant_dup_strv                  (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
1871                                                          <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a> *length);</pre>
1872 <p>
1873 Gets the contents of an array of strings <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>.  This call
1874 makes a deep copy; the return result should be released with
1875 <a class="link" href="glib-String-Utility-Functions.html#g-strfreev" title="g_strfreev ()"><code class="function">g_strfreev()</code></a>.
1876 </p>
1877 <p>
1878 If <em class="parameter"><code>length</code></em> is non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> then the number of elements in the result
1879 is stored there.  In any case, the resulting array will be
1880 <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated.
1881 </p>
1882 <p>
1883 For an empty array, <em class="parameter"><code>length</code></em> will be set to 0 and a pointer to a
1884 <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> pointer will be returned.</p>
1885 <div class="variablelist"><table border="0">
1886 <col align="left" valign="top">
1887 <tbody>
1888 <tr>
1889 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
1890 <td> an array of strings <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
1891 </td>
1892 </tr>
1893 <tr>
1894 <td><p><span class="term"><em class="parameter"><code>length</code></em> :</span></p></td>
1895 <td> the length of the result, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
1896 </td>
1897 </tr>
1898 <tr>
1899 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1900 <td> an array of constant strings
1901 </td>
1902 </tr>
1903 </tbody>
1904 </table></div>
1905 <p class="since">Since 2.24</p>
1906 </div>
1907 <hr>
1908 <div class="refsect2" title="g_variant_new_maybe ()">
1909 <a name="g-variant-new-maybe"></a><h3>g_variant_new_maybe ()</h3>
1910 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new_maybe                 (const <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="returnvalue">GVariantType</span></a> *child_type,
1911                                                          <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *child);</pre>
1912 <p>
1913 Depending on if <em class="parameter"><code>value</code></em> is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, either wraps <em class="parameter"><code>value</code></em> inside of a
1914 maybe container or creates a Nothing instance for the given <em class="parameter"><code>type</code></em>.
1915 </p>
1916 <p>
1917 At least one of <em class="parameter"><code>type</code></em> and <em class="parameter"><code>value</code></em> must be non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.  If <em class="parameter"><code>type</code></em> is
1918 non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> then it must be a definite type.  If they are both
1919 non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> then <em class="parameter"><code>type</code></em> must be the type of <em class="parameter"><code>value</code></em>.</p>
1920 <div class="variablelist"><table border="0">
1921 <col align="left" valign="top">
1922 <tbody>
1923 <tr>
1924 <td><p><span class="term"><em class="parameter"><code>child_type</code></em> :</span></p></td>
1925 <td> the <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="type">GVariantType</span></a> of the child
1926 </td>
1927 </tr>
1928 <tr>
1929 <td><p><span class="term"><em class="parameter"><code>child</code></em> :</span></p></td>
1930 <td> the child value, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
1931 </td>
1932 </tr>
1933 <tr>
1934 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1935 <td> a new <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> maybe instance
1936 </td>
1937 </tr>
1938 </tbody>
1939 </table></div>
1940 <p class="since">Since 2.24</p>
1941 </div>
1942 <hr>
1943 <div class="refsect2" title="g_variant_new_array ()">
1944 <a name="g-variant-new-array"></a><h3>g_variant_new_array ()</h3>
1945 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new_array                 (const <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="returnvalue">GVariantType</span></a> *child_type,
1946                                                          <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> * const *children,
1947                                                          <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a> n_children);</pre>
1948 <p>
1949 Creates a new <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> array from <em class="parameter"><code>children</code></em>.
1950 </p>
1951 <p>
1952 <em class="parameter"><code>child_type</code></em> must be non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> if <em class="parameter"><code>n_children</code></em> is zero.  Otherwise, the
1953 child type is determined by inspecting the first element of the
1954 <em class="parameter"><code>children</code></em> array.  If <em class="parameter"><code>child_type</code></em> is non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> then it must be a
1955 definite type.
1956 </p>
1957 <p>
1958 The items of the array are taken from the <em class="parameter"><code>children</code></em> array.  No entry
1959 in the <em class="parameter"><code>children</code></em> array may be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
1960 </p>
1961 <p>
1962 All items in the array must have the same type, which must be the
1963 same as <em class="parameter"><code>child_type</code></em>, if given.</p>
1964 <div class="variablelist"><table border="0">
1965 <col align="left" valign="top">
1966 <tbody>
1967 <tr>
1968 <td><p><span class="term"><em class="parameter"><code>child_type</code></em> :</span></p></td>
1969 <td> the element type of the new array
1970 </td>
1971 </tr>
1972 <tr>
1973 <td><p><span class="term"><em class="parameter"><code>children</code></em> :</span></p></td>
1974 <td> an array of <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> pointers, the children
1975 </td>
1976 </tr>
1977 <tr>
1978 <td><p><span class="term"><em class="parameter"><code>n_children</code></em> :</span></p></td>
1979 <td> the length of <em class="parameter"><code>children</code></em>
1980 </td>
1981 </tr>
1982 <tr>
1983 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1984 <td> a new <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> array
1985 </td>
1986 </tr>
1987 </tbody>
1988 </table></div>
1989 <p class="since">Since 2.24</p>
1990 </div>
1991 <hr>
1992 <div class="refsect2" title="g_variant_new_tuple ()">
1993 <a name="g-variant-new-tuple"></a><h3>g_variant_new_tuple ()</h3>
1994 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new_tuple                 (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> * const *children,
1995                                                          <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a> n_children);</pre>
1996 <p>
1997 Creates a new tuple <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> out of the items in <em class="parameter"><code>children</code></em>.  The
1998 type is determined from the types of <em class="parameter"><code>children</code></em>.  No entry in the
1999 <em class="parameter"><code>children</code></em> array may be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
2000 </p>
2001 <p>
2002 If <em class="parameter"><code>n_children</code></em> is 0 then the unit tuple is constructed.</p>
2003 <div class="variablelist"><table border="0">
2004 <col align="left" valign="top">
2005 <tbody>
2006 <tr>
2007 <td><p><span class="term"><em class="parameter"><code>children</code></em> :</span></p></td>
2008 <td> the items to make the tuple out of
2009 </td>
2010 </tr>
2011 <tr>
2012 <td><p><span class="term"><em class="parameter"><code>n_children</code></em> :</span></p></td>
2013 <td> the length of <em class="parameter"><code>children</code></em>
2014 </td>
2015 </tr>
2016 <tr>
2017 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2018 <td> a new <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> tuple
2019 </td>
2020 </tr>
2021 </tbody>
2022 </table></div>
2023 <p class="since">Since 2.24</p>
2024 </div>
2025 <hr>
2026 <div class="refsect2" title="g_variant_new_dict_entry ()">
2027 <a name="g-variant-new-dict-entry"></a><h3>g_variant_new_dict_entry ()</h3>
2028 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new_dict_entry            (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *key,
2029                                                          <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
2030 <p>
2031 Creates a new dictionary entry <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>.  <em class="parameter"><code>key</code></em> and <em class="parameter"><code>value</code></em> must be
2032 non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
2033 </p>
2034 <p>
2035 <em class="parameter"><code>key</code></em> must be a value of a basic type (ie: not a container).</p>
2036 <div class="variablelist"><table border="0">
2037 <col align="left" valign="top">
2038 <tbody>
2039 <tr>
2040 <td><p><span class="term"><em class="parameter"><code>key</code></em> :</span></p></td>
2041 <td> a basic <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>, the key
2042 </td>
2043 </tr>
2044 <tr>
2045 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
2046 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>, the value
2047 </td>
2048 </tr>
2049 <tr>
2050 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2051 <td> a new dictionary entry <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
2052 </td>
2053 </tr>
2054 </tbody>
2055 </table></div>
2056 <p class="since">Since 2.24</p>
2057 </div>
2058 <hr>
2059 <div class="refsect2" title="g_variant_get_maybe ()">
2060 <a name="g-variant-get-maybe"></a><h3>g_variant_get_maybe ()</h3>
2061 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_get_maybe                 (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
2062 <p>
2063 Given a maybe-typed <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance, extract its value.  If the
2064 value is Nothing, then this function returns <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.</p>
2065 <div class="variablelist"><table border="0">
2066 <col align="left" valign="top">
2067 <tbody>
2068 <tr>
2069 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
2070 <td> a maybe-typed value
2071 </td>
2072 </tr>
2073 <tr>
2074 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2075 <td> the contents of <em class="parameter"><code>value</code></em>, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
2076 </td>
2077 </tr>
2078 </tbody>
2079 </table></div>
2080 <p class="since">Since 2.24</p>
2081 </div>
2082 <hr>
2083 <div class="refsect2" title="g_variant_n_children ()">
2084 <a name="g-variant-n-children"></a><h3>g_variant_n_children ()</h3>
2085 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a>               g_variant_n_children                (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
2086 <p>
2087 Determines the number of children in a container <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance.
2088 This includes variants, maybes, arrays, tuples and dictionary
2089 entries.  It is an error to call this function on any other type of
2090 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>.
2091 </p>
2092 <p>
2093 For variants, the return value is always 1.  For values with maybe
2094 types, it is always zero or one.  For arrays, it is the length of the
2095 array.  For tuples it is the number of tuple items (which depends
2096 only on the type).  For dictionary entries, it is always 2
2097 </p>
2098 <p>
2099 This function is O(1).</p>
2100 <div class="variablelist"><table border="0">
2101 <col align="left" valign="top">
2102 <tbody>
2103 <tr>
2104 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
2105 <td> a container <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
2106 </td>
2107 </tr>
2108 <tr>
2109 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2110 <td> the number of children in the container
2111 </td>
2112 </tr>
2113 </tbody>
2114 </table></div>
2115 <p class="since">Since 2.24</p>
2116 </div>
2117 <hr>
2118 <div class="refsect2" title="g_variant_get_child_value ()">
2119 <a name="g-variant-get-child-value"></a><h3>g_variant_get_child_value ()</h3>
2120 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_get_child_value           (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
2121                                                          <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a> index_);</pre>
2122 <p>
2123 Reads a child item out of a container <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance.  This
2124 includes variants, maybes, arrays, tuples and dictionary
2125 entries.  It is an error to call this function on any other type of
2126 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>.
2127 </p>
2128 <p>
2129 It is an error if <em class="parameter"><code>index_</code></em> is greater than the number of child items
2130 in the container.  See <a class="link" href="glib-GVariant.html#g-variant-n-children" title="g_variant_n_children ()"><code class="function">g_variant_n_children()</code></a>.
2131 </p>
2132 <p>
2133 This function is O(1).</p>
2134 <div class="variablelist"><table border="0">
2135 <col align="left" valign="top">
2136 <tbody>
2137 <tr>
2138 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
2139 <td> a container <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
2140 </td>
2141 </tr>
2142 <tr>
2143 <td><p><span class="term"><em class="parameter"><code>index_</code></em> :</span></p></td>
2144 <td> the index of the child to fetch
2145 </td>
2146 </tr>
2147 <tr>
2148 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2149 <td> the child at the specified index
2150 </td>
2151 </tr>
2152 </tbody>
2153 </table></div>
2154 <p class="since">Since 2.24</p>
2155 </div>
2156 <hr>
2157 <div class="refsect2" title="g_variant_get_child ()">
2158 <a name="g-variant-get-child"></a><h3>g_variant_get_child ()</h3>
2159 <pre class="programlisting"><span class="returnvalue">void</span>                g_variant_get_child                 (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
2160                                                          <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a> index_,
2161                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *format_string,
2162                                                          ...);</pre>
2163 <p>
2164 Reads a child item out of a container <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance and
2165 deconstructs it according to <em class="parameter"><code>format_string</code></em>.  This call is
2166 essentially a combination of <a class="link" href="glib-GVariant.html#g-variant-get-child-value" title="g_variant_get_child_value ()"><code class="function">g_variant_get_child_value()</code></a> and
2167 <a class="link" href="glib-GVariant.html#g-variant-get" title="g_variant_get ()"><code class="function">g_variant_get()</code></a>.</p>
2168 <div class="variablelist"><table border="0">
2169 <col align="left" valign="top">
2170 <tbody>
2171 <tr>
2172 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
2173 <td> a container <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
2174 </td>
2175 </tr>
2176 <tr>
2177 <td><p><span class="term"><em class="parameter"><code>index_</code></em> :</span></p></td>
2178 <td> the index of the child to deconstruct
2179 </td>
2180 </tr>
2181 <tr>
2182 <td><p><span class="term"><em class="parameter"><code>format_string</code></em> :</span></p></td>
2183 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> format string
2184 </td>
2185 </tr>
2186 <tr>
2187 <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
2188 <td> arguments, as per <em class="parameter"><code>format_string</code></em>
2189 </td>
2190 </tr>
2191 </tbody>
2192 </table></div>
2193 <p class="since">Since 2.24</p>
2194 </div>
2195 <hr>
2196 <div class="refsect2" title="g_variant_get_fixed_array ()">
2197 <a name="g-variant-get-fixed-array"></a><h3>g_variant_get_fixed_array ()</h3>
2198 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="returnvalue">gconstpointer</span></a>       g_variant_get_fixed_array           (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
2199                                                          <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a> *n_elements,
2200                                                          <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a> element_size);</pre>
2201 <p>
2202 Provides access to the serialised data for an array of fixed-sized
2203 items.
2204 </p>
2205 <p>
2206 <em class="parameter"><code>value</code></em> must be an array with fixed-sized elements.  Numeric types are
2207 fixed-size as are tuples containing only other fixed-sized types.
2208 </p>
2209 <p>
2210 <em class="parameter"><code>element_size</code></em> must be the size of a single element in the array.  For
2211 example, if calling this function for an array of 32 bit integers,
2212 you might say <code class="code">sizeof (gint32)</code>.  This value isn't used
2213 except for the purpose of a double-check that the form of the
2214 seralised data matches the caller's expectation.
2215 </p>
2216 <p>
2217 <em class="parameter"><code>n_elements</code></em>, which must be non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> is set equal to the number of
2218 items in the array.</p>
2219 <div class="variablelist"><table border="0">
2220 <col align="left" valign="top">
2221 <tbody>
2222 <tr>
2223 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
2224 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> array with fixed-sized elements
2225 </td>
2226 </tr>
2227 <tr>
2228 <td><p><span class="term"><em class="parameter"><code>n_elements</code></em> :</span></p></td>
2229 <td> a pointer to the location to store the number of items
2230 </td>
2231 </tr>
2232 <tr>
2233 <td><p><span class="term"><em class="parameter"><code>element_size</code></em> :</span></p></td>
2234 <td> the size of each element
2235 </td>
2236 </tr>
2237 <tr>
2238 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2239 <td> a pointer to the fixed array
2240 </td>
2241 </tr>
2242 </tbody>
2243 </table></div>
2244 <p class="since">Since 2.24</p>
2245 </div>
2246 <hr>
2247 <div class="refsect2" title="g_variant_get_size ()">
2248 <a name="g-variant-get-size"></a><h3>g_variant_get_size ()</h3>
2249 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a>               g_variant_get_size                  (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
2250 <p>
2251 Determines the number of bytes that would be required to store <em class="parameter"><code>value</code></em>
2252 with <a class="link" href="glib-GVariant.html#g-variant-store" title="g_variant_store ()"><code class="function">g_variant_store()</code></a>.
2253 </p>
2254 <p>
2255 If <em class="parameter"><code>value</code></em> has a fixed-sized type then this function always returned
2256 that fixed size.
2257 </p>
2258 <p>
2259 In the case that <em class="parameter"><code>value</code></em> is already in serialised form or the size has
2260 already been calculated (ie: this function has been called before)
2261 then this function is O(1).  Otherwise, the size is calculated, an
2262 operation which is approximately O(n) in the number of values
2263 involved.</p>
2264 <div class="variablelist"><table border="0">
2265 <col align="left" valign="top">
2266 <tbody>
2267 <tr>
2268 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
2269 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
2270 </td>
2271 </tr>
2272 <tr>
2273 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2274 <td> the serialised size of <em class="parameter"><code>value</code></em>
2275 </td>
2276 </tr>
2277 </tbody>
2278 </table></div>
2279 <p class="since">Since 2.24</p>
2280 </div>
2281 <hr>
2282 <div class="refsect2" title="g_variant_get_data ()">
2283 <a name="g-variant-get-data"></a><h3>g_variant_get_data ()</h3>
2284 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="returnvalue">gconstpointer</span></a>       g_variant_get_data                  (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
2285 <p>
2286 Returns a pointer to the serialised form of a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance.
2287 The returned data may not be in fully-normalised form if read from an
2288 untrusted source.  The returned data must not be freed; it remains
2289 valid for as long as <em class="parameter"><code>value</code></em> exists.
2290 </p>
2291 <p>
2292 If <em class="parameter"><code>value</code></em> is a fixed-sized value that was deserialised from a
2293 corrupted serialised container then <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> may be returned.  In this
2294 case, the proper thing to do is typically to use the appropriate
2295 number of nul bytes in place of <em class="parameter"><code>value</code></em>.  If <em class="parameter"><code>value</code></em> is not fixed-sized
2296 then <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> is never returned.
2297 </p>
2298 <p>
2299 In the case that <em class="parameter"><code>value</code></em> is already in serialised form, this function
2300 is O(1).  If the value is not already in serialised form,
2301 serialisation occurs implicitly and is approximately O(n) in the size
2302 of the result.</p>
2303 <div class="variablelist"><table border="0">
2304 <col align="left" valign="top">
2305 <tbody>
2306 <tr>
2307 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
2308 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
2309 </td>
2310 </tr>
2311 <tr>
2312 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2313 <td> the serialised form of <em class="parameter"><code>value</code></em>, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
2314 </td>
2315 </tr>
2316 </tbody>
2317 </table></div>
2318 <p class="since">Since 2.24</p>
2319 </div>
2320 <hr>
2321 <div class="refsect2" title="g_variant_store ()">
2322 <a name="g-variant-store"></a><h3>g_variant_store ()</h3>
2323 <pre class="programlisting"><span class="returnvalue">void</span>                g_variant_store                     (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
2324                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> data);</pre>
2325 <p>
2326 Stores the serialised form of <em class="parameter"><code>value</code></em> at <em class="parameter"><code>data</code></em>.  <em class="parameter"><code>data</code></em> should be
2327 large enough.  See <a class="link" href="glib-GVariant.html#g-variant-get-size" title="g_variant_get_size ()"><code class="function">g_variant_get_size()</code></a>.
2328 </p>
2329 <p>
2330 The stored data is in machine native byte order but may not be in
2331 fully-normalised form if read from an untrusted source.  See
2332 <code class="function">g_variant_normalise()</code> for a solution.
2333 </p>
2334 <p>
2335 This function is approximately O(n) in the size of <em class="parameter"><code>data</code></em>.</p>
2336 <div class="variablelist"><table border="0">
2337 <col align="left" valign="top">
2338 <tbody>
2339 <tr>
2340 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
2341 <td> the <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> to store
2342 </td>
2343 </tr>
2344 <tr>
2345 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
2346 <td> the location to store the serialised data at
2347 </td>
2348 </tr>
2349 </tbody>
2350 </table></div>
2351 <p class="since">Since 2.24</p>
2352 </div>
2353 <hr>
2354 <div class="refsect2" title="g_variant_new_from_data ()">
2355 <a name="g-variant-new-from-data"></a><h3>g_variant_new_from_data ()</h3>
2356 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new_from_data             (const <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="returnvalue">GVariantType</span></a> *type,
2357                                                          <a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="returnvalue">gconstpointer</span></a> data,
2358                                                          <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a> size,
2359                                                          <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> trusted,
2360                                                          <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="returnvalue">GDestroyNotify</span></a> notify,
2361                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> user_data);</pre>
2362 <p>
2363 Creates a new <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance from serialised data.
2364 </p>
2365 <p>
2366 <em class="parameter"><code>type</code></em> is the type of <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance that will be constructed.
2367 The interpretation of <em class="parameter"><code>data</code></em> depends on knowing the type.
2368 </p>
2369 <p>
2370 <em class="parameter"><code>data</code></em> is not modified by this function and must remain valid with an
2371 unchanging value until such a time as <em class="parameter"><code>notify</code></em> is called with
2372 <em class="parameter"><code>user_data</code></em>.  If the contents of <em class="parameter"><code>data</code></em> change before that time then
2373 the result is undefined.
2374 </p>
2375 <p>
2376 If <em class="parameter"><code>data</code></em> is trusted to be serialised data in normal form then
2377 <em class="parameter"><code>trusted</code></em> should be <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>.  This applies to serialised data created
2378 within this process or read from a trusted location on the disk (such
2379 as a file installed in /usr/lib alongside your application).  You
2380 should set trusted to <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> if <em class="parameter"><code>data</code></em> is read from the network, a
2381 file in the user's home directory, etc.
2382 </p>
2383 <p>
2384 <em class="parameter"><code>notify</code></em> will be called with <em class="parameter"><code>user_data</code></em> when <em class="parameter"><code>data</code></em> is no longer
2385 needed.  The exact time of this call is unspecified and might even be
2386 before this function returns.</p>
2387 <div class="variablelist"><table border="0">
2388 <col align="left" valign="top">
2389 <tbody>
2390 <tr>
2391 <td><p><span class="term"><em class="parameter"><code>type</code></em> :</span></p></td>
2392 <td> a <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="type">GVariantType</span></a>
2393 </td>
2394 </tr>
2395 <tr>
2396 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
2397 <td> the serialised data
2398 </td>
2399 </tr>
2400 <tr>
2401 <td><p><span class="term"><em class="parameter"><code>size</code></em> :</span></p></td>
2402 <td> the size of <em class="parameter"><code>data</code></em>
2403 </td>
2404 </tr>
2405 <tr>
2406 <td><p><span class="term"><em class="parameter"><code>trusted</code></em> :</span></p></td>
2407 <td> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>data</code></em> is definitely in normal form
2408 </td>
2409 </tr>
2410 <tr>
2411 <td><p><span class="term"><em class="parameter"><code>notify</code></em> :</span></p></td>
2412 <td> function to call when <em class="parameter"><code>data</code></em> is no longer needed
2413 </td>
2414 </tr>
2415 <tr>
2416 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
2417 <td> data for <em class="parameter"><code>notify</code></em>
2418 </td>
2419 </tr>
2420 <tr>
2421 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2422 <td> a new floating <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> of type <em class="parameter"><code>type</code></em>
2423 </td>
2424 </tr>
2425 </tbody>
2426 </table></div>
2427 <p class="since">Since 2.24</p>
2428 </div>
2429 <hr>
2430 <div class="refsect2" title="g_variant_byteswap ()">
2431 <a name="g-variant-byteswap"></a><h3>g_variant_byteswap ()</h3>
2432 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_byteswap                  (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
2433 <p>
2434 Performs a byteswapping operation on the contents of <em class="parameter"><code>value</code></em>.  The
2435 result is that all multi-byte numeric data contained in <em class="parameter"><code>value</code></em> is
2436 byteswapped.  That includes 16, 32, and 64bit signed and unsigned
2437 integers as well as file handles and double precision floating point
2438 values.
2439 </p>
2440 <p>
2441 This function is an identity mapping on any value that does not
2442 contain multi-byte numeric data.  That include strings, booleans,
2443 bytes and containers containing only these things (recursively).
2444 </p>
2445 <p>
2446 The returned value is always in normal form and is marked as trusted.</p>
2447 <div class="variablelist"><table border="0">
2448 <col align="left" valign="top">
2449 <tbody>
2450 <tr>
2451 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
2452 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
2453 </td>
2454 </tr>
2455 <tr>
2456 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2457 <td> the byteswapped form of <em class="parameter"><code>value</code></em>
2458 </td>
2459 </tr>
2460 </tbody>
2461 </table></div>
2462 <p class="since">Since 2.24</p>
2463 </div>
2464 <hr>
2465 <div class="refsect2" title="g_variant_get_normal_form ()">
2466 <a name="g-variant-get-normal-form"></a><h3>g_variant_get_normal_form ()</h3>
2467 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_get_normal_form           (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
2468 <p>
2469 Gets a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance that has the same value as <em class="parameter"><code>value</code></em> and is
2470 trusted to be in normal form.
2471 </p>
2472 <p>
2473 If <em class="parameter"><code>value</code></em> is already trusted to be in normal form then a new
2474 reference to <em class="parameter"><code>value</code></em> is returned.
2475 </p>
2476 <p>
2477 If <em class="parameter"><code>value</code></em> is not already trusted, then it is scanned to check if it
2478 is in normal form.  If it is found to be in normal form then it is
2479 marked as trusted and a new reference to it is returned.
2480 </p>
2481 <p>
2482 If <em class="parameter"><code>value</code></em> is found not to be in normal form then a new trusted
2483 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is created with the same value as <em class="parameter"><code>value</code></em>.
2484 </p>
2485 <p>
2486 It makes sense to call this function if you've received <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
2487 data from untrusted sources and you want to ensure your serialised
2488 output is definitely in normal form.</p>
2489 <div class="variablelist"><table border="0">
2490 <col align="left" valign="top">
2491 <tbody>
2492 <tr>
2493 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
2494 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
2495 </td>
2496 </tr>
2497 <tr>
2498 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2499 <td> a trusted <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
2500 </td>
2501 </tr>
2502 </tbody>
2503 </table></div>
2504 <p class="since">Since 2.24</p>
2505 </div>
2506 <hr>
2507 <div class="refsect2" title="g_variant_is_normal_form ()">
2508 <a name="g-variant-is-normal-form"></a><h3>g_variant_is_normal_form ()</h3>
2509 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_variant_is_normal_form            (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
2510 <p>
2511 Checks if <em class="parameter"><code>value</code></em> is in normal form.
2512 </p>
2513 <p>
2514 The main reason to do this is to detect if a given chunk of
2515 serialised data is in normal form: load the data into a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
2516 using <code class="function">g_variant_create_from_data()</code> and then use this function to
2517 check.
2518 </p>
2519 <p>
2520 If <em class="parameter"><code>value</code></em> is found to be in normal form then it will be marked as
2521 being trusted.  If the value was already marked as being trusted then
2522 this function will immediately return <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>.</p>
2523 <div class="variablelist"><table border="0">
2524 <col align="left" valign="top">
2525 <tbody>
2526 <tr>
2527 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
2528 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
2529 </td>
2530 </tr>
2531 <tr>
2532 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2533 <td> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>value</code></em> is in normal form
2534 </td>
2535 </tr>
2536 </tbody>
2537 </table></div>
2538 <p class="since">Since 2.24</p>
2539 </div>
2540 <hr>
2541 <div class="refsect2" title="g_variant_hash ()">
2542 <a name="g-variant-hash"></a><h3>g_variant_hash ()</h3>
2543 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               g_variant_hash                      (<a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="returnvalue">gconstpointer</span></a> value);</pre>
2544 <p>
2545 Generates a hash value for a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance.
2546 </p>
2547 <p>
2548 The output of this function is guaranteed to be the same for a given
2549 value only per-process.  It may change between different processor
2550 architectures or even different versions of GLib.  Do not use this
2551 function as a basis for building protocols or file formats.
2552 </p>
2553 <p>
2554 The type of <em class="parameter"><code>value</code></em> is <a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a> only to allow use of this
2555 function with <a class="link" href="glib-Hash-Tables.html#GHashTable" title="GHashTable"><span class="type">GHashTable</span></a>.  <em class="parameter"><code>value</code></em> must be a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>.</p>
2556 <div class="variablelist"><table border="0">
2557 <col align="left" valign="top">
2558 <tbody>
2559 <tr>
2560 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
2561 <td> a basic <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> value as a <a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a>
2562 </td>
2563 </tr>
2564 <tr>
2565 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2566 <td> a hash value corresponding to <em class="parameter"><code>value</code></em>
2567 </td>
2568 </tr>
2569 </tbody>
2570 </table></div>
2571 <p class="since">Since 2.24</p>
2572 </div>
2573 <hr>
2574 <div class="refsect2" title="g_variant_equal ()">
2575 <a name="g-variant-equal"></a><h3>g_variant_equal ()</h3>
2576 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_variant_equal                     (<a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="returnvalue">gconstpointer</span></a> one,
2577                                                          <a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="returnvalue">gconstpointer</span></a> two);</pre>
2578 <p>
2579 Checks if <em class="parameter"><code>one</code></em> and <em class="parameter"><code>two</code></em> have the same type and value.
2580 </p>
2581 <p>
2582 The types of <em class="parameter"><code>one</code></em> and <em class="parameter"><code>two</code></em> are <a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a> only to allow use of
2583 this function with <a class="link" href="glib-Hash-Tables.html#GHashTable" title="GHashTable"><span class="type">GHashTable</span></a>.  They must each be a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>.</p>
2584 <div class="variablelist"><table border="0">
2585 <col align="left" valign="top">
2586 <tbody>
2587 <tr>
2588 <td><p><span class="term"><em class="parameter"><code>one</code></em> :</span></p></td>
2589 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
2590 </td>
2591 </tr>
2592 <tr>
2593 <td><p><span class="term"><em class="parameter"><code>two</code></em> :</span></p></td>
2594 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
2595 </td>
2596 </tr>
2597 <tr>
2598 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2599 <td> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>one</code></em> and <em class="parameter"><code>two</code></em> are equal
2600 </td>
2601 </tr>
2602 </tbody>
2603 </table></div>
2604 <p class="since">Since 2.24</p>
2605 </div>
2606 <hr>
2607 <div class="refsect2" title="g_variant_print ()">
2608 <a name="g-variant-print"></a><h3>g_variant_print ()</h3>
2609 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_variant_print                     (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
2610                                                          <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> type_annotate);</pre>
2611 <p>
2612 Pretty-prints <em class="parameter"><code>value</code></em> in the format understood by <a class="link" href="glib-GVariant.html#g-variant-parse" title="g_variant_parse ()"><code class="function">g_variant_parse()</code></a>.
2613 </p>
2614 <p>
2615 If <em class="parameter"><code>type_annotate</code></em> is <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>, then type information is included in
2616 the output.</p>
2617 <div class="variablelist"><table border="0">
2618 <col align="left" valign="top">
2619 <tbody>
2620 <tr>
2621 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
2622 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
2623 </td>
2624 </tr>
2625 <tr>
2626 <td><p><span class="term"><em class="parameter"><code>type_annotate</code></em> :</span></p></td>
2627 <td> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if type information should be included in
2628                 the output
2629 </td>
2630 </tr>
2631 <tr>
2632 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2633 <td> a newly-allocated string holding the result.
2634 </td>
2635 </tr>
2636 </tbody>
2637 </table></div>
2638 </div>
2639 <hr>
2640 <div class="refsect2" title="g_variant_print_string ()">
2641 <a name="g-variant-print-string"></a><h3>g_variant_print_string ()</h3>
2642 <pre class="programlisting"><a class="link" href="glib-Strings.html#GString" title="GString"><span class="returnvalue">GString</span></a> *           g_variant_print_string              (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value,
2643                                                          <a class="link" href="glib-Strings.html#GString" title="GString"><span class="returnvalue">GString</span></a> *string,
2644                                                          <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> type_annotate);</pre>
2645 <p>
2646 Behaves as <a class="link" href="glib-GVariant.html#g-variant-print" title="g_variant_print ()"><code class="function">g_variant_print()</code></a>, but operates on a <a class="link" href="glib-Strings.html#GString" title="GString"><span class="type">GString</span></a>.
2647 </p>
2648 <p>
2649 If <em class="parameter"><code>string</code></em> is non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> then it is appended to and returned.  Else,
2650 a new empty <a class="link" href="glib-Strings.html#GString" title="GString"><span class="type">GString</span></a> is allocated and it is returned.</p>
2651 <div class="variablelist"><table border="0">
2652 <col align="left" valign="top">
2653 <tbody>
2654 <tr>
2655 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
2656 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
2657 </td>
2658 </tr>
2659 <tr>
2660 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
2661 <td> a <a class="link" href="glib-Strings.html#GString" title="GString"><span class="type">GString</span></a>, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
2662 </td>
2663 </tr>
2664 <tr>
2665 <td><p><span class="term"><em class="parameter"><code>type_annotate</code></em> :</span></p></td>
2666 <td> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if type information should be included in
2667                 the output
2668 </td>
2669 </tr>
2670 <tr>
2671 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2672 <td> a <a class="link" href="glib-Strings.html#GString" title="GString"><span class="type">GString</span></a> containing the string
2673 </td>
2674 </tr>
2675 </tbody>
2676 </table></div>
2677 <p class="since">Since 2.24</p>
2678 </div>
2679 <hr>
2680 <div class="refsect2" title="GVariantIter">
2681 <a name="GVariantIter"></a><h3>GVariantIter</h3>
2682 <pre class="programlisting">typedef struct {
2683 } GVariantIter;
2684 </pre>
2685 <p>
2686 <a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="type">GVariantIter</span></a> is an opaque data structure and can only be accessed
2687 using the following functions.</p>
2688 </div>
2689 <hr>
2690 <div class="refsect2" title="g_variant_iter_copy ()">
2691 <a name="g-variant-iter-copy"></a><h3>g_variant_iter_copy ()</h3>
2692 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="returnvalue">GVariantIter</span></a> *      g_variant_iter_copy                 (<a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="returnvalue">GVariantIter</span></a> *iter);</pre>
2693 <p>
2694 Creates a new heap-allocated <a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="type">GVariantIter</span></a> to iterate over the
2695 container that was being iterated over by <em class="parameter"><code>iter</code></em>.  Iteration begins on
2696 the new iterator from the current position of the old iterator but
2697 the two copies are independent past that point.
2698 </p>
2699 <p>
2700 Use <a class="link" href="glib-GVariant.html#g-variant-iter-free" title="g_variant_iter_free ()"><code class="function">g_variant_iter_free()</code></a> to free the return value when you no longer
2701 need it.
2702 </p>
2703 <p>
2704 A reference is taken to the container that <em class="parameter"><code>iter</code></em> is iterating over
2705 and will be releated only when <a class="link" href="glib-GVariant.html#g-variant-iter-free" title="g_variant_iter_free ()"><code class="function">g_variant_iter_free()</code></a> is called.</p>
2706 <div class="variablelist"><table border="0">
2707 <col align="left" valign="top">
2708 <tbody>
2709 <tr>
2710 <td><p><span class="term"><em class="parameter"><code>iter</code></em> :</span></p></td>
2711 <td> a <a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="type">GVariantIter</span></a>
2712 </td>
2713 </tr>
2714 <tr>
2715 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2716 <td> a new heap-allocated <a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="type">GVariantIter</span></a>
2717 </td>
2718 </tr>
2719 </tbody>
2720 </table></div>
2721 <p class="since">Since 2.24</p>
2722 </div>
2723 <hr>
2724 <div class="refsect2" title="g_variant_iter_free ()">
2725 <a name="g-variant-iter-free"></a><h3>g_variant_iter_free ()</h3>
2726 <pre class="programlisting"><span class="returnvalue">void</span>                g_variant_iter_free                 (<a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="returnvalue">GVariantIter</span></a> *iter);</pre>
2727 <p>
2728 Frees a heap-allocated <a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="type">GVariantIter</span></a>.  Only call this function on
2729 iterators that were returned by <a class="link" href="glib-GVariant.html#g-variant-iter-new" title="g_variant_iter_new ()"><code class="function">g_variant_iter_new()</code></a> or
2730 <a class="link" href="glib-GVariant.html#g-variant-iter-copy" title="g_variant_iter_copy ()"><code class="function">g_variant_iter_copy()</code></a>.</p>
2731 <div class="variablelist"><table border="0">
2732 <col align="left" valign="top">
2733 <tbody><tr>
2734 <td><p><span class="term"><em class="parameter"><code>iter</code></em> :</span></p></td>
2735 <td> a heap-allocated <a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="type">GVariantIter</span></a>
2736 </td>
2737 </tr></tbody>
2738 </table></div>
2739 <p class="since">Since 2.24</p>
2740 </div>
2741 <hr>
2742 <div class="refsect2" title="g_variant_iter_init ()">
2743 <a name="g-variant-iter-init"></a><h3>g_variant_iter_init ()</h3>
2744 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a>               g_variant_iter_init                 (<a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="returnvalue">GVariantIter</span></a> *iter,
2745                                                          <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
2746 <p>
2747 Initialises (without allocating) a <a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="type">GVariantIter</span></a>.  <em class="parameter"><code>iter</code></em> may be
2748 completely uninitialised prior to this call; its old value is
2749 ignored.
2750 </p>
2751 <p>
2752 The iterator remains valid for as long as <em class="parameter"><code>value</code></em> exists, and need not
2753 be freed in any way.</p>
2754 <div class="variablelist"><table border="0">
2755 <col align="left" valign="top">
2756 <tbody>
2757 <tr>
2758 <td><p><span class="term"><em class="parameter"><code>iter</code></em> :</span></p></td>
2759 <td> a pointer to a <a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="type">GVariantIter</span></a>
2760 </td>
2761 </tr>
2762 <tr>
2763 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
2764 <td> a container <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
2765 </td>
2766 </tr>
2767 <tr>
2768 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2769 <td> the number of items in <em class="parameter"><code>value</code></em>
2770 </td>
2771 </tr>
2772 </tbody>
2773 </table></div>
2774 <p class="since">Since 2.24</p>
2775 </div>
2776 <hr>
2777 <div class="refsect2" title="g_variant_iter_n_children ()">
2778 <a name="g-variant-iter-n-children"></a><h3>g_variant_iter_n_children ()</h3>
2779 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a>               g_variant_iter_n_children           (<a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="returnvalue">GVariantIter</span></a> *iter);</pre>
2780 <p>
2781 Queries the number of child items in the container that we are
2782 iterating over.  This is the total number of items -- not the number
2783 of items remaining.
2784 </p>
2785 <p>
2786 This function might be useful for preallocation of arrays.</p>
2787 <div class="variablelist"><table border="0">
2788 <col align="left" valign="top">
2789 <tbody>
2790 <tr>
2791 <td><p><span class="term"><em class="parameter"><code>iter</code></em> :</span></p></td>
2792 <td> a <a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="type">GVariantIter</span></a>
2793 </td>
2794 </tr>
2795 <tr>
2796 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2797 <td> the number of children in the container
2798 </td>
2799 </tr>
2800 </tbody>
2801 </table></div>
2802 <p class="since">Since 2.24</p>
2803 </div>
2804 <hr>
2805 <div class="refsect2" title="g_variant_iter_new ()">
2806 <a name="g-variant-iter-new"></a><h3>g_variant_iter_new ()</h3>
2807 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="returnvalue">GVariantIter</span></a> *      g_variant_iter_new                  (<a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
2808 <p>
2809 Creates a heap-allocated <a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="type">GVariantIter</span></a> for iterating over the items
2810 in <em class="parameter"><code>value</code></em>.
2811 </p>
2812 <p>
2813 Use <a class="link" href="glib-GVariant.html#g-variant-iter-free" title="g_variant_iter_free ()"><code class="function">g_variant_iter_free()</code></a> to free the return value when you no longer
2814 need it.
2815 </p>
2816 <p>
2817 A reference is taken to <em class="parameter"><code>value</code></em> and will be released only when
2818 <a class="link" href="glib-GVariant.html#g-variant-iter-free" title="g_variant_iter_free ()"><code class="function">g_variant_iter_free()</code></a> is called.</p>
2819 <div class="variablelist"><table border="0">
2820 <col align="left" valign="top">
2821 <tbody>
2822 <tr>
2823 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
2824 <td> a container <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
2825 </td>
2826 </tr>
2827 <tr>
2828 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2829 <td> a new heap-allocated <a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="type">GVariantIter</span></a>
2830 </td>
2831 </tr>
2832 </tbody>
2833 </table></div>
2834 <p class="since">Since 2.24</p>
2835 </div>
2836 <hr>
2837 <div class="refsect2" title="g_variant_iter_next_value ()">
2838 <a name="g-variant-iter-next-value"></a><h3>g_variant_iter_next_value ()</h3>
2839 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_iter_next_value           (<a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="returnvalue">GVariantIter</span></a> *iter);</pre>
2840 <p>
2841 Gets the next item in the container.  If no more items remain then
2842 <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> is returned.
2843 </p>
2844 <p>
2845 Use <a class="link" href="glib-GVariant.html#g-variant-unref" title="g_variant_unref ()"><code class="function">g_variant_unref()</code></a> to drop your reference on the return value when
2846 you no longer need it.
2847 </p>
2848 <p>
2849 </p>
2850 <div class="example">
2851 <a name="id850315"></a><p class="title"><b>Example 23. Iterating with <a class="link" href="glib-GVariant.html#g-variant-iter-next-value" title="g_variant_iter_next_value ()"><code class="function">g_variant_iter_next_value()</code></a></b></p>
2852 <div class="example-contents"><pre class="programlisting">
2853   /* recursively iterate a container */
2854   void
2855   iterate_container_recursive (GVariant *container)
2856   {
2857     GVariantIter iter;
2858     GVariant *child;
2859
2860     g_variant_iter_init (&amp;iter, dictionary);
2861     while ((child = g_variant_iter_next_value (&amp;iter)))
2862       {
2863         g_print ("type '%s'\n", g_variant_get_type_string (child));
2864
2865         if (g_variant_is_container (child))
2866           iterate_container_recursive (child);
2867
2868         g_variant_unref (child);
2869       }
2870   }
2871 </pre></div>
2872 </div>
2873 <p><br class="example-break"></p>
2874 <div class="variablelist"><table border="0">
2875 <col align="left" valign="top">
2876 <tbody>
2877 <tr>
2878 <td><p><span class="term"><em class="parameter"><code>iter</code></em> :</span></p></td>
2879 <td> a <a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="type">GVariantIter</span></a>
2880 </td>
2881 </tr>
2882 <tr>
2883 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2884 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
2885 </td>
2886 </tr>
2887 </tbody>
2888 </table></div>
2889 <p class="since">Since 2.24</p>
2890 </div>
2891 <hr>
2892 <div class="refsect2" title="g_variant_iter_next ()">
2893 <a name="g-variant-iter-next"></a><h3>g_variant_iter_next ()</h3>
2894 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_variant_iter_next                 (<a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="returnvalue">GVariantIter</span></a> *iter,
2895                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *format_string,
2896                                                          ...);</pre>
2897 <p>
2898 Gets the next item in the container and unpacks it into the variable
2899 argument list according to <em class="parameter"><code>format_string</code></em>, returning <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>.
2900 </p>
2901 <p>
2902 If no more items remain then <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> is returned.
2903 </p>
2904 <p>
2905 All of the pointers given on the variable arguments list of this
2906 function are assumed to point at uninitialised memory.  It is the
2907 responsibility of the caller to free all of the values returned by
2908 the unpacking process.
2909 </p>
2910 <p>
2911 </p>
2912 <div class="example">
2913 <a name="id850511"></a><p class="title"><b>Example 24. Memory management with <a class="link" href="glib-GVariant.html#g-variant-iter-next" title="g_variant_iter_next ()"><code class="function">g_variant_iter_next()</code></a></b></p>
2914 <div class="example-contents"><pre class="programlisting">
2915   /* Iterates a dictionary of type 'a{sv}' */
2916   void
2917   iterate_dictionary (GVariant *dictionary)
2918   {
2919     GVariantIter iter;
2920     GVariant *value;
2921     gchar *key;
2922
2923     g_variant_iter_init (&amp;iter, dictionary);
2924     while (g_variant_iter_next (&amp;iter, "{sv}", &amp;key, &amp;value))
2925       {
2926         g_print ("Item '%s' has type '%s'\n", key,
2927                  g_variant_get_type_string (value));
2928
2929         /* must free data for ourselves */
2930         g_variant_unref (value);
2931         g_free (key);
2932       }
2933   }
2934  </pre></div>
2935 </div>
2936 <p><br class="example-break">
2937 </p>
2938 <p>
2939 For a solution that is likely to be more convenient to C programmers
2940 when dealing with loops, see <a class="link" href="glib-GVariant.html#g-variant-iter-loop" title="g_variant_iter_loop ()"><code class="function">g_variant_iter_loop()</code></a>.</p>
2941 <div class="variablelist"><table border="0">
2942 <col align="left" valign="top">
2943 <tbody>
2944 <tr>
2945 <td><p><span class="term"><em class="parameter"><code>iter</code></em> :</span></p></td>
2946 <td> a <a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="type">GVariantIter</span></a>
2947 </td>
2948 </tr>
2949 <tr>
2950 <td><p><span class="term"><em class="parameter"><code>format_string</code></em> :</span></p></td>
2951 <td> a GVariant format string
2952 </td>
2953 </tr>
2954 <tr>
2955 <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
2956 <td> the arguments to unpack the value into
2957 </td>
2958 </tr>
2959 <tr>
2960 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2961 <td> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if a value was unpacked, or <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> if there as no
2962           value
2963 </td>
2964 </tr>
2965 </tbody>
2966 </table></div>
2967 <p class="since">Since 2.24</p>
2968 </div>
2969 <hr>
2970 <div class="refsect2" title="g_variant_iter_loop ()">
2971 <a name="g-variant-iter-loop"></a><h3>g_variant_iter_loop ()</h3>
2972 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_variant_iter_loop                 (<a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="returnvalue">GVariantIter</span></a> *iter,
2973                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *format_string,
2974                                                          ...);</pre>
2975 <p>
2976 Gets the next item in the container and unpacks it into the variable
2977 argument list according to <em class="parameter"><code>format_string</code></em>, returning <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>.
2978 </p>
2979 <p>
2980 If no more items remain then <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> is returned.
2981 </p>
2982 <p>
2983 On the first call to this function, the pointers appearing on the
2984 variable argument list are assumed to point at uninitialised memory.
2985 On the second and later calls, it is assumed that the same pointers
2986 will be given and that they will point to the memory as set by the
2987 previous call to this function.  This allows the previous values to
2988 be freed, as appropriate.
2989 </p>
2990 <p>
2991 This function is intended to be used with a while loop as
2992 demonstrated in the following example.  This function can only be
2993 used when iterating over an array.  It is only valid to call this
2994 function with a string constant for the format string and the same
2995 string constant must be used each time.  Mixing calls to this
2996 function and <a class="link" href="glib-GVariant.html#g-variant-iter-next" title="g_variant_iter_next ()"><code class="function">g_variant_iter_next()</code></a> or <a class="link" href="glib-GVariant.html#g-variant-iter-next-value" title="g_variant_iter_next_value ()"><code class="function">g_variant_iter_next_value()</code></a> on
2997 the same iterator is not recommended.
2998 </p>
2999 <p>
3000 </p>
3001 <div class="example">
3002 <a name="id850793"></a><p class="title"><b>Example 25. Memory management with <a class="link" href="glib-GVariant.html#g-variant-iter-loop" title="g_variant_iter_loop ()"><code class="function">g_variant_iter_loop()</code></a></b></p>
3003 <div class="example-contents"><pre class="programlisting">
3004   /* Iterates a dictionary of type 'a{sv}' */
3005   void
3006   iterate_dictionary (GVariant *dictionary)
3007   {
3008     GVariantIter iter;
3009     GVariant *value;
3010     gchar *key;
3011
3012     g_variant_iter_init (&amp;iter, dictionary);
3013     while (g_variant_iter_loop (&amp;iter, "{sv}", &amp;key, &amp;value))
3014       {
3015         g_print ("Item '%s' has type '%s'\n", key,
3016                  g_variant_get_type_string (value));
3017
3018         /* no need to free 'key' and 'value' here */
3019       }
3020   }
3021  </pre></div>
3022 </div>
3023 <p><br class="example-break">
3024 </p>
3025 <p>
3026 If you want a slightly less magical alternative that requires more
3027 typing, see <a class="link" href="glib-GVariant.html#g-variant-iter-next" title="g_variant_iter_next ()"><code class="function">g_variant_iter_next()</code></a>.</p>
3028 <div class="variablelist"><table border="0">
3029 <col align="left" valign="top">
3030 <tbody>
3031 <tr>
3032 <td><p><span class="term"><em class="parameter"><code>iter</code></em> :</span></p></td>
3033 <td> a <a class="link" href="glib-GVariant.html#GVariantIter" title="GVariantIter"><span class="type">GVariantIter</span></a>
3034 </td>
3035 </tr>
3036 <tr>
3037 <td><p><span class="term"><em class="parameter"><code>format_string</code></em> :</span></p></td>
3038 <td> a GVariant format string
3039 </td>
3040 </tr>
3041 <tr>
3042 <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
3043 <td> the arguments to unpack the value into
3044 </td>
3045 </tr>
3046 <tr>
3047 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
3048 <td> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if a value was unpacked, or <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> if there as no
3049           value
3050 </td>
3051 </tr>
3052 </tbody>
3053 </table></div>
3054 <p class="since">Since 2.24</p>
3055 </div>
3056 <hr>
3057 <div class="refsect2" title="GVariantBuilder">
3058 <a name="GVariantBuilder"></a><h3>GVariantBuilder</h3>
3059 <pre class="programlisting">typedef struct {
3060 } GVariantBuilder;
3061 </pre>
3062 <p>
3063 A utility type for constructing container-type <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instances.
3064 </p>
3065 <p>
3066 This is an opaque structure and may only be accessed using the
3067 following functions.
3068 </p>
3069 <p>
3070 <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a> is not threadsafe in any way.  Do not attempt to
3071 access it from more than one thread.</p>
3072 </div>
3073 <hr>
3074 <div class="refsect2" title="g_variant_builder_unref ()">
3075 <a name="g-variant-builder-unref"></a><h3>g_variant_builder_unref ()</h3>
3076 <pre class="programlisting"><span class="returnvalue">void</span>                g_variant_builder_unref             (<a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="returnvalue">GVariantBuilder</span></a> *builder);</pre>
3077 <p>
3078 Decreases the reference count on <em class="parameter"><code>builder</code></em>.
3079 </p>
3080 <p>
3081 In the event that there are no more references, releases all memory
3082 associated with the <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a>.
3083 </p>
3084 <p>
3085 Don't call this on stack-allocated <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a> instances or bad
3086 things will happen.</p>
3087 <div class="variablelist"><table border="0">
3088 <col align="left" valign="top">
3089 <tbody><tr>
3090 <td><p><span class="term"><em class="parameter"><code>builder</code></em> :</span></p></td>
3091 <td> a <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a> allocated by <a class="link" href="glib-GVariant.html#g-variant-builder-new" title="g_variant_builder_new ()"><code class="function">g_variant_builder_new()</code></a>
3092 </td>
3093 </tr></tbody>
3094 </table></div>
3095 <p class="since">Since 2.24</p>
3096 </div>
3097 <hr>
3098 <div class="refsect2" title="g_variant_builder_ref ()">
3099 <a name="g-variant-builder-ref"></a><h3>g_variant_builder_ref ()</h3>
3100 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="returnvalue">GVariantBuilder</span></a> *   g_variant_builder_ref               (<a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="returnvalue">GVariantBuilder</span></a> *builder);</pre>
3101 <p>
3102 Increases the reference count on <em class="parameter"><code>builder</code></em>.
3103 </p>
3104 <p>
3105 Don't call this on stack-allocated <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a> instances or bad
3106 things will happen.</p>
3107 <div class="variablelist"><table border="0">
3108 <col align="left" valign="top">
3109 <tbody>
3110 <tr>
3111 <td><p><span class="term"><em class="parameter"><code>builder</code></em> :</span></p></td>
3112 <td> a <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a> allocated by <a class="link" href="glib-GVariant.html#g-variant-builder-new" title="g_variant_builder_new ()"><code class="function">g_variant_builder_new()</code></a>
3113 </td>
3114 </tr>
3115 <tr>
3116 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
3117 <td> a new reference to <em class="parameter"><code>builder</code></em>
3118 </td>
3119 </tr>
3120 </tbody>
3121 </table></div>
3122 <p class="since">Since 2.24</p>
3123 </div>
3124 <hr>
3125 <div class="refsect2" title="g_variant_builder_new ()">
3126 <a name="g-variant-builder-new"></a><h3>g_variant_builder_new ()</h3>
3127 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="returnvalue">GVariantBuilder</span></a> *   g_variant_builder_new               (const <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="returnvalue">GVariantType</span></a> *type);</pre>
3128 <p>
3129 Allocates and initialises a new <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a>.
3130 </p>
3131 <p>
3132 You should call <a class="link" href="glib-GVariant.html#g-variant-builder-unref" title="g_variant_builder_unref ()"><code class="function">g_variant_builder_unref()</code></a> on the return value when it
3133 is no longer needed.  The memory will not be automatically freed by
3134 any other call.
3135 </p>
3136 <p>
3137 In most cases it is easier to place a <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a> directly on
3138 the stack of the calling function and initialise it with
3139 <a class="link" href="glib-GVariant.html#g-variant-builder-init" title="g_variant_builder_init ()"><code class="function">g_variant_builder_init()</code></a>.</p>
3140 <div class="variablelist"><table border="0">
3141 <col align="left" valign="top">
3142 <tbody>
3143 <tr>
3144 <td><p><span class="term"><em class="parameter"><code>type</code></em> :</span></p></td>
3145 <td> a container type
3146 </td>
3147 </tr>
3148 <tr>
3149 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
3150 <td> a <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a>
3151 </td>
3152 </tr>
3153 </tbody>
3154 </table></div>
3155 <p class="since">Since 2.24</p>
3156 </div>
3157 <hr>
3158 <div class="refsect2" title="g_variant_builder_init ()">
3159 <a name="g-variant-builder-init"></a><h3>g_variant_builder_init ()</h3>
3160 <pre class="programlisting"><span class="returnvalue">void</span>                g_variant_builder_init              (<a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="returnvalue">GVariantBuilder</span></a> *builder,
3161                                                          const <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="returnvalue">GVariantType</span></a> *type);</pre>
3162 <p>
3163 Initialises a <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a> structure.
3164 </p>
3165 <p>
3166 <em class="parameter"><code>type</code></em> must be non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.  It specifies the type of container to
3167 construct.  It can be an indefinite type such as
3168 <a class="link" href="glib-GVariantType.html#G-VARIANT-TYPE-ARRAY:CAPS" title="G_VARIANT_TYPE_ARRAY"><code class="literal">G_VARIANT_TYPE_ARRAY</code></a> or a definite type such as "as" or "(ii)".
3169 Maybe, array, tuple, dictionary entry and variant-typed values may be
3170 constructed.
3171 </p>
3172 <p>
3173 After the builder is initialised, values are added using
3174 <a class="link" href="glib-GVariant.html#g-variant-builder-add-value" title="g_variant_builder_add_value ()"><code class="function">g_variant_builder_add_value()</code></a> or <a class="link" href="glib-GVariant.html#g-variant-builder-add" title="g_variant_builder_add ()"><code class="function">g_variant_builder_add()</code></a>.
3175 </p>
3176 <p>
3177 After all the child values are added, <a class="link" href="glib-GVariant.html#g-variant-builder-end" title="g_variant_builder_end ()"><code class="function">g_variant_builder_end()</code></a> frees
3178 the memory associated with the builder and returns the <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> that
3179 was created.
3180 </p>
3181 <p>
3182 This function completely ignores the previous contents of <em class="parameter"><code>builder</code></em>.
3183 On one hand this means that it is valid to pass in completely
3184 uninitialised memory.  On the other hand, this means that if you are
3185 initialising over top of an existing <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a> you need to
3186 first call <a class="link" href="glib-GVariant.html#g-variant-builder-clear" title="g_variant_builder_clear ()"><code class="function">g_variant_builder_clear()</code></a> in order to avoid leaking
3187 memory.
3188 </p>
3189 <p>
3190 You must not call <a class="link" href="glib-GVariant.html#g-variant-builder-ref" title="g_variant_builder_ref ()"><code class="function">g_variant_builder_ref()</code></a> or
3191 <a class="link" href="glib-GVariant.html#g-variant-builder-unref" title="g_variant_builder_unref ()"><code class="function">g_variant_builder_unref()</code></a> on a <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a> that was initialised
3192 with this function.  If you ever pass a reference to a
3193 <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a> outside of the control of your own code then you
3194 should assume that the person receiving that reference may try to use
3195 reference counting; you should use <a class="link" href="glib-GVariant.html#g-variant-builder-new" title="g_variant_builder_new ()"><code class="function">g_variant_builder_new()</code></a> instead of
3196 this function.</p>
3197 <div class="variablelist"><table border="0">
3198 <col align="left" valign="top">
3199 <tbody>
3200 <tr>
3201 <td><p><span class="term"><em class="parameter"><code>builder</code></em> :</span></p></td>
3202 <td> a <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a>
3203 </td>
3204 </tr>
3205 <tr>
3206 <td><p><span class="term"><em class="parameter"><code>type</code></em> :</span></p></td>
3207 <td> a container type
3208 </td>
3209 </tr>
3210 </tbody>
3211 </table></div>
3212 <p class="since">Since 2.24</p>
3213 </div>
3214 <hr>
3215 <div class="refsect2" title="g_variant_builder_clear ()">
3216 <a name="g-variant-builder-clear"></a><h3>g_variant_builder_clear ()</h3>
3217 <pre class="programlisting"><span class="returnvalue">void</span>                g_variant_builder_clear             (<a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="returnvalue">GVariantBuilder</span></a> *builder);</pre>
3218 <p>
3219 Releases all memory associated with a <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a> without
3220 freeing the <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a> structure itself.
3221 </p>
3222 <p>
3223 It typically only makes sense to do this on a stack-allocated
3224 <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a> if you want to abort building the value part-way
3225 through.  This function need not be called if you call
3226 <a class="link" href="glib-GVariant.html#g-variant-builder-end" title="g_variant_builder_end ()"><code class="function">g_variant_builder_end()</code></a> and it also doesn't need to be called on
3227 builders allocated with g_variant_builder_new (see
3228 <code class="function">g_variant_builder_free()</code> for that).
3229 </p>
3230 <p>
3231 This function leaves the <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a> structure set to all-zeros.
3232 It is valid to call this function on either an initialised
3233 <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a> or one that is set to all-zeros but it is not valid
3234 to call this function on uninitialised memory.</p>
3235 <div class="variablelist"><table border="0">
3236 <col align="left" valign="top">
3237 <tbody><tr>
3238 <td><p><span class="term"><em class="parameter"><code>builder</code></em> :</span></p></td>
3239 <td> a <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a>
3240 </td>
3241 </tr></tbody>
3242 </table></div>
3243 <p class="since">Since 2.24</p>
3244 </div>
3245 <hr>
3246 <div class="refsect2" title="g_variant_builder_add_value ()">
3247 <a name="g-variant-builder-add-value"></a><h3>g_variant_builder_add_value ()</h3>
3248 <pre class="programlisting"><span class="returnvalue">void</span>                g_variant_builder_add_value         (<a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="returnvalue">GVariantBuilder</span></a> *builder,
3249                                                          <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *value);</pre>
3250 <p>
3251 Adds <em class="parameter"><code>value</code></em> to <em class="parameter"><code>builder</code></em>.
3252 </p>
3253 <p>
3254 It is an error to call this function in any way that would create an
3255 inconsistent value to be constructed.  Some examples of this are
3256 putting different types of items into an array, putting the wrong
3257 types or number of items in a tuple, putting more than one value into
3258 a variant, etc.</p>
3259 <div class="variablelist"><table border="0">
3260 <col align="left" valign="top">
3261 <tbody>
3262 <tr>
3263 <td><p><span class="term"><em class="parameter"><code>builder</code></em> :</span></p></td>
3264 <td> a <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a>
3265 </td>
3266 </tr>
3267 <tr>
3268 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
3269 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
3270 </td>
3271 </tr>
3272 </tbody>
3273 </table></div>
3274 <p class="since">Since 2.24</p>
3275 </div>
3276 <hr>
3277 <div class="refsect2" title="g_variant_builder_add ()">
3278 <a name="g-variant-builder-add"></a><h3>g_variant_builder_add ()</h3>
3279 <pre class="programlisting"><span class="returnvalue">void</span>                g_variant_builder_add               (<a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="returnvalue">GVariantBuilder</span></a> *builder,
3280                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *format_string,
3281                                                          ...);</pre>
3282 <p>
3283 Adds to a <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a>.
3284 </p>
3285 <p>
3286 This call is a convenience wrapper that is exactly equivalent to
3287 calling <a class="link" href="glib-GVariant.html#g-variant-new" title="g_variant_new ()"><code class="function">g_variant_new()</code></a> followed by <a class="link" href="glib-GVariant.html#g-variant-builder-add-value" title="g_variant_builder_add_value ()"><code class="function">g_variant_builder_add_value()</code></a>.
3288 </p>
3289 <p>
3290 This function might be used as follows:
3291 </p>
3292 <p>
3293 </p>
3294 <pre class="programlisting">
3295 GVariant *
3296 make_pointless_dictionary (void)
3297 {
3298   GVariantBuilder *builder;
3299   int i;
3300
3301   builder = g_variant_builder_new (G_VARIANT_TYPE_CLASS_ARRAY,
3302                                    NULL);
3303   for (i = 0; i &lt; 16; i++)
3304     {
3305       gchar buf[3];
3306
3307       sprintf (buf, "%d", i);
3308       g_variant_builder_add (builder, "{is}", i, buf);
3309     }
3310
3311   return g_variant_builder_end (builder);
3312 }
3313 </pre>
3314 <div class="variablelist"><table border="0">
3315 <col align="left" valign="top">
3316 <tbody>
3317 <tr>
3318 <td><p><span class="term"><em class="parameter"><code>builder</code></em> :</span></p></td>
3319 <td> a <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a>
3320 </td>
3321 </tr>
3322 <tr>
3323 <td><p><span class="term"><em class="parameter"><code>format_string</code></em> :</span></p></td>
3324 <td> a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> varargs format string
3325 </td>
3326 </tr>
3327 <tr>
3328 <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
3329 <td> arguments, as per <em class="parameter"><code>format_string</code></em>
3330 </td>
3331 </tr>
3332 </tbody>
3333 </table></div>
3334 <p class="since">Since 2.24</p>
3335 </div>
3336 <hr>
3337 <div class="refsect2" title="g_variant_builder_end ()">
3338 <a name="g-variant-builder-end"></a><h3>g_variant_builder_end ()</h3>
3339 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_builder_end               (<a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="returnvalue">GVariantBuilder</span></a> *builder);</pre>
3340 <p>
3341 Ends the builder process and returns the constructed value.
3342 </p>
3343 <p>
3344 This call automatically reduces the reference count on <em class="parameter"><code>builder</code></em> by
3345 one, unless it has previously had <code class="function">g_variant_builder_no_autofree()</code>
3346 called on it.  Unless you've taken other actions, this is usually
3347 sufficient to free <em class="parameter"><code>builder</code></em>.
3348 </p>
3349 <p>
3350 Even if additional references are held, it is not permissible to use
3351 <em class="parameter"><code>builder</code></em> in any way after this call except for further reference
3352 counting operations.
3353 </p>
3354 <p>
3355 It is an error to call this function in any way that would create an
3356 inconsistent value to be constructed (ie: insufficient number of
3357 items added to a container with a specific number of children
3358 required).  It is also an error to call this function if the builder
3359 was created with an indefinite array or maybe type and no children
3360 have been added; in this case it is impossible to infer the type of
3361 the empty array.</p>
3362 <div class="variablelist"><table border="0">
3363 <col align="left" valign="top">
3364 <tbody>
3365 <tr>
3366 <td><p><span class="term"><em class="parameter"><code>builder</code></em> :</span></p></td>
3367 <td> a <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a>
3368 </td>
3369 </tr>
3370 <tr>
3371 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
3372 <td> a new, floating, <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
3373 </td>
3374 </tr>
3375 </tbody>
3376 </table></div>
3377 <p class="since">Since 2.24</p>
3378 </div>
3379 <hr>
3380 <div class="refsect2" title="g_variant_builder_open ()">
3381 <a name="g-variant-builder-open"></a><h3>g_variant_builder_open ()</h3>
3382 <pre class="programlisting"><span class="returnvalue">void</span>                g_variant_builder_open              (<a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="returnvalue">GVariantBuilder</span></a> *builder,
3383                                                          const <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="returnvalue">GVariantType</span></a> *type);</pre>
3384 <p>
3385 Opens a subcontainer inside the given <em class="parameter"><code>builder</code></em>.  When done adding
3386 items to the subcontainer, <a class="link" href="glib-GVariant.html#g-variant-builder-close" title="g_variant_builder_close ()"><code class="function">g_variant_builder_close()</code></a> must be called.
3387 </p>
3388 <p>
3389 It is an error to call this function in any way that would cause an
3390 inconsistent value to be constructed (ie: adding too many values or
3391 a value of an incorrect type).</p>
3392 <div class="variablelist"><table border="0">
3393 <col align="left" valign="top">
3394 <tbody>
3395 <tr>
3396 <td><p><span class="term"><em class="parameter"><code>builder</code></em> :</span></p></td>
3397 <td> a <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a>
3398 </td>
3399 </tr>
3400 <tr>
3401 <td><p><span class="term"><em class="parameter"><code>type</code></em> :</span></p></td>
3402 <td> a <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="type">GVariantType</span></a>
3403 </td>
3404 </tr>
3405 </tbody>
3406 </table></div>
3407 <p class="since">Since 2.24</p>
3408 </div>
3409 <hr>
3410 <div class="refsect2" title="g_variant_builder_close ()">
3411 <a name="g-variant-builder-close"></a><h3>g_variant_builder_close ()</h3>
3412 <pre class="programlisting"><span class="returnvalue">void</span>                g_variant_builder_close             (<a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="returnvalue">GVariantBuilder</span></a> *builder);</pre>
3413 <p>
3414 Closes the subcontainer inside the given <em class="parameter"><code>builder</code></em> that was opened by
3415 the most recent call to <a class="link" href="glib-GVariant.html#g-variant-builder-open" title="g_variant_builder_open ()"><code class="function">g_variant_builder_open()</code></a>.
3416 </p>
3417 <p>
3418 It is an error to call this function in any way that would create an
3419 inconsistent value to be constructed (ie: too few values added to the
3420 subcontainer).</p>
3421 <div class="variablelist"><table border="0">
3422 <col align="left" valign="top">
3423 <tbody><tr>
3424 <td><p><span class="term"><em class="parameter"><code>builder</code></em> :</span></p></td>
3425 <td> a <a class="link" href="glib-GVariant.html#GVariantBuilder" title="GVariantBuilder"><span class="type">GVariantBuilder</span></a>
3426 </td>
3427 </tr></tbody>
3428 </table></div>
3429 <p class="since">Since 2.24</p>
3430 </div>
3431 <hr>
3432 <div class="refsect2" title="G_VARIANT_PARSE_ERROR">
3433 <a name="G-VARIANT-PARSE-ERROR:CAPS"></a><h3>G_VARIANT_PARSE_ERROR</h3>
3434 <pre class="programlisting">#define G_VARIANT_PARSE_ERROR (g_variant_parser_get_error_quark ())
3435 </pre>
3436 <p>
3437 Error domain for GVariant text format parsing.  Specific error codes
3438 are not currently defined for this domain.  See <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> for
3439 information on error domains.</p>
3440 </div>
3441 <hr>
3442 <div class="refsect2" title="g_variant_parse ()">
3443 <a name="g-variant-parse"></a><h3>g_variant_parse ()</h3>
3444 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_parse                     (const <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="returnvalue">GVariantType</span></a> *type,
3445                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *text,
3446                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *limit,
3447                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **endptr,
3448                                                          <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="returnvalue">GError</span></a> **error);</pre>
3449 <p>
3450 Parses a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> from a text representation.
3451 </p>
3452 <p>
3453 A single <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> is parsed from the content of <em class="parameter"><code>text</code></em>.
3454 </p>
3455 <p>
3456 The memory at <em class="parameter"><code>limit</code></em> will never be accessed and the parser behaves as
3457 if the character at <em class="parameter"><code>limit</code></em> is the nul terminator.  This has the
3458 effect of bounding <em class="parameter"><code>text</code></em>.
3459 </p>
3460 <p>
3461 If <em class="parameter"><code>endptr</code></em> is non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> then <em class="parameter"><code>text</code></em> is permitted to contain data
3462 following the value that this function parses and <em class="parameter"><code>endptr</code></em> will be
3463 updated to point to the first character past the end of the text
3464 parsed by this function.  If <em class="parameter"><code>endptr</code></em> is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> and there is extra data
3465 then an error is returned.
3466 </p>
3467 <p>
3468 If <em class="parameter"><code>type</code></em> is non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> then the value will be parsed to have that
3469 type.  This may result in additional parse errors (in the case that
3470 the parsed value doesn't fit the type) but may also result in fewer
3471 errors (in the case that the type would have been ambiguous, such as
3472 with empty arrays).
3473 </p>
3474 <p>
3475 In the event that the parsing is successful, the resulting <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
3476 is returned.
3477 </p>
3478 <p>
3479 In case of any error, <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> will be returned.  If <em class="parameter"><code>error</code></em> is non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
3480 then it will be set to reflect the error that occured.
3481 </p>
3482 <p>
3483 Officially, the language understood by the parser is "any string
3484 produced by <a class="link" href="glib-GVariant.html#g-variant-print" title="g_variant_print ()"><code class="function">g_variant_print()</code></a>".</p>
3485 <div class="variablelist"><table border="0">
3486 <col align="left" valign="top">
3487 <tbody>
3488 <tr>
3489 <td><p><span class="term"><em class="parameter"><code>type</code></em> :</span></p></td>
3490 <td> a <a class="link" href="glib-GVariantType.html#GVariantType" title="GVariantType"><span class="type">GVariantType</span></a>, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
3491 </td>
3492 </tr>
3493 <tr>
3494 <td><p><span class="term"><em class="parameter"><code>text</code></em> :</span></p></td>
3495 <td> a string containing a GVariant in text form
3496 </td>
3497 </tr>
3498 <tr>
3499 <td><p><span class="term"><em class="parameter"><code>limit</code></em> :</span></p></td>
3500 <td> a pointer to the end of <em class="parameter"><code>text</code></em>, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
3501 </td>
3502 </tr>
3503 <tr>
3504 <td><p><span class="term"><em class="parameter"><code>endptr</code></em> :</span></p></td>
3505 <td> a location to store the end pointer, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
3506 </td>
3507 </tr>
3508 <tr>
3509 <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
3510 <td> a pointer to a <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> pointer, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
3511 </td>
3512 </tr>
3513 <tr>
3514 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
3515 <td> a reference to a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
3516 </td>
3517 </tr>
3518 </tbody>
3519 </table></div>
3520 </div>
3521 <hr>
3522 <div class="refsect2" title="g_variant_new_parsed_va ()">
3523 <a name="g-variant-new-parsed-va"></a><h3>g_variant_new_parsed_va ()</h3>
3524 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new_parsed_va             (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *format,
3525                                                          <span class="returnvalue">va_list</span> *app);</pre>
3526 <p>
3527 Parses <em class="parameter"><code>format</code></em> and returns the result.
3528 </p>
3529 <p>
3530 This is the version of <a class="link" href="glib-GVariant.html#g-variant-new-parsed" title="g_variant_new_parsed ()"><code class="function">g_variant_new_parsed()</code></a> intended to be used
3531 from libraries.
3532 </p>
3533 <p>
3534 The return value will be floating if it was a newly created GVariant
3535 instance.  In the case that <em class="parameter"><code>format</code></em> simply specified the collection
3536 of a <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> pointer (eg: <em class="parameter"><code>format</code></em> was "%*") then the collected
3537 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> pointer will be returned unmodified, without adding any
3538 additional references.
3539 </p>
3540 <p>
3541 In order to behave correctly in all cases it is necessary for the
3542 calling function to <a class="link" href="glib-GVariant.html#g-variant-ref-sink" title="g_variant_ref_sink ()"><code class="function">g_variant_ref_sink()</code></a> the return result before
3543 returning control to the user that originally provided the pointer.
3544 At this point, the caller will have their own full reference to the
3545 result.  This can also be done by adding the result to a container,
3546 or by passing it to another <a class="link" href="glib-GVariant.html#g-variant-new" title="g_variant_new ()"><code class="function">g_variant_new()</code></a> call.</p>
3547 <div class="variablelist"><table border="0">
3548 <col align="left" valign="top">
3549 <tbody>
3550 <tr>
3551 <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
3552 <td> a text format <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
3553 </td>
3554 </tr>
3555 <tr>
3556 <td><p><span class="term"><em class="parameter"><code>app</code></em> :</span></p></td>
3557 <td> a pointer to a <span class="type">va_list</span>
3558 </td>
3559 </tr>
3560 <tr>
3561 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
3562 <td> a new, usually floating, <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
3563 </td>
3564 </tr>
3565 </tbody>
3566 </table></div>
3567 </div>
3568 <hr>
3569 <div class="refsect2" title="g_variant_new_parsed ()">
3570 <a name="g-variant-new-parsed"></a><h3>g_variant_new_parsed ()</h3>
3571 <pre class="programlisting"><a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="returnvalue">GVariant</span></a> *          g_variant_new_parsed                (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *format,
3572                                                          ...);</pre>
3573 <p>
3574 Parses <em class="parameter"><code>format</code></em> and returns the result.
3575 </p>
3576 <p>
3577 <em class="parameter"><code>format</code></em> must be a text format <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> with one extention: at any
3578 point that a value may appear in the text, a '%' character followed
3579 by a GVariant format string (as per <a class="link" href="glib-GVariant.html#g-variant-new" title="g_variant_new ()"><code class="function">g_variant_new()</code></a>) may appear.  In
3580 that case, the same arguments are collected from the argument list as
3581 <a class="link" href="glib-GVariant.html#g-variant-new" title="g_variant_new ()"><code class="function">g_variant_new()</code></a> would have collected.
3582 </p>
3583 <p>
3584 Consider this simple example:
3585 </p>
3586 <p>
3587 </p>
3588 <div class="informalexample"><pre class="programlisting">
3589  g_variant_new_parsed ("[('one', 1), ('two', %i), (%s, 3)]", 2, "three");
3590 </pre></div>
3591 <p>
3592 </p>
3593 <p>
3594 In the example, the variable argument parameters are collected and
3595 filled in as if they were part of the original string to produce the
3596 result of <code class="code">[('one', 1), ('two', 2), ('three', 3)]</code>.
3597 </p>
3598 <p>
3599 This function is intended only to be used with <em class="parameter"><code>format</code></em> as a string
3600 literal.  Any parse error is fatal to the calling process.  If you
3601 want to parse data from untrusted sources, use <a class="link" href="glib-GVariant.html#g-variant-parse" title="g_variant_parse ()"><code class="function">g_variant_parse()</code></a>.
3602 </p>
3603 <p>
3604 You may not use this function to return, unmodified, a single
3605 <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> pointer from the argument list.  ie: <em class="parameter"><code>format</code></em> may not solely
3606 be anything along the lines of "%*", "%?", "<code class="literal">r</code>", or anything starting
3607 with "%@".</p>
3608 <div class="variablelist"><table border="0">
3609 <col align="left" valign="top">
3610 <tbody>
3611 <tr>
3612 <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
3613 <td> a text format <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a>
3614 </td>
3615 </tr>
3616 <tr>
3617 <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
3618 <td> arguments as per <em class="parameter"><code>format</code></em>
3619 </td>
3620 </tr>
3621 <tr>
3622 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
3623 <td> a new floating <a class="link" href="glib-GVariant.html#GVariant" title="GVariant"><span class="type">GVariant</span></a> instance
3624 </td>
3625 </tr>
3626 </tbody>
3627 </table></div>
3628 </div>
3629 </div>
3630 <div class="refsect1" title="See Also">
3631 <a name="glib-GVariant.see-also"></a><h2>See Also</h2>
3632 GVariantType
3633 </div>
3634 </div>
3635 <div class="footer">
3636 <hr>
3637           Generated by GTK-Doc V1.13</div>
3638 </body>
3639 </html>