doc/reference/html/json-glib-JSON-GVariant-Integration.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>JSON GVariant Integration: JSON-GLib Reference Manual</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="index.html" title="JSON-GLib Reference Manual">
   8 <link rel="up" href="json-advanced.html" title="Part IV. JSON-GLib Advanced API">
   9 <link rel="prev" href="json-glib-Boxed-Types-Serialization.html" title="Boxed Types Serialization">
  10 <link rel="next" href="json-glib-Versioning-information.html" title="Versioning information">
  11 <meta name="generator" content="GTK-Doc V1.25.1 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
  16 <td width="100%" align="left" class="shortcuts">
  17 <a href="#" class="shortcut">Top</a><span id="nav_description">  <span class="dim">|</span>
  18                   <a href="#json-glib-JSON-GVariant-Integration.description" class="shortcut">Description</a></span>
  19 </td>
  20 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
  21 <td><a accesskey="u" href="json-advanced.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  22 <td><a accesskey="p" href="json-glib-Boxed-Types-Serialization.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  23 <td><a accesskey="n" href="json-glib-Versioning-information.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
  24 </tr></table>
  25 <div class="refentry">
  26 <a name="json-glib-JSON-GVariant-Integration"></a><div class="titlepage"></div>
  27 <div class="refnamediv"><table width="100%"><tr>
  28 <td valign="top">
  29 <h2><span class="refentrytitle"><a name="json-glib-JSON-GVariant-Integration.top_of_page"></a>JSON GVariant Integration</span></h2>
  30 <p>JSON GVariant Integration — Serialize and deserialize GVariant types</p>
  31 </td>
  32 <td class="gallery_image" valign="top" align="right"></td>
  33 </tr></table></div>
  34 <div class="refsect1">
  35 <a name="json-glib-JSON-GVariant-Integration.functions"></a><h2>Functions</h2>
  36 <div class="informaltable"><table class="informaltable" width="100%" border="0">
  37 <colgroup>
  38 <col width="150px" class="functions_return">
  39 <col class="functions_name">
  40 </colgroup>
  41 <tbody>
  42 <tr>
  43 <td class="function_type">
  44 <a class="link" href="json-glib-JSON-Node.html#JsonNode"><span class="returnvalue">JsonNode</span></a> *
  45 </td>
  46 <td class="function_name">
  47 <a class="link" href="json-glib-JSON-GVariant-Integration.html#json-gvariant-serialize" title="json_gvariant_serialize ()">json_gvariant_serialize</a> <span class="c_punctuation">()</span>
  48 </td>
  49 </tr>
  50 <tr>
  51 <td class="function_type">
  52 <span class="returnvalue">gchar</span> *
  53 </td>
  54 <td class="function_name">
  55 <a class="link" href="json-glib-JSON-GVariant-Integration.html#json-gvariant-serialize-data" title="json_gvariant_serialize_data ()">json_gvariant_serialize_data</a> <span class="c_punctuation">()</span>
  56 </td>
  57 </tr>
  58 <tr>
  59 <td class="function_type">
  60 <span class="returnvalue">GVariant</span> *
  61 </td>
  62 <td class="function_name">
  63 <a class="link" href="json-glib-JSON-GVariant-Integration.html#json-gvariant-deserialize" title="json_gvariant_deserialize ()">json_gvariant_deserialize</a> <span class="c_punctuation">()</span>
  64 </td>
  65 </tr>
  66 <tr>
  67 <td class="function_type">
  68 <span class="returnvalue">GVariant</span> *
  69 </td>
  70 <td class="function_name">
  71 <a class="link" href="json-glib-JSON-GVariant-Integration.html#json-gvariant-deserialize-data" title="json_gvariant_deserialize_data ()">json_gvariant_deserialize_data</a> <span class="c_punctuation">()</span>
  72 </td>
  73 </tr>
  74 </tbody>
  75 </table></div>
  76 </div>
  77 <div class="refsect1">
  78 <a name="json-glib-JSON-GVariant-Integration.description"></a><h2>Description</h2>
  79 <p>Use <a class="link" href="json-glib-JSON-GVariant-Integration.html#json-gvariant-serialize" title="json_gvariant_serialize ()"><code class="function">json_gvariant_serialize()</code></a> and <a class="link" href="json-glib-JSON-GVariant-Integration.html#json-gvariant-serialize-data" title="json_gvariant_serialize_data ()"><code class="function">json_gvariant_serialize_data()</code></a> to
  80 convert from any <span class="type">GVariant</span> value to a <a class="link" href="json-glib-JSON-Node.html#JsonNode"><span class="type">JsonNode</span></a> tree or its string
  81 representation.</p>
  82 <p>Use <a class="link" href="json-glib-JSON-GVariant-Integration.html#json-gvariant-deserialize" title="json_gvariant_deserialize ()"><code class="function">json_gvariant_deserialize()</code></a> and <a class="link" href="json-glib-JSON-GVariant-Integration.html#json-gvariant-deserialize-data" title="json_gvariant_deserialize_data ()"><code class="function">json_gvariant_deserialize_data()</code></a> to
  83 obtain the <span class="type">GVariant</span> value from a <a class="link" href="json-glib-JSON-Node.html#JsonNode"><span class="type">JsonNode</span></a> tree or directly from a JSON
  84 string.</p>
  85 <p>Since many <span class="type">GVariant</span> data types cannot be directly represented as
  86 JSON, a <span class="type">GVariant</span> type string (signature) should be provided to these
  87 methods in order to obtain a correct, type-contrained result.
  88 If no signature is provided, conversion can still be done, but the
  89 resulting <span class="type">GVariant</span> value will be "guessed" from the JSON data types
  90 using the following rules:</p>
  91 <div class="refsect3">
  92 <a name="id-1.5.5.4.5"></a><h4>Strings</h4>
  93 <p>JSON strings map to GVariant <code class="literal">(s)</code>.</p>
  94 </div>
  95 <div class="refsect3">
  96 <a name="id-1.5.5.4.6"></a><h4>Integers</h4>
  97 <p>JSON integers map to GVariant int64 <code class="literal">(x)</code>.</p>
  98 </div>
  99 <div class="refsect3">
 100 <a name="id-1.5.5.4.7"></a><h4>Booleans</h4>
 101 <p>JSON booleans map to GVariant boolean <code class="literal">(b)</code>.</p>
 102 </div>
 103 <div class="refsect3">
 104 <a name="id-1.5.5.4.8"></a><h4>Numbers</h4>
 105 <p>JSON numbers map to GVariant double <code class="literal">(d)</code>.</p>
 106 </div>
 107 <div class="refsect3">
 108 <a name="id-1.5.5.4.9"></a><h4>Arrays</h4>
 109 <p>JSON arrays map to GVariant arrays of variants <code class="literal">(av)</code>.</p>
 110 </div>
 111 <div class="refsect3">
 112 <a name="id-1.5.5.4.10"></a><h4>Objects</h4>
 113 <p>JSON objects map to GVariant dictionaries of string to variants <code class="literal">(a{sv})</code>.</p>
 114 </div>
 115 <div class="refsect3">
 116 <a name="id-1.5.5.4.11"></a><h4>Null values</h4>
 117 <p>JSON null values map to GVariant maybe variants <code class="literal">(mv)</code>.</p>
 118 </div>
 119 </div>
 120 <div class="refsect1">
 121 <a name="json-glib-JSON-GVariant-Integration.functions_details"></a><h2>Functions</h2>
 122 <div class="refsect2">
 123 <a name="json-gvariant-serialize"></a><h3>json_gvariant_serialize ()</h3>
 124 <pre class="programlisting"><a class="link" href="json-glib-JSON-Node.html#JsonNode"><span class="returnvalue">JsonNode</span></a> *
 125 json_gvariant_serialize (<em class="parameter"><code><span class="type">GVariant</span> *variant</code></em>);</pre>
 126 <p>Converts <em class="parameter"><code>variant</code></em>
 127  to a JSON tree.</p>
 128 <div class="refsect3">
 129 <a name="json-gvariant-serialize.parameters"></a><h4>Parameters</h4>
 130 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 131 <colgroup>
 132 <col width="150px" class="parameters_name">
 133 <col class="parameters_description">
 134 <col width="200px" class="parameters_annotations">
 135 </colgroup>
 136 <tbody><tr>
 137 <td class="parameter_name"><p>variant</p></td>
 138 <td class="parameter_description"><p>A <span class="type">GVariant</span> to convert</p></td>
 139 <td class="parameter_annotations"> </td>
 140 </tr></tbody>
 141 </table></div>
 142 </div>
 143 <div class="refsect3">
 144 <a name="json-gvariant-serialize.returns"></a><h4>Returns</h4>
 145 <p> A <a class="link" href="json-glib-JSON-Node.html#JsonNode"><span class="type">JsonNode</span></a> representing the root of the
 146 JSON data structure obtained from <em class="parameter"><code>variant</code></em>
 147 . </p>
 148 <p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p>
 149 </div>
 150 <p class="since">Since: <a class="link" href="ix08.html#api-index-0.14">0.14</a></p>
 151 </div>
 152 <hr>
 153 <div class="refsect2">
 154 <a name="json-gvariant-serialize-data"></a><h3>json_gvariant_serialize_data ()</h3>
 155 <pre class="programlisting"><span class="returnvalue">gchar</span> *
 156 json_gvariant_serialize_data (<em class="parameter"><code><span class="type">GVariant</span> *variant</code></em>,
 157                               <em class="parameter"><code><span class="type">gsize</span> *length</code></em>);</pre>
 158 <p>Converts <em class="parameter"><code>variant</code></em>
 159  to its JSON encoded string representation. This method
 160 is actually a helper function. It uses <a class="link" href="json-glib-JSON-GVariant-Integration.html#json-gvariant-serialize" title="json_gvariant_serialize ()"><code class="function">json_gvariant_serialize()</code></a> to obtain the
 161 JSON tree, and then <a class="link" href="JsonGenerator.html" title="JsonGenerator"><span class="type">JsonGenerator</span></a> to stringify it.</p>
 162 <div class="refsect3">
 163 <a name="json-gvariant-serialize-data.parameters"></a><h4>Parameters</h4>
 164 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 165 <colgroup>
 166 <col width="150px" class="parameters_name">
 167 <col class="parameters_description">
 168 <col width="200px" class="parameters_annotations">
 169 </colgroup>
 170 <tbody>
 171 <tr>
 172 <td class="parameter_name"><p>variant</p></td>
 173 <td class="parameter_description"><p>A <span class="type">GVariant</span> to convert</p></td>
 174 <td class="parameter_annotations"> </td>
 175 </tr>
 176 <tr>
 177 <td class="parameter_name"><p>length</p></td>
 178 <td class="parameter_description"><p> Return location for the length of the returned
 179 string, or <code class="literal">NULL</code>. </p></td>
 180 <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
 181 </tr>
 182 </tbody>
 183 </table></div>
 184 </div>
 185 <div class="refsect3">
 186 <a name="json-gvariant-serialize-data.returns"></a><h4>Returns</h4>
 187 <p> The JSON encoded string corresponding to
 188 <em class="parameter"><code>variant</code></em>
 189 . </p>
 190 <p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p>
 191 </div>
 192 <p class="since">Since: <a class="link" href="ix08.html#api-index-0.14">0.14</a></p>
 193 </div>
 194 <hr>
 195 <div class="refsect2">
 196 <a name="json-gvariant-deserialize"></a><h3>json_gvariant_deserialize ()</h3>
 197 <pre class="programlisting"><span class="returnvalue">GVariant</span> *
 198 json_gvariant_deserialize (<em class="parameter"><code><a class="link" href="json-glib-JSON-Node.html#JsonNode"><span class="type">JsonNode</span></a> *json_node</code></em>,
 199                            <em class="parameter"><code>const <span class="type">gchar</span> *signature</code></em>,
 200                            <em class="parameter"><code><span class="type">GError</span> **error</code></em>);</pre>
 201 <p>Converts a JSON data structure to a GVariant value using <em class="parameter"><code>signature</code></em>
 202  to
 203 resolve ambiguous data types. If no error occurs, the resulting <span class="type">GVariant</span>
 204 is guaranteed to conform to <em class="parameter"><code>signature</code></em>
 205 .</p>
 206 <p>If <em class="parameter"><code>signature</code></em>
 207  is not <code class="literal">NULL</code> but does not represent a valid GVariant type
 208 string, <code class="literal">NULL</code> is returned and error is set to <code class="literal">G_IO_ERROR_INVALID_ARGUMENT</code>.
 209 If a <em class="parameter"><code>signature</code></em>
 210  is provided but the JSON structure cannot be mapped to it,
 211 <code class="literal">NULL</code> is returned and error is set to <code class="literal">G_IO_ERROR_INVALID_DATA</code>.
 212 If <em class="parameter"><code>signature</code></em>
 213  is <code class="literal">NULL</code>, the conversion is done based strictly on the types
 214 in the JSON nodes.</p>
 215 <p>The returned variant has a floating reference that will need to be sunk
 216 by the caller code.</p>
 217 <div class="refsect3">
 218 <a name="json-gvariant-deserialize.parameters"></a><h4>Parameters</h4>
 219 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 220 <colgroup>
 221 <col width="150px" class="parameters_name">
 222 <col class="parameters_description">
 223 <col width="200px" class="parameters_annotations">
 224 </colgroup>
 225 <tbody>
 226 <tr>
 227 <td class="parameter_name"><p>json_node</p></td>
 228 <td class="parameter_description"><p>A <a class="link" href="json-glib-JSON-Node.html#JsonNode"><span class="type">JsonNode</span></a> to convert</p></td>
 229 <td class="parameter_annotations"> </td>
 230 </tr>
 231 <tr>
 232 <td class="parameter_name"><p>signature</p></td>
 233 <td class="parameter_description"><p> A valid <span class="type">GVariant</span> type string, or <code class="literal">NULL</code>. </p></td>
 234 <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
 235 </tr>
 236 <tr>
 237 <td class="parameter_name"><p>error</p></td>
 238 <td class="parameter_description"><p>A pointer to a <span class="type">GError</span></p></td>
 239 <td class="parameter_annotations"> </td>
 240 </tr>
 241 </tbody>
 242 </table></div>
 243 </div>
 244 <div class="refsect3">
 245 <a name="json-gvariant-deserialize.returns"></a><h4>Returns</h4>
 246 <p> A newly created, floating <span class="type">GVariant</span>
 247 compliant with <em class="parameter"><code>signature</code></em>
 248 , or <code class="literal">NULL</code> on error. </p>
 249 <p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p>
 250 </div>
 251 <p class="since">Since: <a class="link" href="ix08.html#api-index-0.14">0.14</a></p>
 252 </div>
 253 <hr>
 254 <div class="refsect2">
 255 <a name="json-gvariant-deserialize-data"></a><h3>json_gvariant_deserialize_data ()</h3>
 256 <pre class="programlisting"><span class="returnvalue">GVariant</span> *
 257 json_gvariant_deserialize_data (<em class="parameter"><code>const <span class="type">gchar</span> *json</code></em>,
 258                                 <em class="parameter"><code><span class="type">gssize</span> length</code></em>,
 259                                 <em class="parameter"><code>const <span class="type">gchar</span> *signature</code></em>,
 260                                 <em class="parameter"><code><span class="type">GError</span> **error</code></em>);</pre>
 261 <p>Converts a JSON string to a <span class="type">GVariant</span> value. This method works exactly
 262 like <a class="link" href="json-glib-JSON-GVariant-Integration.html#json-gvariant-deserialize" title="json_gvariant_deserialize ()"><code class="function">json_gvariant_deserialize()</code></a>, but takes a JSON encoded string instead.
 263 The string is first converted to a <a class="link" href="json-glib-JSON-Node.html#JsonNode"><span class="type">JsonNode</span></a> using <a class="link" href="JsonParser.html" title="JsonParser"><span class="type">JsonParser</span></a>, and then
 264 <a class="link" href="json-glib-JSON-GVariant-Integration.html#json-gvariant-deserialize" title="json_gvariant_deserialize ()"><code class="function">json_gvariant_deserialize()</code></a> is called.</p>
 265 <p>The returned variant has a floating reference that will need to be sunk
 266 by the caller code.</p>
 267 <div class="refsect3">
 268 <a name="json-gvariant-deserialize-data.parameters"></a><h4>Parameters</h4>
 269 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 270 <colgroup>
 271 <col width="150px" class="parameters_name">
 272 <col class="parameters_description">
 273 <col width="200px" class="parameters_annotations">
 274 </colgroup>
 275 <tbody>
 276 <tr>
 277 <td class="parameter_name"><p>json</p></td>
 278 <td class="parameter_description"><p>A JSON data string</p></td>
 279 <td class="parameter_annotations"> </td>
 280 </tr>
 281 <tr>
 282 <td class="parameter_name"><p>length</p></td>
 283 <td class="parameter_description"><p>The length of <em class="parameter"><code>json</code></em>
 284 , or -1 if <code class="literal">NULL</code>-terminated</p></td>
 285 <td class="parameter_annotations"> </td>
 286 </tr>
 287 <tr>
 288 <td class="parameter_name"><p>signature</p></td>
 289 <td class="parameter_description"><p> A valid <span class="type">GVariant</span> type string, or <code class="literal">NULL</code>. </p></td>
 290 <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
 291 </tr>
 292 <tr>
 293 <td class="parameter_name"><p>error</p></td>
 294 <td class="parameter_description"><p>A pointer to a <span class="type">GError</span></p></td>
 295 <td class="parameter_annotations"> </td>
 296 </tr>
 297 </tbody>
 298 </table></div>
 299 </div>
 300 <div class="refsect3">
 301 <a name="json-gvariant-deserialize-data.returns"></a><h4>Returns</h4>
 302 <p> A newly created, floating <span class="type">GVariant</span> compliant
 303 with <em class="parameter"><code>signature</code></em>
 304 , or <code class="literal">NULL</code> on error. </p>
 305 <p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p>
 306 </div>
 307 <p class="since">Since: <a class="link" href="ix08.html#api-index-0.14">0.14</a></p>
 308 </div>
 309 </div>
 310 <div class="refsect1">
 311 <a name="json-glib-JSON-GVariant-Integration.other_details"></a><h2>Types and Values</h2>
 312 </div>
 313 </div>
 314 <div class="footer">
 315 <hr>Generated by GTK-Doc V1.25.1</div>
 316 </body>
 317 </html>