g_variant_get_fixed_array: document which types are appropriate
[platform/upstream/glib.git] / glib / gvariant.c
1 /*
2  * Copyright © 2007, 2008 Ryan Lortie
3  * Copyright © 2010 Codethink Limited
4  *
5  * This library is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Lesser General Public
7  * License as published by the Free Software Foundation; either
8  * version 2 of the licence, or (at your option) any later version.
9  *
10  * This library is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13  * Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public
16  * License along with this library; if not, write to the
17  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18  * Boston, MA 02111-1307, USA.
19  *
20  * Author: Ryan Lortie <desrt@desrt.ca>
21  */
22
23 /* Prologue {{{1 */
24
25 #include "config.h"
26
27 #include <glib/gvariant-serialiser.h>
28 #include "gvariant-internal.h"
29 #include <glib/gvariant-core.h>
30 #include <glib/gtestutils.h>
31 #include <glib/gstrfuncs.h>
32 #include <glib/gslice.h>
33 #include <glib/ghash.h>
34 #include <glib/gmem.h>
35
36 #include <string.h>
37
38
39 /**
40  * SECTION:gvariant
41  * @title: GVariant
42  * @short_description: strongly typed value datatype
43  * @see_also: GVariantType
44  *
45  * #GVariant is a variant datatype; it stores a value along with
46  * information about the type of that value.  The range of possible
47  * values is determined by the type.  The type system used by #GVariant
48  * is #GVariantType.
49  *
50  * #GVariant instances always have a type and a value (which are given
51  * at construction time).  The type and value of a #GVariant instance
52  * can never change other than by the #GVariant itself being
53  * destroyed.  A #GVariant cannot contain a pointer.
54  *
55  * #GVariant is reference counted using g_variant_ref() and
56  * g_variant_unref().  #GVariant also has floating reference counts --
57  * see g_variant_ref_sink().
58  *
59  * #GVariant is completely threadsafe.  A #GVariant instance can be
60  * concurrently accessed in any way from any number of threads without
61  * problems.
62  *
63  * #GVariant is heavily optimised for dealing with data in serialised
64  * form.  It works particularly well with data located in memory-mapped
65  * files.  It can perform nearly all deserialisation operations in a
66  * small constant time, usually touching only a single memory page.
67  * Serialised #GVariant data can also be sent over the network.
68  *
69  * #GVariant is largely compatible with D-Bus.  Almost all types of
70  * #GVariant instances can be sent over D-Bus.  See #GVariantType for
71  * exceptions.  (However, #GVariant's serialisation format is not the same
72  * as the serialisation format of a D-Bus message body: use #GDBusMessage,
73  * in the gio library, for those.)
74  *
75  * For convenience to C programmers, #GVariant features powerful
76  * varargs-based value construction and destruction.  This feature is
77  * designed to be embedded in other libraries.
78  *
79  * There is a Python-inspired text language for describing #GVariant
80  * values.  #GVariant includes a printer for this language and a parser
81  * with type inferencing.
82  *
83  * <refsect2>
84  *  <title>Memory Use</title>
85  *  <para>
86  *   #GVariant tries to be quite efficient with respect to memory use.
87  *   This section gives a rough idea of how much memory is used by the
88  *   current implementation.  The information here is subject to change
89  *   in the future.
90  *  </para>
91  *  <para>
92  *   The memory allocated by #GVariant can be grouped into 4 broad
93  *   purposes: memory for serialised data, memory for the type
94  *   information cache, buffer management memory and memory for the
95  *   #GVariant structure itself.
96  *  </para>
97  *  <refsect3 id="gvariant-serialised-data-memory">
98  *   <title>Serialised Data Memory</title>
99  *   <para>
100  *    This is the memory that is used for storing GVariant data in
101  *    serialised form.  This is what would be sent over the network or
102  *    what would end up on disk.
103  *   </para>
104  *   <para>
105  *    The amount of memory required to store a boolean is 1 byte.  16,
106  *    32 and 64 bit integers and double precision floating point numbers
107  *    use their "natural" size.  Strings (including object path and
108  *    signature strings) are stored with a nul terminator, and as such
109  *    use the length of the string plus 1 byte.
110  *   </para>
111  *   <para>
112  *    Maybe types use no space at all to represent the null value and
113  *    use the same amount of space (sometimes plus one byte) as the
114  *    equivalent non-maybe-typed value to represent the non-null case.
115  *   </para>
116  *   <para>
117  *    Arrays use the amount of space required to store each of their
118  *    members, concatenated.  Additionally, if the items stored in an
119  *    array are not of a fixed-size (ie: strings, other arrays, etc)
120  *    then an additional framing offset is stored for each item.  The
121  *    size of this offset is either 1, 2 or 4 bytes depending on the
122  *    overall size of the container.  Additionally, extra padding bytes
123  *    are added as required for alignment of child values.
124  *   </para>
125  *   <para>
126  *    Tuples (including dictionary entries) use the amount of space
127  *    required to store each of their members, concatenated, plus one
128  *    framing offset (as per arrays) for each non-fixed-sized item in
129  *    the tuple, except for the last one.  Additionally, extra padding
130  *    bytes are added as required for alignment of child values.
131  *   </para>
132  *   <para>
133  *    Variants use the same amount of space as the item inside of the
134  *    variant, plus 1 byte, plus the length of the type string for the
135  *    item inside the variant.
136  *   </para>
137  *   <para>
138  *    As an example, consider a dictionary mapping strings to variants.
139  *    In the case that the dictionary is empty, 0 bytes are required for
140  *    the serialisation.
141  *   </para>
142  *   <para>
143  *    If we add an item "width" that maps to the int32 value of 500 then
144  *    we will use 4 byte to store the int32 (so 6 for the variant
145  *    containing it) and 6 bytes for the string.  The variant must be
146  *    aligned to 8 after the 6 bytes of the string, so that's 2 extra
147  *    bytes.  6 (string) + 2 (padding) + 6 (variant) is 14 bytes used
148  *    for the dictionary entry.  An additional 1 byte is added to the
149  *    array as a framing offset making a total of 15 bytes.
150  *   </para>
151  *   <para>
152  *    If we add another entry, "title" that maps to a nullable string
153  *    that happens to have a value of null, then we use 0 bytes for the
154  *    null value (and 3 bytes for the variant to contain it along with
155  *    its type string) plus 6 bytes for the string.  Again, we need 2
156  *    padding bytes.  That makes a total of 6 + 2 + 3 = 11 bytes.
157  *   </para>
158  *   <para>
159  *    We now require extra padding between the two items in the array.
160  *    After the 14 bytes of the first item, that's 2 bytes required.  We
161  *    now require 2 framing offsets for an extra two bytes.  14 + 2 + 11
162  *    + 2 = 29 bytes to encode the entire two-item dictionary.
163  *   </para>
164  *  </refsect3>
165  *  <refsect3>
166  *   <title>Type Information Cache</title>
167  *   <para>
168  *    For each GVariant type that currently exists in the program a type
169  *    information structure is kept in the type information cache.  The
170  *    type information structure is required for rapid deserialisation.
171  *   </para>
172  *   <para>
173  *    Continuing with the above example, if a #GVariant exists with the
174  *    type "a{sv}" then a type information struct will exist for
175  *    "a{sv}", "{sv}", "s", and "v".  Multiple uses of the same type
176  *    will share the same type information.  Additionally, all
177  *    single-digit types are stored in read-only static memory and do
178  *    not contribute to the writable memory footprint of a program using
179  *    #GVariant.
180  *   </para>
181  *   <para>
182  *    Aside from the type information structures stored in read-only
183  *    memory, there are two forms of type information.  One is used for
184  *    container types where there is a single element type: arrays and
185  *    maybe types.  The other is used for container types where there
186  *    are multiple element types: tuples and dictionary entries.
187  *   </para>
188  *   <para>
189  *    Array type info structures are 6 * sizeof (void *), plus the
190  *    memory required to store the type string itself.  This means that
191  *    on 32bit systems, the cache entry for "a{sv}" would require 30
192  *    bytes of memory (plus malloc overhead).
193  *   </para>
194  *   <para>
195  *    Tuple type info structures are 6 * sizeof (void *), plus 4 *
196  *    sizeof (void *) for each item in the tuple, plus the memory
197  *    required to store the type string itself.  A 2-item tuple, for
198  *    example, would have a type information structure that consumed
199  *    writable memory in the size of 14 * sizeof (void *) (plus type
200  *    string)  This means that on 32bit systems, the cache entry for
201  *    "{sv}" would require 61 bytes of memory (plus malloc overhead).
202  *   </para>
203  *   <para>
204  *    This means that in total, for our "a{sv}" example, 91 bytes of
205  *    type information would be allocated.
206  *   </para>
207  *   <para>
208  *    The type information cache, additionally, uses a #GHashTable to
209  *    store and lookup the cached items and stores a pointer to this
210  *    hash table in static storage.  The hash table is freed when there
211  *    are zero items in the type cache.
212  *   </para>
213  *   <para>
214  *    Although these sizes may seem large it is important to remember
215  *    that a program will probably only have a very small number of
216  *    different types of values in it and that only one type information
217  *    structure is required for many different values of the same type.
218  *   </para>
219  *  </refsect3>
220  *  <refsect3>
221  *   <title>Buffer Management Memory</title>
222  *   <para>
223  *    #GVariant uses an internal buffer management structure to deal
224  *    with the various different possible sources of serialised data
225  *    that it uses.  The buffer is responsible for ensuring that the
226  *    correct call is made when the data is no longer in use by
227  *    #GVariant.  This may involve a g_free() or a g_slice_free() or
228  *    even g_mapped_file_unref().
229  *   </para>
230  *   <para>
231  *    One buffer management structure is used for each chunk of
232  *    serialised data.  The size of the buffer management structure is 4
233  *    * (void *).  On 32bit systems, that's 16 bytes.
234  *   </para>
235  *  </refsect3>
236  *  <refsect3>
237  *   <title>GVariant structure</title>
238  *   <para>
239  *    The size of a #GVariant structure is 6 * (void *).  On 32 bit
240  *    systems, that's 24 bytes.
241  *   </para>
242  *   <para>
243  *    #GVariant structures only exist if they are explicitly created
244  *    with API calls.  For example, if a #GVariant is constructed out of
245  *    serialised data for the example given above (with the dictionary)
246  *    then although there are 9 individual values that comprise the
247  *    entire dictionary (two keys, two values, two variants containing
248  *    the values, two dictionary entries, plus the dictionary itself),
249  *    only 1 #GVariant instance exists -- the one referring to the
250  *    dictionary.
251  *   </para>
252  *   <para>
253  *    If calls are made to start accessing the other values then
254  *    #GVariant instances will exist for those values only for as long
255  *    as they are in use (ie: until you call g_variant_unref()).  The
256  *    type information is shared.  The serialised data and the buffer
257  *    management structure for that serialised data is shared by the
258  *    child.
259  *   </para>
260  *  </refsect3>
261  *  <refsect3>
262  *   <title>Summary</title>
263  *   <para>
264  *    To put the entire example together, for our dictionary mapping
265  *    strings to variants (with two entries, as given above), we are
266  *    using 91 bytes of memory for type information, 29 byes of memory
267  *    for the serialised data, 16 bytes for buffer management and 24
268  *    bytes for the #GVariant instance, or a total of 160 bytes, plus
269  *    malloc overhead.  If we were to use g_variant_get_child_value() to
270  *    access the two dictionary entries, we would use an additional 48
271  *    bytes.  If we were to have other dictionaries of the same type, we
272  *    would use more memory for the serialised data and buffer
273  *    management for those dictionaries, but the type information would
274  *    be shared.
275  *   </para>
276  *  </refsect3>
277  * </refsect2>
278  */
279
280 /* definition of GVariant structure is in gvariant-core.c */
281
282 /* this is a g_return_val_if_fail() for making
283  * sure a (GVariant *) has the required type.
284  */
285 #define TYPE_CHECK(value, TYPE, val) \
286   if G_UNLIKELY (!g_variant_is_of_type (value, TYPE)) {           \
287     g_return_if_fail_warning (G_LOG_DOMAIN, G_STRFUNC,            \
288                               "g_variant_is_of_type (" #value     \
289                               ", " #TYPE ")");                    \
290     return val;                                                   \
291   }
292
293 /* Numeric Type Constructor/Getters {{{1 */
294 /* < private >
295  * g_variant_new_from_trusted:
296  * @type: the #GVariantType
297  * @data: the data to use
298  * @size: the size of @data
299  * @returns: a new floating #GVariant
300  *
301  * Constructs a new trusted #GVariant instance from the provided data.
302  * This is used to implement g_variant_new_* for all the basic types.
303  */
304 static GVariant *
305 g_variant_new_from_trusted (const GVariantType *type,
306                             gconstpointer       data,
307                             gsize               size)
308 {
309   GVariant *value;
310   GBuffer *buffer;
311
312   buffer = g_buffer_new_from_data (data, size);
313   value = g_variant_new_from_buffer (type, buffer, TRUE);
314   g_buffer_unref (buffer);
315
316   return value;
317 }
318
319 /**
320  * g_variant_new_boolean:
321  * @value: a #gboolean value
322  * @returns: (transfer none): a floating reference to a new boolean #GVariant instance
323  *
324  * Creates a new boolean #GVariant instance -- either %TRUE or %FALSE.
325  *
326  * Since: 2.24
327  **/
328 GVariant *
329 g_variant_new_boolean (gboolean value)
330 {
331   guchar v = value;
332
333   return g_variant_new_from_trusted (G_VARIANT_TYPE_BOOLEAN, &v, 1);
334 }
335
336 /**
337  * g_variant_get_boolean:
338  * @value: a boolean #GVariant instance
339  * @returns: %TRUE or %FALSE
340  *
341  * Returns the boolean value of @value.
342  *
343  * It is an error to call this function with a @value of any type
344  * other than %G_VARIANT_TYPE_BOOLEAN.
345  *
346  * Since: 2.24
347  **/
348 gboolean
349 g_variant_get_boolean (GVariant *value)
350 {
351   const guchar *data;
352
353   TYPE_CHECK (value, G_VARIANT_TYPE_BOOLEAN, FALSE);
354
355   data = g_variant_get_data (value);
356
357   return data != NULL ? *data != 0 : FALSE;
358 }
359
360 /* the constructors and accessors for byte, int{16,32,64}, handles and
361  * doubles all look pretty much exactly the same, so we reduce
362  * copy/pasting here.
363  */
364 #define NUMERIC_TYPE(TYPE, type, ctype) \
365   GVariant *g_variant_new_##type (ctype value) {                \
366     return g_variant_new_from_trusted (G_VARIANT_TYPE_##TYPE,   \
367                                        &value, sizeof value);   \
368   }                                                             \
369   ctype g_variant_get_##type (GVariant *value) {                \
370     const ctype *data;                                          \
371     TYPE_CHECK (value, G_VARIANT_TYPE_ ## TYPE, 0);             \
372     data = g_variant_get_data (value);                          \
373     return data != NULL ? *data : 0;                            \
374   }
375
376
377 /**
378  * g_variant_new_byte:
379  * @value: a #guint8 value
380  * @returns: (transfer none): a floating reference to a new byte #GVariant instance
381  *
382  * Creates a new byte #GVariant instance.
383  *
384  * Since: 2.24
385  **/
386 /**
387  * g_variant_get_byte:
388  * @value: a byte #GVariant instance
389  * @returns: a #guchar
390  *
391  * Returns the byte value of @value.
392  *
393  * It is an error to call this function with a @value of any type
394  * other than %G_VARIANT_TYPE_BYTE.
395  *
396  * Since: 2.24
397  **/
398 NUMERIC_TYPE (BYTE, byte, guchar)
399
400 /**
401  * g_variant_new_int16:
402  * @value: a #gint16 value
403  * @returns: (transfer none): a floating reference to a new int16 #GVariant instance
404  *
405  * Creates a new int16 #GVariant instance.
406  *
407  * Since: 2.24
408  **/
409 /**
410  * g_variant_get_int16:
411  * @value: a int16 #GVariant instance
412  * @returns: a #gint16
413  *
414  * Returns the 16-bit signed integer value of @value.
415  *
416  * It is an error to call this function with a @value of any type
417  * other than %G_VARIANT_TYPE_INT16.
418  *
419  * Since: 2.24
420  **/
421 NUMERIC_TYPE (INT16, int16, gint16)
422
423 /**
424  * g_variant_new_uint16:
425  * @value: a #guint16 value
426  * @returns: (transfer none): a floating reference to a new uint16 #GVariant instance
427  *
428  * Creates a new uint16 #GVariant instance.
429  *
430  * Since: 2.24
431  **/
432 /**
433  * g_variant_get_uint16:
434  * @value: a uint16 #GVariant instance
435  * @returns: a #guint16
436  *
437  * Returns the 16-bit unsigned integer value of @value.
438  *
439  * It is an error to call this function with a @value of any type
440  * other than %G_VARIANT_TYPE_UINT16.
441  *
442  * Since: 2.24
443  **/
444 NUMERIC_TYPE (UINT16, uint16, guint16)
445
446 /**
447  * g_variant_new_int32:
448  * @value: a #gint32 value
449  * @returns: (transfer none): a floating reference to a new int32 #GVariant instance
450  *
451  * Creates a new int32 #GVariant instance.
452  *
453  * Since: 2.24
454  **/
455 /**
456  * g_variant_get_int32:
457  * @value: a int32 #GVariant instance
458  * @returns: a #gint32
459  *
460  * Returns the 32-bit signed integer value of @value.
461  *
462  * It is an error to call this function with a @value of any type
463  * other than %G_VARIANT_TYPE_INT32.
464  *
465  * Since: 2.24
466  **/
467 NUMERIC_TYPE (INT32, int32, gint32)
468
469 /**
470  * g_variant_new_uint32:
471  * @value: a #guint32 value
472  * @returns: (transfer none): a floating reference to a new uint32 #GVariant instance
473  *
474  * Creates a new uint32 #GVariant instance.
475  *
476  * Since: 2.24
477  **/
478 /**
479  * g_variant_get_uint32:
480  * @value: a uint32 #GVariant instance
481  * @returns: a #guint32
482  *
483  * Returns the 32-bit unsigned integer value of @value.
484  *
485  * It is an error to call this function with a @value of any type
486  * other than %G_VARIANT_TYPE_UINT32.
487  *
488  * Since: 2.24
489  **/
490 NUMERIC_TYPE (UINT32, uint32, guint32)
491
492 /**
493  * g_variant_new_int64:
494  * @value: a #gint64 value
495  * @returns: (transfer none): a floating reference to a new int64 #GVariant instance
496  *
497  * Creates a new int64 #GVariant instance.
498  *
499  * Since: 2.24
500  **/
501 /**
502  * g_variant_get_int64:
503  * @value: a int64 #GVariant instance
504  * @returns: a #gint64
505  *
506  * Returns the 64-bit signed integer value of @value.
507  *
508  * It is an error to call this function with a @value of any type
509  * other than %G_VARIANT_TYPE_INT64.
510  *
511  * Since: 2.24
512  **/
513 NUMERIC_TYPE (INT64, int64, gint64)
514
515 /**
516  * g_variant_new_uint64:
517  * @value: a #guint64 value
518  * @returns: (transfer none): a floating reference to a new uint64 #GVariant instance
519  *
520  * Creates a new uint64 #GVariant instance.
521  *
522  * Since: 2.24
523  **/
524 /**
525  * g_variant_get_uint64:
526  * @value: a uint64 #GVariant instance
527  * @returns: a #guint64
528  *
529  * Returns the 64-bit unsigned integer value of @value.
530  *
531  * It is an error to call this function with a @value of any type
532  * other than %G_VARIANT_TYPE_UINT64.
533  *
534  * Since: 2.24
535  **/
536 NUMERIC_TYPE (UINT64, uint64, guint64)
537
538 /**
539  * g_variant_new_handle:
540  * @value: a #gint32 value
541  * @returns: (transfer none): a floating reference to a new handle #GVariant instance
542  *
543  * Creates a new handle #GVariant instance.
544  *
545  * By convention, handles are indexes into an array of file descriptors
546  * that are sent alongside a D-Bus message.  If you're not interacting
547  * with D-Bus, you probably don't need them.
548  *
549  * Since: 2.24
550  **/
551 /**
552  * g_variant_get_handle:
553  * @value: a handle #GVariant instance
554  * @returns: a #gint32
555  *
556  * Returns the 32-bit signed integer value of @value.
557  *
558  * It is an error to call this function with a @value of any type other
559  * than %G_VARIANT_TYPE_HANDLE.
560  *
561  * By convention, handles are indexes into an array of file descriptors
562  * that are sent alongside a D-Bus message.  If you're not interacting
563  * with D-Bus, you probably don't need them.
564  *
565  * Since: 2.24
566  **/
567 NUMERIC_TYPE (HANDLE, handle, gint32)
568
569 /**
570  * g_variant_new_double:
571  * @value: a #gdouble floating point value
572  * @returns: (transfer none): a floating reference to a new double #GVariant instance
573  *
574  * Creates a new double #GVariant instance.
575  *
576  * Since: 2.24
577  **/
578 /**
579  * g_variant_get_double:
580  * @value: a double #GVariant instance
581  * @returns: a #gdouble
582  *
583  * Returns the double precision floating point value of @value.
584  *
585  * It is an error to call this function with a @value of any type
586  * other than %G_VARIANT_TYPE_DOUBLE.
587  *
588  * Since: 2.24
589  **/
590 NUMERIC_TYPE (DOUBLE, double, gdouble)
591
592 /* Container type Constructor / Deconstructors {{{1 */
593 /**
594  * g_variant_new_maybe:
595  * @child_type: (allow-none): the #GVariantType of the child, or %NULL
596  * @child: (allow-none): the child value, or %NULL
597  * @returns: (transfer none): a floating reference to a new #GVariant maybe instance
598  *
599  * Depending on if @child is %NULL, either wraps @child inside of a
600  * maybe container or creates a Nothing instance for the given @type.
601  *
602  * At least one of @child_type and @child must be non-%NULL.
603  * If @child_type is non-%NULL then it must be a definite type.
604  * If they are both non-%NULL then @child_type must be the type
605  * of @child.
606  *
607  * If @child is a floating reference (see g_variant_ref_sink()), the new
608  * instance takes ownership of @child.
609  *
610  * Since: 2.24
611  **/
612 GVariant *
613 g_variant_new_maybe (const GVariantType *child_type,
614                      GVariant           *child)
615 {
616   GVariantType *maybe_type;
617   GVariant *value;
618
619   g_return_val_if_fail (child_type == NULL || g_variant_type_is_definite
620                         (child_type), 0);
621   g_return_val_if_fail (child_type != NULL || child != NULL, NULL);
622   g_return_val_if_fail (child_type == NULL || child == NULL ||
623                         g_variant_is_of_type (child, child_type),
624                         NULL);
625
626   if (child_type == NULL)
627     child_type = g_variant_get_type (child);
628
629   maybe_type = g_variant_type_new_maybe (child_type);
630
631   if (child != NULL)
632     {
633       GVariant **children;
634       gboolean trusted;
635
636       children = g_new (GVariant *, 1);
637       children[0] = g_variant_ref_sink (child);
638       trusted = g_variant_is_trusted (children[0]);
639
640       value = g_variant_new_from_children (maybe_type, children, 1, trusted);
641     }
642   else
643     value = g_variant_new_from_children (maybe_type, NULL, 0, TRUE);
644
645   g_variant_type_free (maybe_type);
646
647   return value;
648 }
649
650 /**
651  * g_variant_get_maybe:
652  * @value: a maybe-typed value
653  * @returns: (allow-none) (transfer full): the contents of @value, or %NULL
654  *
655  * Given a maybe-typed #GVariant instance, extract its value.  If the
656  * value is Nothing, then this function returns %NULL.
657  *
658  * Since: 2.24
659  **/
660 GVariant *
661 g_variant_get_maybe (GVariant *value)
662 {
663   TYPE_CHECK (value, G_VARIANT_TYPE_MAYBE, NULL);
664
665   if (g_variant_n_children (value))
666     return g_variant_get_child_value (value, 0);
667
668   return NULL;
669 }
670
671 /**
672  * g_variant_new_variant: (constructor)
673  * @value: a #GVariant instance
674  * @returns: (transfer none): a floating reference to a new variant #GVariant instance
675  *
676  * Boxes @value.  The result is a #GVariant instance representing a
677  * variant containing the original value.
678  *
679  * If @child is a floating reference (see g_variant_ref_sink()), the new
680  * instance takes ownership of @child.
681  *
682  * Since: 2.24
683  **/
684 GVariant *
685 g_variant_new_variant (GVariant *value)
686 {
687   g_return_val_if_fail (value != NULL, NULL);
688
689   g_variant_ref_sink (value);
690
691   return g_variant_new_from_children (G_VARIANT_TYPE_VARIANT,
692                                       g_memdup (&value, sizeof value),
693                                       1, g_variant_is_trusted (value));
694 }
695
696 /**
697  * g_variant_get_variant:
698  * @value: a variant #GVariant instance
699  * @returns: (transfer full): the item contained in the variant
700  *
701  * Unboxes @value.  The result is the #GVariant instance that was
702  * contained in @value.
703  *
704  * Since: 2.24
705  **/
706 GVariant *
707 g_variant_get_variant (GVariant *value)
708 {
709   TYPE_CHECK (value, G_VARIANT_TYPE_VARIANT, NULL);
710
711   return g_variant_get_child_value (value, 0);
712 }
713
714 /**
715  * g_variant_new_array:
716  * @child_type: (allow-none): the element type of the new array
717  * @children: (allow-none) (array length=n_children): an array of
718  *            #GVariant pointers, the children
719  * @n_children: the length of @children
720  * @returns: (transfer none): a floating reference to a new #GVariant array
721  *
722  * Creates a new #GVariant array from @children.
723  *
724  * @child_type must be non-%NULL if @n_children is zero.  Otherwise, the
725  * child type is determined by inspecting the first element of the
726  * @children array.  If @child_type is non-%NULL then it must be a
727  * definite type.
728  *
729  * The items of the array are taken from the @children array.  No entry
730  * in the @children array may be %NULL.
731  *
732  * All items in the array must have the same type, which must be the
733  * same as @child_type, if given.
734  *
735  * If the @children are floating references (see g_variant_ref_sink()), the
736  * new instance takes ownership of them as if via g_variant_ref_sink().
737  *
738  * Since: 2.24
739  **/
740 GVariant *
741 g_variant_new_array (const GVariantType *child_type,
742                      GVariant * const   *children,
743                      gsize               n_children)
744 {
745   GVariantType *array_type;
746   GVariant **my_children;
747   gboolean trusted;
748   GVariant *value;
749   gsize i;
750
751   g_return_val_if_fail (n_children > 0 || child_type != NULL, NULL);
752   g_return_val_if_fail (n_children == 0 || children != NULL, NULL);
753   g_return_val_if_fail (child_type == NULL ||
754                         g_variant_type_is_definite (child_type), NULL);
755
756   my_children = g_new (GVariant *, n_children);
757   trusted = TRUE;
758
759   if (child_type == NULL)
760     child_type = g_variant_get_type (children[0]);
761   array_type = g_variant_type_new_array (child_type);
762
763   for (i = 0; i < n_children; i++)
764     {
765       TYPE_CHECK (children[i], child_type, NULL);
766       my_children[i] = g_variant_ref_sink (children[i]);
767       trusted &= g_variant_is_trusted (children[i]);
768     }
769
770   value = g_variant_new_from_children (array_type, my_children,
771                                        n_children, trusted);
772   g_variant_type_free (array_type);
773
774   return value;
775 }
776
777 /*< private >
778  * g_variant_make_tuple_type:
779  * @children: (array length=n_children): an array of GVariant *
780  * @n_children: the length of @children
781  *
782  * Return the type of a tuple containing @children as its items.
783  **/
784 static GVariantType *
785 g_variant_make_tuple_type (GVariant * const *children,
786                            gsize             n_children)
787 {
788   const GVariantType **types;
789   GVariantType *type;
790   gsize i;
791
792   types = g_new (const GVariantType *, n_children);
793
794   for (i = 0; i < n_children; i++)
795     types[i] = g_variant_get_type (children[i]);
796
797   type = g_variant_type_new_tuple (types, n_children);
798   g_free (types);
799
800   return type;
801 }
802
803 /**
804  * g_variant_new_tuple:
805  * @children: (array length=n_children): the items to make the tuple out of
806  * @n_children: the length of @children
807  * @returns: (transfer none): a floating reference to a new #GVariant tuple
808  *
809  * Creates a new tuple #GVariant out of the items in @children.  The
810  * type is determined from the types of @children.  No entry in the
811  * @children array may be %NULL.
812  *
813  * If @n_children is 0 then the unit tuple is constructed.
814  *
815  * If the @children are floating references (see g_variant_ref_sink()), the
816  * new instance takes ownership of them as if via g_variant_ref_sink().
817  *
818  * Since: 2.24
819  **/
820 GVariant *
821 g_variant_new_tuple (GVariant * const *children,
822                      gsize             n_children)
823 {
824   GVariantType *tuple_type;
825   GVariant **my_children;
826   gboolean trusted;
827   GVariant *value;
828   gsize i;
829
830   g_return_val_if_fail (n_children == 0 || children != NULL, NULL);
831
832   my_children = g_new (GVariant *, n_children);
833   trusted = TRUE;
834
835   for (i = 0; i < n_children; i++)
836     {
837       my_children[i] = g_variant_ref_sink (children[i]);
838       trusted &= g_variant_is_trusted (children[i]);
839     }
840
841   tuple_type = g_variant_make_tuple_type (children, n_children);
842   value = g_variant_new_from_children (tuple_type, my_children,
843                                        n_children, trusted);
844   g_variant_type_free (tuple_type);
845
846   return value;
847 }
848
849 /*< private >
850  * g_variant_make_dict_entry_type:
851  * @key: a #GVariant, the key
852  * @val: a #GVariant, the value
853  *
854  * Return the type of a dictionary entry containing @key and @val as its
855  * children.
856  **/
857 static GVariantType *
858 g_variant_make_dict_entry_type (GVariant *key,
859                                 GVariant *val)
860 {
861   return g_variant_type_new_dict_entry (g_variant_get_type (key),
862                                         g_variant_get_type (val));
863 }
864
865 /**
866  * g_variant_new_dict_entry: (constructor)
867  * @key: a basic #GVariant, the key
868  * @value: a #GVariant, the value
869  * @returns: (transfer none): a floating reference to a new dictionary entry #GVariant
870  *
871  * Creates a new dictionary entry #GVariant. @key and @value must be
872  * non-%NULL. @key must be a value of a basic type (ie: not a container).
873  *
874  * If the @key or @value are floating references (see g_variant_ref_sink()),
875  * the new instance takes ownership of them as if via g_variant_ref_sink().
876  *
877  * Since: 2.24
878  **/
879 GVariant *
880 g_variant_new_dict_entry (GVariant *key,
881                           GVariant *value)
882 {
883   GVariantType *dict_type;
884   GVariant **children;
885   gboolean trusted;
886
887   g_return_val_if_fail (key != NULL && value != NULL, NULL);
888   g_return_val_if_fail (!g_variant_is_container (key), NULL);
889
890   children = g_new (GVariant *, 2);
891   children[0] = g_variant_ref_sink (key);
892   children[1] = g_variant_ref_sink (value);
893   trusted = g_variant_is_trusted (key) && g_variant_is_trusted (value);
894
895   dict_type = g_variant_make_dict_entry_type (key, value);
896   value = g_variant_new_from_children (dict_type, children, 2, trusted);
897   g_variant_type_free (dict_type);
898
899   return value;
900 }
901
902 /**
903  * g_variant_lookup: (skip)
904  * @dictionary: a dictionary #GVariant
905  * @key: the key to lookup in the dictionary
906  * @format_string: a GVariant format string
907  * @...: the arguments to unpack the value into
908  *
909  * Looks up a value in a dictionary #GVariant.
910  *
911  * This function is a wrapper around g_variant_lookup_value() and
912  * g_variant_get().  In the case that %NULL would have been returned,
913  * this function returns %FALSE.  Otherwise, it unpacks the returned
914  * value and returns %TRUE.
915  *
916  * See g_variant_get() for information about @format_string.
917  *
918  * Returns: %TRUE if a value was unpacked
919  *
920  * Since: 2.28
921  */
922 gboolean
923 g_variant_lookup (GVariant    *dictionary,
924                   const gchar *key,
925                   const gchar *format_string,
926                   ...)
927 {
928   GVariantType *type;
929   GVariant *value;
930
931   /* flatten */
932   g_variant_get_data (dictionary);
933
934   type = g_variant_format_string_scan_type (format_string, NULL, NULL);
935   value = g_variant_lookup_value (dictionary, key, type);
936   g_variant_type_free (type);
937
938   if (value)
939     {
940       va_list ap;
941
942       va_start (ap, format_string);
943       g_variant_get_va (value, format_string, NULL, &ap);
944       g_variant_unref (value);
945       va_end (ap);
946
947       return TRUE;
948     }
949
950   else
951     return FALSE;
952 }
953
954 /**
955  * g_variant_lookup_value:
956  * @dictionary: a dictionary #GVariant
957  * @key: the key to lookup in the dictionary
958  * @expected_type: (allow-none): a #GVariantType, or %NULL
959  *
960  * Looks up a value in a dictionary #GVariant.
961  *
962  * This function works with dictionaries of the type
963  * <literal>a{s*}</literal> (and equally well with type
964  * <literal>a{o*}</literal>, but we only further discuss the string case
965  * for sake of clarity).
966  *
967  * In the event that @dictionary has the type <literal>a{sv}</literal>,
968  * the @expected_type string specifies what type of value is expected to
969  * be inside of the variant.  If the value inside the variant has a
970  * different type then %NULL is returned.  In the event that @dictionary
971  * has a value type other than <literal>v</literal> then @expected_type
972  * must directly match the key type and it is used to unpack the value
973  * directly or an error occurs.
974  *
975  * In either case, if @key is not found in @dictionary, %NULL is
976  * returned.
977  *
978  * If the key is found and the value has the correct type, it is
979  * returned.  If @expected_type was specified then any non-%NULL return
980  * value will have this type.
981  *
982  * Returns: (transfer full): the value of the dictionary key, or %NULL
983  *
984  * Since: 2.28
985  */
986 GVariant *
987 g_variant_lookup_value (GVariant           *dictionary,
988                         const gchar        *key,
989                         const GVariantType *expected_type)
990 {
991   GVariantIter iter;
992   GVariant *entry;
993   GVariant *value;
994
995   g_return_val_if_fail (g_variant_is_of_type (dictionary,
996                                               G_VARIANT_TYPE ("a{s*}")) ||
997                         g_variant_is_of_type (dictionary,
998                                               G_VARIANT_TYPE ("a{o*}")),
999                         NULL);
1000
1001   g_variant_iter_init (&iter, dictionary);
1002
1003   while ((entry = g_variant_iter_next_value (&iter)))
1004     {
1005       GVariant *entry_key;
1006       gboolean matches;
1007
1008       entry_key = g_variant_get_child_value (entry, 0);
1009       matches = strcmp (g_variant_get_string (entry_key, NULL), key) == 0;
1010       g_variant_unref (entry_key);
1011
1012       if (matches)
1013         break;
1014
1015       g_variant_unref (entry);
1016     }
1017
1018   if (entry == NULL)
1019     return NULL;
1020
1021   value = g_variant_get_child_value (entry, 1);
1022   g_variant_unref (entry);
1023
1024   if (g_variant_is_of_type (value, G_VARIANT_TYPE_VARIANT))
1025     {
1026       GVariant *tmp;
1027
1028       tmp = g_variant_get_variant (value);
1029       g_variant_unref (value);
1030
1031       if (expected_type && !g_variant_is_of_type (tmp, expected_type))
1032         {
1033           g_variant_unref (tmp);
1034           tmp = NULL;
1035         }
1036
1037       value = tmp;
1038     }
1039
1040   g_return_val_if_fail (expected_type == NULL || value == NULL ||
1041                         g_variant_is_of_type (value, expected_type), NULL);
1042
1043   return value;
1044 }
1045
1046 /**
1047  * g_variant_get_fixed_array:
1048  * @value: a #GVariant array with fixed-sized elements
1049  * @n_elements: (out): a pointer to the location to store the number of items
1050  * @element_size: the size of each element
1051  * @returns: (array length=n_elements) (transfer none): a pointer to
1052  *           the fixed array
1053  *
1054  * Provides access to the serialised data for an array of fixed-sized
1055  * items.
1056  *
1057  * @value must be an array with fixed-sized elements.  Numeric types are
1058  * fixed-size, as are tuples containing only other fixed-sized types.
1059  *
1060  * @element_size must be the size of a single element in the array,
1061  * as given by the section on
1062  * <link linkend='gvariant-serialised-data-memory'>Serialised Data
1063  * Memory</link>.
1064  *
1065  * In particular, arrays of these fixed-sized types can be interpreted
1066  * as an array of the given C type, with @element_size set to
1067  * <code>sizeof</code> the appropriate type:
1068  *
1069  * <informaltable>
1070  * <tgroup cols='2'>
1071  * <thead><row><entry>element type</entry> <entry>C type</entry></row></thead>
1072  * <tbody>
1073  * <row><entry>%G_VARIANT_TYPE_INT16 (etc.)</entry>
1074  *   <entry>#gint16 (etc.)</entry></row>
1075  * <row><entry>%G_VARIANT_TYPE_BOOLEAN</entry>
1076  *   <entry>#guchar (not #gboolean!)</entry></row>
1077  * <row><entry>%G_VARIANT_TYPE_BYTE</entry> <entry>#guchar</entry></row>
1078  * <row><entry>%G_VARIANT_TYPE_HANDLE</entry> <entry>#guint32</entry></row>
1079  * <row><entry>%G_VARIANT_TYPE_DOUBLE</entry> <entry>#gdouble</entry></row>
1080  * </tbody>
1081  * </tgroup>
1082  * </informaltable>
1083  *
1084  * For example, if calling this function for an array of 32 bit integers,
1085  * you might say <code>sizeof (gint32)</code>.  This value isn't used
1086  * except for the purpose of a double-check that the form of the
1087  * seralised data matches the caller's expectation.
1088  *
1089  * @n_elements, which must be non-%NULL is set equal to the number of
1090  * items in the array.
1091  *
1092  * Since: 2.24
1093  **/
1094 gconstpointer
1095 g_variant_get_fixed_array (GVariant *value,
1096                            gsize    *n_elements,
1097                            gsize     element_size)
1098 {
1099   GVariantTypeInfo *array_info;
1100   gsize array_element_size;
1101   gconstpointer data;
1102   gsize size;
1103
1104   TYPE_CHECK (value, G_VARIANT_TYPE_ARRAY, NULL);
1105
1106   g_return_val_if_fail (n_elements != NULL, NULL);
1107   g_return_val_if_fail (element_size > 0, NULL);
1108
1109   array_info = g_variant_get_type_info (value);
1110   g_variant_type_info_query_element (array_info, NULL, &array_element_size);
1111
1112   g_return_val_if_fail (array_element_size, NULL);
1113
1114   if G_UNLIKELY (array_element_size != element_size)
1115     {
1116       if (array_element_size)
1117         g_critical ("g_variant_get_fixed_array: assertion "
1118                     "`g_variant_array_has_fixed_size (value, element_size)' "
1119                     "failed: array size %"G_GSIZE_FORMAT" does not match "
1120                     "given element_size %"G_GSIZE_FORMAT".",
1121                     array_element_size, element_size);
1122       else
1123         g_critical ("g_variant_get_fixed_array: assertion "
1124                     "`g_variant_array_has_fixed_size (value, element_size)' "
1125                     "failed: array does not have fixed size.");
1126     }
1127
1128   data = g_variant_get_data (value);
1129   size = g_variant_get_size (value);
1130
1131   if (size % element_size)
1132     *n_elements = 0;
1133   else
1134     *n_elements = size / element_size;
1135
1136   if (*n_elements)
1137     return data;
1138
1139   return NULL;
1140 }
1141
1142 /**
1143  * g_variant_new_fixed_array:
1144  * @element_type: the #GVariantType of each element
1145  * @elements: a pointer to the fixed array of contiguous elements
1146  * @n_elements: the number of elements
1147  * @element_size: the size of each element
1148  * @returns: (transfer none): a floating reference to a new array #GVariant instance
1149  *
1150  * Provides access to the serialised data for an array of fixed-sized
1151  * items.
1152  *
1153  * @value must be an array with fixed-sized elements.  Numeric types are
1154  * fixed-size as are tuples containing only other fixed-sized types.
1155  *
1156  * @element_size must be the size of a single element in the array.  For
1157  * example, if calling this function for an array of 32 bit integers,
1158  * you might say <code>sizeof (gint32)</code>.  This value isn't used
1159  * except for the purpose of a double-check that the form of the
1160  * seralised data matches the caller's expectation.
1161  *
1162  * @n_elements, which must be non-%NULL is set equal to the number of
1163  * items in the array.
1164  *
1165  * Since: 2.32
1166  **/
1167 GVariant *
1168 g_variant_new_fixed_array (const GVariantType  *element_type,
1169                            gconstpointer        elements,
1170                            gsize                n_elements,
1171                            gsize                element_size)
1172 {
1173   GVariantType *array_type;
1174   gsize array_element_size;
1175   GVariantTypeInfo *array_info;
1176   GVariant *value;
1177   gpointer data;
1178
1179   g_return_val_if_fail (g_variant_type_is_definite (element_type), NULL);
1180   g_return_val_if_fail (element_size > 0, NULL);
1181
1182   array_type = g_variant_type_new_array (element_type);
1183   array_info = g_variant_type_info_get (array_type);
1184   g_variant_type_info_query_element (array_info, NULL, &array_element_size);
1185   if G_UNLIKELY (array_element_size != element_size)
1186     {
1187       if (array_element_size)
1188         g_critical ("g_variant_new_fixed_array: array size %" G_GSIZE_FORMAT
1189                     " does not match given element_size %" G_GSIZE_FORMAT ".",
1190                     array_element_size, element_size);
1191       else
1192         g_critical ("g_variant_get_fixed_array: array does not have fixed size.");
1193       return NULL;
1194     }
1195
1196   data = g_memdup (elements, n_elements * element_size);
1197   value = g_variant_new_from_data (array_type, data,
1198                                    n_elements * element_size,
1199                                    FALSE, g_free, data);
1200
1201   g_variant_type_free (array_type);
1202   g_variant_type_info_unref (array_info);
1203
1204   return value;
1205 }
1206
1207 /* String type constructor/getters/validation {{{1 */
1208 /**
1209  * g_variant_new_string:
1210  * @string: a normal utf8 nul-terminated string
1211  * @returns: (transfer none): a floating reference to a new string #GVariant instance
1212  *
1213  * Creates a string #GVariant with the contents of @string.
1214  *
1215  * @string must be valid utf8.
1216  *
1217  * Since: 2.24
1218  **/
1219 GVariant *
1220 g_variant_new_string (const gchar *string)
1221 {
1222   g_return_val_if_fail (string != NULL, NULL);
1223   g_return_val_if_fail (g_utf8_validate (string, -1, NULL), NULL);
1224
1225   return g_variant_new_from_trusted (G_VARIANT_TYPE_STRING,
1226                                      string, strlen (string) + 1);
1227 }
1228
1229 /**
1230  * g_variant_new_object_path:
1231  * @object_path: a normal C nul-terminated string
1232  * @returns: (transfer none): a floating reference to a new object path #GVariant instance
1233  *
1234  * Creates a D-Bus object path #GVariant with the contents of @string.
1235  * @string must be a valid D-Bus object path.  Use
1236  * g_variant_is_object_path() if you're not sure.
1237  *
1238  * Since: 2.24
1239  **/
1240 GVariant *
1241 g_variant_new_object_path (const gchar *object_path)
1242 {
1243   g_return_val_if_fail (g_variant_is_object_path (object_path), NULL);
1244
1245   return g_variant_new_from_trusted (G_VARIANT_TYPE_OBJECT_PATH,
1246                                      object_path, strlen (object_path) + 1);
1247 }
1248
1249 /**
1250  * g_variant_is_object_path:
1251  * @string: a normal C nul-terminated string
1252  * @returns: %TRUE if @string is a D-Bus object path
1253  *
1254  * Determines if a given string is a valid D-Bus object path.  You
1255  * should ensure that a string is a valid D-Bus object path before
1256  * passing it to g_variant_new_object_path().
1257  *
1258  * A valid object path starts with '/' followed by zero or more
1259  * sequences of characters separated by '/' characters.  Each sequence
1260  * must contain only the characters "[A-Z][a-z][0-9]_".  No sequence
1261  * (including the one following the final '/' character) may be empty.
1262  *
1263  * Since: 2.24
1264  **/
1265 gboolean
1266 g_variant_is_object_path (const gchar *string)
1267 {
1268   g_return_val_if_fail (string != NULL, FALSE);
1269
1270   return g_variant_serialiser_is_object_path (string, strlen (string) + 1);
1271 }
1272
1273 /**
1274  * g_variant_new_signature:
1275  * @signature: a normal C nul-terminated string
1276  * @returns: (transfer none): a floating reference to a new signature #GVariant instance
1277  *
1278  * Creates a D-Bus type signature #GVariant with the contents of
1279  * @string.  @string must be a valid D-Bus type signature.  Use
1280  * g_variant_is_signature() if you're not sure.
1281  *
1282  * Since: 2.24
1283  **/
1284 GVariant *
1285 g_variant_new_signature (const gchar *signature)
1286 {
1287   g_return_val_if_fail (g_variant_is_signature (signature), NULL);
1288
1289   return g_variant_new_from_trusted (G_VARIANT_TYPE_SIGNATURE,
1290                                      signature, strlen (signature) + 1);
1291 }
1292
1293 /**
1294  * g_variant_is_signature:
1295  * @string: a normal C nul-terminated string
1296  * @returns: %TRUE if @string is a D-Bus type signature
1297  *
1298  * Determines if a given string is a valid D-Bus type signature.  You
1299  * should ensure that a string is a valid D-Bus type signature before
1300  * passing it to g_variant_new_signature().
1301  *
1302  * D-Bus type signatures consist of zero or more definite #GVariantType
1303  * strings in sequence.
1304  *
1305  * Since: 2.24
1306  **/
1307 gboolean
1308 g_variant_is_signature (const gchar *string)
1309 {
1310   g_return_val_if_fail (string != NULL, FALSE);
1311
1312   return g_variant_serialiser_is_signature (string, strlen (string) + 1);
1313 }
1314
1315 /**
1316  * g_variant_get_string:
1317  * @value: a string #GVariant instance
1318  * @length: (allow-none) (default 0) (out): a pointer to a #gsize,
1319  *          to store the length
1320  * @returns: (transfer none): the constant string, utf8 encoded
1321  *
1322  * Returns the string value of a #GVariant instance with a string
1323  * type.  This includes the types %G_VARIANT_TYPE_STRING,
1324  * %G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE.
1325  *
1326  * The string will always be utf8 encoded.
1327  *
1328  * If @length is non-%NULL then the length of the string (in bytes) is
1329  * returned there.  For trusted values, this information is already
1330  * known.  For untrusted values, a strlen() will be performed.
1331  *
1332  * It is an error to call this function with a @value of any type
1333  * other than those three.
1334  *
1335  * The return value remains valid as long as @value exists.
1336  *
1337  * Since: 2.24
1338  **/
1339 const gchar *
1340 g_variant_get_string (GVariant *value,
1341                       gsize    *length)
1342 {
1343   gconstpointer data;
1344   gsize size;
1345
1346   g_return_val_if_fail (value != NULL, NULL);
1347   g_return_val_if_fail (
1348     g_variant_is_of_type (value, G_VARIANT_TYPE_STRING) ||
1349     g_variant_is_of_type (value, G_VARIANT_TYPE_OBJECT_PATH) ||
1350     g_variant_is_of_type (value, G_VARIANT_TYPE_SIGNATURE), NULL);
1351
1352   data = g_variant_get_data (value);
1353   size = g_variant_get_size (value);
1354
1355   if (!g_variant_is_trusted (value))
1356     {
1357       switch (g_variant_classify (value))
1358         {
1359         case G_VARIANT_CLASS_STRING:
1360           if (g_variant_serialiser_is_string (data, size))
1361             break;
1362
1363           data = "";
1364           size = 1;
1365           break;
1366
1367         case G_VARIANT_CLASS_OBJECT_PATH:
1368           if (g_variant_serialiser_is_object_path (data, size))
1369             break;
1370
1371           data = "/";
1372           size = 2;
1373           break;
1374
1375         case G_VARIANT_CLASS_SIGNATURE:
1376           if (g_variant_serialiser_is_signature (data, size))
1377             break;
1378
1379           data = "";
1380           size = 1;
1381           break;
1382
1383         default:
1384           g_assert_not_reached ();
1385         }
1386     }
1387
1388   if (length)
1389     *length = size - 1;
1390
1391   return data;
1392 }
1393
1394 /**
1395  * g_variant_dup_string:
1396  * @value: a string #GVariant instance
1397  * @length: (out): a pointer to a #gsize, to store the length
1398  * @returns: (transfer full): a newly allocated string, utf8 encoded
1399  *
1400  * Similar to g_variant_get_string() except that instead of returning
1401  * a constant string, the string is duplicated.
1402  *
1403  * The string will always be utf8 encoded.
1404  *
1405  * The return value must be freed using g_free().
1406  *
1407  * Since: 2.24
1408  **/
1409 gchar *
1410 g_variant_dup_string (GVariant *value,
1411                       gsize    *length)
1412 {
1413   return g_strdup (g_variant_get_string (value, length));
1414 }
1415
1416 /**
1417  * g_variant_new_strv:
1418  * @strv: (array length=length) (element-type utf8): an array of strings
1419  * @length: the length of @strv, or -1
1420  * @returns: (transfer none): a new floating #GVariant instance
1421  *
1422  * Constructs an array of strings #GVariant from the given array of
1423  * strings.
1424  *
1425  * If @length is -1 then @strv is %NULL-terminated.
1426  *
1427  * Since: 2.24
1428  **/
1429 GVariant *
1430 g_variant_new_strv (const gchar * const *strv,
1431                     gssize               length)
1432 {
1433   GVariant **strings;
1434   gsize i;
1435
1436   g_return_val_if_fail (length == 0 || strv != NULL, NULL);
1437
1438   if (length < 0)
1439     length = g_strv_length ((gchar **) strv);
1440
1441   strings = g_new (GVariant *, length);
1442   for (i = 0; i < length; i++)
1443     strings[i] = g_variant_ref_sink (g_variant_new_string (strv[i]));
1444
1445   return g_variant_new_from_children (G_VARIANT_TYPE_STRING_ARRAY,
1446                                       strings, length, TRUE);
1447 }
1448
1449 /**
1450  * g_variant_get_strv:
1451  * @value: an array of strings #GVariant
1452  * @length: (out) (allow-none): the length of the result, or %NULL
1453  * @returns: (array length=length zero-terminated=1) (transfer container): an array of constant
1454  * strings
1455  *
1456  * Gets the contents of an array of strings #GVariant.  This call
1457  * makes a shallow copy; the return result should be released with
1458  * g_free(), but the individual strings must not be modified.
1459  *
1460  * If @length is non-%NULL then the number of elements in the result
1461  * is stored there.  In any case, the resulting array will be
1462  * %NULL-terminated.
1463  *
1464  * For an empty array, @length will be set to 0 and a pointer to a
1465  * %NULL pointer will be returned.
1466  *
1467  * Since: 2.24
1468  **/
1469 const gchar **
1470 g_variant_get_strv (GVariant *value,
1471                     gsize    *length)
1472 {
1473   const gchar **strv;
1474   gsize n;
1475   gsize i;
1476
1477   TYPE_CHECK (value, G_VARIANT_TYPE_STRING_ARRAY, NULL);
1478
1479   g_variant_get_data (value);
1480   n = g_variant_n_children (value);
1481   strv = g_new (const gchar *, n + 1);
1482
1483   for (i = 0; i < n; i++)
1484     {
1485       GVariant *string;
1486
1487       string = g_variant_get_child_value (value, i);
1488       strv[i] = g_variant_get_string (string, NULL);
1489       g_variant_unref (string);
1490     }
1491   strv[i] = NULL;
1492
1493   if (length)
1494     *length = n;
1495
1496   return strv;
1497 }
1498
1499 /**
1500  * g_variant_dup_strv:
1501  * @value: an array of strings #GVariant
1502  * @length: (out) (allow-none): the length of the result, or %NULL
1503  * @returns: (array length=length zero-terminated=1) (transfer full): an array of strings
1504  *
1505  * Gets the contents of an array of strings #GVariant.  This call
1506  * makes a deep copy; the return result should be released with
1507  * g_strfreev().
1508  *
1509  * If @length is non-%NULL then the number of elements in the result
1510  * is stored there.  In any case, the resulting array will be
1511  * %NULL-terminated.
1512  *
1513  * For an empty array, @length will be set to 0 and a pointer to a
1514  * %NULL pointer will be returned.
1515  *
1516  * Since: 2.24
1517  **/
1518 gchar **
1519 g_variant_dup_strv (GVariant *value,
1520                     gsize    *length)
1521 {
1522   gchar **strv;
1523   gsize n;
1524   gsize i;
1525
1526   TYPE_CHECK (value, G_VARIANT_TYPE_STRING_ARRAY, NULL);
1527
1528   n = g_variant_n_children (value);
1529   strv = g_new (gchar *, n + 1);
1530
1531   for (i = 0; i < n; i++)
1532     {
1533       GVariant *string;
1534
1535       string = g_variant_get_child_value (value, i);
1536       strv[i] = g_variant_dup_string (string, NULL);
1537       g_variant_unref (string);
1538     }
1539   strv[i] = NULL;
1540
1541   if (length)
1542     *length = n;
1543
1544   return strv;
1545 }
1546
1547 /**
1548  * g_variant_new_objv:
1549  * @strv: (array length=length) (element-type utf8): an array of strings
1550  * @length: the length of @strv, or -1
1551  * @returns: (transfer none): a new floating #GVariant instance
1552  *
1553  * Constructs an array of object paths #GVariant from the given array of
1554  * strings.
1555  *
1556  * Each string must be a valid #GVariant object path; see
1557  * g_variant_is_object_path().
1558  *
1559  * If @length is -1 then @strv is %NULL-terminated.
1560  *
1561  * Since: 2.30
1562  **/
1563 GVariant *
1564 g_variant_new_objv (const gchar * const *strv,
1565                     gssize               length)
1566 {
1567   GVariant **strings;
1568   gsize i;
1569
1570   g_return_val_if_fail (length == 0 || strv != NULL, NULL);
1571
1572   if (length < 0)
1573     length = g_strv_length ((gchar **) strv);
1574
1575   strings = g_new (GVariant *, length);
1576   for (i = 0; i < length; i++)
1577     strings[i] = g_variant_ref_sink (g_variant_new_object_path (strv[i]));
1578
1579   return g_variant_new_from_children (G_VARIANT_TYPE_OBJECT_PATH_ARRAY,
1580                                       strings, length, TRUE);
1581 }
1582
1583 /**
1584  * g_variant_get_objv:
1585  * @value: an array of object paths #GVariant
1586  * @length: (out) (allow-none): the length of the result, or %NULL
1587  * @returns: (array length=length zero-terminated=1) (transfer container): an array of constant
1588  * strings
1589  *
1590  * Gets the contents of an array of object paths #GVariant.  This call
1591  * makes a shallow copy; the return result should be released with
1592  * g_free(), but the individual strings must not be modified.
1593  *
1594  * If @length is non-%NULL then the number of elements in the result
1595  * is stored there.  In any case, the resulting array will be
1596  * %NULL-terminated.
1597  *
1598  * For an empty array, @length will be set to 0 and a pointer to a
1599  * %NULL pointer will be returned.
1600  *
1601  * Since: 2.30
1602  **/
1603 const gchar **
1604 g_variant_get_objv (GVariant *value,
1605                     gsize    *length)
1606 {
1607   const gchar **strv;
1608   gsize n;
1609   gsize i;
1610
1611   TYPE_CHECK (value, G_VARIANT_TYPE_OBJECT_PATH_ARRAY, NULL);
1612
1613   g_variant_get_data (value);
1614   n = g_variant_n_children (value);
1615   strv = g_new (const gchar *, n + 1);
1616
1617   for (i = 0; i < n; i++)
1618     {
1619       GVariant *string;
1620
1621       string = g_variant_get_child_value (value, i);
1622       strv[i] = g_variant_get_string (string, NULL);
1623       g_variant_unref (string);
1624     }
1625   strv[i] = NULL;
1626
1627   if (length)
1628     *length = n;
1629
1630   return strv;
1631 }
1632
1633 /**
1634  * g_variant_dup_objv:
1635  * @value: an array of object paths #GVariant
1636  * @length: (out) (allow-none): the length of the result, or %NULL
1637  * @returns: (array length=length zero-terminated=1) (transfer full): an array of strings
1638  *
1639  * Gets the contents of an array of object paths #GVariant.  This call
1640  * makes a deep copy; the return result should be released with
1641  * g_strfreev().
1642  *
1643  * If @length is non-%NULL then the number of elements in the result
1644  * is stored there.  In any case, the resulting array will be
1645  * %NULL-terminated.
1646  *
1647  * For an empty array, @length will be set to 0 and a pointer to a
1648  * %NULL pointer will be returned.
1649  *
1650  * Since: 2.30
1651  **/
1652 gchar **
1653 g_variant_dup_objv (GVariant *value,
1654                     gsize    *length)
1655 {
1656   gchar **strv;
1657   gsize n;
1658   gsize i;
1659
1660   TYPE_CHECK (value, G_VARIANT_TYPE_OBJECT_PATH_ARRAY, NULL);
1661
1662   n = g_variant_n_children (value);
1663   strv = g_new (gchar *, n + 1);
1664
1665   for (i = 0; i < n; i++)
1666     {
1667       GVariant *string;
1668
1669       string = g_variant_get_child_value (value, i);
1670       strv[i] = g_variant_dup_string (string, NULL);
1671       g_variant_unref (string);
1672     }
1673   strv[i] = NULL;
1674
1675   if (length)
1676     *length = n;
1677
1678   return strv;
1679 }
1680
1681
1682 /**
1683  * g_variant_new_bytestring:
1684  * @string: (array zero-terminated=1) (element-type guint8): a normal
1685  *          nul-terminated string in no particular encoding
1686  * @returns: (transfer none): a floating reference to a new bytestring #GVariant instance
1687  *
1688  * Creates an array-of-bytes #GVariant with the contents of @string.
1689  * This function is just like g_variant_new_string() except that the
1690  * string need not be valid utf8.
1691  *
1692  * The nul terminator character at the end of the string is stored in
1693  * the array.
1694  *
1695  * Since: 2.26
1696  **/
1697 GVariant *
1698 g_variant_new_bytestring (const gchar *string)
1699 {
1700   g_return_val_if_fail (string != NULL, NULL);
1701
1702   return g_variant_new_from_trusted (G_VARIANT_TYPE_BYTESTRING,
1703                                      string, strlen (string) + 1);
1704 }
1705
1706 /**
1707  * g_variant_get_bytestring:
1708  * @value: an array-of-bytes #GVariant instance
1709  * @returns: (transfer none) (array zero-terminated=1) (element-type guint8):
1710  *           the constant string
1711  *
1712  * Returns the string value of a #GVariant instance with an
1713  * array-of-bytes type.  The string has no particular encoding.
1714  *
1715  * If the array does not end with a nul terminator character, the empty
1716  * string is returned.  For this reason, you can always trust that a
1717  * non-%NULL nul-terminated string will be returned by this function.
1718  *
1719  * If the array contains a nul terminator character somewhere other than
1720  * the last byte then the returned string is the string, up to the first
1721  * such nul character.
1722  *
1723  * It is an error to call this function with a @value that is not an
1724  * array of bytes.
1725  *
1726  * The return value remains valid as long as @value exists.
1727  *
1728  * Since: 2.26
1729  **/
1730 const gchar *
1731 g_variant_get_bytestring (GVariant *value)
1732 {
1733   const gchar *string;
1734   gsize size;
1735
1736   TYPE_CHECK (value, G_VARIANT_TYPE_BYTESTRING, NULL);
1737
1738   /* Won't be NULL since this is an array type */
1739   string = g_variant_get_data (value);
1740   size = g_variant_get_size (value);
1741
1742   if (size && string[size - 1] == '\0')
1743     return string;
1744   else
1745     return "";
1746 }
1747
1748 /**
1749  * g_variant_dup_bytestring:
1750  * @value: an array-of-bytes #GVariant instance
1751  * @length: (out) (allow-none) (default NULL): a pointer to a #gsize, to store
1752  *          the length (not including the nul terminator)
1753  * @returns: (transfer full) (array zero-terminated=1 length=length)
1754  *           (element-type guint8): a newly allocated string
1755  *
1756  * Similar to g_variant_get_bytestring() except that instead of
1757  * returning a constant string, the string is duplicated.
1758  *
1759  * The return value must be freed using g_free().
1760  *
1761  * Since: 2.26
1762  **/
1763 gchar *
1764 g_variant_dup_bytestring (GVariant *value,
1765                           gsize    *length)
1766 {
1767   const gchar *original = g_variant_get_bytestring (value);
1768   gsize size;
1769
1770   /* don't crash in case get_bytestring() had an assert failure */
1771   if (original == NULL)
1772     return NULL;
1773
1774   size = strlen (original);
1775
1776   if (length)
1777     *length = size;
1778
1779   return g_memdup (original, size + 1);
1780 }
1781
1782 /**
1783  * g_variant_new_bytestring_array:
1784  * @strv: (array length=length): an array of strings
1785  * @length: the length of @strv, or -1
1786  * @returns: (transfer none): a new floating #GVariant instance
1787  *
1788  * Constructs an array of bytestring #GVariant from the given array of
1789  * strings.
1790  *
1791  * If @length is -1 then @strv is %NULL-terminated.
1792  *
1793  * Since: 2.26
1794  **/
1795 GVariant *
1796 g_variant_new_bytestring_array (const gchar * const *strv,
1797                                 gssize               length)
1798 {
1799   GVariant **strings;
1800   gsize i;
1801
1802   g_return_val_if_fail (length == 0 || strv != NULL, NULL);
1803
1804   if (length < 0)
1805     length = g_strv_length ((gchar **) strv);
1806
1807   strings = g_new (GVariant *, length);
1808   for (i = 0; i < length; i++)
1809     strings[i] = g_variant_ref_sink (g_variant_new_bytestring (strv[i]));
1810
1811   return g_variant_new_from_children (G_VARIANT_TYPE_BYTESTRING_ARRAY,
1812                                       strings, length, TRUE);
1813 }
1814
1815 /**
1816  * g_variant_get_bytestring_array:
1817  * @value: an array of array of bytes #GVariant ('aay')
1818  * @length: (out) (allow-none): the length of the result, or %NULL
1819  * @returns: (array length=length) (transfer container): an array of constant strings
1820  *
1821  * Gets the contents of an array of array of bytes #GVariant.  This call
1822  * makes a shallow copy; the return result should be released with
1823  * g_free(), but the individual strings must not be modified.
1824  *
1825  * If @length is non-%NULL then the number of elements in the result is
1826  * stored there.  In any case, the resulting array will be
1827  * %NULL-terminated.
1828  *
1829  * For an empty array, @length will be set to 0 and a pointer to a
1830  * %NULL pointer will be returned.
1831  *
1832  * Since: 2.26
1833  **/
1834 const gchar **
1835 g_variant_get_bytestring_array (GVariant *value,
1836                                 gsize    *length)
1837 {
1838   const gchar **strv;
1839   gsize n;
1840   gsize i;
1841
1842   TYPE_CHECK (value, G_VARIANT_TYPE_BYTESTRING_ARRAY, NULL);
1843
1844   g_variant_get_data (value);
1845   n = g_variant_n_children (value);
1846   strv = g_new (const gchar *, n + 1);
1847
1848   for (i = 0; i < n; i++)
1849     {
1850       GVariant *string;
1851
1852       string = g_variant_get_child_value (value, i);
1853       strv[i] = g_variant_get_bytestring (string);
1854       g_variant_unref (string);
1855     }
1856   strv[i] = NULL;
1857
1858   if (length)
1859     *length = n;
1860
1861   return strv;
1862 }
1863
1864 /**
1865  * g_variant_dup_bytestring_array:
1866  * @value: an array of array of bytes #GVariant ('aay')
1867  * @length: (out) (allow-none): the length of the result, or %NULL
1868  * @returns: (array length=length) (transfer full): an array of strings
1869  *
1870  * Gets the contents of an array of array of bytes #GVariant.  This call
1871  * makes a deep copy; the return result should be released with
1872  * g_strfreev().
1873  *
1874  * If @length is non-%NULL then the number of elements in the result is
1875  * stored there.  In any case, the resulting array will be
1876  * %NULL-terminated.
1877  *
1878  * For an empty array, @length will be set to 0 and a pointer to a
1879  * %NULL pointer will be returned.
1880  *
1881  * Since: 2.26
1882  **/
1883 gchar **
1884 g_variant_dup_bytestring_array (GVariant *value,
1885                                 gsize    *length)
1886 {
1887   gchar **strv;
1888   gsize n;
1889   gsize i;
1890
1891   TYPE_CHECK (value, G_VARIANT_TYPE_BYTESTRING_ARRAY, NULL);
1892
1893   g_variant_get_data (value);
1894   n = g_variant_n_children (value);
1895   strv = g_new (gchar *, n + 1);
1896
1897   for (i = 0; i < n; i++)
1898     {
1899       GVariant *string;
1900
1901       string = g_variant_get_child_value (value, i);
1902       strv[i] = g_variant_dup_bytestring (string, NULL);
1903       g_variant_unref (string);
1904     }
1905   strv[i] = NULL;
1906
1907   if (length)
1908     *length = n;
1909
1910   return strv;
1911 }
1912
1913 /* Type checking and querying {{{1 */
1914 /**
1915  * g_variant_get_type:
1916  * @value: a #GVariant
1917  * @returns: a #GVariantType
1918  *
1919  * Determines the type of @value.
1920  *
1921  * The return value is valid for the lifetime of @value and must not
1922  * be freed.
1923  *
1924  * Since: 2.24
1925  **/
1926 const GVariantType *
1927 g_variant_get_type (GVariant *value)
1928 {
1929   GVariantTypeInfo *type_info;
1930
1931   g_return_val_if_fail (value != NULL, NULL);
1932
1933   type_info = g_variant_get_type_info (value);
1934
1935   return (GVariantType *) g_variant_type_info_get_type_string (type_info);
1936 }
1937
1938 /**
1939  * g_variant_get_type_string:
1940  * @value: a #GVariant
1941  * @returns: the type string for the type of @value
1942  *
1943  * Returns the type string of @value.  Unlike the result of calling
1944  * g_variant_type_peek_string(), this string is nul-terminated.  This
1945  * string belongs to #GVariant and must not be freed.
1946  *
1947  * Since: 2.24
1948  **/
1949 const gchar *
1950 g_variant_get_type_string (GVariant *value)
1951 {
1952   GVariantTypeInfo *type_info;
1953
1954   g_return_val_if_fail (value != NULL, NULL);
1955
1956   type_info = g_variant_get_type_info (value);
1957
1958   return g_variant_type_info_get_type_string (type_info);
1959 }
1960
1961 /**
1962  * g_variant_is_of_type:
1963  * @value: a #GVariant instance
1964  * @type: a #GVariantType
1965  * @returns: %TRUE if the type of @value matches @type
1966  *
1967  * Checks if a value has a type matching the provided type.
1968  *
1969  * Since: 2.24
1970  **/
1971 gboolean
1972 g_variant_is_of_type (GVariant           *value,
1973                       const GVariantType *type)
1974 {
1975   return g_variant_type_is_subtype_of (g_variant_get_type (value), type);
1976 }
1977
1978 /**
1979  * g_variant_is_container:
1980  * @value: a #GVariant instance
1981  * @returns: %TRUE if @value is a container
1982  *
1983  * Checks if @value is a container.
1984  */
1985 gboolean
1986 g_variant_is_container (GVariant *value)
1987 {
1988   return g_variant_type_is_container (g_variant_get_type (value));
1989 }
1990
1991
1992 /**
1993  * g_variant_classify:
1994  * @value: a #GVariant
1995  * @returns: the #GVariantClass of @value
1996  *
1997  * Classifies @value according to its top-level type.
1998  *
1999  * Since: 2.24
2000  **/
2001 /**
2002  * GVariantClass:
2003  * @G_VARIANT_CLASS_BOOLEAN: The #GVariant is a boolean.
2004  * @G_VARIANT_CLASS_BYTE: The #GVariant is a byte.
2005  * @G_VARIANT_CLASS_INT16: The #GVariant is a signed 16 bit integer.
2006  * @G_VARIANT_CLASS_UINT16: The #GVariant is an unsigned 16 bit integer.
2007  * @G_VARIANT_CLASS_INT32: The #GVariant is a signed 32 bit integer.
2008  * @G_VARIANT_CLASS_UINT32: The #GVariant is an unsigned 32 bit integer.
2009  * @G_VARIANT_CLASS_INT64: The #GVariant is a signed 64 bit integer.
2010  * @G_VARIANT_CLASS_UINT64: The #GVariant is an unsigned 64 bit integer.
2011  * @G_VARIANT_CLASS_HANDLE: The #GVariant is a file handle index.
2012  * @G_VARIANT_CLASS_DOUBLE: The #GVariant is a double precision floating 
2013  *                          point value.
2014  * @G_VARIANT_CLASS_STRING: The #GVariant is a normal string.
2015  * @G_VARIANT_CLASS_OBJECT_PATH: The #GVariant is a D-Bus object path 
2016  *                               string.
2017  * @G_VARIANT_CLASS_SIGNATURE: The #GVariant is a D-Bus signature string.
2018  * @G_VARIANT_CLASS_VARIANT: The #GVariant is a variant.
2019  * @G_VARIANT_CLASS_MAYBE: The #GVariant is a maybe-typed value.
2020  * @G_VARIANT_CLASS_ARRAY: The #GVariant is an array.
2021  * @G_VARIANT_CLASS_TUPLE: The #GVariant is a tuple.
2022  * @G_VARIANT_CLASS_DICT_ENTRY: The #GVariant is a dictionary entry.
2023  *
2024  * The range of possible top-level types of #GVariant instances.
2025  *
2026  * Since: 2.24
2027  **/
2028 GVariantClass
2029 g_variant_classify (GVariant *value)
2030 {
2031   g_return_val_if_fail (value != NULL, 0);
2032
2033   return *g_variant_get_type_string (value);
2034 }
2035
2036 /* Pretty printer {{{1 */
2037 /* This function is not introspectable because if @string is NULL, 
2038    @returns is (transfer full), otherwise it is (transfer none), which
2039    is not supported by GObjectIntrospection */
2040 /**
2041  * g_variant_print_string: (skip)
2042  * @value: a #GVariant
2043  * @string: (allow-none) (default NULL): a #GString, or %NULL
2044  * @type_annotate: %TRUE if type information should be included in
2045  *                 the output
2046  * @returns: a #GString containing the string
2047  *
2048  * Behaves as g_variant_print(), but operates on a #GString.
2049  *
2050  * If @string is non-%NULL then it is appended to and returned.  Else,
2051  * a new empty #GString is allocated and it is returned.
2052  *
2053  * Since: 2.24
2054  **/
2055 GString *
2056 g_variant_print_string (GVariant *value,
2057                         GString  *string,
2058                         gboolean  type_annotate)
2059 {
2060   if G_UNLIKELY (string == NULL)
2061     string = g_string_new (NULL);
2062
2063   switch (g_variant_classify (value))
2064     {
2065     case G_VARIANT_CLASS_MAYBE:
2066       if (type_annotate)
2067         g_string_append_printf (string, "@%s ",
2068                                 g_variant_get_type_string (value));
2069
2070       if (g_variant_n_children (value))
2071         {
2072           gchar *printed_child;
2073           GVariant *element;
2074
2075           /* Nested maybes:
2076            *
2077            * Consider the case of the type "mmi".  In this case we could
2078            * write "just just 4", but "4" alone is totally unambiguous,
2079            * so we try to drop "just" where possible.
2080            *
2081            * We have to be careful not to always drop "just", though,
2082            * since "nothing" needs to be distinguishable from "just
2083            * nothing".  The case where we need to ensure we keep the
2084            * "just" is actually exactly the case where we have a nested
2085            * Nothing.
2086            *
2087            * Instead of searching for that nested Nothing, we just print
2088            * the contained value into a separate string and see if we
2089            * end up with "nothing" at the end of it.  If so, we need to
2090            * add "just" at our level.
2091            */
2092           element = g_variant_get_child_value (value, 0);
2093           printed_child = g_variant_print (element, FALSE);
2094           g_variant_unref (element);
2095
2096           if (g_str_has_suffix (printed_child, "nothing"))
2097             g_string_append (string, "just ");
2098           g_string_append (string, printed_child);
2099           g_free (printed_child);
2100         }
2101       else
2102         g_string_append (string, "nothing");
2103
2104       break;
2105
2106     case G_VARIANT_CLASS_ARRAY:
2107       /* it's an array so the first character of the type string is 'a'
2108        *
2109        * if the first two characters are 'ay' then it's a bytestring.
2110        * under certain conditions we print those as strings.
2111        */
2112       if (g_variant_get_type_string (value)[1] == 'y')
2113         {
2114           const gchar *str;
2115           gsize size;
2116           gsize i;
2117
2118           /* first determine if it is a byte string.
2119            * that's when there's a single nul character: at the end.
2120            */
2121           str = g_variant_get_data (value);
2122           size = g_variant_get_size (value);
2123
2124           for (i = 0; i < size; i++)
2125             if (str[i] == '\0')
2126               break;
2127
2128           /* first nul byte is the last byte -> it's a byte string. */
2129           if (i == size - 1)
2130             {
2131               gchar *escaped = g_strescape (str, NULL);
2132
2133               /* use double quotes only if a ' is in the string */
2134               if (strchr (str, '\''))
2135                 g_string_append_printf (string, "b\"%s\"", escaped);
2136               else
2137                 g_string_append_printf (string, "b'%s'", escaped);
2138
2139               g_free (escaped);
2140               break;
2141             }
2142
2143           else
2144             /* fall through and handle normally... */;
2145         }
2146
2147       /*
2148        * if the first two characters are 'a{' then it's an array of
2149        * dictionary entries (ie: a dictionary) so we print that
2150        * differently.
2151        */
2152       if (g_variant_get_type_string (value)[1] == '{')
2153         /* dictionary */
2154         {
2155           const gchar *comma = "";
2156           gsize n, i;
2157
2158           if ((n = g_variant_n_children (value)) == 0)
2159             {
2160               if (type_annotate)
2161                 g_string_append_printf (string, "@%s ",
2162                                         g_variant_get_type_string (value));
2163               g_string_append (string, "{}");
2164               break;
2165             }
2166
2167           g_string_append_c (string, '{');
2168           for (i = 0; i < n; i++)
2169             {
2170               GVariant *entry, *key, *val;
2171
2172               g_string_append (string, comma);
2173               comma = ", ";
2174
2175               entry = g_variant_get_child_value (value, i);
2176               key = g_variant_get_child_value (entry, 0);
2177               val = g_variant_get_child_value (entry, 1);
2178               g_variant_unref (entry);
2179
2180               g_variant_print_string (key, string, type_annotate);
2181               g_variant_unref (key);
2182               g_string_append (string, ": ");
2183               g_variant_print_string (val, string, type_annotate);
2184               g_variant_unref (val);
2185               type_annotate = FALSE;
2186             }
2187           g_string_append_c (string, '}');
2188         }
2189       else
2190         /* normal (non-dictionary) array */
2191         {
2192           const gchar *comma = "";
2193           gsize n, i;
2194
2195           if ((n = g_variant_n_children (value)) == 0)
2196             {
2197               if (type_annotate)
2198                 g_string_append_printf (string, "@%s ",
2199                                         g_variant_get_type_string (value));
2200               g_string_append (string, "[]");
2201               break;
2202             }
2203
2204           g_string_append_c (string, '[');
2205           for (i = 0; i < n; i++)
2206             {
2207               GVariant *element;
2208
2209               g_string_append (string, comma);
2210               comma = ", ";
2211
2212               element = g_variant_get_child_value (value, i);
2213
2214               g_variant_print_string (element, string, type_annotate);
2215               g_variant_unref (element);
2216               type_annotate = FALSE;
2217             }
2218           g_string_append_c (string, ']');
2219         }
2220
2221       break;
2222
2223     case G_VARIANT_CLASS_TUPLE:
2224       {
2225         gsize n, i;
2226
2227         n = g_variant_n_children (value);
2228
2229         g_string_append_c (string, '(');
2230         for (i = 0; i < n; i++)
2231           {
2232             GVariant *element;
2233
2234             element = g_variant_get_child_value (value, i);
2235             g_variant_print_string (element, string, type_annotate);
2236             g_string_append (string, ", ");
2237             g_variant_unref (element);
2238           }
2239
2240         /* for >1 item:  remove final ", "
2241          * for 1 item:   remove final " ", but leave the ","
2242          * for 0 items:  there is only "(", so remove nothing
2243          */
2244         g_string_truncate (string, string->len - (n > 0) - (n > 1));
2245         g_string_append_c (string, ')');
2246       }
2247       break;
2248
2249     case G_VARIANT_CLASS_DICT_ENTRY:
2250       {
2251         GVariant *element;
2252
2253         g_string_append_c (string, '{');
2254
2255         element = g_variant_get_child_value (value, 0);
2256         g_variant_print_string (element, string, type_annotate);
2257         g_variant_unref (element);
2258
2259         g_string_append (string, ", ");
2260
2261         element = g_variant_get_child_value (value, 1);
2262         g_variant_print_string (element, string, type_annotate);
2263         g_variant_unref (element);
2264
2265         g_string_append_c (string, '}');
2266       }
2267       break;
2268
2269     case G_VARIANT_CLASS_VARIANT:
2270       {
2271         GVariant *child = g_variant_get_variant (value);
2272
2273         /* Always annotate types in nested variants, because they are
2274          * (by nature) of variable type.
2275          */
2276         g_string_append_c (string, '<');
2277         g_variant_print_string (child, string, TRUE);
2278         g_string_append_c (string, '>');
2279
2280         g_variant_unref (child);
2281       }
2282       break;
2283
2284     case G_VARIANT_CLASS_BOOLEAN:
2285       if (g_variant_get_boolean (value))
2286         g_string_append (string, "true");
2287       else
2288         g_string_append (string, "false");
2289       break;
2290
2291     case G_VARIANT_CLASS_STRING:
2292       {
2293         const gchar *str = g_variant_get_string (value, NULL);
2294         gunichar quote = strchr (str, '\'') ? '"' : '\'';
2295
2296         g_string_append_c (string, quote);
2297
2298         while (*str)
2299           {
2300             gunichar c = g_utf8_get_char (str);
2301
2302             if (c == quote || c == '\\')
2303               g_string_append_c (string, '\\');
2304
2305             if (g_unichar_isprint (c))
2306               g_string_append_unichar (string, c);
2307
2308             else
2309               {
2310                 g_string_append_c (string, '\\');
2311                 if (c < 0x10000)
2312                   switch (c)
2313                     {
2314                     case '\a':
2315                       g_string_append_c (string, 'a');
2316                       break;
2317
2318                     case '\b':
2319                       g_string_append_c (string, 'b');
2320                       break;
2321
2322                     case '\f':
2323                       g_string_append_c (string, 'f');
2324                       break;
2325
2326                     case '\n':
2327                       g_string_append_c (string, 'n');
2328                       break;
2329
2330                     case '\r':
2331                       g_string_append_c (string, 'r');
2332                       break;
2333
2334                     case '\t':
2335                       g_string_append_c (string, 't');
2336                       break;
2337
2338                     case '\v':
2339                       g_string_append_c (string, 'v');
2340                       break;
2341
2342                     default:
2343                       g_string_append_printf (string, "u%04x", c);
2344                       break;
2345                     }
2346                  else
2347                    g_string_append_printf (string, "U%08x", c);
2348               }
2349
2350             str = g_utf8_next_char (str);
2351           }
2352
2353         g_string_append_c (string, quote);
2354       }
2355       break;
2356
2357     case G_VARIANT_CLASS_BYTE:
2358       if (type_annotate)
2359         g_string_append (string, "byte ");
2360       g_string_append_printf (string, "0x%02x",
2361                               g_variant_get_byte (value));
2362       break;
2363
2364     case G_VARIANT_CLASS_INT16:
2365       if (type_annotate)
2366         g_string_append (string, "int16 ");
2367       g_string_append_printf (string, "%"G_GINT16_FORMAT,
2368                               g_variant_get_int16 (value));
2369       break;
2370
2371     case G_VARIANT_CLASS_UINT16:
2372       if (type_annotate)
2373         g_string_append (string, "uint16 ");
2374       g_string_append_printf (string, "%"G_GUINT16_FORMAT,
2375                               g_variant_get_uint16 (value));
2376       break;
2377
2378     case G_VARIANT_CLASS_INT32:
2379       /* Never annotate this type because it is the default for numbers
2380        * (and this is a *pretty* printer)
2381        */
2382       g_string_append_printf (string, "%"G_GINT32_FORMAT,
2383                               g_variant_get_int32 (value));
2384       break;
2385
2386     case G_VARIANT_CLASS_HANDLE:
2387       if (type_annotate)
2388         g_string_append (string, "handle ");
2389       g_string_append_printf (string, "%"G_GINT32_FORMAT,
2390                               g_variant_get_handle (value));
2391       break;
2392
2393     case G_VARIANT_CLASS_UINT32:
2394       if (type_annotate)
2395         g_string_append (string, "uint32 ");
2396       g_string_append_printf (string, "%"G_GUINT32_FORMAT,
2397                               g_variant_get_uint32 (value));
2398       break;
2399
2400     case G_VARIANT_CLASS_INT64:
2401       if (type_annotate)
2402         g_string_append (string, "int64 ");
2403       g_string_append_printf (string, "%"G_GINT64_FORMAT,
2404                               g_variant_get_int64 (value));
2405       break;
2406
2407     case G_VARIANT_CLASS_UINT64:
2408       if (type_annotate)
2409         g_string_append (string, "uint64 ");
2410       g_string_append_printf (string, "%"G_GUINT64_FORMAT,
2411                               g_variant_get_uint64 (value));
2412       break;
2413
2414     case G_VARIANT_CLASS_DOUBLE:
2415       {
2416         gchar buffer[100];
2417         gint i;
2418
2419         g_ascii_dtostr (buffer, sizeof buffer, g_variant_get_double (value));
2420
2421         for (i = 0; buffer[i]; i++)
2422           if (buffer[i] == '.' || buffer[i] == 'e' ||
2423               buffer[i] == 'n' || buffer[i] == 'N')
2424             break;
2425
2426         /* if there is no '.' or 'e' in the float then add one */
2427         if (buffer[i] == '\0')
2428           {
2429             buffer[i++] = '.';
2430             buffer[i++] = '0';
2431             buffer[i++] = '\0';
2432           }
2433
2434         g_string_append (string, buffer);
2435       }
2436       break;
2437
2438     case G_VARIANT_CLASS_OBJECT_PATH:
2439       if (type_annotate)
2440         g_string_append (string, "objectpath ");
2441       g_string_append_printf (string, "\'%s\'",
2442                               g_variant_get_string (value, NULL));
2443       break;
2444
2445     case G_VARIANT_CLASS_SIGNATURE:
2446       if (type_annotate)
2447         g_string_append (string, "signature ");
2448       g_string_append_printf (string, "\'%s\'",
2449                               g_variant_get_string (value, NULL));
2450       break;
2451
2452     default:
2453       g_assert_not_reached ();
2454   }
2455
2456   return string;
2457 }
2458
2459 /**
2460  * g_variant_print:
2461  * @value: a #GVariant
2462  * @type_annotate: %TRUE if type information should be included in
2463  *                 the output
2464  * @returns: (transfer full): a newly-allocated string holding the result.
2465  *
2466  * Pretty-prints @value in the format understood by g_variant_parse().
2467  *
2468  * The format is described <link linkend='gvariant-text'>here</link>.
2469  *
2470  * If @type_annotate is %TRUE, then type information is included in
2471  * the output.
2472  */
2473 gchar *
2474 g_variant_print (GVariant *value,
2475                  gboolean  type_annotate)
2476 {
2477   return g_string_free (g_variant_print_string (value, NULL, type_annotate),
2478                         FALSE);
2479 };
2480
2481 /* Hash, Equal, Compare {{{1 */
2482 /**
2483  * g_variant_hash:
2484  * @value: (type GVariant): a basic #GVariant value as a #gconstpointer
2485  * @returns: a hash value corresponding to @value
2486  *
2487  * Generates a hash value for a #GVariant instance.
2488  *
2489  * The output of this function is guaranteed to be the same for a given
2490  * value only per-process.  It may change between different processor
2491  * architectures or even different versions of GLib.  Do not use this
2492  * function as a basis for building protocols or file formats.
2493  *
2494  * The type of @value is #gconstpointer only to allow use of this
2495  * function with #GHashTable.  @value must be a #GVariant.
2496  *
2497  * Since: 2.24
2498  **/
2499 guint
2500 g_variant_hash (gconstpointer value_)
2501 {
2502   GVariant *value = (GVariant *) value_;
2503
2504   switch (g_variant_classify (value))
2505     {
2506     case G_VARIANT_CLASS_STRING:
2507     case G_VARIANT_CLASS_OBJECT_PATH:
2508     case G_VARIANT_CLASS_SIGNATURE:
2509       return g_str_hash (g_variant_get_string (value, NULL));
2510
2511     case G_VARIANT_CLASS_BOOLEAN:
2512       /* this is a very odd thing to hash... */
2513       return g_variant_get_boolean (value);
2514
2515     case G_VARIANT_CLASS_BYTE:
2516       return g_variant_get_byte (value);
2517
2518     case G_VARIANT_CLASS_INT16:
2519     case G_VARIANT_CLASS_UINT16:
2520       {
2521         const guint16 *ptr;
2522
2523         ptr = g_variant_get_data (value);
2524
2525         if (ptr)
2526           return *ptr;
2527         else
2528           return 0;
2529       }
2530
2531     case G_VARIANT_CLASS_INT32:
2532     case G_VARIANT_CLASS_UINT32:
2533     case G_VARIANT_CLASS_HANDLE:
2534       {
2535         const guint *ptr;
2536
2537         ptr = g_variant_get_data (value);
2538
2539         if (ptr)
2540           return *ptr;
2541         else
2542           return 0;
2543       }
2544
2545     case G_VARIANT_CLASS_INT64:
2546     case G_VARIANT_CLASS_UINT64:
2547     case G_VARIANT_CLASS_DOUBLE:
2548       /* need a separate case for these guys because otherwise
2549        * performance could be quite bad on big endian systems
2550        */
2551       {
2552         const guint *ptr;
2553
2554         ptr = g_variant_get_data (value);
2555
2556         if (ptr)
2557           return ptr[0] + ptr[1];
2558         else
2559           return 0;
2560       }
2561
2562     default:
2563       g_return_val_if_fail (!g_variant_is_container (value), 0);
2564       g_assert_not_reached ();
2565     }
2566 }
2567
2568 /**
2569  * g_variant_equal:
2570  * @one: (type GVariant): a #GVariant instance
2571  * @two: (type GVariant): a #GVariant instance
2572  * @returns: %TRUE if @one and @two are equal
2573  *
2574  * Checks if @one and @two have the same type and value.
2575  *
2576  * The types of @one and @two are #gconstpointer only to allow use of
2577  * this function with #GHashTable.  They must each be a #GVariant.
2578  *
2579  * Since: 2.24
2580  **/
2581 gboolean
2582 g_variant_equal (gconstpointer one,
2583                  gconstpointer two)
2584 {
2585   gboolean equal;
2586
2587   g_return_val_if_fail (one != NULL && two != NULL, FALSE);
2588
2589   if (g_variant_get_type_info ((GVariant *) one) !=
2590       g_variant_get_type_info ((GVariant *) two))
2591     return FALSE;
2592
2593   /* if both values are trusted to be in their canonical serialised form
2594    * then a simple memcmp() of their serialised data will answer the
2595    * question.
2596    *
2597    * if not, then this might generate a false negative (since it is
2598    * possible for two different byte sequences to represent the same
2599    * value).  for now we solve this by pretty-printing both values and
2600    * comparing the result.
2601    */
2602   if (g_variant_is_trusted ((GVariant *) one) &&
2603       g_variant_is_trusted ((GVariant *) two))
2604     {
2605       gconstpointer data_one, data_two;
2606       gsize size_one, size_two;
2607
2608       size_one = g_variant_get_size ((GVariant *) one);
2609       size_two = g_variant_get_size ((GVariant *) two);
2610
2611       if (size_one != size_two)
2612         return FALSE;
2613
2614       data_one = g_variant_get_data ((GVariant *) one);
2615       data_two = g_variant_get_data ((GVariant *) two);
2616
2617       equal = memcmp (data_one, data_two, size_one) == 0;
2618     }
2619   else
2620     {
2621       gchar *strone, *strtwo;
2622
2623       strone = g_variant_print ((GVariant *) one, FALSE);
2624       strtwo = g_variant_print ((GVariant *) two, FALSE);
2625       equal = strcmp (strone, strtwo) == 0;
2626       g_free (strone);
2627       g_free (strtwo);
2628     }
2629
2630   return equal;
2631 }
2632
2633 /**
2634  * g_variant_compare:
2635  * @one: (type GVariant): a basic-typed #GVariant instance
2636  * @two: (type GVariant): a #GVariant instance of the same type
2637  * @returns: negative value if a &lt; b;
2638  *           zero if a = b;
2639  *           positive value if a &gt; b.
2640  *
2641  * Compares @one and @two.
2642  *
2643  * The types of @one and @two are #gconstpointer only to allow use of
2644  * this function with #GTree, #GPtrArray, etc.  They must each be a
2645  * #GVariant.
2646  *
2647  * Comparison is only defined for basic types (ie: booleans, numbers,
2648  * strings).  For booleans, %FALSE is less than %TRUE.  Numbers are
2649  * ordered in the usual way.  Strings are in ASCII lexographical order.
2650  *
2651  * It is a programmer error to attempt to compare container values or
2652  * two values that have types that are not exactly equal.  For example,
2653  * you cannot compare a 32-bit signed integer with a 32-bit unsigned
2654  * integer.  Also note that this function is not particularly
2655  * well-behaved when it comes to comparison of doubles; in particular,
2656  * the handling of incomparable values (ie: NaN) is undefined.
2657  *
2658  * If you only require an equality comparison, g_variant_equal() is more
2659  * general.
2660  *
2661  * Since: 2.26
2662  **/
2663 gint
2664 g_variant_compare (gconstpointer one,
2665                    gconstpointer two)
2666 {
2667   GVariant *a = (GVariant *) one;
2668   GVariant *b = (GVariant *) two;
2669
2670   g_return_val_if_fail (g_variant_classify (a) == g_variant_classify (b), 0);
2671
2672   switch (g_variant_classify (a))
2673     {
2674     case G_VARIANT_CLASS_BYTE:
2675       return ((gint) g_variant_get_byte (a)) -
2676              ((gint) g_variant_get_byte (b));
2677
2678     case G_VARIANT_CLASS_INT16:
2679       return ((gint) g_variant_get_int16 (a)) -
2680              ((gint) g_variant_get_int16 (b));
2681
2682     case G_VARIANT_CLASS_UINT16:
2683       return ((gint) g_variant_get_uint16 (a)) -
2684              ((gint) g_variant_get_uint16 (b));
2685
2686     case G_VARIANT_CLASS_INT32:
2687       {
2688         gint32 a_val = g_variant_get_int32 (a);
2689         gint32 b_val = g_variant_get_int32 (b);
2690
2691         return (a_val == b_val) ? 0 : (a_val > b_val) ? 1 : -1;
2692       }
2693
2694     case G_VARIANT_CLASS_UINT32:
2695       {
2696         guint32 a_val = g_variant_get_uint32 (a);
2697         guint32 b_val = g_variant_get_uint32 (b);
2698
2699         return (a_val == b_val) ? 0 : (a_val > b_val) ? 1 : -1;
2700       }
2701
2702     case G_VARIANT_CLASS_INT64:
2703       {
2704         gint64 a_val = g_variant_get_int64 (a);
2705         gint64 b_val = g_variant_get_int64 (b);
2706
2707         return (a_val == b_val) ? 0 : (a_val > b_val) ? 1 : -1;
2708       }
2709
2710     case G_VARIANT_CLASS_UINT64:
2711       {
2712         guint64 a_val = g_variant_get_uint64 (a);
2713         guint64 b_val = g_variant_get_uint64 (b);
2714
2715         return (a_val == b_val) ? 0 : (a_val > b_val) ? 1 : -1;
2716       }
2717
2718     case G_VARIANT_CLASS_DOUBLE:
2719       {
2720         gdouble a_val = g_variant_get_double (a);
2721         gdouble b_val = g_variant_get_double (b);
2722
2723         return (a_val == b_val) ? 0 : (a_val > b_val) ? 1 : -1;
2724       }
2725
2726     case G_VARIANT_CLASS_STRING:
2727     case G_VARIANT_CLASS_OBJECT_PATH:
2728     case G_VARIANT_CLASS_SIGNATURE:
2729       return strcmp (g_variant_get_string (a, NULL),
2730                      g_variant_get_string (b, NULL));
2731
2732     default:
2733       g_return_val_if_fail (!g_variant_is_container (a), 0);
2734       g_assert_not_reached ();
2735     }
2736 }
2737
2738 /* GVariantIter {{{1 */
2739 /**
2740  * GVariantIter: (skip)
2741  *
2742  * #GVariantIter is an opaque data structure and can only be accessed
2743  * using the following functions.
2744  **/
2745 struct stack_iter
2746 {
2747   GVariant *value;
2748   gssize n, i;
2749
2750   const gchar *loop_format;
2751
2752   gsize padding[3];
2753   gsize magic;
2754 };
2755
2756 G_STATIC_ASSERT (sizeof (struct stack_iter) <= sizeof (GVariantIter));
2757
2758 struct heap_iter
2759 {
2760   struct stack_iter iter;
2761
2762   GVariant *value_ref;
2763   gsize magic;
2764 };
2765
2766 #define GVSI(i)                 ((struct stack_iter *) (i))
2767 #define GVHI(i)                 ((struct heap_iter *) (i))
2768 #define GVSI_MAGIC              ((gsize) 3579507750u)
2769 #define GVHI_MAGIC              ((gsize) 1450270775u)
2770 #define is_valid_iter(i)        (i != NULL && \
2771                                  GVSI(i)->magic == GVSI_MAGIC)
2772 #define is_valid_heap_iter(i)   (GVHI(i)->magic == GVHI_MAGIC && \
2773                                  is_valid_iter(i))
2774
2775 /**
2776  * g_variant_iter_new:
2777  * @value: a container #GVariant
2778  * @returns: (transfer full): a new heap-allocated #GVariantIter
2779  *
2780  * Creates a heap-allocated #GVariantIter for iterating over the items
2781  * in @value.
2782  *
2783  * Use g_variant_iter_free() to free the return value when you no longer
2784  * need it.
2785  *
2786  * A reference is taken to @value and will be released only when
2787  * g_variant_iter_free() is called.
2788  *
2789  * Since: 2.24
2790  **/
2791 GVariantIter *
2792 g_variant_iter_new (GVariant *value)
2793 {
2794   GVariantIter *iter;
2795
2796   iter = (GVariantIter *) g_slice_new (struct heap_iter);
2797   GVHI(iter)->value_ref = g_variant_ref (value);
2798   GVHI(iter)->magic = GVHI_MAGIC;
2799
2800   g_variant_iter_init (iter, value);
2801
2802   return iter;
2803 }
2804
2805 /**
2806  * g_variant_iter_init: (skip)
2807  * @iter: a pointer to a #GVariantIter
2808  * @value: a container #GVariant
2809  * @returns: the number of items in @value
2810  *
2811  * Initialises (without allocating) a #GVariantIter.  @iter may be
2812  * completely uninitialised prior to this call; its old value is
2813  * ignored.
2814  *
2815  * The iterator remains valid for as long as @value exists, and need not
2816  * be freed in any way.
2817  *
2818  * Since: 2.24
2819  **/
2820 gsize
2821 g_variant_iter_init (GVariantIter *iter,
2822                      GVariant     *value)
2823 {
2824   GVSI(iter)->magic = GVSI_MAGIC;
2825   GVSI(iter)->value = value;
2826   GVSI(iter)->n = g_variant_n_children (value);
2827   GVSI(iter)->i = -1;
2828   GVSI(iter)->loop_format = NULL;
2829
2830   return GVSI(iter)->n;
2831 }
2832
2833 /**
2834  * g_variant_iter_copy:
2835  * @iter: a #GVariantIter
2836  * @returns: (transfer full): a new heap-allocated #GVariantIter
2837  *
2838  * Creates a new heap-allocated #GVariantIter to iterate over the
2839  * container that was being iterated over by @iter.  Iteration begins on
2840  * the new iterator from the current position of the old iterator but
2841  * the two copies are independent past that point.
2842  *
2843  * Use g_variant_iter_free() to free the return value when you no longer
2844  * need it.
2845  *
2846  * A reference is taken to the container that @iter is iterating over
2847  * and will be releated only when g_variant_iter_free() is called.
2848  *
2849  * Since: 2.24
2850  **/
2851 GVariantIter *
2852 g_variant_iter_copy (GVariantIter *iter)
2853 {
2854   GVariantIter *copy;
2855
2856   g_return_val_if_fail (is_valid_iter (iter), 0);
2857
2858   copy = g_variant_iter_new (GVSI(iter)->value);
2859   GVSI(copy)->i = GVSI(iter)->i;
2860
2861   return copy;
2862 }
2863
2864 /**
2865  * g_variant_iter_n_children:
2866  * @iter: a #GVariantIter
2867  * @returns: the number of children in the container
2868  *
2869  * Queries the number of child items in the container that we are
2870  * iterating over.  This is the total number of items -- not the number
2871  * of items remaining.
2872  *
2873  * This function might be useful for preallocation of arrays.
2874  *
2875  * Since: 2.24
2876  **/
2877 gsize
2878 g_variant_iter_n_children (GVariantIter *iter)
2879 {
2880   g_return_val_if_fail (is_valid_iter (iter), 0);
2881
2882   return GVSI(iter)->n;
2883 }
2884
2885 /**
2886  * g_variant_iter_free:
2887  * @iter: (transfer full): a heap-allocated #GVariantIter
2888  *
2889  * Frees a heap-allocated #GVariantIter.  Only call this function on
2890  * iterators that were returned by g_variant_iter_new() or
2891  * g_variant_iter_copy().
2892  *
2893  * Since: 2.24
2894  **/
2895 void
2896 g_variant_iter_free (GVariantIter *iter)
2897 {
2898   g_return_if_fail (is_valid_heap_iter (iter));
2899
2900   g_variant_unref (GVHI(iter)->value_ref);
2901   GVHI(iter)->magic = 0;
2902
2903   g_slice_free (struct heap_iter, GVHI(iter));
2904 }
2905
2906 /**
2907  * g_variant_iter_next_value:
2908  * @iter: a #GVariantIter
2909  * @returns: (allow-none) (transfer full): a #GVariant, or %NULL
2910  *
2911  * Gets the next item in the container.  If no more items remain then
2912  * %NULL is returned.
2913  *
2914  * Use g_variant_unref() to drop your reference on the return value when
2915  * you no longer need it.
2916  *
2917  * <example>
2918  *  <title>Iterating with g_variant_iter_next_value()</title>
2919  *  <programlisting>
2920  *   /<!-- -->* recursively iterate a container *<!-- -->/
2921  *   void
2922  *   iterate_container_recursive (GVariant *container)
2923  *   {
2924  *     GVariantIter iter;
2925  *     GVariant *child;
2926  *
2927  *     g_variant_iter_init (&iter, container);
2928  *     while ((child = g_variant_iter_next_value (&iter)))
2929  *       {
2930  *         g_print ("type '%s'\n", g_variant_get_type_string (child));
2931  *
2932  *         if (g_variant_is_container (child))
2933  *           iterate_container_recursive (child);
2934  *
2935  *         g_variant_unref (child);
2936  *       }
2937  *   }
2938  * </programlisting>
2939  * </example>
2940  *
2941  * Since: 2.24
2942  **/
2943 GVariant *
2944 g_variant_iter_next_value (GVariantIter *iter)
2945 {
2946   g_return_val_if_fail (is_valid_iter (iter), FALSE);
2947
2948   if G_UNLIKELY (GVSI(iter)->i >= GVSI(iter)->n)
2949     {
2950       g_critical ("g_variant_iter_next_value: must not be called again "
2951                   "after NULL has already been returned.");
2952       return NULL;
2953     }
2954
2955   GVSI(iter)->i++;
2956
2957   if (GVSI(iter)->i < GVSI(iter)->n)
2958     return g_variant_get_child_value (GVSI(iter)->value, GVSI(iter)->i);
2959
2960   return NULL;
2961 }
2962
2963 /* GVariantBuilder {{{1 */
2964 /**
2965  * GVariantBuilder:
2966  *
2967  * A utility type for constructing container-type #GVariant instances.
2968  *
2969  * This is an opaque structure and may only be accessed using the
2970  * following functions.
2971  *
2972  * #GVariantBuilder is not threadsafe in any way.  Do not attempt to
2973  * access it from more than one thread.
2974  **/
2975
2976 struct stack_builder
2977 {
2978   GVariantBuilder *parent;
2979   GVariantType *type;
2980
2981   /* type constraint explicitly specified by 'type'.
2982    * for tuple types, this moves along as we add more items.
2983    */
2984   const GVariantType *expected_type;
2985
2986   /* type constraint implied by previous array item.
2987    */
2988   const GVariantType *prev_item_type;
2989
2990   /* constraints on the number of children.  max = -1 for unlimited. */
2991   gsize min_items;
2992   gsize max_items;
2993
2994   /* dynamically-growing pointer array */
2995   GVariant **children;
2996   gsize allocated_children;
2997   gsize offset;
2998
2999   /* set to '1' if all items in the container will have the same type
3000    * (ie: maybe, array, variant) '0' if not (ie: tuple, dict entry)
3001    */
3002   guint uniform_item_types : 1;
3003
3004   /* set to '1' initially and changed to '0' if an untrusted value is
3005    * added
3006    */
3007   guint trusted : 1;
3008
3009   gsize magic;
3010 };
3011
3012 G_STATIC_ASSERT (sizeof (struct stack_builder) <= sizeof (GVariantBuilder));
3013
3014 struct heap_builder
3015 {
3016   GVariantBuilder builder;
3017   gsize magic;
3018
3019   gint ref_count;
3020 };
3021
3022 #define GVSB(b)                  ((struct stack_builder *) (b))
3023 #define GVHB(b)                  ((struct heap_builder *) (b))
3024 #define GVSB_MAGIC               ((gsize) 1033660112u)
3025 #define GVHB_MAGIC               ((gsize) 3087242682u)
3026 #define is_valid_builder(b)      (b != NULL && \
3027                                   GVSB(b)->magic == GVSB_MAGIC)
3028 #define is_valid_heap_builder(b) (GVHB(b)->magic == GVHB_MAGIC)
3029
3030 /**
3031  * g_variant_builder_new:
3032  * @type: a container type
3033  * @returns: (transfer full): a #GVariantBuilder
3034  *
3035  * Allocates and initialises a new #GVariantBuilder.
3036  *
3037  * You should call g_variant_builder_unref() on the return value when it
3038  * is no longer needed.  The memory will not be automatically freed by
3039  * any other call.
3040  *
3041  * In most cases it is easier to place a #GVariantBuilder directly on
3042  * the stack of the calling function and initialise it with
3043  * g_variant_builder_init().
3044  *
3045  * Since: 2.24
3046  **/
3047 GVariantBuilder *
3048 g_variant_builder_new (const GVariantType *type)
3049 {
3050   GVariantBuilder *builder;
3051
3052   builder = (GVariantBuilder *) g_slice_new (struct heap_builder);
3053   g_variant_builder_init (builder, type);
3054   GVHB(builder)->magic = GVHB_MAGIC;
3055   GVHB(builder)->ref_count = 1;
3056
3057   return builder;
3058 }
3059
3060 /**
3061  * g_variant_builder_unref:
3062  * @builder: (transfer full): a #GVariantBuilder allocated by g_variant_builder_new()
3063  *
3064  * Decreases the reference count on @builder.
3065  *
3066  * In the event that there are no more references, releases all memory
3067  * associated with the #GVariantBuilder.
3068  *
3069  * Don't call this on stack-allocated #GVariantBuilder instances or bad
3070  * things will happen.
3071  *
3072  * Since: 2.24
3073  **/
3074 void
3075 g_variant_builder_unref (GVariantBuilder *builder)
3076 {
3077   g_return_if_fail (is_valid_heap_builder (builder));
3078
3079   if (--GVHB(builder)->ref_count)
3080     return;
3081
3082   g_variant_builder_clear (builder);
3083   GVHB(builder)->magic = 0;
3084
3085   g_slice_free (struct heap_builder, GVHB(builder));
3086 }
3087
3088 /**
3089  * g_variant_builder_ref:
3090  * @builder: a #GVariantBuilder allocated by g_variant_builder_new()
3091  * @returns: (transfer full): a new reference to @builder
3092  *
3093  * Increases the reference count on @builder.
3094  *
3095  * Don't call this on stack-allocated #GVariantBuilder instances or bad
3096  * things will happen.
3097  *
3098  * Since: 2.24
3099  **/
3100 GVariantBuilder *
3101 g_variant_builder_ref (GVariantBuilder *builder)
3102 {
3103   g_return_val_if_fail (is_valid_heap_builder (builder), NULL);
3104
3105   GVHB(builder)->ref_count++;
3106
3107   return builder;
3108 }
3109
3110 /**
3111  * g_variant_builder_clear: (skip)
3112  * @builder: a #GVariantBuilder
3113  *
3114  * Releases all memory associated with a #GVariantBuilder without
3115  * freeing the #GVariantBuilder structure itself.
3116  *
3117  * It typically only makes sense to do this on a stack-allocated
3118  * #GVariantBuilder if you want to abort building the value part-way
3119  * through.  This function need not be called if you call
3120  * g_variant_builder_end() and it also doesn't need to be called on
3121  * builders allocated with g_variant_builder_new (see
3122  * g_variant_builder_unref() for that).
3123  *
3124  * This function leaves the #GVariantBuilder structure set to all-zeros.
3125  * It is valid to call this function on either an initialised
3126  * #GVariantBuilder or one that is set to all-zeros but it is not valid
3127  * to call this function on uninitialised memory.
3128  *
3129  * Since: 2.24
3130  **/
3131 void
3132 g_variant_builder_clear (GVariantBuilder *builder)
3133 {
3134   gsize i;
3135
3136   if (GVSB(builder)->magic == 0)
3137     /* all-zeros case */
3138     return;
3139
3140   g_return_if_fail (is_valid_builder (builder));
3141
3142   g_variant_type_free (GVSB(builder)->type);
3143
3144   for (i = 0; i < GVSB(builder)->offset; i++)
3145     g_variant_unref (GVSB(builder)->children[i]);
3146
3147   g_free (GVSB(builder)->children);
3148
3149   if (GVSB(builder)->parent)
3150     {
3151       g_variant_builder_clear (GVSB(builder)->parent);
3152       g_slice_free (GVariantBuilder, GVSB(builder)->parent);
3153     }
3154
3155   memset (builder, 0, sizeof (GVariantBuilder));
3156 }
3157
3158 /**
3159  * g_variant_builder_init: (skip)
3160  * @builder: a #GVariantBuilder
3161  * @type: a container type
3162  *
3163  * Initialises a #GVariantBuilder structure.
3164  *
3165  * @type must be non-%NULL.  It specifies the type of container to
3166  * construct.  It can be an indefinite type such as
3167  * %G_VARIANT_TYPE_ARRAY or a definite type such as "as" or "(ii)".
3168  * Maybe, array, tuple, dictionary entry and variant-typed values may be
3169  * constructed.
3170  *
3171  * After the builder is initialised, values are added using
3172  * g_variant_builder_add_value() or g_variant_builder_add().
3173  *
3174  * After all the child values are added, g_variant_builder_end() frees
3175  * the memory associated with the builder and returns the #GVariant that
3176  * was created.
3177  *
3178  * This function completely ignores the previous contents of @builder.
3179  * On one hand this means that it is valid to pass in completely
3180  * uninitialised memory.  On the other hand, this means that if you are
3181  * initialising over top of an existing #GVariantBuilder you need to
3182  * first call g_variant_builder_clear() in order to avoid leaking
3183  * memory.
3184  *
3185  * You must not call g_variant_builder_ref() or
3186  * g_variant_builder_unref() on a #GVariantBuilder that was initialised
3187  * with this function.  If you ever pass a reference to a
3188  * #GVariantBuilder outside of the control of your own code then you
3189  * should assume that the person receiving that reference may try to use
3190  * reference counting; you should use g_variant_builder_new() instead of
3191  * this function.
3192  *
3193  * Since: 2.24
3194  **/
3195 void
3196 g_variant_builder_init (GVariantBuilder    *builder,
3197                         const GVariantType *type)
3198 {
3199   g_return_if_fail (type != NULL);
3200   g_return_if_fail (g_variant_type_is_container (type));
3201
3202   memset (builder, 0, sizeof (GVariantBuilder));
3203
3204   GVSB(builder)->type = g_variant_type_copy (type);
3205   GVSB(builder)->magic = GVSB_MAGIC;
3206   GVSB(builder)->trusted = TRUE;
3207
3208   switch (*(const gchar *) type)
3209     {
3210     case G_VARIANT_CLASS_VARIANT:
3211       GVSB(builder)->uniform_item_types = TRUE;
3212       GVSB(builder)->allocated_children = 1;
3213       GVSB(builder)->expected_type = NULL;
3214       GVSB(builder)->min_items = 1;
3215       GVSB(builder)->max_items = 1;
3216       break;
3217
3218     case G_VARIANT_CLASS_ARRAY:
3219       GVSB(builder)->uniform_item_types = TRUE;
3220       GVSB(builder)->allocated_children = 8;
3221       GVSB(builder)->expected_type =
3222         g_variant_type_element (GVSB(builder)->type);
3223       GVSB(builder)->min_items = 0;
3224       GVSB(builder)->max_items = -1;
3225       break;
3226
3227     case G_VARIANT_CLASS_MAYBE:
3228       GVSB(builder)->uniform_item_types = TRUE;
3229       GVSB(builder)->allocated_children = 1;
3230       GVSB(builder)->expected_type =
3231         g_variant_type_element (GVSB(builder)->type);
3232       GVSB(builder)->min_items = 0;
3233       GVSB(builder)->max_items = 1;
3234       break;
3235
3236     case G_VARIANT_CLASS_DICT_ENTRY:
3237       GVSB(builder)->uniform_item_types = FALSE;
3238       GVSB(builder)->allocated_children = 2;
3239       GVSB(builder)->expected_type =
3240         g_variant_type_key (GVSB(builder)->type);
3241       GVSB(builder)->min_items = 2;
3242       GVSB(builder)->max_items = 2;
3243       break;
3244
3245     case 'r': /* G_VARIANT_TYPE_TUPLE was given */
3246       GVSB(builder)->uniform_item_types = FALSE;
3247       GVSB(builder)->allocated_children = 8;
3248       GVSB(builder)->expected_type = NULL;
3249       GVSB(builder)->min_items = 0;
3250       GVSB(builder)->max_items = -1;
3251       break;
3252
3253     case G_VARIANT_CLASS_TUPLE: /* a definite tuple type was given */
3254       GVSB(builder)->allocated_children = g_variant_type_n_items (type);
3255       GVSB(builder)->expected_type =
3256         g_variant_type_first (GVSB(builder)->type);
3257       GVSB(builder)->min_items = GVSB(builder)->allocated_children;
3258       GVSB(builder)->max_items = GVSB(builder)->allocated_children;
3259       GVSB(builder)->uniform_item_types = FALSE;
3260       break;
3261
3262     default:
3263       g_assert_not_reached ();
3264    }
3265
3266   GVSB(builder)->children = g_new (GVariant *,
3267                                    GVSB(builder)->allocated_children);
3268 }
3269
3270 static void
3271 g_variant_builder_make_room (struct stack_builder *builder)
3272 {
3273   if (builder->offset == builder->allocated_children)
3274     {
3275       builder->allocated_children *= 2;
3276       builder->children = g_renew (GVariant *, builder->children,
3277                                    builder->allocated_children);
3278     }
3279 }
3280
3281 /**
3282  * g_variant_builder_add_value:
3283  * @builder: a #GVariantBuilder
3284  * @value: a #GVariant
3285  *
3286  * Adds @value to @builder.
3287  *
3288  * It is an error to call this function in any way that would create an
3289  * inconsistent value to be constructed.  Some examples of this are
3290  * putting different types of items into an array, putting the wrong
3291  * types or number of items in a tuple, putting more than one value into
3292  * a variant, etc.
3293  *
3294  * If @value is a floating reference (see g_variant_ref_sink()),
3295  * the @builder instance takes ownership of @value.
3296  *
3297  * Since: 2.24
3298  **/
3299 void
3300 g_variant_builder_add_value (GVariantBuilder *builder,
3301                              GVariant        *value)
3302 {
3303   g_return_if_fail (is_valid_builder (builder));
3304   g_return_if_fail (GVSB(builder)->offset < GVSB(builder)->max_items);
3305   g_return_if_fail (!GVSB(builder)->expected_type ||
3306                     g_variant_is_of_type (value,
3307                                           GVSB(builder)->expected_type));
3308   g_return_if_fail (!GVSB(builder)->prev_item_type ||
3309                     g_variant_is_of_type (value,
3310                                           GVSB(builder)->prev_item_type));
3311
3312   GVSB(builder)->trusted &= g_variant_is_trusted (value);
3313
3314   if (!GVSB(builder)->uniform_item_types)
3315     {
3316       /* advance our expected type pointers */
3317       if (GVSB(builder)->expected_type)
3318         GVSB(builder)->expected_type =
3319           g_variant_type_next (GVSB(builder)->expected_type);
3320
3321       if (GVSB(builder)->prev_item_type)
3322         GVSB(builder)->prev_item_type =
3323           g_variant_type_next (GVSB(builder)->prev_item_type);
3324     }
3325   else
3326     GVSB(builder)->prev_item_type = g_variant_get_type (value);
3327
3328   g_variant_builder_make_room (GVSB(builder));
3329
3330   GVSB(builder)->children[GVSB(builder)->offset++] =
3331     g_variant_ref_sink (value);
3332 }
3333
3334 /**
3335  * g_variant_builder_open:
3336  * @builder: a #GVariantBuilder
3337  * @type: a #GVariantType
3338  *
3339  * Opens a subcontainer inside the given @builder.  When done adding
3340  * items to the subcontainer, g_variant_builder_close() must be called.
3341  *
3342  * It is an error to call this function in any way that would cause an
3343  * inconsistent value to be constructed (ie: adding too many values or
3344  * a value of an incorrect type).
3345  *
3346  * Since: 2.24
3347  **/
3348 void
3349 g_variant_builder_open (GVariantBuilder    *builder,
3350                         const GVariantType *type)
3351 {
3352   GVariantBuilder *parent;
3353
3354   g_return_if_fail (is_valid_builder (builder));
3355   g_return_if_fail (GVSB(builder)->offset < GVSB(builder)->max_items);
3356   g_return_if_fail (!GVSB(builder)->expected_type ||
3357                     g_variant_type_is_subtype_of (type,
3358                                                   GVSB(builder)->expected_type));
3359   g_return_if_fail (!GVSB(builder)->prev_item_type ||
3360                     g_variant_type_is_subtype_of (GVSB(builder)->prev_item_type,
3361                                                   type));
3362
3363   parent = g_slice_dup (GVariantBuilder, builder);
3364   g_variant_builder_init (builder, type);
3365   GVSB(builder)->parent = parent;
3366
3367   /* push the prev_item_type down into the subcontainer */
3368   if (GVSB(parent)->prev_item_type)
3369     {
3370       if (!GVSB(builder)->uniform_item_types)
3371         /* tuples and dict entries */
3372         GVSB(builder)->prev_item_type =
3373           g_variant_type_first (GVSB(parent)->prev_item_type);
3374
3375       else if (!g_variant_type_is_variant (GVSB(builder)->type))
3376         /* maybes and arrays */
3377         GVSB(builder)->prev_item_type =
3378           g_variant_type_element (GVSB(parent)->prev_item_type);
3379     }
3380 }
3381
3382 /**
3383  * g_variant_builder_close:
3384  * @builder: a #GVariantBuilder
3385  *
3386  * Closes the subcontainer inside the given @builder that was opened by
3387  * the most recent call to g_variant_builder_open().
3388  *
3389  * It is an error to call this function in any way that would create an
3390  * inconsistent value to be constructed (ie: too few values added to the
3391  * subcontainer).
3392  *
3393  * Since: 2.24
3394  **/
3395 void
3396 g_variant_builder_close (GVariantBuilder *builder)
3397 {
3398   GVariantBuilder *parent;
3399
3400   g_return_if_fail (is_valid_builder (builder));
3401   g_return_if_fail (GVSB(builder)->parent != NULL);
3402
3403   parent = GVSB(builder)->parent;
3404   GVSB(builder)->parent = NULL;
3405
3406   g_variant_builder_add_value (parent, g_variant_builder_end (builder));
3407   *builder = *parent;
3408
3409   g_slice_free (GVariantBuilder, parent);
3410 }
3411
3412 /*< private >
3413  * g_variant_make_maybe_type:
3414  * @element: a #GVariant
3415  *
3416  * Return the type of a maybe containing @element.
3417  */
3418 static GVariantType *
3419 g_variant_make_maybe_type (GVariant *element)
3420 {
3421   return g_variant_type_new_maybe (g_variant_get_type (element));
3422 }
3423
3424 /*< private >
3425  * g_variant_make_array_type:
3426  * @element: a #GVariant
3427  *
3428  * Return the type of an array containing @element.
3429  */
3430 static GVariantType *
3431 g_variant_make_array_type (GVariant *element)
3432 {
3433   return g_variant_type_new_array (g_variant_get_type (element));
3434 }
3435
3436 /**
3437  * g_variant_builder_end:
3438  * @builder: a #GVariantBuilder
3439  * @returns: (transfer none): a new, floating, #GVariant
3440  *
3441  * Ends the builder process and returns the constructed value.
3442  *
3443  * It is not permissible to use @builder in any way after this call
3444  * except for reference counting operations (in the case of a
3445  * heap-allocated #GVariantBuilder) or by reinitialising it with
3446  * g_variant_builder_init() (in the case of stack-allocated).
3447  *
3448  * It is an error to call this function in any way that would create an
3449  * inconsistent value to be constructed (ie: insufficient number of
3450  * items added to a container with a specific number of children
3451  * required).  It is also an error to call this function if the builder
3452  * was created with an indefinite array or maybe type and no children
3453  * have been added; in this case it is impossible to infer the type of
3454  * the empty array.
3455  *
3456  * Since: 2.24
3457  **/
3458 GVariant *
3459 g_variant_builder_end (GVariantBuilder *builder)
3460 {
3461   GVariantType *my_type;
3462   GVariant *value;
3463
3464   g_return_val_if_fail (is_valid_builder (builder), NULL);
3465   g_return_val_if_fail (GVSB(builder)->offset >= GVSB(builder)->min_items,
3466                         NULL);
3467   g_return_val_if_fail (!GVSB(builder)->uniform_item_types ||
3468                         GVSB(builder)->prev_item_type != NULL ||
3469                         g_variant_type_is_definite (GVSB(builder)->type),
3470                         NULL);
3471
3472   if (g_variant_type_is_definite (GVSB(builder)->type))
3473     my_type = g_variant_type_copy (GVSB(builder)->type);
3474
3475   else if (g_variant_type_is_maybe (GVSB(builder)->type))
3476     my_type = g_variant_make_maybe_type (GVSB(builder)->children[0]);
3477
3478   else if (g_variant_type_is_array (GVSB(builder)->type))
3479     my_type = g_variant_make_array_type (GVSB(builder)->children[0]);
3480
3481   else if (g_variant_type_is_tuple (GVSB(builder)->type))
3482     my_type = g_variant_make_tuple_type (GVSB(builder)->children,
3483                                          GVSB(builder)->offset);
3484
3485   else if (g_variant_type_is_dict_entry (GVSB(builder)->type))
3486     my_type = g_variant_make_dict_entry_type (GVSB(builder)->children[0],
3487                                               GVSB(builder)->children[1]);
3488   else
3489     g_assert_not_reached ();
3490
3491   value = g_variant_new_from_children (my_type,
3492                                        g_renew (GVariant *,
3493                                                 GVSB(builder)->children,
3494                                                 GVSB(builder)->offset),
3495                                        GVSB(builder)->offset,
3496                                        GVSB(builder)->trusted);
3497   GVSB(builder)->children = NULL;
3498   GVSB(builder)->offset = 0;
3499
3500   g_variant_builder_clear (builder);
3501   g_variant_type_free (my_type);
3502
3503   return value;
3504 }
3505
3506 /* Format strings {{{1 */
3507 /*< private >
3508  * g_variant_format_string_scan:
3509  * @string: a string that may be prefixed with a format string
3510  * @limit: (allow-none) (default NULL): a pointer to the end of @string,
3511  *         or %NULL
3512  * @endptr: (allow-none) (default NULL): location to store the end pointer,
3513  *          or %NULL
3514  * @returns: %TRUE if there was a valid format string
3515  *
3516  * Checks the string pointed to by @string for starting with a properly
3517  * formed #GVariant varargs format string.  If no valid format string is
3518  * found then %FALSE is returned.
3519  *
3520  * If @string does start with a valid format string then %TRUE is
3521  * returned.  If @endptr is non-%NULL then it is updated to point to the
3522  * first character after the format string.
3523  *
3524  * If @limit is non-%NULL then @limit (and any charater after it) will
3525  * not be accessed and the effect is otherwise equivalent to if the
3526  * character at @limit were nul.
3527  *
3528  * See the section on <link linkend='gvariant-format-strings'>GVariant
3529  * Format Strings</link>.
3530  *
3531  * Since: 2.24
3532  */
3533 gboolean
3534 g_variant_format_string_scan (const gchar  *string,
3535                               const gchar  *limit,
3536                               const gchar **endptr)
3537 {
3538 #define next_char() (string == limit ? '\0' : *string++)
3539 #define peek_char() (string == limit ? '\0' : *string)
3540   char c;
3541
3542   switch (next_char())
3543     {
3544     case 'b': case 'y': case 'n': case 'q': case 'i': case 'u':
3545     case 'x': case 't': case 'h': case 'd': case 's': case 'o':
3546     case 'g': case 'v': case '*': case '?': case 'r':
3547       break;
3548
3549     case 'm':
3550       return g_variant_format_string_scan (string, limit, endptr);
3551
3552     case 'a':
3553     case '@':
3554       return g_variant_type_string_scan (string, limit, endptr);
3555
3556     case '(':
3557       while (peek_char() != ')')
3558         if (!g_variant_format_string_scan (string, limit, &string))
3559           return FALSE;
3560
3561       next_char(); /* consume ')' */
3562       break;
3563
3564     case '{':
3565       c = next_char();
3566
3567       if (c == '&')
3568         {
3569           c = next_char ();
3570
3571           if (c != 's' && c != 'o' && c != 'g')
3572             return FALSE;
3573         }
3574       else
3575         {
3576           if (c == '@')
3577             c = next_char ();
3578
3579           /* ISO/IEC 9899:1999 (C99) §7.21.5.2:
3580            *    The terminating null character is considered to be
3581            *    part of the string.
3582            */
3583           if (c != '\0' && strchr ("bynqiuxthdsog?", c) == NULL)
3584             return FALSE;
3585         }
3586
3587       if (!g_variant_format_string_scan (string, limit, &string))
3588         return FALSE;
3589
3590       if (next_char() != '}')
3591         return FALSE;
3592
3593       break;
3594
3595     case '^':
3596       if ((c = next_char()) == 'a')
3597         {
3598           if ((c = next_char()) == '&')
3599             {
3600               if ((c = next_char()) == 'a')
3601                 {
3602                   if ((c = next_char()) == 'y')
3603                     break;      /* '^a&ay' */
3604                 }
3605
3606               else if (c == 's' || c == 'o')
3607                 break;          /* '^a&s', '^a&o' */
3608             }
3609
3610           else if (c == 'a')
3611             {
3612               if ((c = next_char()) == 'y')
3613                 break;          /* '^aay' */
3614             }
3615
3616           else if (c == 's' || c == 'o')
3617             break;              /* '^as', '^ao' */
3618
3619           else if (c == 'y')
3620             break;              /* '^ay' */
3621         }
3622       else if (c == '&')
3623         {
3624           if ((c = next_char()) == 'a')
3625             {
3626               if ((c = next_char()) == 'y')
3627                 break;          /* '^&ay' */
3628             }
3629         }
3630
3631       return FALSE;
3632
3633     case '&':
3634       c = next_char();
3635
3636       if (c != 's' && c != 'o' && c != 'g')
3637         return FALSE;
3638
3639       break;
3640
3641     default:
3642       return FALSE;
3643     }
3644
3645   if (endptr != NULL)
3646     *endptr = string;
3647
3648 #undef next_char
3649 #undef peek_char
3650
3651   return TRUE;
3652 }
3653
3654 /*< private >
3655  * g_variant_format_string_scan_type:
3656  * @string: a string that may be prefixed with a format string
3657  * @limit: (allow-none) (default NULL): a pointer to the end of @string,
3658  *         or %NULL
3659  * @endptr: (allow-none) (default NULL): location to store the end pointer,
3660  *          or %NULL
3661  * @returns: (allow-none): a #GVariantType if there was a valid format string
3662  *
3663  * If @string starts with a valid format string then this function will
3664  * return the type that the format string corresponds to.  Otherwise
3665  * this function returns %NULL.
3666  *
3667  * Use g_variant_type_free() to free the return value when you no longer
3668  * need it.
3669  *
3670  * This function is otherwise exactly like
3671  * g_variant_format_string_scan().
3672  *
3673  * Since: 2.24
3674  */
3675 GVariantType *
3676 g_variant_format_string_scan_type (const gchar  *string,
3677                                    const gchar  *limit,
3678                                    const gchar **endptr)
3679 {
3680   const gchar *my_end;
3681   gchar *dest;
3682   gchar *new;
3683
3684   if (endptr == NULL)
3685     endptr = &my_end;
3686
3687   if (!g_variant_format_string_scan (string, limit, endptr))
3688     return NULL;
3689
3690   dest = new = g_malloc (*endptr - string + 1);
3691   while (string != *endptr)
3692     {
3693       if (*string != '@' && *string != '&' && *string != '^')
3694         *dest++ = *string;
3695       string++;
3696     }
3697   *dest = '\0';
3698
3699   return (GVariantType *) G_VARIANT_TYPE (new);
3700 }
3701
3702 static gboolean
3703 valid_format_string (const gchar *format_string,
3704                      gboolean     single,
3705                      GVariant    *value)
3706 {
3707   const gchar *endptr;
3708   GVariantType *type;
3709
3710   type = g_variant_format_string_scan_type (format_string, NULL, &endptr);
3711
3712   if G_UNLIKELY (type == NULL || (single && *endptr != '\0'))
3713     {
3714       if (single)
3715         g_critical ("`%s' is not a valid GVariant format string",
3716                     format_string);
3717       else
3718         g_critical ("`%s' does not have a valid GVariant format "
3719                     "string as a prefix", format_string);
3720
3721       if (type != NULL)
3722         g_variant_type_free (type);
3723
3724       return FALSE;
3725     }
3726
3727   if G_UNLIKELY (value && !g_variant_is_of_type (value, type))
3728     {
3729       gchar *fragment;
3730       gchar *typestr;
3731
3732       fragment = g_strndup (format_string, endptr - format_string);
3733       typestr = g_variant_type_dup_string (type);
3734
3735       g_critical ("the GVariant format string `%s' has a type of "
3736                   "`%s' but the given value has a type of `%s'",
3737                   fragment, typestr, g_variant_get_type_string (value));
3738
3739       g_variant_type_free (type);
3740
3741       return FALSE;
3742     }
3743
3744   g_variant_type_free (type);
3745
3746   return TRUE;
3747 }
3748
3749 /* Variable Arguments {{{1 */
3750 /* We consider 2 main classes of format strings:
3751  *
3752  *   - recursive format strings
3753  *      these are ones that result in recursion and the collection of
3754  *      possibly more than one argument.  Maybe types, tuples,
3755  *      dictionary entries.
3756  *
3757  *   - leaf format string
3758  *      these result in the collection of a single argument.
3759  *
3760  * Leaf format strings are further subdivided into two categories:
3761  *
3762  *   - single non-null pointer ("nnp")
3763  *      these either collect or return a single non-null pointer.
3764  *
3765  *   - other
3766  *      these collect or return something else (bool, number, etc).
3767  *
3768  * Based on the above, the varargs handling code is split into 4 main parts:
3769  *
3770  *   - nnp handling code
3771  *   - leaf handling code (which may invoke nnp code)
3772  *   - generic handling code (may be recursive, may invoke leaf code)
3773  *   - user-facing API (which invokes the generic code)
3774  *
3775  * Each section implements some of the following functions:
3776  *
3777  *   - skip:
3778  *      collect the arguments for the format string as if
3779  *      g_variant_new() had been called, but do nothing with them.  used
3780  *      for skipping over arguments when constructing a Nothing maybe
3781  *      type.
3782  *
3783  *   - new:
3784  *      create a GVariant *
3785  *
3786  *   - get:
3787  *      unpack a GVariant *
3788  *
3789  *   - free (nnp only):
3790  *      free a previously allocated item
3791  */
3792
3793 static gboolean
3794 g_variant_format_string_is_leaf (const gchar *str)
3795 {
3796   return str[0] != 'm' && str[0] != '(' && str[0] != '{';
3797 }
3798
3799 static gboolean
3800 g_variant_format_string_is_nnp (const gchar *str)
3801 {
3802   return str[0] == 'a' || str[0] == 's' || str[0] == 'o' || str[0] == 'g' ||
3803          str[0] == '^' || str[0] == '@' || str[0] == '*' || str[0] == '?' ||
3804          str[0] == 'r' || str[0] == 'v' || str[0] == '&';
3805 }
3806
3807 /* Single non-null pointer ("nnp") {{{2 */
3808 static void
3809 g_variant_valist_free_nnp (const gchar *str,
3810                            gpointer     ptr)
3811 {
3812   switch (*str)
3813     {
3814     case 'a':
3815       g_variant_iter_free (ptr);
3816       break;
3817
3818     case '^':
3819       if (str[2] != '&')        /* '^as', '^ao' */
3820         g_strfreev (ptr);
3821       else                      /* '^a&s', '^a&o' */
3822         g_free (ptr);
3823       break;
3824
3825     case 's':
3826     case 'o':
3827     case 'g':
3828       g_free (ptr);
3829       break;
3830
3831     case '@':
3832     case '*':
3833     case '?':
3834     case 'v':
3835       g_variant_unref (ptr);
3836       break;
3837
3838     case '&':
3839       break;
3840
3841     default:
3842       g_assert_not_reached ();
3843     }
3844 }
3845
3846 static gchar
3847 g_variant_scan_convenience (const gchar **str,
3848                             gboolean     *constant,
3849                             guint        *arrays)
3850 {
3851   *constant = FALSE;
3852   *arrays = 0;
3853
3854   for (;;)
3855     {
3856       char c = *(*str)++;
3857
3858       if (c == '&')
3859         *constant = TRUE;
3860
3861       else if (c == 'a')
3862         (*arrays)++;
3863
3864       else
3865         return c;
3866     }
3867 }
3868
3869 static GVariant *
3870 g_variant_valist_new_nnp (const gchar **str,
3871                           gpointer      ptr)
3872 {
3873   if (**str == '&')
3874     (*str)++;
3875
3876   switch (*(*str)++)
3877     {
3878     case 'a':
3879       if (ptr != NULL)
3880         {
3881           const GVariantType *type;
3882           GVariant *value;
3883
3884           value = g_variant_builder_end (ptr);
3885           type = g_variant_get_type (value);
3886
3887           if G_UNLIKELY (!g_variant_type_is_array (type))
3888             g_error ("g_variant_new: expected array GVariantBuilder but "
3889                      "the built value has type `%s'",
3890                      g_variant_get_type_string (value));
3891
3892           type = g_variant_type_element (type);
3893
3894           if G_UNLIKELY (!g_variant_type_is_subtype_of (type, (GVariantType *) *str))
3895             g_error ("g_variant_new: expected GVariantBuilder array element "
3896                      "type `%s' but the built value has element type `%s'",
3897                      g_variant_type_dup_string ((GVariantType *) *str),
3898                      g_variant_get_type_string (value) + 1);
3899
3900           g_variant_type_string_scan (*str, NULL, str);
3901
3902           return value;
3903         }
3904       else
3905
3906         /* special case: NULL pointer for empty array */
3907         {
3908           const GVariantType *type = (GVariantType *) *str;
3909
3910           g_variant_type_string_scan (*str, NULL, str);
3911
3912           if G_UNLIKELY (!g_variant_type_is_definite (type))
3913             g_error ("g_variant_new: NULL pointer given with indefinite "
3914                      "array type; unable to determine which type of empty "
3915                      "array to construct.");
3916
3917           return g_variant_new_array (type, NULL, 0);
3918         }
3919
3920     case 's':
3921       {
3922         GVariant *value;
3923
3924         value = g_variant_new_string (ptr);
3925
3926         if (value == NULL)
3927           value = g_variant_new_string ("[Invalid UTF-8]");
3928
3929         return value;
3930       }
3931
3932     case 'o':
3933       return g_variant_new_object_path (ptr);
3934
3935     case 'g':
3936       return g_variant_new_signature (ptr);
3937
3938     case '^':
3939       {
3940         gboolean constant;
3941         guint arrays;
3942         gchar type;
3943
3944         type = g_variant_scan_convenience (str, &constant, &arrays);
3945
3946         if (type == 's')
3947           return g_variant_new_strv (ptr, -1);
3948
3949         if (type == 'o')
3950           return g_variant_new_objv (ptr, -1);
3951
3952         if (arrays > 1)
3953           return g_variant_new_bytestring_array (ptr, -1);
3954
3955         return g_variant_new_bytestring (ptr);
3956       }
3957
3958     case '@':
3959       if G_UNLIKELY (!g_variant_is_of_type (ptr, (GVariantType *) *str))
3960         g_error ("g_variant_new: expected GVariant of type `%s' but "
3961                  "received value has type `%s'",
3962                  g_variant_type_dup_string ((GVariantType *) *str),
3963                  g_variant_get_type_string (ptr));
3964
3965       g_variant_type_string_scan (*str, NULL, str);
3966
3967       return ptr;
3968
3969     case '*':
3970       return ptr;
3971
3972     case '?':
3973       if G_UNLIKELY (!g_variant_type_is_basic (g_variant_get_type (ptr)))
3974         g_error ("g_variant_new: format string `?' expects basic-typed "
3975                  "GVariant, but received value has type `%s'",
3976                  g_variant_get_type_string (ptr));
3977
3978       return ptr;
3979
3980     case 'r':
3981       if G_UNLIKELY (!g_variant_type_is_tuple (g_variant_get_type (ptr)))
3982         g_error ("g_variant_new: format string `r` expects tuple-typed "
3983                  "GVariant, but received value has type `%s'",
3984                  g_variant_get_type_string (ptr));
3985
3986       return ptr;
3987
3988     case 'v':
3989       return g_variant_new_variant (ptr);
3990
3991     default:
3992       g_assert_not_reached ();
3993     }
3994 }
3995
3996 static gpointer
3997 g_variant_valist_get_nnp (const gchar **str,
3998                           GVariant     *value)
3999 {
4000   switch (*(*str)++)
4001     {
4002     case 'a':
4003       g_variant_type_string_scan (*str, NULL, str);
4004       return g_variant_iter_new (value);
4005
4006     case '&':
4007       (*str)++;
4008       return (gchar *) g_variant_get_string (value, NULL);
4009
4010     case 's':
4011     case 'o':
4012     case 'g':
4013       return g_variant_dup_string (value, NULL);
4014
4015     case '^':
4016       {
4017         gboolean constant;
4018         guint arrays;
4019         gchar type;
4020
4021         type = g_variant_scan_convenience (str, &constant, &arrays);
4022
4023         if (type == 's')
4024           {
4025             if (constant)
4026               return g_variant_get_strv (value, NULL);
4027             else
4028               return g_variant_dup_strv (value, NULL);
4029           }
4030
4031         else if (type == 'o')
4032           {
4033             if (constant)
4034               return g_variant_get_objv (value, NULL);
4035             else
4036               return g_variant_dup_objv (value, NULL);
4037           }
4038
4039         else if (arrays > 1)
4040           {
4041             if (constant)
4042               return g_variant_get_bytestring_array (value, NULL);
4043             else
4044               return g_variant_dup_bytestring_array (value, NULL);
4045           }
4046
4047         else
4048           {
4049             if (constant)
4050               return (gchar *) g_variant_get_bytestring (value);
4051             else
4052               return g_variant_dup_bytestring (value, NULL);
4053           }
4054       }
4055
4056     case '@':
4057       g_variant_type_string_scan (*str, NULL, str);
4058       /* fall through */
4059
4060     case '*':
4061     case '?':
4062     case 'r':
4063       return g_variant_ref (value);
4064
4065     case 'v':
4066       return g_variant_get_variant (value);
4067
4068     default:
4069       g_assert_not_reached ();
4070     }
4071 }
4072
4073 /* Leaves {{{2 */
4074 static void
4075 g_variant_valist_skip_leaf (const gchar **str,
4076                             va_list      *app)
4077 {
4078   if (g_variant_format_string_is_nnp (*str))
4079     {
4080       g_variant_format_string_scan (*str, NULL, str);
4081       va_arg (*app, gpointer);
4082       return;
4083     }
4084
4085   switch (*(*str)++)
4086     {
4087     case 'b':
4088     case 'y':
4089     case 'n':
4090     case 'q':
4091     case 'i':
4092     case 'u':
4093     case 'h':
4094       va_arg (*app, int);
4095       return;
4096
4097     case 'x':
4098     case 't':
4099       va_arg (*app, guint64);
4100       return;
4101
4102     case 'd':
4103       va_arg (*app, gdouble);
4104       return;
4105
4106     default:
4107       g_assert_not_reached ();
4108     }
4109 }
4110
4111 static GVariant *
4112 g_variant_valist_new_leaf (const gchar **str,
4113                            va_list      *app)
4114 {
4115   if (g_variant_format_string_is_nnp (*str))
4116     return g_variant_valist_new_nnp (str, va_arg (*app, gpointer));
4117
4118   switch (*(*str)++)
4119     {
4120     case 'b':
4121       return g_variant_new_boolean (va_arg (*app, gboolean));
4122
4123     case 'y':
4124       return g_variant_new_byte (va_arg (*app, guint));
4125
4126     case 'n':
4127       return g_variant_new_int16 (va_arg (*app, gint));
4128
4129     case 'q':
4130       return g_variant_new_uint16 (va_arg (*app, guint));
4131
4132     case 'i':
4133       return g_variant_new_int32 (va_arg (*app, gint));
4134
4135     case 'u':
4136       return g_variant_new_uint32 (va_arg (*app, guint));
4137
4138     case 'x':
4139       return g_variant_new_int64 (va_arg (*app, gint64));
4140
4141     case 't':
4142       return g_variant_new_uint64 (va_arg (*app, guint64));
4143
4144     case 'h':
4145       return g_variant_new_handle (va_arg (*app, gint));
4146
4147     case 'd':
4148       return g_variant_new_double (va_arg (*app, gdouble));
4149
4150     default:
4151       g_assert_not_reached ();
4152     }
4153 }
4154
4155 /* The code below assumes this */
4156 G_STATIC_ASSERT (sizeof (gboolean) == sizeof (guint32));
4157 G_STATIC_ASSERT (sizeof (gdouble) == sizeof (guint64));
4158
4159 static void
4160 g_variant_valist_get_leaf (const gchar **str,
4161                            GVariant     *value,
4162                            gboolean      free,
4163                            va_list      *app)
4164 {
4165   gpointer ptr = va_arg (*app, gpointer);
4166
4167   if (ptr == NULL)
4168     {
4169       g_variant_format_string_scan (*str, NULL, str);
4170       return;
4171     }
4172
4173   if (g_variant_format_string_is_nnp (*str))
4174     {
4175       gpointer *nnp = (gpointer *) ptr;
4176
4177       if (free && *nnp != NULL)
4178         g_variant_valist_free_nnp (*str, *nnp);
4179
4180       *nnp = NULL;
4181
4182       if (value != NULL)
4183         *nnp = g_variant_valist_get_nnp (str, value);
4184       else
4185         g_variant_format_string_scan (*str, NULL, str);
4186
4187       return;
4188     }
4189
4190   if (value != NULL)
4191     {
4192       switch (*(*str)++)
4193         {
4194         case 'b':
4195           *(gboolean *) ptr = g_variant_get_boolean (value);
4196           return;
4197
4198         case 'y':
4199           *(guchar *) ptr = g_variant_get_byte (value);
4200           return;
4201
4202         case 'n':
4203           *(gint16 *) ptr = g_variant_get_int16 (value);
4204           return;
4205
4206         case 'q':
4207           *(guint16 *) ptr = g_variant_get_uint16 (value);
4208           return;
4209
4210         case 'i':
4211           *(gint32 *) ptr = g_variant_get_int32 (value);
4212           return;
4213
4214         case 'u':
4215           *(guint32 *) ptr = g_variant_get_uint32 (value);
4216           return;
4217
4218         case 'x':
4219           *(gint64 *) ptr = g_variant_get_int64 (value);
4220           return;
4221
4222         case 't':
4223           *(guint64 *) ptr = g_variant_get_uint64 (value);
4224           return;
4225
4226         case 'h':
4227           *(gint32 *) ptr = g_variant_get_handle (value);
4228           return;
4229
4230         case 'd':
4231           *(gdouble *) ptr = g_variant_get_double (value);
4232           return;
4233         }
4234     }
4235   else
4236     {
4237       switch (*(*str)++)
4238         {
4239         case 'y':
4240           *(guchar *) ptr = 0;
4241           return;
4242
4243         case 'n':
4244         case 'q':
4245           *(guint16 *) ptr = 0;
4246           return;
4247
4248         case 'i':
4249         case 'u':
4250         case 'h':
4251         case 'b':
4252           *(guint32 *) ptr = 0;
4253           return;
4254
4255         case 'x':
4256         case 't':
4257         case 'd':
4258           *(guint64 *) ptr = 0;
4259           return;
4260         }
4261     }
4262
4263   g_assert_not_reached ();
4264 }
4265
4266 /* Generic (recursive) {{{2 */
4267 static void
4268 g_variant_valist_skip (const gchar **str,
4269                        va_list      *app)
4270 {
4271   if (g_variant_format_string_is_leaf (*str))
4272     g_variant_valist_skip_leaf (str, app);
4273
4274   else if (**str == 'm') /* maybe */
4275     {
4276       (*str)++;
4277
4278       if (!g_variant_format_string_is_nnp (*str))
4279         va_arg (*app, gboolean);
4280
4281       g_variant_valist_skip (str, app);
4282     }
4283   else /* tuple, dictionary entry */
4284     {
4285       g_assert (**str == '(' || **str == '{');
4286       (*str)++;
4287       while (**str != ')' && **str != '}')
4288         g_variant_valist_skip (str, app);
4289       (*str)++;
4290     }
4291 }
4292
4293 static GVariant *
4294 g_variant_valist_new (const gchar **str,
4295                       va_list      *app)
4296 {
4297   if (g_variant_format_string_is_leaf (*str))
4298     return g_variant_valist_new_leaf (str, app);
4299
4300   if (**str == 'm') /* maybe */
4301     {
4302       GVariantType *type = NULL;
4303       GVariant *value = NULL;
4304
4305       (*str)++;
4306
4307       if (g_variant_format_string_is_nnp (*str))
4308         {
4309           gpointer nnp = va_arg (*app, gpointer);
4310
4311           if (nnp != NULL)
4312             value = g_variant_valist_new_nnp (str, nnp);
4313           else
4314             type = g_variant_format_string_scan_type (*str, NULL, str);
4315         }
4316       else
4317         {
4318           gboolean just = va_arg (*app, gboolean);
4319
4320           if (just)
4321             value = g_variant_valist_new (str, app);
4322           else
4323             {
4324               type = g_variant_format_string_scan_type (*str, NULL, NULL);
4325               g_variant_valist_skip (str, app);
4326             }
4327         }
4328
4329       value = g_variant_new_maybe (type, value);
4330
4331       if (type != NULL)
4332         g_variant_type_free (type);
4333
4334       return value;
4335     }
4336   else /* tuple, dictionary entry */
4337     {
4338       GVariantBuilder b;
4339
4340       if (**str == '(')
4341         g_variant_builder_init (&b, G_VARIANT_TYPE_TUPLE);
4342       else
4343         {
4344           g_assert (**str == '{');
4345           g_variant_builder_init (&b, G_VARIANT_TYPE_DICT_ENTRY);
4346         }
4347
4348       (*str)++; /* '(' */
4349       while (**str != ')' && **str != '}')
4350         g_variant_builder_add_value (&b, g_variant_valist_new (str, app));
4351       (*str)++; /* ')' */
4352
4353       return g_variant_builder_end (&b);
4354     }
4355 }
4356
4357 static void
4358 g_variant_valist_get (const gchar **str,
4359                       GVariant     *value,
4360                       gboolean      free,
4361                       va_list      *app)
4362 {
4363   if (g_variant_format_string_is_leaf (*str))
4364     g_variant_valist_get_leaf (str, value, free, app);
4365
4366   else if (**str == 'm')
4367     {
4368       (*str)++;
4369
4370       if (value != NULL)
4371         value = g_variant_get_maybe (value);
4372
4373       if (!g_variant_format_string_is_nnp (*str))
4374         {
4375           gboolean *ptr = va_arg (*app, gboolean *);
4376
4377           if (ptr != NULL)
4378             *ptr = value != NULL;
4379         }
4380
4381       g_variant_valist_get (str, value, free, app);
4382
4383       if (value != NULL)
4384         g_variant_unref (value);
4385     }
4386
4387   else /* tuple, dictionary entry */
4388     {
4389       gint index = 0;
4390
4391       g_assert (**str == '(' || **str == '{');
4392
4393       (*str)++;
4394       while (**str != ')' && **str != '}')
4395         {
4396           if (value != NULL)
4397             {
4398               GVariant *child = g_variant_get_child_value (value, index++);
4399               g_variant_valist_get (str, child, free, app);
4400               g_variant_unref (child);
4401             }
4402           else
4403             g_variant_valist_get (str, NULL, free, app);
4404         }
4405       (*str)++;
4406     }
4407 }
4408
4409 /* User-facing API {{{2 */
4410 /**
4411  * g_variant_new: (skip)
4412  * @format_string: a #GVariant format string
4413  * @...: arguments, as per @format_string
4414  * @returns: a new floating #GVariant instance
4415  *
4416  * Creates a new #GVariant instance.
4417  *
4418  * Think of this function as an analogue to g_strdup_printf().
4419  *
4420  * The type of the created instance and the arguments that are
4421  * expected by this function are determined by @format_string.  See the
4422  * section on <link linkend='gvariant-format-strings'>GVariant Format
4423  * Strings</link>.  Please note that the syntax of the format string is
4424  * very likely to be extended in the future.
4425  *
4426  * The first character of the format string must not be '*' '?' '@' or
4427  * 'r'; in essence, a new #GVariant must always be constructed by this
4428  * function (and not merely passed through it unmodified).
4429  *
4430  * Since: 2.24
4431  **/
4432 GVariant *
4433 g_variant_new (const gchar *format_string,
4434                ...)
4435 {
4436   GVariant *value;
4437   va_list ap;
4438
4439   g_return_val_if_fail (valid_format_string (format_string, TRUE, NULL) &&
4440                         format_string[0] != '?' && format_string[0] != '@' &&
4441                         format_string[0] != '*' && format_string[0] != 'r',
4442                         NULL);
4443
4444   va_start (ap, format_string);
4445   value = g_variant_new_va (format_string, NULL, &ap);
4446   va_end (ap);
4447
4448   return value;
4449 }
4450
4451 /**
4452  * g_variant_new_va: (skip)
4453  * @format_string: a string that is prefixed with a format string
4454  * @endptr: (allow-none) (default NULL): location to store the end pointer,
4455  *          or %NULL
4456  * @app: a pointer to a #va_list
4457  * @returns: a new, usually floating, #GVariant
4458  *
4459  * This function is intended to be used by libraries based on
4460  * #GVariant that want to provide g_variant_new()-like functionality
4461  * to their users.
4462  *
4463  * The API is more general than g_variant_new() to allow a wider range
4464  * of possible uses.
4465  *
4466  * @format_string must still point to a valid format string, but it only
4467  * needs to be nul-terminated if @endptr is %NULL.  If @endptr is
4468  * non-%NULL then it is updated to point to the first character past the
4469  * end of the format string.
4470  *
4471  * @app is a pointer to a #va_list.  The arguments, according to
4472  * @format_string, are collected from this #va_list and the list is left
4473  * pointing to the argument following the last.
4474  *
4475  * These two generalisations allow mixing of multiple calls to
4476  * g_variant_new_va() and g_variant_get_va() within a single actual
4477  * varargs call by the user.
4478  *
4479  * The return value will be floating if it was a newly created GVariant
4480  * instance (for example, if the format string was "(ii)").  In the case
4481  * that the format_string was '*', '?', 'r', or a format starting with
4482  * '@' then the collected #GVariant pointer will be returned unmodified,
4483  * without adding any additional references.
4484  *
4485  * In order to behave correctly in all cases it is necessary for the
4486  * calling function to g_variant_ref_sink() the return result before
4487  * returning control to the user that originally provided the pointer.
4488  * At this point, the caller will have their own full reference to the
4489  * result.  This can also be done by adding the result to a container,
4490  * or by passing it to another g_variant_new() call.
4491  *
4492  * Since: 2.24
4493  **/
4494 GVariant *
4495 g_variant_new_va (const gchar  *format_string,
4496                   const gchar **endptr,
4497                   va_list      *app)
4498 {
4499   GVariant *value;
4500
4501   g_return_val_if_fail (valid_format_string (format_string, !endptr, NULL),
4502                         NULL);
4503   g_return_val_if_fail (app != NULL, NULL);
4504
4505   value = g_variant_valist_new (&format_string, app);
4506
4507   if (endptr != NULL)
4508     *endptr = format_string;
4509
4510   return value;
4511 }
4512
4513 /**
4514  * g_variant_get: (skip)
4515  * @value: a #GVariant instance
4516  * @format_string: a #GVariant format string
4517  * @...: arguments, as per @format_string
4518  *
4519  * Deconstructs a #GVariant instance.
4520  *
4521  * Think of this function as an analogue to scanf().
4522  *
4523  * The arguments that are expected by this function are entirely
4524  * determined by @format_string.  @format_string also restricts the
4525  * permissible types of @value.  It is an error to give a value with
4526  * an incompatible type.  See the section on <link
4527  * linkend='gvariant-format-strings'>GVariant Format Strings</link>.
4528  * Please note that the syntax of the format string is very likely to be
4529  * extended in the future.
4530  *
4531  * Since: 2.24
4532  **/
4533 void
4534 g_variant_get (GVariant    *value,
4535                const gchar *format_string,
4536                ...)
4537 {
4538   va_list ap;
4539
4540   g_return_if_fail (valid_format_string (format_string, TRUE, value));
4541
4542   /* if any direct-pointer-access formats are in use, flatten first */
4543   if (strchr (format_string, '&'))
4544     g_variant_get_data (value);
4545
4546   va_start (ap, format_string);
4547   g_variant_get_va (value, format_string, NULL, &ap);
4548   va_end (ap);
4549 }
4550
4551 /**
4552  * g_variant_get_va: (skip)
4553  * @value: a #GVariant
4554  * @format_string: a string that is prefixed with a format string
4555  * @endptr: (allow-none) (default NULL): location to store the end pointer,
4556  *          or %NULL
4557  * @app: a pointer to a #va_list
4558  *
4559  * This function is intended to be used by libraries based on #GVariant
4560  * that want to provide g_variant_get()-like functionality to their
4561  * users.
4562  *
4563  * The API is more general than g_variant_get() to allow a wider range
4564  * of possible uses.
4565  *
4566  * @format_string must still point to a valid format string, but it only
4567  * need to be nul-terminated if @endptr is %NULL.  If @endptr is
4568  * non-%NULL then it is updated to point to the first character past the
4569  * end of the format string.
4570  *
4571  * @app is a pointer to a #va_list.  The arguments, according to
4572  * @format_string, are collected from this #va_list and the list is left
4573  * pointing to the argument following the last.
4574  *
4575  * These two generalisations allow mixing of multiple calls to
4576  * g_variant_new_va() and g_variant_get_va() within a single actual
4577  * varargs call by the user.
4578  *
4579  * Since: 2.24
4580  **/
4581 void
4582 g_variant_get_va (GVariant     *value,
4583                   const gchar  *format_string,
4584                   const gchar **endptr,
4585                   va_list      *app)
4586 {
4587   g_return_if_fail (valid_format_string (format_string, !endptr, value));
4588   g_return_if_fail (value != NULL);
4589   g_return_if_fail (app != NULL);
4590
4591   /* if any direct-pointer-access formats are in use, flatten first */
4592   if (strchr (format_string, '&'))
4593     g_variant_get_data (value);
4594
4595   g_variant_valist_get (&format_string, value, FALSE, app);
4596
4597   if (endptr != NULL)
4598     *endptr = format_string;
4599 }
4600
4601 /* Varargs-enabled Utility Functions {{{1 */
4602
4603 /**
4604  * g_variant_builder_add: (skp)
4605  * @builder: a #GVariantBuilder
4606  * @format_string: a #GVariant varargs format string
4607  * @...: arguments, as per @format_string
4608  *
4609  * Adds to a #GVariantBuilder.
4610  *
4611  * This call is a convenience wrapper that is exactly equivalent to
4612  * calling g_variant_new() followed by g_variant_builder_add_value().
4613  *
4614  * This function might be used as follows:
4615  *
4616  * <programlisting>
4617  * GVariant *
4618  * make_pointless_dictionary (void)
4619  * {
4620  *   GVariantBuilder *builder;
4621  *   int i;
4622  *
4623  *   builder = g_variant_builder_new (G_VARIANT_TYPE_ARRAY);
4624  *   for (i = 0; i < 16; i++)
4625  *     {
4626  *       gchar buf[3];
4627  *
4628  *       sprintf (buf, "%d", i);
4629  *       g_variant_builder_add (builder, "{is}", i, buf);
4630  *     }
4631  *
4632  *   return g_variant_builder_end (builder);
4633  * }
4634  * </programlisting>
4635  *
4636  * Since: 2.24
4637  **/
4638 void
4639 g_variant_builder_add (GVariantBuilder *builder,
4640                        const gchar     *format_string,
4641                        ...)
4642 {
4643   GVariant *variant;
4644   va_list ap;
4645
4646   va_start (ap, format_string);
4647   variant = g_variant_new_va (format_string, NULL, &ap);
4648   va_end (ap);
4649
4650   g_variant_builder_add_value (builder, variant);
4651 }
4652
4653 /**
4654  * g_variant_get_child: (skip)
4655  * @value: a container #GVariant
4656  * @index_: the index of the child to deconstruct
4657  * @format_string: a #GVariant format string
4658  * @...: arguments, as per @format_string
4659  *
4660  * Reads a child item out of a container #GVariant instance and
4661  * deconstructs it according to @format_string.  This call is
4662  * essentially a combination of g_variant_get_child_value() and
4663  * g_variant_get().
4664  *
4665  * Since: 2.24
4666  **/
4667 void
4668 g_variant_get_child (GVariant    *value,
4669                      gsize        index_,
4670                      const gchar *format_string,
4671                      ...)
4672 {
4673   GVariant *child;
4674   va_list ap;
4675
4676   child = g_variant_get_child_value (value, index_);
4677   g_return_if_fail (valid_format_string (format_string, TRUE, child));
4678
4679   va_start (ap, format_string);
4680   g_variant_get_va (child, format_string, NULL, &ap);
4681   va_end (ap);
4682
4683   g_variant_unref (child);
4684 }
4685
4686 /**
4687  * g_variant_iter_next: (skip)
4688  * @iter: a #GVariantIter
4689  * @format_string: a GVariant format string
4690  * @...: the arguments to unpack the value into
4691  * @returns: %TRUE if a value was unpacked, or %FALSE if there as no
4692  *           value
4693  *
4694  * Gets the next item in the container and unpacks it into the variable
4695  * argument list according to @format_string, returning %TRUE.
4696  *
4697  * If no more items remain then %FALSE is returned.
4698  *
4699  * All of the pointers given on the variable arguments list of this
4700  * function are assumed to point at uninitialised memory.  It is the
4701  * responsibility of the caller to free all of the values returned by
4702  * the unpacking process.
4703  *
4704  * See the section on <link linkend='gvariant-format-strings'>GVariant
4705  * Format Strings</link>.
4706  *
4707  * <example>
4708  *  <title>Memory management with g_variant_iter_next()</title>
4709  *  <programlisting>
4710  *   /<!-- -->* Iterates a dictionary of type 'a{sv}' *<!-- -->/
4711  *   void
4712  *   iterate_dictionary (GVariant *dictionary)
4713  *   {
4714  *     GVariantIter iter;
4715  *     GVariant *value;
4716  *     gchar *key;
4717  *
4718  *     g_variant_iter_init (&iter, dictionary);
4719  *     while (g_variant_iter_next (&iter, "{sv}", &key, &value))
4720  *       {
4721  *         g_print ("Item '%s' has type '%s'\n", key,
4722  *                  g_variant_get_type_string (value));
4723  *
4724  *         /<!-- -->* must free data for ourselves *<!-- -->/
4725  *         g_variant_unref (value);
4726  *         g_free (key);
4727  *       }
4728  *   }
4729  *  </programlisting>
4730  * </example>
4731  *
4732  * For a solution that is likely to be more convenient to C programmers
4733  * when dealing with loops, see g_variant_iter_loop().
4734  *
4735  * Since: 2.24
4736  **/
4737 gboolean
4738 g_variant_iter_next (GVariantIter *iter,
4739                      const gchar  *format_string,
4740                      ...)
4741 {
4742   GVariant *value;
4743
4744   value = g_variant_iter_next_value (iter);
4745
4746   g_return_val_if_fail (valid_format_string (format_string, TRUE, value),
4747                         FALSE);
4748
4749   if (value != NULL)
4750     {
4751       va_list ap;
4752
4753       va_start (ap, format_string);
4754       g_variant_valist_get (&format_string, value, FALSE, &ap);
4755       va_end (ap);
4756
4757       g_variant_unref (value);
4758     }
4759
4760   return value != NULL;
4761 }
4762
4763 /**
4764  * g_variant_iter_loop: (skip)
4765  * @iter: a #GVariantIter
4766  * @format_string: a GVariant format string
4767  * @...: the arguments to unpack the value into
4768  * @returns: %TRUE if a value was unpacked, or %FALSE if there as no
4769  *           value
4770  *
4771  * Gets the next item in the container and unpacks it into the variable
4772  * argument list according to @format_string, returning %TRUE.
4773  *
4774  * If no more items remain then %FALSE is returned.
4775  *
4776  * On the first call to this function, the pointers appearing on the
4777  * variable argument list are assumed to point at uninitialised memory.
4778  * On the second and later calls, it is assumed that the same pointers
4779  * will be given and that they will point to the memory as set by the
4780  * previous call to this function.  This allows the previous values to
4781  * be freed, as appropriate.
4782  *
4783  * This function is intended to be used with a while loop as
4784  * demonstrated in the following example.  This function can only be
4785  * used when iterating over an array.  It is only valid to call this
4786  * function with a string constant for the format string and the same
4787  * string constant must be used each time.  Mixing calls to this
4788  * function and g_variant_iter_next() or g_variant_iter_next_value() on
4789  * the same iterator is not recommended.
4790  *
4791  * See the section on <link linkend='gvariant-format-strings'>GVariant
4792  * Format Strings</link>.
4793  *
4794  * <example>
4795  *  <title>Memory management with g_variant_iter_loop()</title>
4796  *  <programlisting>
4797  *   /<!-- -->* Iterates a dictionary of type 'a{sv}' *<!-- -->/
4798  *   void
4799  *   iterate_dictionary (GVariant *dictionary)
4800  *   {
4801  *     GVariantIter iter;
4802  *     GVariant *value;
4803  *     gchar *key;
4804  *
4805  *     g_variant_iter_init (&iter, dictionary);
4806  *     while (g_variant_iter_loop (&iter, "{sv}", &key, &value))
4807  *       {
4808  *         g_print ("Item '%s' has type '%s'\n", key,
4809  *                  g_variant_get_type_string (value));
4810  *
4811  *         /<!-- -->* no need to free 'key' and 'value' here *<!-- -->/
4812  *       }
4813  *   }
4814  *  </programlisting>
4815  * </example>
4816  *
4817  * For most cases you should use g_variant_iter_next().
4818  *
4819  * This function is really only useful when unpacking into #GVariant or
4820  * #GVariantIter in order to allow you to skip the call to
4821  * g_variant_unref() or g_variant_iter_free().
4822  *
4823  * For example, if you are only looping over simple integer and string
4824  * types, g_variant_iter_next() is definitely preferred.  For string
4825  * types, use the '&' prefix to avoid allocating any memory at all (and
4826  * thereby avoiding the need to free anything as well).
4827  *
4828  * Since: 2.24
4829  **/
4830 gboolean
4831 g_variant_iter_loop (GVariantIter *iter,
4832                      const gchar  *format_string,
4833                      ...)
4834 {
4835   gboolean first_time = GVSI(iter)->loop_format == NULL;
4836   GVariant *value;
4837   va_list ap;
4838
4839   g_return_val_if_fail (first_time ||
4840                         format_string == GVSI(iter)->loop_format,
4841                         FALSE);
4842
4843   if (first_time)
4844     {
4845       TYPE_CHECK (GVSI(iter)->value, G_VARIANT_TYPE_ARRAY, FALSE);
4846       GVSI(iter)->loop_format = format_string;
4847
4848       if (strchr (format_string, '&'))
4849         g_variant_get_data (GVSI(iter)->value);
4850     }
4851
4852   value = g_variant_iter_next_value (iter);
4853
4854   g_return_val_if_fail (!first_time ||
4855                         valid_format_string (format_string, TRUE, value),
4856                         FALSE);
4857
4858   va_start (ap, format_string);
4859   g_variant_valist_get (&format_string, value, !first_time, &ap);
4860   va_end (ap);
4861
4862   if (value != NULL)
4863     g_variant_unref (value);
4864
4865   return value != NULL;
4866 }
4867
4868 /* Serialised data {{{1 */
4869 static GVariant *
4870 g_variant_deep_copy (GVariant *value)
4871 {
4872   switch (g_variant_classify (value))
4873     {
4874     case G_VARIANT_CLASS_MAYBE:
4875     case G_VARIANT_CLASS_ARRAY:
4876     case G_VARIANT_CLASS_TUPLE:
4877     case G_VARIANT_CLASS_DICT_ENTRY:
4878     case G_VARIANT_CLASS_VARIANT:
4879       {
4880         GVariantBuilder builder;
4881         GVariantIter iter;
4882         GVariant *child;
4883
4884         g_variant_builder_init (&builder, g_variant_get_type (value));
4885         g_variant_iter_init (&iter, value);
4886
4887         while ((child = g_variant_iter_next_value (&iter)))
4888           {
4889             g_variant_builder_add_value (&builder, g_variant_deep_copy (child));
4890             g_variant_unref (child);
4891           }
4892
4893         return g_variant_builder_end (&builder);
4894       }
4895
4896     case G_VARIANT_CLASS_BOOLEAN:
4897       return g_variant_new_boolean (g_variant_get_boolean (value));
4898
4899     case G_VARIANT_CLASS_BYTE:
4900       return g_variant_new_byte (g_variant_get_byte (value));
4901
4902     case G_VARIANT_CLASS_INT16:
4903       return g_variant_new_int16 (g_variant_get_int16 (value));
4904
4905     case G_VARIANT_CLASS_UINT16:
4906       return g_variant_new_uint16 (g_variant_get_uint16 (value));
4907
4908     case G_VARIANT_CLASS_INT32:
4909       return g_variant_new_int32 (g_variant_get_int32 (value));
4910
4911     case G_VARIANT_CLASS_UINT32:
4912       return g_variant_new_uint32 (g_variant_get_uint32 (value));
4913
4914     case G_VARIANT_CLASS_INT64:
4915       return g_variant_new_int64 (g_variant_get_int64 (value));
4916
4917     case G_VARIANT_CLASS_UINT64:
4918       return g_variant_new_uint64 (g_variant_get_uint64 (value));
4919
4920     case G_VARIANT_CLASS_HANDLE:
4921       return g_variant_new_handle (g_variant_get_handle (value));
4922
4923     case G_VARIANT_CLASS_DOUBLE:
4924       return g_variant_new_double (g_variant_get_double (value));
4925
4926     case G_VARIANT_CLASS_STRING:
4927       return g_variant_new_string (g_variant_get_string (value, NULL));
4928
4929     case G_VARIANT_CLASS_OBJECT_PATH:
4930       return g_variant_new_object_path (g_variant_get_string (value, NULL));
4931
4932     case G_VARIANT_CLASS_SIGNATURE:
4933       return g_variant_new_signature (g_variant_get_string (value, NULL));
4934     }
4935
4936   g_assert_not_reached ();
4937 }
4938
4939 /**
4940  * g_variant_get_normal_form:
4941  * @value: a #GVariant
4942  * @returns: (transfer full): a trusted #GVariant
4943  *
4944  * Gets a #GVariant instance that has the same value as @value and is
4945  * trusted to be in normal form.
4946  *
4947  * If @value is already trusted to be in normal form then a new
4948  * reference to @value is returned.
4949  *
4950  * If @value is not already trusted, then it is scanned to check if it
4951  * is in normal form.  If it is found to be in normal form then it is
4952  * marked as trusted and a new reference to it is returned.
4953  *
4954  * If @value is found not to be in normal form then a new trusted
4955  * #GVariant is created with the same value as @value.
4956  *
4957  * It makes sense to call this function if you've received #GVariant
4958  * data from untrusted sources and you want to ensure your serialised
4959  * output is definitely in normal form.
4960  *
4961  * Since: 2.24
4962  **/
4963 GVariant *
4964 g_variant_get_normal_form (GVariant *value)
4965 {
4966   GVariant *trusted;
4967
4968   if (g_variant_is_normal_form (value))
4969     return g_variant_ref (value);
4970
4971   trusted = g_variant_deep_copy (value);
4972   g_assert (g_variant_is_trusted (trusted));
4973
4974   return g_variant_ref_sink (trusted);
4975 }
4976
4977 /**
4978  * g_variant_byteswap:
4979  * @value: a #GVariant
4980  * @returns: (transfer full): the byteswapped form of @value
4981  *
4982  * Performs a byteswapping operation on the contents of @value.  The
4983  * result is that all multi-byte numeric data contained in @value is
4984  * byteswapped.  That includes 16, 32, and 64bit signed and unsigned
4985  * integers as well as file handles and double precision floating point
4986  * values.
4987  *
4988  * This function is an identity mapping on any value that does not
4989  * contain multi-byte numeric data.  That include strings, booleans,
4990  * bytes and containers containing only these things (recursively).
4991  *
4992  * The returned value is always in normal form and is marked as trusted.
4993  *
4994  * Since: 2.24
4995  **/
4996 GVariant *
4997 g_variant_byteswap (GVariant *value)
4998 {
4999   GVariantTypeInfo *type_info;
5000   guint alignment;
5001   GVariant *new;
5002
5003   type_info = g_variant_get_type_info (value);
5004
5005   g_variant_type_info_query (type_info, &alignment, NULL);
5006
5007   if (alignment)
5008     /* (potentially) contains multi-byte numeric data */
5009     {
5010       GVariantSerialised serialised;
5011       GVariant *trusted;
5012       GBuffer *buffer;
5013
5014       trusted = g_variant_get_normal_form (value);
5015       serialised.type_info = g_variant_get_type_info (trusted);
5016       serialised.size = g_variant_get_size (trusted);
5017       serialised.data = g_malloc (serialised.size);
5018       g_variant_store (trusted, serialised.data);
5019       g_variant_unref (trusted);
5020
5021       g_variant_serialised_byteswap (serialised);
5022
5023       buffer = g_buffer_new_take_data (serialised.data, serialised.size);
5024       new = g_variant_new_from_buffer (g_variant_get_type (value), buffer, TRUE);
5025       g_buffer_unref (buffer);
5026     }
5027   else
5028     /* contains no multi-byte data */
5029     new = value;
5030
5031   return g_variant_ref_sink (new);
5032 }
5033
5034 /**
5035  * g_variant_new_from_data:
5036  * @type: a definite #GVariantType
5037  * @data: (array length=size) (element-type guint8): the serialised data
5038  * @size: the size of @data
5039  * @trusted: %TRUE if @data is definitely in normal form
5040  * @notify: (scope async): function to call when @data is no longer needed
5041  * @user_data: data for @notify
5042  * @returns: (transfer none): a new floating #GVariant of type @type
5043  *
5044  * Creates a new #GVariant instance from serialised data.
5045  *
5046  * @type is the type of #GVariant instance that will be constructed.
5047  * The interpretation of @data depends on knowing the type.
5048  *
5049  * @data is not modified by this function and must remain valid with an
5050  * unchanging value until such a time as @notify is called with
5051  * @user_data.  If the contents of @data change before that time then
5052  * the result is undefined.
5053  *
5054  * If @data is trusted to be serialised data in normal form then
5055  * @trusted should be %TRUE.  This applies to serialised data created
5056  * within this process or read from a trusted location on the disk (such
5057  * as a file installed in /usr/lib alongside your application).  You
5058  * should set trusted to %FALSE if @data is read from the network, a
5059  * file in the user's home directory, etc.
5060  *
5061  * @notify will be called with @user_data when @data is no longer
5062  * needed.  The exact time of this call is unspecified and might even be
5063  * before this function returns.
5064  *
5065  * Since: 2.24
5066  **/
5067 GVariant *
5068 g_variant_new_from_data (const GVariantType *type,
5069                          gconstpointer       data,
5070                          gsize               size,
5071                          gboolean            trusted,
5072                          GDestroyNotify      notify,
5073                          gpointer            user_data)
5074 {
5075   GVariant *value;
5076   GBuffer *buffer;
5077
5078   g_return_val_if_fail (g_variant_type_is_definite (type), NULL);
5079   g_return_val_if_fail (data != NULL || size == 0, NULL);
5080
5081   if (notify)
5082     buffer = g_buffer_new_from_pointer (data, size, notify, user_data);
5083   else
5084     buffer = g_buffer_new_from_static_data (data, size);
5085
5086   value = g_variant_new_from_buffer (type, buffer, trusted);
5087   g_buffer_unref (buffer);
5088
5089   return value;
5090 }
5091
5092 /* Epilogue {{{1 */
5093 /* vim:set foldmethod=marker: */