2 * Copyright © 2007, 2008 Ryan Lortie
3 * Copyright © 2010 Codethink Limited
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.
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.
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.
20 * Author: Ryan Lortie <desrt@desrt.ca>
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>
42 * @short_description: strongly typed value datatype
43 * @see_also: GVariantType
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
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.
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().
59 * #GVariant is completely threadsafe. A #GVariant instance can be
60 * concurrently accessed in any way from any number of threads without
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.
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.)
75 * For space-efficiency, the #GVariant serialisation format does not
76 * automatically include the variant's type or endianness, which must
77 * either be implied from context (such as knowledge that a particular
78 * file format always contains a little-endian %G_VARIANT_TYPE_VARIANT)
79 * or supplied out-of-band (for instance, a type and/or endianness
80 * indicator could be placed at the beginning of a file, network message
83 * A #GVariant's size is limited mainly by any lower level operating
84 * system constraints, such as the number of bits in #gsize. For
85 * example, it is reasonable to have a 2GB file mapped into memory
86 * with #GMappedFile, and call g_variant_new_from_data() on it.
88 * For convenience to C programmers, #GVariant features powerful
89 * varargs-based value construction and destruction. This feature is
90 * designed to be embedded in other libraries.
92 * There is a Python-inspired text language for describing #GVariant
93 * values. #GVariant includes a printer for this language and a parser
94 * with type inferencing.
97 * <title>Memory Use</title>
99 * #GVariant tries to be quite efficient with respect to memory use.
100 * This section gives a rough idea of how much memory is used by the
101 * current implementation. The information here is subject to change
105 * The memory allocated by #GVariant can be grouped into 4 broad
106 * purposes: memory for serialised data, memory for the type
107 * information cache, buffer management memory and memory for the
108 * #GVariant structure itself.
110 * <refsect3 id="gvariant-serialised-data-memory">
111 * <title>Serialised Data Memory</title>
113 * This is the memory that is used for storing GVariant data in
114 * serialised form. This is what would be sent over the network or
115 * what would end up on disk.
118 * The amount of memory required to store a boolean is 1 byte. 16,
119 * 32 and 64 bit integers and double precision floating point numbers
120 * use their "natural" size. Strings (including object path and
121 * signature strings) are stored with a nul terminator, and as such
122 * use the length of the string plus 1 byte.
125 * Maybe types use no space at all to represent the null value and
126 * use the same amount of space (sometimes plus one byte) as the
127 * equivalent non-maybe-typed value to represent the non-null case.
130 * Arrays use the amount of space required to store each of their
131 * members, concatenated. Additionally, if the items stored in an
132 * array are not of a fixed-size (ie: strings, other arrays, etc)
133 * then an additional framing offset is stored for each item. The
134 * size of this offset is either 1, 2 or 4 bytes depending on the
135 * overall size of the container. Additionally, extra padding bytes
136 * are added as required for alignment of child values.
139 * Tuples (including dictionary entries) use the amount of space
140 * required to store each of their members, concatenated, plus one
141 * framing offset (as per arrays) for each non-fixed-sized item in
142 * the tuple, except for the last one. Additionally, extra padding
143 * bytes are added as required for alignment of child values.
146 * Variants use the same amount of space as the item inside of the
147 * variant, plus 1 byte, plus the length of the type string for the
148 * item inside the variant.
151 * As an example, consider a dictionary mapping strings to variants.
152 * In the case that the dictionary is empty, 0 bytes are required for
156 * If we add an item "width" that maps to the int32 value of 500 then
157 * we will use 4 byte to store the int32 (so 6 for the variant
158 * containing it) and 6 bytes for the string. The variant must be
159 * aligned to 8 after the 6 bytes of the string, so that's 2 extra
160 * bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used
161 * for the dictionary entry. An additional 1 byte is added to the
162 * array as a framing offset making a total of 15 bytes.
165 * If we add another entry, "title" that maps to a nullable string
166 * that happens to have a value of null, then we use 0 bytes for the
167 * null value (and 3 bytes for the variant to contain it along with
168 * its type string) plus 6 bytes for the string. Again, we need 2
169 * padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes.
172 * We now require extra padding between the two items in the array.
173 * After the 14 bytes of the first item, that's 2 bytes required. We
174 * now require 2 framing offsets for an extra two bytes. 14 + 2 + 11
175 * + 2 = 29 bytes to encode the entire two-item dictionary.
179 * <title>Type Information Cache</title>
181 * For each GVariant type that currently exists in the program a type
182 * information structure is kept in the type information cache. The
183 * type information structure is required for rapid deserialisation.
186 * Continuing with the above example, if a #GVariant exists with the
187 * type "a{sv}" then a type information struct will exist for
188 * "a{sv}", "{sv}", "s", and "v". Multiple uses of the same type
189 * will share the same type information. Additionally, all
190 * single-digit types are stored in read-only static memory and do
191 * not contribute to the writable memory footprint of a program using
195 * Aside from the type information structures stored in read-only
196 * memory, there are two forms of type information. One is used for
197 * container types where there is a single element type: arrays and
198 * maybe types. The other is used for container types where there
199 * are multiple element types: tuples and dictionary entries.
202 * Array type info structures are 6 * sizeof (void *), plus the
203 * memory required to store the type string itself. This means that
204 * on 32bit systems, the cache entry for "a{sv}" would require 30
205 * bytes of memory (plus malloc overhead).
208 * Tuple type info structures are 6 * sizeof (void *), plus 4 *
209 * sizeof (void *) for each item in the tuple, plus the memory
210 * required to store the type string itself. A 2-item tuple, for
211 * example, would have a type information structure that consumed
212 * writable memory in the size of 14 * sizeof (void *) (plus type
213 * string) This means that on 32bit systems, the cache entry for
214 * "{sv}" would require 61 bytes of memory (plus malloc overhead).
217 * This means that in total, for our "a{sv}" example, 91 bytes of
218 * type information would be allocated.
221 * The type information cache, additionally, uses a #GHashTable to
222 * store and lookup the cached items and stores a pointer to this
223 * hash table in static storage. The hash table is freed when there
224 * are zero items in the type cache.
227 * Although these sizes may seem large it is important to remember
228 * that a program will probably only have a very small number of
229 * different types of values in it and that only one type information
230 * structure is required for many different values of the same type.
234 * <title>Buffer Management Memory</title>
236 * #GVariant uses an internal buffer management structure to deal
237 * with the various different possible sources of serialised data
238 * that it uses. The buffer is responsible for ensuring that the
239 * correct call is made when the data is no longer in use by
240 * #GVariant. This may involve a g_free() or a g_slice_free() or
241 * even g_mapped_file_unref().
244 * One buffer management structure is used for each chunk of
245 * serialised data. The size of the buffer management structure is 4
246 * * (void *). On 32bit systems, that's 16 bytes.
250 * <title>GVariant structure</title>
252 * The size of a #GVariant structure is 6 * (void *). On 32 bit
253 * systems, that's 24 bytes.
256 * #GVariant structures only exist if they are explicitly created
257 * with API calls. For example, if a #GVariant is constructed out of
258 * serialised data for the example given above (with the dictionary)
259 * then although there are 9 individual values that comprise the
260 * entire dictionary (two keys, two values, two variants containing
261 * the values, two dictionary entries, plus the dictionary itself),
262 * only 1 #GVariant instance exists -- the one referring to the
266 * If calls are made to start accessing the other values then
267 * #GVariant instances will exist for those values only for as long
268 * as they are in use (ie: until you call g_variant_unref()). The
269 * type information is shared. The serialised data and the buffer
270 * management structure for that serialised data is shared by the
275 * <title>Summary</title>
277 * To put the entire example together, for our dictionary mapping
278 * strings to variants (with two entries, as given above), we are
279 * using 91 bytes of memory for type information, 29 byes of memory
280 * for the serialised data, 16 bytes for buffer management and 24
281 * bytes for the #GVariant instance, or a total of 160 bytes, plus
282 * malloc overhead. If we were to use g_variant_get_child_value() to
283 * access the two dictionary entries, we would use an additional 48
284 * bytes. If we were to have other dictionaries of the same type, we
285 * would use more memory for the serialised data and buffer
286 * management for those dictionaries, but the type information would
293 /* definition of GVariant structure is in gvariant-core.c */
295 /* this is a g_return_val_if_fail() for making
296 * sure a (GVariant *) has the required type.
298 #define TYPE_CHECK(value, TYPE, val) \
299 if G_UNLIKELY (!g_variant_is_of_type (value, TYPE)) { \
300 g_return_if_fail_warning (G_LOG_DOMAIN, G_STRFUNC, \
301 "g_variant_is_of_type (" #value \
306 /* Numeric Type Constructor/Getters {{{1 */
308 * g_variant_new_from_trusted:
309 * @type: the #GVariantType
310 * @data: the data to use
311 * @size: the size of @data
313 * Constructs a new trusted #GVariant instance from the provided data.
314 * This is used to implement g_variant_new_* for all the basic types.
316 * Returns: a new floating #GVariant
319 g_variant_new_from_trusted (const GVariantType
*type
,
326 bytes
= g_bytes_new (data
, size
);
327 value
= g_variant_new_from_bytes (type
, bytes
, TRUE
);
328 g_bytes_unref (bytes
);
334 * g_variant_new_boolean:
335 * @value: a #gboolean value
337 * Creates a new boolean #GVariant instance -- either %TRUE or %FALSE.
339 * Returns: (transfer none): a floating reference to a new boolean #GVariant instance
344 g_variant_new_boolean (gboolean value
)
348 return g_variant_new_from_trusted (G_VARIANT_TYPE_BOOLEAN
, &v
, 1);
352 * g_variant_get_boolean:
353 * @value: a boolean #GVariant instance
355 * Returns the boolean value of @value.
357 * It is an error to call this function with a @value of any type
358 * other than %G_VARIANT_TYPE_BOOLEAN.
360 * Returns: %TRUE or %FALSE
365 g_variant_get_boolean (GVariant
*value
)
369 TYPE_CHECK (value
, G_VARIANT_TYPE_BOOLEAN
, FALSE
);
371 data
= g_variant_get_data (value
);
373 return data
!= NULL
? *data
!= 0 : FALSE
;
376 /* the constructors and accessors for byte, int{16,32,64}, handles and
377 * doubles all look pretty much exactly the same, so we reduce
380 #define NUMERIC_TYPE(TYPE, type, ctype) \
381 GVariant *g_variant_new_##type (ctype value) { \
382 return g_variant_new_from_trusted (G_VARIANT_TYPE_##TYPE, \
383 &value, sizeof value); \
385 ctype g_variant_get_##type (GVariant *value) { \
387 TYPE_CHECK (value, G_VARIANT_TYPE_ ## TYPE, 0); \
388 data = g_variant_get_data (value); \
389 return data != NULL ? *data : 0; \
394 * g_variant_new_byte:
395 * @value: a #guint8 value
397 * Creates a new byte #GVariant instance.
399 * Returns: (transfer none): a floating reference to a new byte #GVariant instance
404 * g_variant_get_byte:
405 * @value: a byte #GVariant instance
407 * Returns the byte value of @value.
409 * It is an error to call this function with a @value of any type
410 * other than %G_VARIANT_TYPE_BYTE.
416 NUMERIC_TYPE (BYTE
, byte
, guchar
)
419 * g_variant_new_int16:
420 * @value: a #gint16 value
422 * Creates a new int16 #GVariant instance.
424 * Returns: (transfer none): a floating reference to a new int16 #GVariant instance
429 * g_variant_get_int16:
430 * @value: a int16 #GVariant instance
432 * Returns the 16-bit signed integer value of @value.
434 * It is an error to call this function with a @value of any type
435 * other than %G_VARIANT_TYPE_INT16.
441 NUMERIC_TYPE (INT16
, int16
, gint16
)
444 * g_variant_new_uint16:
445 * @value: a #guint16 value
447 * Creates a new uint16 #GVariant instance.
449 * Returns: (transfer none): a floating reference to a new uint16 #GVariant instance
454 * g_variant_get_uint16:
455 * @value: a uint16 #GVariant instance
457 * Returns the 16-bit unsigned integer value of @value.
459 * It is an error to call this function with a @value of any type
460 * other than %G_VARIANT_TYPE_UINT16.
462 * Returns: a #guint16
466 NUMERIC_TYPE (UINT16
, uint16
, guint16
)
469 * g_variant_new_int32:
470 * @value: a #gint32 value
472 * Creates a new int32 #GVariant instance.
474 * Returns: (transfer none): a floating reference to a new int32 #GVariant instance
479 * g_variant_get_int32:
480 * @value: a int32 #GVariant instance
482 * Returns the 32-bit signed integer value of @value.
484 * It is an error to call this function with a @value of any type
485 * other than %G_VARIANT_TYPE_INT32.
491 NUMERIC_TYPE (INT32
, int32
, gint32
)
494 * g_variant_new_uint32:
495 * @value: a #guint32 value
497 * Creates a new uint32 #GVariant instance.
499 * Returns: (transfer none): a floating reference to a new uint32 #GVariant instance
504 * g_variant_get_uint32:
505 * @value: a uint32 #GVariant instance
507 * Returns the 32-bit unsigned integer value of @value.
509 * It is an error to call this function with a @value of any type
510 * other than %G_VARIANT_TYPE_UINT32.
512 * Returns: a #guint32
516 NUMERIC_TYPE (UINT32
, uint32
, guint32
)
519 * g_variant_new_int64:
520 * @value: a #gint64 value
522 * Creates a new int64 #GVariant instance.
524 * Returns: (transfer none): a floating reference to a new int64 #GVariant instance
529 * g_variant_get_int64:
530 * @value: a int64 #GVariant instance
532 * Returns the 64-bit signed integer value of @value.
534 * It is an error to call this function with a @value of any type
535 * other than %G_VARIANT_TYPE_INT64.
541 NUMERIC_TYPE (INT64
, int64
, gint64
)
544 * g_variant_new_uint64:
545 * @value: a #guint64 value
547 * Creates a new uint64 #GVariant instance.
549 * Returns: (transfer none): a floating reference to a new uint64 #GVariant instance
554 * g_variant_get_uint64:
555 * @value: a uint64 #GVariant instance
557 * Returns the 64-bit unsigned integer value of @value.
559 * It is an error to call this function with a @value of any type
560 * other than %G_VARIANT_TYPE_UINT64.
562 * Returns: a #guint64
566 NUMERIC_TYPE (UINT64
, uint64
, guint64
)
569 * g_variant_new_handle:
570 * @value: a #gint32 value
572 * Creates a new handle #GVariant instance.
574 * By convention, handles are indexes into an array of file descriptors
575 * that are sent alongside a D-Bus message. If you're not interacting
576 * with D-Bus, you probably don't need them.
578 * Returns: (transfer none): a floating reference to a new handle #GVariant instance
583 * g_variant_get_handle:
584 * @value: a handle #GVariant instance
586 * Returns the 32-bit signed integer value of @value.
588 * It is an error to call this function with a @value of any type other
589 * than %G_VARIANT_TYPE_HANDLE.
591 * By convention, handles are indexes into an array of file descriptors
592 * that are sent alongside a D-Bus message. If you're not interacting
593 * with D-Bus, you probably don't need them.
599 NUMERIC_TYPE (HANDLE
, handle
, gint32
)
602 * g_variant_new_double:
603 * @value: a #gdouble floating point value
605 * Creates a new double #GVariant instance.
607 * Returns: (transfer none): a floating reference to a new double #GVariant instance
612 * g_variant_get_double:
613 * @value: a double #GVariant instance
615 * Returns the double precision floating point value of @value.
617 * It is an error to call this function with a @value of any type
618 * other than %G_VARIANT_TYPE_DOUBLE.
620 * Returns: a #gdouble
624 NUMERIC_TYPE (DOUBLE
, double, gdouble
)
626 /* Container type Constructor / Deconstructors {{{1 */
628 * g_variant_new_maybe:
629 * @child_type: (allow-none): the #GVariantType of the child, or %NULL
630 * @child: (allow-none): the child value, or %NULL
632 * Depending on if @child is %NULL, either wraps @child inside of a
633 * maybe container or creates a Nothing instance for the given @type.
635 * At least one of @child_type and @child must be non-%NULL.
636 * If @child_type is non-%NULL then it must be a definite type.
637 * If they are both non-%NULL then @child_type must be the type
640 * If @child is a floating reference (see g_variant_ref_sink()), the new
641 * instance takes ownership of @child.
643 * Returns: (transfer none): a floating reference to a new #GVariant maybe instance
648 g_variant_new_maybe (const GVariantType
*child_type
,
651 GVariantType
*maybe_type
;
654 g_return_val_if_fail (child_type
== NULL
|| g_variant_type_is_definite
656 g_return_val_if_fail (child_type
!= NULL
|| child
!= NULL
, NULL
);
657 g_return_val_if_fail (child_type
== NULL
|| child
== NULL
||
658 g_variant_is_of_type (child
, child_type
),
661 if (child_type
== NULL
)
662 child_type
= g_variant_get_type (child
);
664 maybe_type
= g_variant_type_new_maybe (child_type
);
671 children
= g_new (GVariant
*, 1);
672 children
[0] = g_variant_ref_sink (child
);
673 trusted
= g_variant_is_trusted (children
[0]);
675 value
= g_variant_new_from_children (maybe_type
, children
, 1, trusted
);
678 value
= g_variant_new_from_children (maybe_type
, NULL
, 0, TRUE
);
680 g_variant_type_free (maybe_type
);
686 * g_variant_get_maybe:
687 * @value: a maybe-typed value
689 * Given a maybe-typed #GVariant instance, extract its value. If the
690 * value is Nothing, then this function returns %NULL.
692 * Returns: (allow-none) (transfer full): the contents of @value, or %NULL
697 g_variant_get_maybe (GVariant
*value
)
699 TYPE_CHECK (value
, G_VARIANT_TYPE_MAYBE
, NULL
);
701 if (g_variant_n_children (value
))
702 return g_variant_get_child_value (value
, 0);
708 * g_variant_new_variant: (constructor)
709 * @value: a #GVariant instance
711 * Boxes @value. The result is a #GVariant instance representing a
712 * variant containing the original value.
714 * If @child is a floating reference (see g_variant_ref_sink()), the new
715 * instance takes ownership of @child.
717 * Returns: (transfer none): a floating reference to a new variant #GVariant instance
722 g_variant_new_variant (GVariant
*value
)
724 g_return_val_if_fail (value
!= NULL
, NULL
);
726 g_variant_ref_sink (value
);
728 return g_variant_new_from_children (G_VARIANT_TYPE_VARIANT
,
729 g_memdup (&value
, sizeof value
),
730 1, g_variant_is_trusted (value
));
734 * g_variant_get_variant:
735 * @value: a variant #GVariant instance
737 * Unboxes @value. The result is the #GVariant instance that was
738 * contained in @value.
740 * Returns: (transfer full): the item contained in the variant
745 g_variant_get_variant (GVariant
*value
)
747 TYPE_CHECK (value
, G_VARIANT_TYPE_VARIANT
, NULL
);
749 return g_variant_get_child_value (value
, 0);
753 * g_variant_new_array:
754 * @child_type: (allow-none): the element type of the new array
755 * @children: (allow-none) (array length=n_children): an array of
756 * #GVariant pointers, the children
757 * @n_children: the length of @children
759 * Creates a new #GVariant array from @children.
761 * @child_type must be non-%NULL if @n_children is zero. Otherwise, the
762 * child type is determined by inspecting the first element of the
763 * @children array. If @child_type is non-%NULL then it must be a
766 * The items of the array are taken from the @children array. No entry
767 * in the @children array may be %NULL.
769 * All items in the array must have the same type, which must be the
770 * same as @child_type, if given.
772 * If the @children are floating references (see g_variant_ref_sink()), the
773 * new instance takes ownership of them as if via g_variant_ref_sink().
775 * Returns: (transfer none): a floating reference to a new #GVariant array
780 g_variant_new_array (const GVariantType
*child_type
,
781 GVariant
* const *children
,
784 GVariantType
*array_type
;
785 GVariant
**my_children
;
790 g_return_val_if_fail (n_children
> 0 || child_type
!= NULL
, NULL
);
791 g_return_val_if_fail (n_children
== 0 || children
!= NULL
, NULL
);
792 g_return_val_if_fail (child_type
== NULL
||
793 g_variant_type_is_definite (child_type
), NULL
);
795 my_children
= g_new (GVariant
*, n_children
);
798 if (child_type
== NULL
)
799 child_type
= g_variant_get_type (children
[0]);
800 array_type
= g_variant_type_new_array (child_type
);
802 for (i
= 0; i
< n_children
; i
++)
804 TYPE_CHECK (children
[i
], child_type
, NULL
);
805 my_children
[i
] = g_variant_ref_sink (children
[i
]);
806 trusted
&= g_variant_is_trusted (children
[i
]);
809 value
= g_variant_new_from_children (array_type
, my_children
,
810 n_children
, trusted
);
811 g_variant_type_free (array_type
);
817 * g_variant_make_tuple_type:
818 * @children: (array length=n_children): an array of GVariant *
819 * @n_children: the length of @children
821 * Return the type of a tuple containing @children as its items.
823 static GVariantType
*
824 g_variant_make_tuple_type (GVariant
* const *children
,
827 const GVariantType
**types
;
831 types
= g_new (const GVariantType
*, n_children
);
833 for (i
= 0; i
< n_children
; i
++)
834 types
[i
] = g_variant_get_type (children
[i
]);
836 type
= g_variant_type_new_tuple (types
, n_children
);
843 * g_variant_new_tuple:
844 * @children: (array length=n_children): the items to make the tuple out of
845 * @n_children: the length of @children
847 * Creates a new tuple #GVariant out of the items in @children. The
848 * type is determined from the types of @children. No entry in the
849 * @children array may be %NULL.
851 * If @n_children is 0 then the unit tuple is constructed.
853 * If the @children are floating references (see g_variant_ref_sink()), the
854 * new instance takes ownership of them as if via g_variant_ref_sink().
856 * Returns: (transfer none): a floating reference to a new #GVariant tuple
861 g_variant_new_tuple (GVariant
* const *children
,
864 GVariantType
*tuple_type
;
865 GVariant
**my_children
;
870 g_return_val_if_fail (n_children
== 0 || children
!= NULL
, NULL
);
872 my_children
= g_new (GVariant
*, n_children
);
875 for (i
= 0; i
< n_children
; i
++)
877 my_children
[i
] = g_variant_ref_sink (children
[i
]);
878 trusted
&= g_variant_is_trusted (children
[i
]);
881 tuple_type
= g_variant_make_tuple_type (children
, n_children
);
882 value
= g_variant_new_from_children (tuple_type
, my_children
,
883 n_children
, trusted
);
884 g_variant_type_free (tuple_type
);
890 * g_variant_make_dict_entry_type:
891 * @key: a #GVariant, the key
892 * @val: a #GVariant, the value
894 * Return the type of a dictionary entry containing @key and @val as its
897 static GVariantType
*
898 g_variant_make_dict_entry_type (GVariant
*key
,
901 return g_variant_type_new_dict_entry (g_variant_get_type (key
),
902 g_variant_get_type (val
));
906 * g_variant_new_dict_entry: (constructor)
907 * @key: a basic #GVariant, the key
908 * @value: a #GVariant, the value
910 * Creates a new dictionary entry #GVariant. @key and @value must be
911 * non-%NULL. @key must be a value of a basic type (ie: not a container).
913 * If the @key or @value are floating references (see g_variant_ref_sink()),
914 * the new instance takes ownership of them as if via g_variant_ref_sink().
916 * Returns: (transfer none): a floating reference to a new dictionary entry #GVariant
921 g_variant_new_dict_entry (GVariant
*key
,
924 GVariantType
*dict_type
;
928 g_return_val_if_fail (key
!= NULL
&& value
!= NULL
, NULL
);
929 g_return_val_if_fail (!g_variant_is_container (key
), NULL
);
931 children
= g_new (GVariant
*, 2);
932 children
[0] = g_variant_ref_sink (key
);
933 children
[1] = g_variant_ref_sink (value
);
934 trusted
= g_variant_is_trusted (key
) && g_variant_is_trusted (value
);
936 dict_type
= g_variant_make_dict_entry_type (key
, value
);
937 value
= g_variant_new_from_children (dict_type
, children
, 2, trusted
);
938 g_variant_type_free (dict_type
);
944 * g_variant_lookup: (skip)
945 * @dictionary: a dictionary #GVariant
946 * @key: the key to lookup in the dictionary
947 * @format_string: a GVariant format string
948 * @...: the arguments to unpack the value into
950 * Looks up a value in a dictionary #GVariant.
952 * This function is a wrapper around g_variant_lookup_value() and
953 * g_variant_get(). In the case that %NULL would have been returned,
954 * this function returns %FALSE. Otherwise, it unpacks the returned
955 * value and returns %TRUE.
957 * See g_variant_get() for information about @format_string.
959 * Returns: %TRUE if a value was unpacked
964 g_variant_lookup (GVariant
*dictionary
,
966 const gchar
*format_string
,
973 g_variant_get_data (dictionary
);
975 type
= g_variant_format_string_scan_type (format_string
, NULL
, NULL
);
976 value
= g_variant_lookup_value (dictionary
, key
, type
);
977 g_variant_type_free (type
);
983 va_start (ap
, format_string
);
984 g_variant_get_va (value
, format_string
, NULL
, &ap
);
985 g_variant_unref (value
);
996 * g_variant_lookup_value:
997 * @dictionary: a dictionary #GVariant
998 * @key: the key to lookup in the dictionary
999 * @expected_type: (allow-none): a #GVariantType, or %NULL
1001 * Looks up a value in a dictionary #GVariant.
1003 * This function works with dictionaries of the type
1004 * <literal>a{s*}</literal> (and equally well with type
1005 * <literal>a{o*}</literal>, but we only further discuss the string case
1006 * for sake of clarity).
1008 * In the event that @dictionary has the type <literal>a{sv}</literal>,
1009 * the @expected_type string specifies what type of value is expected to
1010 * be inside of the variant. If the value inside the variant has a
1011 * different type then %NULL is returned. In the event that @dictionary
1012 * has a value type other than <literal>v</literal> then @expected_type
1013 * must directly match the key type and it is used to unpack the value
1014 * directly or an error occurs.
1016 * In either case, if @key is not found in @dictionary, %NULL is
1019 * If the key is found and the value has the correct type, it is
1020 * returned. If @expected_type was specified then any non-%NULL return
1021 * value will have this type.
1023 * Returns: (transfer full): the value of the dictionary key, or %NULL
1028 g_variant_lookup_value (GVariant
*dictionary
,
1030 const GVariantType
*expected_type
)
1036 g_return_val_if_fail (g_variant_is_of_type (dictionary
,
1037 G_VARIANT_TYPE ("a{s*}")) ||
1038 g_variant_is_of_type (dictionary
,
1039 G_VARIANT_TYPE ("a{o*}")),
1042 g_variant_iter_init (&iter
, dictionary
);
1044 while ((entry
= g_variant_iter_next_value (&iter
)))
1046 GVariant
*entry_key
;
1049 entry_key
= g_variant_get_child_value (entry
, 0);
1050 matches
= strcmp (g_variant_get_string (entry_key
, NULL
), key
) == 0;
1051 g_variant_unref (entry_key
);
1056 g_variant_unref (entry
);
1062 value
= g_variant_get_child_value (entry
, 1);
1063 g_variant_unref (entry
);
1065 if (g_variant_is_of_type (value
, G_VARIANT_TYPE_VARIANT
))
1069 tmp
= g_variant_get_variant (value
);
1070 g_variant_unref (value
);
1072 if (expected_type
&& !g_variant_is_of_type (tmp
, expected_type
))
1074 g_variant_unref (tmp
);
1081 g_return_val_if_fail (expected_type
== NULL
|| value
== NULL
||
1082 g_variant_is_of_type (value
, expected_type
), NULL
);
1088 * g_variant_get_fixed_array:
1089 * @value: a #GVariant array with fixed-sized elements
1090 * @n_elements: (out): a pointer to the location to store the number of items
1091 * @element_size: the size of each element
1093 * Provides access to the serialised data for an array of fixed-sized
1096 * @value must be an array with fixed-sized elements. Numeric types are
1097 * fixed-size, as are tuples containing only other fixed-sized types.
1099 * @element_size must be the size of a single element in the array,
1100 * as given by the section on
1101 * <link linkend='gvariant-serialised-data-memory'>Serialised Data
1104 * In particular, arrays of these fixed-sized types can be interpreted
1105 * as an array of the given C type, with @element_size set to
1106 * <code>sizeof</code> the appropriate type:
1110 * <thead><row><entry>element type</entry> <entry>C type</entry></row></thead>
1112 * <row><entry>%G_VARIANT_TYPE_INT16 (etc.)</entry>
1113 * <entry>#gint16 (etc.)</entry></row>
1114 * <row><entry>%G_VARIANT_TYPE_BOOLEAN</entry>
1115 * <entry>#guchar (not #gboolean!)</entry></row>
1116 * <row><entry>%G_VARIANT_TYPE_BYTE</entry> <entry>#guchar</entry></row>
1117 * <row><entry>%G_VARIANT_TYPE_HANDLE</entry> <entry>#guint32</entry></row>
1118 * <row><entry>%G_VARIANT_TYPE_DOUBLE</entry> <entry>#gdouble</entry></row>
1123 * For example, if calling this function for an array of 32 bit integers,
1124 * you might say <code>sizeof (gint32)</code>. This value isn't used
1125 * except for the purpose of a double-check that the form of the
1126 * serialised data matches the caller's expectation.
1128 * @n_elements, which must be non-%NULL is set equal to the number of
1129 * items in the array.
1131 * Returns: (array length=n_elements) (transfer none): a pointer to
1137 g_variant_get_fixed_array (GVariant
*value
,
1141 GVariantTypeInfo
*array_info
;
1142 gsize array_element_size
;
1146 TYPE_CHECK (value
, G_VARIANT_TYPE_ARRAY
, NULL
);
1148 g_return_val_if_fail (n_elements
!= NULL
, NULL
);
1149 g_return_val_if_fail (element_size
> 0, NULL
);
1151 array_info
= g_variant_get_type_info (value
);
1152 g_variant_type_info_query_element (array_info
, NULL
, &array_element_size
);
1154 g_return_val_if_fail (array_element_size
, NULL
);
1156 if G_UNLIKELY (array_element_size
!= element_size
)
1158 if (array_element_size
)
1159 g_critical ("g_variant_get_fixed_array: assertion "
1160 "`g_variant_array_has_fixed_size (value, element_size)' "
1161 "failed: array size %"G_GSIZE_FORMAT
" does not match "
1162 "given element_size %"G_GSIZE_FORMAT
".",
1163 array_element_size
, element_size
);
1165 g_critical ("g_variant_get_fixed_array: assertion "
1166 "`g_variant_array_has_fixed_size (value, element_size)' "
1167 "failed: array does not have fixed size.");
1170 data
= g_variant_get_data (value
);
1171 size
= g_variant_get_size (value
);
1173 if (size
% element_size
)
1176 *n_elements
= size
/ element_size
;
1185 * g_variant_new_fixed_array:
1186 * @element_type: the #GVariantType of each element
1187 * @elements: a pointer to the fixed array of contiguous elements
1188 * @n_elements: the number of elements
1189 * @element_size: the size of each element
1191 * Provides access to the serialised data for an array of fixed-sized
1194 * @value must be an array with fixed-sized elements. Numeric types are
1195 * fixed-size as are tuples containing only other fixed-sized types.
1197 * @element_size must be the size of a single element in the array. For
1198 * example, if calling this function for an array of 32 bit integers,
1199 * you might say <code>sizeof (gint32)</code>. This value isn't used
1200 * except for the purpose of a double-check that the form of the
1201 * serialised data matches the caller's expectation.
1203 * @n_elements, which must be non-%NULL is set equal to the number of
1204 * items in the array.
1206 * Returns: (transfer none): a floating reference to a new array #GVariant instance
1211 g_variant_new_fixed_array (const GVariantType
*element_type
,
1212 gconstpointer elements
,
1216 GVariantType
*array_type
;
1217 gsize array_element_size
;
1218 GVariantTypeInfo
*array_info
;
1222 g_return_val_if_fail (g_variant_type_is_definite (element_type
), NULL
);
1223 g_return_val_if_fail (element_size
> 0, NULL
);
1225 array_type
= g_variant_type_new_array (element_type
);
1226 array_info
= g_variant_type_info_get (array_type
);
1227 g_variant_type_info_query_element (array_info
, NULL
, &array_element_size
);
1228 if G_UNLIKELY (array_element_size
!= element_size
)
1230 if (array_element_size
)
1231 g_critical ("g_variant_new_fixed_array: array size %" G_GSIZE_FORMAT
1232 " does not match given element_size %" G_GSIZE_FORMAT
".",
1233 array_element_size
, element_size
);
1235 g_critical ("g_variant_get_fixed_array: array does not have fixed size.");
1239 data
= g_memdup (elements
, n_elements
* element_size
);
1240 value
= g_variant_new_from_data (array_type
, data
,
1241 n_elements
* element_size
,
1242 FALSE
, g_free
, data
);
1244 g_variant_type_free (array_type
);
1245 g_variant_type_info_unref (array_info
);
1250 /* String type constructor/getters/validation {{{1 */
1252 * g_variant_new_string:
1253 * @string: a normal utf8 nul-terminated string
1255 * Creates a string #GVariant with the contents of @string.
1257 * @string must be valid utf8.
1259 * Returns: (transfer none): a floating reference to a new string #GVariant instance
1264 g_variant_new_string (const gchar
*string
)
1266 g_return_val_if_fail (string
!= NULL
, NULL
);
1267 g_return_val_if_fail (g_utf8_validate (string
, -1, NULL
), NULL
);
1269 return g_variant_new_from_trusted (G_VARIANT_TYPE_STRING
,
1270 string
, strlen (string
) + 1);
1274 * g_variant_new_object_path:
1275 * @object_path: a normal C nul-terminated string
1277 * Creates a D-Bus object path #GVariant with the contents of @string.
1278 * @string must be a valid D-Bus object path. Use
1279 * g_variant_is_object_path() if you're not sure.
1281 * Returns: (transfer none): a floating reference to a new object path #GVariant instance
1286 g_variant_new_object_path (const gchar
*object_path
)
1288 g_return_val_if_fail (g_variant_is_object_path (object_path
), NULL
);
1290 return g_variant_new_from_trusted (G_VARIANT_TYPE_OBJECT_PATH
,
1291 object_path
, strlen (object_path
) + 1);
1295 * g_variant_is_object_path:
1296 * @string: a normal C nul-terminated string
1298 * Determines if a given string is a valid D-Bus object path. You
1299 * should ensure that a string is a valid D-Bus object path before
1300 * passing it to g_variant_new_object_path().
1302 * A valid object path starts with '/' followed by zero or more
1303 * sequences of characters separated by '/' characters. Each sequence
1304 * must contain only the characters "[A-Z][a-z][0-9]_". No sequence
1305 * (including the one following the final '/' character) may be empty.
1307 * Returns: %TRUE if @string is a D-Bus object path
1312 g_variant_is_object_path (const gchar
*string
)
1314 g_return_val_if_fail (string
!= NULL
, FALSE
);
1316 return g_variant_serialiser_is_object_path (string
, strlen (string
) + 1);
1320 * g_variant_new_signature:
1321 * @signature: a normal C nul-terminated string
1323 * Creates a D-Bus type signature #GVariant with the contents of
1324 * @string. @string must be a valid D-Bus type signature. Use
1325 * g_variant_is_signature() if you're not sure.
1327 * Returns: (transfer none): a floating reference to a new signature #GVariant instance
1332 g_variant_new_signature (const gchar
*signature
)
1334 g_return_val_if_fail (g_variant_is_signature (signature
), NULL
);
1336 return g_variant_new_from_trusted (G_VARIANT_TYPE_SIGNATURE
,
1337 signature
, strlen (signature
) + 1);
1341 * g_variant_is_signature:
1342 * @string: a normal C nul-terminated string
1344 * Determines if a given string is a valid D-Bus type signature. You
1345 * should ensure that a string is a valid D-Bus type signature before
1346 * passing it to g_variant_new_signature().
1348 * D-Bus type signatures consist of zero or more definite #GVariantType
1349 * strings in sequence.
1351 * Returns: %TRUE if @string is a D-Bus type signature
1356 g_variant_is_signature (const gchar
*string
)
1358 g_return_val_if_fail (string
!= NULL
, FALSE
);
1360 return g_variant_serialiser_is_signature (string
, strlen (string
) + 1);
1364 * g_variant_get_string:
1365 * @value: a string #GVariant instance
1366 * @length: (allow-none) (default 0) (out): a pointer to a #gsize,
1367 * to store the length
1369 * Returns the string value of a #GVariant instance with a string
1370 * type. This includes the types %G_VARIANT_TYPE_STRING,
1371 * %G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE.
1373 * The string will always be utf8 encoded.
1375 * If @length is non-%NULL then the length of the string (in bytes) is
1376 * returned there. For trusted values, this information is already
1377 * known. For untrusted values, a strlen() will be performed.
1379 * It is an error to call this function with a @value of any type
1380 * other than those three.
1382 * The return value remains valid as long as @value exists.
1384 * Returns: (transfer none): the constant string, utf8 encoded
1389 g_variant_get_string (GVariant
*value
,
1395 g_return_val_if_fail (value
!= NULL
, NULL
);
1396 g_return_val_if_fail (
1397 g_variant_is_of_type (value
, G_VARIANT_TYPE_STRING
) ||
1398 g_variant_is_of_type (value
, G_VARIANT_TYPE_OBJECT_PATH
) ||
1399 g_variant_is_of_type (value
, G_VARIANT_TYPE_SIGNATURE
), NULL
);
1401 data
= g_variant_get_data (value
);
1402 size
= g_variant_get_size (value
);
1404 if (!g_variant_is_trusted (value
))
1406 switch (g_variant_classify (value
))
1408 case G_VARIANT_CLASS_STRING
:
1409 if (g_variant_serialiser_is_string (data
, size
))
1416 case G_VARIANT_CLASS_OBJECT_PATH
:
1417 if (g_variant_serialiser_is_object_path (data
, size
))
1424 case G_VARIANT_CLASS_SIGNATURE
:
1425 if (g_variant_serialiser_is_signature (data
, size
))
1433 g_assert_not_reached ();
1444 * g_variant_dup_string:
1445 * @value: a string #GVariant instance
1446 * @length: (out): a pointer to a #gsize, to store the length
1448 * Similar to g_variant_get_string() except that instead of returning
1449 * a constant string, the string is duplicated.
1451 * The string will always be utf8 encoded.
1453 * The return value must be freed using g_free().
1455 * Returns: (transfer full): a newly allocated string, utf8 encoded
1460 g_variant_dup_string (GVariant
*value
,
1463 return g_strdup (g_variant_get_string (value
, length
));
1467 * g_variant_new_strv:
1468 * @strv: (array length=length) (element-type utf8): an array of strings
1469 * @length: the length of @strv, or -1
1471 * Constructs an array of strings #GVariant from the given array of
1474 * If @length is -1 then @strv is %NULL-terminated.
1476 * Returns: (transfer none): a new floating #GVariant instance
1481 g_variant_new_strv (const gchar
* const *strv
,
1487 g_return_val_if_fail (length
== 0 || strv
!= NULL
, NULL
);
1490 length
= g_strv_length ((gchar
**) strv
);
1492 strings
= g_new (GVariant
*, length
);
1493 for (i
= 0; i
< length
; i
++)
1494 strings
[i
] = g_variant_ref_sink (g_variant_new_string (strv
[i
]));
1496 return g_variant_new_from_children (G_VARIANT_TYPE_STRING_ARRAY
,
1497 strings
, length
, TRUE
);
1501 * g_variant_get_strv:
1502 * @value: an array of strings #GVariant
1503 * @length: (out) (allow-none): the length of the result, or %NULL
1505 * Gets the contents of an array of strings #GVariant. This call
1506 * makes a shallow copy; the return result should be released with
1507 * g_free(), but the individual strings must not be modified.
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
1513 * For an empty array, @length will be set to 0 and a pointer to a
1514 * %NULL pointer will be returned.
1516 * Returns: (array length=length zero-terminated=1) (transfer container): an array of constant strings
1521 g_variant_get_strv (GVariant
*value
,
1528 TYPE_CHECK (value
, G_VARIANT_TYPE_STRING_ARRAY
, NULL
);
1530 g_variant_get_data (value
);
1531 n
= g_variant_n_children (value
);
1532 strv
= g_new (const gchar
*, n
+ 1);
1534 for (i
= 0; i
< n
; i
++)
1538 string
= g_variant_get_child_value (value
, i
);
1539 strv
[i
] = g_variant_get_string (string
, NULL
);
1540 g_variant_unref (string
);
1551 * g_variant_dup_strv:
1552 * @value: an array of strings #GVariant
1553 * @length: (out) (allow-none): the length of the result, or %NULL
1555 * Gets the contents of an array of strings #GVariant. This call
1556 * makes a deep copy; the return result should be released with
1559 * If @length is non-%NULL then the number of elements in the result
1560 * is stored there. In any case, the resulting array will be
1563 * For an empty array, @length will be set to 0 and a pointer to a
1564 * %NULL pointer will be returned.
1566 * Returns: (array length=length zero-terminated=1) (transfer full): an array of strings
1571 g_variant_dup_strv (GVariant
*value
,
1578 TYPE_CHECK (value
, G_VARIANT_TYPE_STRING_ARRAY
, NULL
);
1580 n
= g_variant_n_children (value
);
1581 strv
= g_new (gchar
*, n
+ 1);
1583 for (i
= 0; i
< n
; i
++)
1587 string
= g_variant_get_child_value (value
, i
);
1588 strv
[i
] = g_variant_dup_string (string
, NULL
);
1589 g_variant_unref (string
);
1600 * g_variant_new_objv:
1601 * @strv: (array length=length) (element-type utf8): an array of strings
1602 * @length: the length of @strv, or -1
1604 * Constructs an array of object paths #GVariant from the given array of
1607 * Each string must be a valid #GVariant object path; see
1608 * g_variant_is_object_path().
1610 * If @length is -1 then @strv is %NULL-terminated.
1612 * Returns: (transfer none): a new floating #GVariant instance
1617 g_variant_new_objv (const gchar
* const *strv
,
1623 g_return_val_if_fail (length
== 0 || strv
!= NULL
, NULL
);
1626 length
= g_strv_length ((gchar
**) strv
);
1628 strings
= g_new (GVariant
*, length
);
1629 for (i
= 0; i
< length
; i
++)
1630 strings
[i
] = g_variant_ref_sink (g_variant_new_object_path (strv
[i
]));
1632 return g_variant_new_from_children (G_VARIANT_TYPE_OBJECT_PATH_ARRAY
,
1633 strings
, length
, TRUE
);
1637 * g_variant_get_objv:
1638 * @value: an array of object paths #GVariant
1639 * @length: (out) (allow-none): the length of the result, or %NULL
1641 * Gets the contents of an array of object paths #GVariant. This call
1642 * makes a shallow copy; the return result should be released with
1643 * g_free(), but the individual strings must not be modified.
1645 * If @length is non-%NULL then the number of elements in the result
1646 * is stored there. In any case, the resulting array will be
1649 * For an empty array, @length will be set to 0 and a pointer to a
1650 * %NULL pointer will be returned.
1652 * Returns: (array length=length zero-terminated=1) (transfer container): an array of constant strings
1657 g_variant_get_objv (GVariant
*value
,
1664 TYPE_CHECK (value
, G_VARIANT_TYPE_OBJECT_PATH_ARRAY
, NULL
);
1666 g_variant_get_data (value
);
1667 n
= g_variant_n_children (value
);
1668 strv
= g_new (const gchar
*, n
+ 1);
1670 for (i
= 0; i
< n
; i
++)
1674 string
= g_variant_get_child_value (value
, i
);
1675 strv
[i
] = g_variant_get_string (string
, NULL
);
1676 g_variant_unref (string
);
1687 * g_variant_dup_objv:
1688 * @value: an array of object paths #GVariant
1689 * @length: (out) (allow-none): the length of the result, or %NULL
1691 * Gets the contents of an array of object paths #GVariant. This call
1692 * makes a deep copy; the return result should be released with
1695 * If @length is non-%NULL then the number of elements in the result
1696 * is stored there. In any case, the resulting array will be
1699 * For an empty array, @length will be set to 0 and a pointer to a
1700 * %NULL pointer will be returned.
1702 * Returns: (array length=length zero-terminated=1) (transfer full): an array of strings
1707 g_variant_dup_objv (GVariant
*value
,
1714 TYPE_CHECK (value
, G_VARIANT_TYPE_OBJECT_PATH_ARRAY
, NULL
);
1716 n
= g_variant_n_children (value
);
1717 strv
= g_new (gchar
*, n
+ 1);
1719 for (i
= 0; i
< n
; i
++)
1723 string
= g_variant_get_child_value (value
, i
);
1724 strv
[i
] = g_variant_dup_string (string
, NULL
);
1725 g_variant_unref (string
);
1737 * g_variant_new_bytestring:
1738 * @string: (array zero-terminated=1) (element-type guint8): a normal
1739 * nul-terminated string in no particular encoding
1741 * Creates an array-of-bytes #GVariant with the contents of @string.
1742 * This function is just like g_variant_new_string() except that the
1743 * string need not be valid utf8.
1745 * The nul terminator character at the end of the string is stored in
1748 * Returns: (transfer none): a floating reference to a new bytestring #GVariant instance
1753 g_variant_new_bytestring (const gchar
*string
)
1755 g_return_val_if_fail (string
!= NULL
, NULL
);
1757 return g_variant_new_from_trusted (G_VARIANT_TYPE_BYTESTRING
,
1758 string
, strlen (string
) + 1);
1762 * g_variant_get_bytestring:
1763 * @value: an array-of-bytes #GVariant instance
1765 * Returns the string value of a #GVariant instance with an
1766 * array-of-bytes type. The string has no particular encoding.
1768 * If the array does not end with a nul terminator character, the empty
1769 * string is returned. For this reason, you can always trust that a
1770 * non-%NULL nul-terminated string will be returned by this function.
1772 * If the array contains a nul terminator character somewhere other than
1773 * the last byte then the returned string is the string, up to the first
1774 * such nul character.
1776 * It is an error to call this function with a @value that is not an
1779 * The return value remains valid as long as @value exists.
1781 * Returns: (transfer none) (array zero-terminated=1) (element-type guint8):
1782 * the constant string
1787 g_variant_get_bytestring (GVariant
*value
)
1789 const gchar
*string
;
1792 TYPE_CHECK (value
, G_VARIANT_TYPE_BYTESTRING
, NULL
);
1794 /* Won't be NULL since this is an array type */
1795 string
= g_variant_get_data (value
);
1796 size
= g_variant_get_size (value
);
1798 if (size
&& string
[size
- 1] == '\0')
1805 * g_variant_dup_bytestring:
1806 * @value: an array-of-bytes #GVariant instance
1807 * @length: (out) (allow-none) (default NULL): a pointer to a #gsize, to store
1808 * the length (not including the nul terminator)
1810 * Similar to g_variant_get_bytestring() except that instead of
1811 * returning a constant string, the string is duplicated.
1813 * The return value must be freed using g_free().
1815 * Returns: (transfer full) (array zero-terminated=1 length=length) (element-type guint8):
1816 * a newly allocated string
1821 g_variant_dup_bytestring (GVariant
*value
,
1824 const gchar
*original
= g_variant_get_bytestring (value
);
1827 /* don't crash in case get_bytestring() had an assert failure */
1828 if (original
== NULL
)
1831 size
= strlen (original
);
1836 return g_memdup (original
, size
+ 1);
1840 * g_variant_new_bytestring_array:
1841 * @strv: (array length=length): an array of strings
1842 * @length: the length of @strv, or -1
1844 * Constructs an array of bytestring #GVariant from the given array of
1847 * If @length is -1 then @strv is %NULL-terminated.
1849 * Returns: (transfer none): a new floating #GVariant instance
1854 g_variant_new_bytestring_array (const gchar
* const *strv
,
1860 g_return_val_if_fail (length
== 0 || strv
!= NULL
, NULL
);
1863 length
= g_strv_length ((gchar
**) strv
);
1865 strings
= g_new (GVariant
*, length
);
1866 for (i
= 0; i
< length
; i
++)
1867 strings
[i
] = g_variant_ref_sink (g_variant_new_bytestring (strv
[i
]));
1869 return g_variant_new_from_children (G_VARIANT_TYPE_BYTESTRING_ARRAY
,
1870 strings
, length
, TRUE
);
1874 * g_variant_get_bytestring_array:
1875 * @value: an array of array of bytes #GVariant ('aay')
1876 * @length: (out) (allow-none): the length of the result, or %NULL
1878 * Gets the contents of an array of array of bytes #GVariant. This call
1879 * makes a shallow copy; the return result should be released with
1880 * g_free(), but the individual strings must not be modified.
1882 * If @length is non-%NULL then the number of elements in the result is
1883 * stored there. In any case, the resulting array will be
1886 * For an empty array, @length will be set to 0 and a pointer to a
1887 * %NULL pointer will be returned.
1889 * Returns: (array length=length) (transfer container): an array of constant strings
1894 g_variant_get_bytestring_array (GVariant
*value
,
1901 TYPE_CHECK (value
, G_VARIANT_TYPE_BYTESTRING_ARRAY
, NULL
);
1903 g_variant_get_data (value
);
1904 n
= g_variant_n_children (value
);
1905 strv
= g_new (const gchar
*, n
+ 1);
1907 for (i
= 0; i
< n
; i
++)
1911 string
= g_variant_get_child_value (value
, i
);
1912 strv
[i
] = g_variant_get_bytestring (string
);
1913 g_variant_unref (string
);
1924 * g_variant_dup_bytestring_array:
1925 * @value: an array of array of bytes #GVariant ('aay')
1926 * @length: (out) (allow-none): the length of the result, or %NULL
1928 * Gets the contents of an array of array of bytes #GVariant. This call
1929 * makes a deep copy; the return result should be released with
1932 * If @length is non-%NULL then the number of elements in the result is
1933 * stored there. In any case, the resulting array will be
1936 * For an empty array, @length will be set to 0 and a pointer to a
1937 * %NULL pointer will be returned.
1939 * Returns: (array length=length) (transfer full): an array of strings
1944 g_variant_dup_bytestring_array (GVariant
*value
,
1951 TYPE_CHECK (value
, G_VARIANT_TYPE_BYTESTRING_ARRAY
, NULL
);
1953 g_variant_get_data (value
);
1954 n
= g_variant_n_children (value
);
1955 strv
= g_new (gchar
*, n
+ 1);
1957 for (i
= 0; i
< n
; i
++)
1961 string
= g_variant_get_child_value (value
, i
);
1962 strv
[i
] = g_variant_dup_bytestring (string
, NULL
);
1963 g_variant_unref (string
);
1973 /* Type checking and querying {{{1 */
1975 * g_variant_get_type:
1976 * @value: a #GVariant
1978 * Determines the type of @value.
1980 * The return value is valid for the lifetime of @value and must not
1983 * Returns: a #GVariantType
1987 const GVariantType
*
1988 g_variant_get_type (GVariant
*value
)
1990 GVariantTypeInfo
*type_info
;
1992 g_return_val_if_fail (value
!= NULL
, NULL
);
1994 type_info
= g_variant_get_type_info (value
);
1996 return (GVariantType
*) g_variant_type_info_get_type_string (type_info
);
2000 * g_variant_get_type_string:
2001 * @value: a #GVariant
2003 * Returns the type string of @value. Unlike the result of calling
2004 * g_variant_type_peek_string(), this string is nul-terminated. This
2005 * string belongs to #GVariant and must not be freed.
2007 * Returns: the type string for the type of @value
2012 g_variant_get_type_string (GVariant
*value
)
2014 GVariantTypeInfo
*type_info
;
2016 g_return_val_if_fail (value
!= NULL
, NULL
);
2018 type_info
= g_variant_get_type_info (value
);
2020 return g_variant_type_info_get_type_string (type_info
);
2024 * g_variant_is_of_type:
2025 * @value: a #GVariant instance
2026 * @type: a #GVariantType
2028 * Checks if a value has a type matching the provided type.
2030 * Returns: %TRUE if the type of @value matches @type
2035 g_variant_is_of_type (GVariant
*value
,
2036 const GVariantType
*type
)
2038 return g_variant_type_is_subtype_of (g_variant_get_type (value
), type
);
2042 * g_variant_is_container:
2043 * @value: a #GVariant instance
2045 * Checks if @value is a container.
2047 * Returns: %TRUE if @value is a container
2052 g_variant_is_container (GVariant
*value
)
2054 return g_variant_type_is_container (g_variant_get_type (value
));
2059 * g_variant_classify:
2060 * @value: a #GVariant
2062 * Classifies @value according to its top-level type.
2064 * Returns: the #GVariantClass of @value
2070 * @G_VARIANT_CLASS_BOOLEAN: The #GVariant is a boolean.
2071 * @G_VARIANT_CLASS_BYTE: The #GVariant is a byte.
2072 * @G_VARIANT_CLASS_INT16: The #GVariant is a signed 16 bit integer.
2073 * @G_VARIANT_CLASS_UINT16: The #GVariant is an unsigned 16 bit integer.
2074 * @G_VARIANT_CLASS_INT32: The #GVariant is a signed 32 bit integer.
2075 * @G_VARIANT_CLASS_UINT32: The #GVariant is an unsigned 32 bit integer.
2076 * @G_VARIANT_CLASS_INT64: The #GVariant is a signed 64 bit integer.
2077 * @G_VARIANT_CLASS_UINT64: The #GVariant is an unsigned 64 bit integer.
2078 * @G_VARIANT_CLASS_HANDLE: The #GVariant is a file handle index.
2079 * @G_VARIANT_CLASS_DOUBLE: The #GVariant is a double precision floating
2081 * @G_VARIANT_CLASS_STRING: The #GVariant is a normal string.
2082 * @G_VARIANT_CLASS_OBJECT_PATH: The #GVariant is a D-Bus object path
2084 * @G_VARIANT_CLASS_SIGNATURE: The #GVariant is a D-Bus signature string.
2085 * @G_VARIANT_CLASS_VARIANT: The #GVariant is a variant.
2086 * @G_VARIANT_CLASS_MAYBE: The #GVariant is a maybe-typed value.
2087 * @G_VARIANT_CLASS_ARRAY: The #GVariant is an array.
2088 * @G_VARIANT_CLASS_TUPLE: The #GVariant is a tuple.
2089 * @G_VARIANT_CLASS_DICT_ENTRY: The #GVariant is a dictionary entry.
2091 * The range of possible top-level types of #GVariant instances.
2096 g_variant_classify (GVariant
*value
)
2098 g_return_val_if_fail (value
!= NULL
, 0);
2100 return *g_variant_get_type_string (value
);
2103 /* Pretty printer {{{1 */
2104 /* This function is not introspectable because if @string is NULL,
2105 @returns is (transfer full), otherwise it is (transfer none), which
2106 is not supported by GObjectIntrospection */
2108 * g_variant_print_string: (skip)
2109 * @value: a #GVariant
2110 * @string: (allow-none) (default NULL): a #GString, or %NULL
2111 * @type_annotate: %TRUE if type information should be included in
2114 * Behaves as g_variant_print(), but operates on a #GString.
2116 * If @string is non-%NULL then it is appended to and returned. Else,
2117 * a new empty #GString is allocated and it is returned.
2119 * Returns: a #GString containing the string
2124 g_variant_print_string (GVariant
*value
,
2126 gboolean type_annotate
)
2128 if G_UNLIKELY (string
== NULL
)
2129 string
= g_string_new (NULL
);
2131 switch (g_variant_classify (value
))
2133 case G_VARIANT_CLASS_MAYBE
:
2135 g_string_append_printf (string
, "@%s ",
2136 g_variant_get_type_string (value
));
2138 if (g_variant_n_children (value
))
2140 gchar
*printed_child
;
2145 * Consider the case of the type "mmi". In this case we could
2146 * write "just just 4", but "4" alone is totally unambiguous,
2147 * so we try to drop "just" where possible.
2149 * We have to be careful not to always drop "just", though,
2150 * since "nothing" needs to be distinguishable from "just
2151 * nothing". The case where we need to ensure we keep the
2152 * "just" is actually exactly the case where we have a nested
2155 * Instead of searching for that nested Nothing, we just print
2156 * the contained value into a separate string and see if we
2157 * end up with "nothing" at the end of it. If so, we need to
2158 * add "just" at our level.
2160 element
= g_variant_get_child_value (value
, 0);
2161 printed_child
= g_variant_print (element
, FALSE
);
2162 g_variant_unref (element
);
2164 if (g_str_has_suffix (printed_child
, "nothing"))
2165 g_string_append (string
, "just ");
2166 g_string_append (string
, printed_child
);
2167 g_free (printed_child
);
2170 g_string_append (string
, "nothing");
2174 case G_VARIANT_CLASS_ARRAY
:
2175 /* it's an array so the first character of the type string is 'a'
2177 * if the first two characters are 'ay' then it's a bytestring.
2178 * under certain conditions we print those as strings.
2180 if (g_variant_get_type_string (value
)[1] == 'y')
2186 /* first determine if it is a byte string.
2187 * that's when there's a single nul character: at the end.
2189 str
= g_variant_get_data (value
);
2190 size
= g_variant_get_size (value
);
2192 for (i
= 0; i
< size
; i
++)
2196 /* first nul byte is the last byte -> it's a byte string. */
2199 gchar
*escaped
= g_strescape (str
, NULL
);
2201 /* use double quotes only if a ' is in the string */
2202 if (strchr (str
, '\''))
2203 g_string_append_printf (string
, "b\"%s\"", escaped
);
2205 g_string_append_printf (string
, "b'%s'", escaped
);
2212 /* fall through and handle normally... */;
2216 * if the first two characters are 'a{' then it's an array of
2217 * dictionary entries (ie: a dictionary) so we print that
2220 if (g_variant_get_type_string (value
)[1] == '{')
2223 const gchar
*comma
= "";
2226 if ((n
= g_variant_n_children (value
)) == 0)
2229 g_string_append_printf (string
, "@%s ",
2230 g_variant_get_type_string (value
));
2231 g_string_append (string
, "{}");
2235 g_string_append_c (string
, '{');
2236 for (i
= 0; i
< n
; i
++)
2238 GVariant
*entry
, *key
, *val
;
2240 g_string_append (string
, comma
);
2243 entry
= g_variant_get_child_value (value
, i
);
2244 key
= g_variant_get_child_value (entry
, 0);
2245 val
= g_variant_get_child_value (entry
, 1);
2246 g_variant_unref (entry
);
2248 g_variant_print_string (key
, string
, type_annotate
);
2249 g_variant_unref (key
);
2250 g_string_append (string
, ": ");
2251 g_variant_print_string (val
, string
, type_annotate
);
2252 g_variant_unref (val
);
2253 type_annotate
= FALSE
;
2255 g_string_append_c (string
, '}');
2258 /* normal (non-dictionary) array */
2260 const gchar
*comma
= "";
2263 if ((n
= g_variant_n_children (value
)) == 0)
2266 g_string_append_printf (string
, "@%s ",
2267 g_variant_get_type_string (value
));
2268 g_string_append (string
, "[]");
2272 g_string_append_c (string
, '[');
2273 for (i
= 0; i
< n
; i
++)
2277 g_string_append (string
, comma
);
2280 element
= g_variant_get_child_value (value
, i
);
2282 g_variant_print_string (element
, string
, type_annotate
);
2283 g_variant_unref (element
);
2284 type_annotate
= FALSE
;
2286 g_string_append_c (string
, ']');
2291 case G_VARIANT_CLASS_TUPLE
:
2295 n
= g_variant_n_children (value
);
2297 g_string_append_c (string
, '(');
2298 for (i
= 0; i
< n
; i
++)
2302 element
= g_variant_get_child_value (value
, i
);
2303 g_variant_print_string (element
, string
, type_annotate
);
2304 g_string_append (string
, ", ");
2305 g_variant_unref (element
);
2308 /* for >1 item: remove final ", "
2309 * for 1 item: remove final " ", but leave the ","
2310 * for 0 items: there is only "(", so remove nothing
2312 g_string_truncate (string
, string
->len
- (n
> 0) - (n
> 1));
2313 g_string_append_c (string
, ')');
2317 case G_VARIANT_CLASS_DICT_ENTRY
:
2321 g_string_append_c (string
, '{');
2323 element
= g_variant_get_child_value (value
, 0);
2324 g_variant_print_string (element
, string
, type_annotate
);
2325 g_variant_unref (element
);
2327 g_string_append (string
, ", ");
2329 element
= g_variant_get_child_value (value
, 1);
2330 g_variant_print_string (element
, string
, type_annotate
);
2331 g_variant_unref (element
);
2333 g_string_append_c (string
, '}');
2337 case G_VARIANT_CLASS_VARIANT
:
2339 GVariant
*child
= g_variant_get_variant (value
);
2341 /* Always annotate types in nested variants, because they are
2342 * (by nature) of variable type.
2344 g_string_append_c (string
, '<');
2345 g_variant_print_string (child
, string
, TRUE
);
2346 g_string_append_c (string
, '>');
2348 g_variant_unref (child
);
2352 case G_VARIANT_CLASS_BOOLEAN
:
2353 if (g_variant_get_boolean (value
))
2354 g_string_append (string
, "true");
2356 g_string_append (string
, "false");
2359 case G_VARIANT_CLASS_STRING
:
2361 const gchar
*str
= g_variant_get_string (value
, NULL
);
2362 gunichar quote
= strchr (str
, '\'') ? '"' : '\'';
2364 g_string_append_c (string
, quote
);
2368 gunichar c
= g_utf8_get_char (str
);
2370 if (c
== quote
|| c
== '\\')
2371 g_string_append_c (string
, '\\');
2373 if (g_unichar_isprint (c
))
2374 g_string_append_unichar (string
, c
);
2378 g_string_append_c (string
, '\\');
2383 g_string_append_c (string
, 'a');
2387 g_string_append_c (string
, 'b');
2391 g_string_append_c (string
, 'f');
2395 g_string_append_c (string
, 'n');
2399 g_string_append_c (string
, 'r');
2403 g_string_append_c (string
, 't');
2407 g_string_append_c (string
, 'v');
2411 g_string_append_printf (string
, "u%04x", c
);
2415 g_string_append_printf (string
, "U%08x", c
);
2418 str
= g_utf8_next_char (str
);
2421 g_string_append_c (string
, quote
);
2425 case G_VARIANT_CLASS_BYTE
:
2427 g_string_append (string
, "byte ");
2428 g_string_append_printf (string
, "0x%02x",
2429 g_variant_get_byte (value
));
2432 case G_VARIANT_CLASS_INT16
:
2434 g_string_append (string
, "int16 ");
2435 g_string_append_printf (string
, "%"G_GINT16_FORMAT
,
2436 g_variant_get_int16 (value
));
2439 case G_VARIANT_CLASS_UINT16
:
2441 g_string_append (string
, "uint16 ");
2442 g_string_append_printf (string
, "%"G_GUINT16_FORMAT
,
2443 g_variant_get_uint16 (value
));
2446 case G_VARIANT_CLASS_INT32
:
2447 /* Never annotate this type because it is the default for numbers
2448 * (and this is a *pretty* printer)
2450 g_string_append_printf (string
, "%"G_GINT32_FORMAT
,
2451 g_variant_get_int32 (value
));
2454 case G_VARIANT_CLASS_HANDLE
:
2456 g_string_append (string
, "handle ");
2457 g_string_append_printf (string
, "%"G_GINT32_FORMAT
,
2458 g_variant_get_handle (value
));
2461 case G_VARIANT_CLASS_UINT32
:
2463 g_string_append (string
, "uint32 ");
2464 g_string_append_printf (string
, "%"G_GUINT32_FORMAT
,
2465 g_variant_get_uint32 (value
));
2468 case G_VARIANT_CLASS_INT64
:
2470 g_string_append (string
, "int64 ");
2471 g_string_append_printf (string
, "%"G_GINT64_FORMAT
,
2472 g_variant_get_int64 (value
));
2475 case G_VARIANT_CLASS_UINT64
:
2477 g_string_append (string
, "uint64 ");
2478 g_string_append_printf (string
, "%"G_GUINT64_FORMAT
,
2479 g_variant_get_uint64 (value
));
2482 case G_VARIANT_CLASS_DOUBLE
:
2487 g_ascii_dtostr (buffer
, sizeof buffer
, g_variant_get_double (value
));
2489 for (i
= 0; buffer
[i
]; i
++)
2490 if (buffer
[i
] == '.' || buffer
[i
] == 'e' ||
2491 buffer
[i
] == 'n' || buffer
[i
] == 'N')
2494 /* if there is no '.' or 'e' in the float then add one */
2495 if (buffer
[i
] == '\0')
2502 g_string_append (string
, buffer
);
2506 case G_VARIANT_CLASS_OBJECT_PATH
:
2508 g_string_append (string
, "objectpath ");
2509 g_string_append_printf (string
, "\'%s\'",
2510 g_variant_get_string (value
, NULL
));
2513 case G_VARIANT_CLASS_SIGNATURE
:
2515 g_string_append (string
, "signature ");
2516 g_string_append_printf (string
, "\'%s\'",
2517 g_variant_get_string (value
, NULL
));
2521 g_assert_not_reached ();
2529 * @value: a #GVariant
2530 * @type_annotate: %TRUE if type information should be included in
2533 * Pretty-prints @value in the format understood by g_variant_parse().
2535 * The format is described <link linkend='gvariant-text'>here</link>.
2537 * If @type_annotate is %TRUE, then type information is included in
2540 * Returns: (transfer full): a newly-allocated string holding the result.
2545 g_variant_print (GVariant
*value
,
2546 gboolean type_annotate
)
2548 return g_string_free (g_variant_print_string (value
, NULL
, type_annotate
),
2552 /* Hash, Equal, Compare {{{1 */
2555 * @value: (type GVariant): a basic #GVariant value as a #gconstpointer
2557 * Generates a hash value for a #GVariant instance.
2559 * The output of this function is guaranteed to be the same for a given
2560 * value only per-process. It may change between different processor
2561 * architectures or even different versions of GLib. Do not use this
2562 * function as a basis for building protocols or file formats.
2564 * The type of @value is #gconstpointer only to allow use of this
2565 * function with #GHashTable. @value must be a #GVariant.
2567 * Returns: a hash value corresponding to @value
2572 g_variant_hash (gconstpointer value_
)
2574 GVariant
*value
= (GVariant
*) value_
;
2576 switch (g_variant_classify (value
))
2578 case G_VARIANT_CLASS_STRING
:
2579 case G_VARIANT_CLASS_OBJECT_PATH
:
2580 case G_VARIANT_CLASS_SIGNATURE
:
2581 return g_str_hash (g_variant_get_string (value
, NULL
));
2583 case G_VARIANT_CLASS_BOOLEAN
:
2584 /* this is a very odd thing to hash... */
2585 return g_variant_get_boolean (value
);
2587 case G_VARIANT_CLASS_BYTE
:
2588 return g_variant_get_byte (value
);
2590 case G_VARIANT_CLASS_INT16
:
2591 case G_VARIANT_CLASS_UINT16
:
2595 ptr
= g_variant_get_data (value
);
2603 case G_VARIANT_CLASS_INT32
:
2604 case G_VARIANT_CLASS_UINT32
:
2605 case G_VARIANT_CLASS_HANDLE
:
2609 ptr
= g_variant_get_data (value
);
2617 case G_VARIANT_CLASS_INT64
:
2618 case G_VARIANT_CLASS_UINT64
:
2619 case G_VARIANT_CLASS_DOUBLE
:
2620 /* need a separate case for these guys because otherwise
2621 * performance could be quite bad on big endian systems
2626 ptr
= g_variant_get_data (value
);
2629 return ptr
[0] + ptr
[1];
2635 g_return_val_if_fail (!g_variant_is_container (value
), 0);
2636 g_assert_not_reached ();
2642 * @one: (type GVariant): a #GVariant instance
2643 * @two: (type GVariant): a #GVariant instance
2645 * Checks if @one and @two have the same type and value.
2647 * The types of @one and @two are #gconstpointer only to allow use of
2648 * this function with #GHashTable. They must each be a #GVariant.
2650 * Returns: %TRUE if @one and @two are equal
2655 g_variant_equal (gconstpointer one
,
2660 g_return_val_if_fail (one
!= NULL
&& two
!= NULL
, FALSE
);
2662 if (g_variant_get_type_info ((GVariant
*) one
) !=
2663 g_variant_get_type_info ((GVariant
*) two
))
2666 /* if both values are trusted to be in their canonical serialised form
2667 * then a simple memcmp() of their serialised data will answer the
2670 * if not, then this might generate a false negative (since it is
2671 * possible for two different byte sequences to represent the same
2672 * value). for now we solve this by pretty-printing both values and
2673 * comparing the result.
2675 if (g_variant_is_trusted ((GVariant
*) one
) &&
2676 g_variant_is_trusted ((GVariant
*) two
))
2678 gconstpointer data_one
, data_two
;
2679 gsize size_one
, size_two
;
2681 size_one
= g_variant_get_size ((GVariant
*) one
);
2682 size_two
= g_variant_get_size ((GVariant
*) two
);
2684 if (size_one
!= size_two
)
2687 data_one
= g_variant_get_data ((GVariant
*) one
);
2688 data_two
= g_variant_get_data ((GVariant
*) two
);
2690 equal
= memcmp (data_one
, data_two
, size_one
) == 0;
2694 gchar
*strone
, *strtwo
;
2696 strone
= g_variant_print ((GVariant
*) one
, FALSE
);
2697 strtwo
= g_variant_print ((GVariant
*) two
, FALSE
);
2698 equal
= strcmp (strone
, strtwo
) == 0;
2707 * g_variant_compare:
2708 * @one: (type GVariant): a basic-typed #GVariant instance
2709 * @two: (type GVariant): a #GVariant instance of the same type
2711 * Compares @one and @two.
2713 * The types of @one and @two are #gconstpointer only to allow use of
2714 * this function with #GTree, #GPtrArray, etc. They must each be a
2717 * Comparison is only defined for basic types (ie: booleans, numbers,
2718 * strings). For booleans, %FALSE is less than %TRUE. Numbers are
2719 * ordered in the usual way. Strings are in ASCII lexographical order.
2721 * It is a programmer error to attempt to compare container values or
2722 * two values that have types that are not exactly equal. For example,
2723 * you cannot compare a 32-bit signed integer with a 32-bit unsigned
2724 * integer. Also note that this function is not particularly
2725 * well-behaved when it comes to comparison of doubles; in particular,
2726 * the handling of incomparable values (ie: NaN) is undefined.
2728 * If you only require an equality comparison, g_variant_equal() is more
2731 * Returns: negative value if a < b;
2733 * positive value if a > b.
2738 g_variant_compare (gconstpointer one
,
2741 GVariant
*a
= (GVariant
*) one
;
2742 GVariant
*b
= (GVariant
*) two
;
2744 g_return_val_if_fail (g_variant_classify (a
) == g_variant_classify (b
), 0);
2746 switch (g_variant_classify (a
))
2748 case G_VARIANT_CLASS_BYTE
:
2749 return ((gint
) g_variant_get_byte (a
)) -
2750 ((gint
) g_variant_get_byte (b
));
2752 case G_VARIANT_CLASS_INT16
:
2753 return ((gint
) g_variant_get_int16 (a
)) -
2754 ((gint
) g_variant_get_int16 (b
));
2756 case G_VARIANT_CLASS_UINT16
:
2757 return ((gint
) g_variant_get_uint16 (a
)) -
2758 ((gint
) g_variant_get_uint16 (b
));
2760 case G_VARIANT_CLASS_INT32
:
2762 gint32 a_val
= g_variant_get_int32 (a
);
2763 gint32 b_val
= g_variant_get_int32 (b
);
2765 return (a_val
== b_val
) ? 0 : (a_val
> b_val
) ? 1 : -1;
2768 case G_VARIANT_CLASS_UINT32
:
2770 guint32 a_val
= g_variant_get_uint32 (a
);
2771 guint32 b_val
= g_variant_get_uint32 (b
);
2773 return (a_val
== b_val
) ? 0 : (a_val
> b_val
) ? 1 : -1;
2776 case G_VARIANT_CLASS_INT64
:
2778 gint64 a_val
= g_variant_get_int64 (a
);
2779 gint64 b_val
= g_variant_get_int64 (b
);
2781 return (a_val
== b_val
) ? 0 : (a_val
> b_val
) ? 1 : -1;
2784 case G_VARIANT_CLASS_UINT64
:
2786 guint64 a_val
= g_variant_get_uint64 (a
);
2787 guint64 b_val
= g_variant_get_uint64 (b
);
2789 return (a_val
== b_val
) ? 0 : (a_val
> b_val
) ? 1 : -1;
2792 case G_VARIANT_CLASS_DOUBLE
:
2794 gdouble a_val
= g_variant_get_double (a
);
2795 gdouble b_val
= g_variant_get_double (b
);
2797 return (a_val
== b_val
) ? 0 : (a_val
> b_val
) ? 1 : -1;
2800 case G_VARIANT_CLASS_STRING
:
2801 case G_VARIANT_CLASS_OBJECT_PATH
:
2802 case G_VARIANT_CLASS_SIGNATURE
:
2803 return strcmp (g_variant_get_string (a
, NULL
),
2804 g_variant_get_string (b
, NULL
));
2807 g_return_val_if_fail (!g_variant_is_container (a
), 0);
2808 g_assert_not_reached ();
2812 /* GVariantIter {{{1 */
2814 * GVariantIter: (skip)
2816 * #GVariantIter is an opaque data structure and can only be accessed
2817 * using the following functions.
2824 const gchar
*loop_format
;
2830 G_STATIC_ASSERT (sizeof (struct stack_iter
) <= sizeof (GVariantIter
));
2834 struct stack_iter iter
;
2836 GVariant
*value_ref
;
2840 #define GVSI(i) ((struct stack_iter *) (i))
2841 #define GVHI(i) ((struct heap_iter *) (i))
2842 #define GVSI_MAGIC ((gsize) 3579507750u)
2843 #define GVHI_MAGIC ((gsize) 1450270775u)
2844 #define is_valid_iter(i) (i != NULL && \
2845 GVSI(i)->magic == GVSI_MAGIC)
2846 #define is_valid_heap_iter(i) (GVHI(i)->magic == GVHI_MAGIC && \
2850 * g_variant_iter_new:
2851 * @value: a container #GVariant
2853 * Creates a heap-allocated #GVariantIter for iterating over the items
2856 * Use g_variant_iter_free() to free the return value when you no longer
2859 * A reference is taken to @value and will be released only when
2860 * g_variant_iter_free() is called.
2862 * Returns: (transfer full): a new heap-allocated #GVariantIter
2867 g_variant_iter_new (GVariant
*value
)
2871 iter
= (GVariantIter
*) g_slice_new (struct heap_iter
);
2872 GVHI(iter
)->value_ref
= g_variant_ref (value
);
2873 GVHI(iter
)->magic
= GVHI_MAGIC
;
2875 g_variant_iter_init (iter
, value
);
2881 * g_variant_iter_init: (skip)
2882 * @iter: a pointer to a #GVariantIter
2883 * @value: a container #GVariant
2885 * Initialises (without allocating) a #GVariantIter. @iter may be
2886 * completely uninitialised prior to this call; its old value is
2889 * The iterator remains valid for as long as @value exists, and need not
2890 * be freed in any way.
2892 * Returns: the number of items in @value
2897 g_variant_iter_init (GVariantIter
*iter
,
2900 GVSI(iter
)->magic
= GVSI_MAGIC
;
2901 GVSI(iter
)->value
= value
;
2902 GVSI(iter
)->n
= g_variant_n_children (value
);
2904 GVSI(iter
)->loop_format
= NULL
;
2906 return GVSI(iter
)->n
;
2910 * g_variant_iter_copy:
2911 * @iter: a #GVariantIter
2913 * Creates a new heap-allocated #GVariantIter to iterate over the
2914 * container that was being iterated over by @iter. Iteration begins on
2915 * the new iterator from the current position of the old iterator but
2916 * the two copies are independent past that point.
2918 * Use g_variant_iter_free() to free the return value when you no longer
2921 * A reference is taken to the container that @iter is iterating over
2922 * and will be releated only when g_variant_iter_free() is called.
2924 * Returns: (transfer full): a new heap-allocated #GVariantIter
2929 g_variant_iter_copy (GVariantIter
*iter
)
2933 g_return_val_if_fail (is_valid_iter (iter
), 0);
2935 copy
= g_variant_iter_new (GVSI(iter
)->value
);
2936 GVSI(copy
)->i
= GVSI(iter
)->i
;
2942 * g_variant_iter_n_children:
2943 * @iter: a #GVariantIter
2945 * Queries the number of child items in the container that we are
2946 * iterating over. This is the total number of items -- not the number
2947 * of items remaining.
2949 * This function might be useful for preallocation of arrays.
2951 * Returns: the number of children in the container
2956 g_variant_iter_n_children (GVariantIter
*iter
)
2958 g_return_val_if_fail (is_valid_iter (iter
), 0);
2960 return GVSI(iter
)->n
;
2964 * g_variant_iter_free:
2965 * @iter: (transfer full): a heap-allocated #GVariantIter
2967 * Frees a heap-allocated #GVariantIter. Only call this function on
2968 * iterators that were returned by g_variant_iter_new() or
2969 * g_variant_iter_copy().
2974 g_variant_iter_free (GVariantIter
*iter
)
2976 g_return_if_fail (is_valid_heap_iter (iter
));
2978 g_variant_unref (GVHI(iter
)->value_ref
);
2979 GVHI(iter
)->magic
= 0;
2981 g_slice_free (struct heap_iter
, GVHI(iter
));
2985 * g_variant_iter_next_value:
2986 * @iter: a #GVariantIter
2988 * Gets the next item in the container. If no more items remain then
2989 * %NULL is returned.
2991 * Use g_variant_unref() to drop your reference on the return value when
2992 * you no longer need it.
2995 * <title>Iterating with g_variant_iter_next_value()</title>
2997 * /<!-- -->* recursively iterate a container *<!-- -->/
2999 * iterate_container_recursive (GVariant *container)
3001 * GVariantIter iter;
3004 * g_variant_iter_init (&iter, container);
3005 * while ((child = g_variant_iter_next_value (&iter)))
3007 * g_print ("type '%s'\n", g_variant_get_type_string (child));
3009 * if (g_variant_is_container (child))
3010 * iterate_container_recursive (child);
3012 * g_variant_unref (child);
3018 * Returns: (allow-none) (transfer full): a #GVariant, or %NULL
3023 g_variant_iter_next_value (GVariantIter
*iter
)
3025 g_return_val_if_fail (is_valid_iter (iter
), FALSE
);
3027 if G_UNLIKELY (GVSI(iter
)->i
>= GVSI(iter
)->n
)
3029 g_critical ("g_variant_iter_next_value: must not be called again "
3030 "after NULL has already been returned.");
3036 if (GVSI(iter
)->i
< GVSI(iter
)->n
)
3037 return g_variant_get_child_value (GVSI(iter
)->value
, GVSI(iter
)->i
);
3042 /* GVariantBuilder {{{1 */
3046 * A utility type for constructing container-type #GVariant instances.
3048 * This is an opaque structure and may only be accessed using the
3049 * following functions.
3051 * #GVariantBuilder is not threadsafe in any way. Do not attempt to
3052 * access it from more than one thread.
3055 struct stack_builder
3057 GVariantBuilder
*parent
;
3060 /* type constraint explicitly specified by 'type'.
3061 * for tuple types, this moves along as we add more items.
3063 const GVariantType
*expected_type
;
3065 /* type constraint implied by previous array item.
3067 const GVariantType
*prev_item_type
;
3069 /* constraints on the number of children. max = -1 for unlimited. */
3073 /* dynamically-growing pointer array */
3074 GVariant
**children
;
3075 gsize allocated_children
;
3078 /* set to '1' if all items in the container will have the same type
3079 * (ie: maybe, array, variant) '0' if not (ie: tuple, dict entry)
3081 guint uniform_item_types
: 1;
3083 /* set to '1' initially and changed to '0' if an untrusted value is
3091 G_STATIC_ASSERT (sizeof (struct stack_builder
) <= sizeof (GVariantBuilder
));
3095 GVariantBuilder builder
;
3101 #define GVSB(b) ((struct stack_builder *) (b))
3102 #define GVHB(b) ((struct heap_builder *) (b))
3103 #define GVSB_MAGIC ((gsize) 1033660112u)
3104 #define GVHB_MAGIC ((gsize) 3087242682u)
3105 #define is_valid_builder(b) (b != NULL && \
3106 GVSB(b)->magic == GVSB_MAGIC)
3107 #define is_valid_heap_builder(b) (GVHB(b)->magic == GVHB_MAGIC)
3110 * g_variant_builder_new:
3111 * @type: a container type
3113 * Allocates and initialises a new #GVariantBuilder.
3115 * You should call g_variant_builder_unref() on the return value when it
3116 * is no longer needed. The memory will not be automatically freed by
3119 * In most cases it is easier to place a #GVariantBuilder directly on
3120 * the stack of the calling function and initialise it with
3121 * g_variant_builder_init().
3123 * Returns: (transfer full): a #GVariantBuilder
3128 g_variant_builder_new (const GVariantType
*type
)
3130 GVariantBuilder
*builder
;
3132 builder
= (GVariantBuilder
*) g_slice_new (struct heap_builder
);
3133 g_variant_builder_init (builder
, type
);
3134 GVHB(builder
)->magic
= GVHB_MAGIC
;
3135 GVHB(builder
)->ref_count
= 1;
3141 * g_variant_builder_unref:
3142 * @builder: (transfer full): a #GVariantBuilder allocated by g_variant_builder_new()
3144 * Decreases the reference count on @builder.
3146 * In the event that there are no more references, releases all memory
3147 * associated with the #GVariantBuilder.
3149 * Don't call this on stack-allocated #GVariantBuilder instances or bad
3150 * things will happen.
3155 g_variant_builder_unref (GVariantBuilder
*builder
)
3157 g_return_if_fail (is_valid_heap_builder (builder
));
3159 if (--GVHB(builder
)->ref_count
)
3162 g_variant_builder_clear (builder
);
3163 GVHB(builder
)->magic
= 0;
3165 g_slice_free (struct heap_builder
, GVHB(builder
));
3169 * g_variant_builder_ref:
3170 * @builder: a #GVariantBuilder allocated by g_variant_builder_new()
3172 * Increases the reference count on @builder.
3174 * Don't call this on stack-allocated #GVariantBuilder instances or bad
3175 * things will happen.
3177 * Returns: (transfer full): a new reference to @builder
3182 g_variant_builder_ref (GVariantBuilder
*builder
)
3184 g_return_val_if_fail (is_valid_heap_builder (builder
), NULL
);
3186 GVHB(builder
)->ref_count
++;
3192 * g_variant_builder_clear: (skip)
3193 * @builder: a #GVariantBuilder
3195 * Releases all memory associated with a #GVariantBuilder without
3196 * freeing the #GVariantBuilder structure itself.
3198 * It typically only makes sense to do this on a stack-allocated
3199 * #GVariantBuilder if you want to abort building the value part-way
3200 * through. This function need not be called if you call
3201 * g_variant_builder_end() and it also doesn't need to be called on
3202 * builders allocated with g_variant_builder_new (see
3203 * g_variant_builder_unref() for that).
3205 * This function leaves the #GVariantBuilder structure set to all-zeros.
3206 * It is valid to call this function on either an initialised
3207 * #GVariantBuilder or one that is set to all-zeros but it is not valid
3208 * to call this function on uninitialised memory.
3213 g_variant_builder_clear (GVariantBuilder
*builder
)
3217 if (GVSB(builder
)->magic
== 0)
3218 /* all-zeros case */
3221 g_return_if_fail (is_valid_builder (builder
));
3223 g_variant_type_free (GVSB(builder
)->type
);
3225 for (i
= 0; i
< GVSB(builder
)->offset
; i
++)
3226 g_variant_unref (GVSB(builder
)->children
[i
]);
3228 g_free (GVSB(builder
)->children
);
3230 if (GVSB(builder
)->parent
)
3232 g_variant_builder_clear (GVSB(builder
)->parent
);
3233 g_slice_free (GVariantBuilder
, GVSB(builder
)->parent
);
3236 memset (builder
, 0, sizeof (GVariantBuilder
));
3240 * g_variant_builder_init: (skip)
3241 * @builder: a #GVariantBuilder
3242 * @type: a container type
3244 * Initialises a #GVariantBuilder structure.
3246 * @type must be non-%NULL. It specifies the type of container to
3247 * construct. It can be an indefinite type such as
3248 * %G_VARIANT_TYPE_ARRAY or a definite type such as "as" or "(ii)".
3249 * Maybe, array, tuple, dictionary entry and variant-typed values may be
3252 * After the builder is initialised, values are added using
3253 * g_variant_builder_add_value() or g_variant_builder_add().
3255 * After all the child values are added, g_variant_builder_end() frees
3256 * the memory associated with the builder and returns the #GVariant that
3259 * This function completely ignores the previous contents of @builder.
3260 * On one hand this means that it is valid to pass in completely
3261 * uninitialised memory. On the other hand, this means that if you are
3262 * initialising over top of an existing #GVariantBuilder you need to
3263 * first call g_variant_builder_clear() in order to avoid leaking
3266 * You must not call g_variant_builder_ref() or
3267 * g_variant_builder_unref() on a #GVariantBuilder that was initialised
3268 * with this function. If you ever pass a reference to a
3269 * #GVariantBuilder outside of the control of your own code then you
3270 * should assume that the person receiving that reference may try to use
3271 * reference counting; you should use g_variant_builder_new() instead of
3277 g_variant_builder_init (GVariantBuilder
*builder
,
3278 const GVariantType
*type
)
3280 g_return_if_fail (type
!= NULL
);
3281 g_return_if_fail (g_variant_type_is_container (type
));
3283 memset (builder
, 0, sizeof (GVariantBuilder
));
3285 GVSB(builder
)->type
= g_variant_type_copy (type
);
3286 GVSB(builder
)->magic
= GVSB_MAGIC
;
3287 GVSB(builder
)->trusted
= TRUE
;
3289 switch (*(const gchar
*) type
)
3291 case G_VARIANT_CLASS_VARIANT
:
3292 GVSB(builder
)->uniform_item_types
= TRUE
;
3293 GVSB(builder
)->allocated_children
= 1;
3294 GVSB(builder
)->expected_type
= NULL
;
3295 GVSB(builder
)->min_items
= 1;
3296 GVSB(builder
)->max_items
= 1;
3299 case G_VARIANT_CLASS_ARRAY
:
3300 GVSB(builder
)->uniform_item_types
= TRUE
;
3301 GVSB(builder
)->allocated_children
= 8;
3302 GVSB(builder
)->expected_type
=
3303 g_variant_type_element (GVSB(builder
)->type
);
3304 GVSB(builder
)->min_items
= 0;
3305 GVSB(builder
)->max_items
= -1;
3308 case G_VARIANT_CLASS_MAYBE
:
3309 GVSB(builder
)->uniform_item_types
= TRUE
;
3310 GVSB(builder
)->allocated_children
= 1;
3311 GVSB(builder
)->expected_type
=
3312 g_variant_type_element (GVSB(builder
)->type
);
3313 GVSB(builder
)->min_items
= 0;
3314 GVSB(builder
)->max_items
= 1;
3317 case G_VARIANT_CLASS_DICT_ENTRY
:
3318 GVSB(builder
)->uniform_item_types
= FALSE
;
3319 GVSB(builder
)->allocated_children
= 2;
3320 GVSB(builder
)->expected_type
=
3321 g_variant_type_key (GVSB(builder
)->type
);
3322 GVSB(builder
)->min_items
= 2;
3323 GVSB(builder
)->max_items
= 2;
3326 case 'r': /* G_VARIANT_TYPE_TUPLE was given */
3327 GVSB(builder
)->uniform_item_types
= FALSE
;
3328 GVSB(builder
)->allocated_children
= 8;
3329 GVSB(builder
)->expected_type
= NULL
;
3330 GVSB(builder
)->min_items
= 0;
3331 GVSB(builder
)->max_items
= -1;
3334 case G_VARIANT_CLASS_TUPLE
: /* a definite tuple type was given */
3335 GVSB(builder
)->allocated_children
= g_variant_type_n_items (type
);
3336 GVSB(builder
)->expected_type
=
3337 g_variant_type_first (GVSB(builder
)->type
);
3338 GVSB(builder
)->min_items
= GVSB(builder
)->allocated_children
;
3339 GVSB(builder
)->max_items
= GVSB(builder
)->allocated_children
;
3340 GVSB(builder
)->uniform_item_types
= FALSE
;
3344 g_assert_not_reached ();
3347 GVSB(builder
)->children
= g_new (GVariant
*,
3348 GVSB(builder
)->allocated_children
);
3352 g_variant_builder_make_room (struct stack_builder
*builder
)
3354 if (builder
->offset
== builder
->allocated_children
)
3356 builder
->allocated_children
*= 2;
3357 builder
->children
= g_renew (GVariant
*, builder
->children
,
3358 builder
->allocated_children
);
3363 * g_variant_builder_add_value:
3364 * @builder: a #GVariantBuilder
3365 * @value: a #GVariant
3367 * Adds @value to @builder.
3369 * It is an error to call this function in any way that would create an
3370 * inconsistent value to be constructed. Some examples of this are
3371 * putting different types of items into an array, putting the wrong
3372 * types or number of items in a tuple, putting more than one value into
3375 * If @value is a floating reference (see g_variant_ref_sink()),
3376 * the @builder instance takes ownership of @value.
3381 g_variant_builder_add_value (GVariantBuilder
*builder
,
3384 g_return_if_fail (is_valid_builder (builder
));
3385 g_return_if_fail (GVSB(builder
)->offset
< GVSB(builder
)->max_items
);
3386 g_return_if_fail (!GVSB(builder
)->expected_type
||
3387 g_variant_is_of_type (value
,
3388 GVSB(builder
)->expected_type
));
3389 g_return_if_fail (!GVSB(builder
)->prev_item_type
||
3390 g_variant_is_of_type (value
,
3391 GVSB(builder
)->prev_item_type
));
3393 GVSB(builder
)->trusted
&= g_variant_is_trusted (value
);
3395 if (!GVSB(builder
)->uniform_item_types
)
3397 /* advance our expected type pointers */
3398 if (GVSB(builder
)->expected_type
)
3399 GVSB(builder
)->expected_type
=
3400 g_variant_type_next (GVSB(builder
)->expected_type
);
3402 if (GVSB(builder
)->prev_item_type
)
3403 GVSB(builder
)->prev_item_type
=
3404 g_variant_type_next (GVSB(builder
)->prev_item_type
);
3407 GVSB(builder
)->prev_item_type
= g_variant_get_type (value
);
3409 g_variant_builder_make_room (GVSB(builder
));
3411 GVSB(builder
)->children
[GVSB(builder
)->offset
++] =
3412 g_variant_ref_sink (value
);
3416 * g_variant_builder_open:
3417 * @builder: a #GVariantBuilder
3418 * @type: a #GVariantType
3420 * Opens a subcontainer inside the given @builder. When done adding
3421 * items to the subcontainer, g_variant_builder_close() must be called.
3423 * It is an error to call this function in any way that would cause an
3424 * inconsistent value to be constructed (ie: adding too many values or
3425 * a value of an incorrect type).
3430 g_variant_builder_open (GVariantBuilder
*builder
,
3431 const GVariantType
*type
)
3433 GVariantBuilder
*parent
;
3435 g_return_if_fail (is_valid_builder (builder
));
3436 g_return_if_fail (GVSB(builder
)->offset
< GVSB(builder
)->max_items
);
3437 g_return_if_fail (!GVSB(builder
)->expected_type
||
3438 g_variant_type_is_subtype_of (type
,
3439 GVSB(builder
)->expected_type
));
3440 g_return_if_fail (!GVSB(builder
)->prev_item_type
||
3441 g_variant_type_is_subtype_of (GVSB(builder
)->prev_item_type
,
3444 parent
= g_slice_dup (GVariantBuilder
, builder
);
3445 g_variant_builder_init (builder
, type
);
3446 GVSB(builder
)->parent
= parent
;
3448 /* push the prev_item_type down into the subcontainer */
3449 if (GVSB(parent
)->prev_item_type
)
3451 if (!GVSB(builder
)->uniform_item_types
)
3452 /* tuples and dict entries */
3453 GVSB(builder
)->prev_item_type
=
3454 g_variant_type_first (GVSB(parent
)->prev_item_type
);
3456 else if (!g_variant_type_is_variant (GVSB(builder
)->type
))
3457 /* maybes and arrays */
3458 GVSB(builder
)->prev_item_type
=
3459 g_variant_type_element (GVSB(parent
)->prev_item_type
);
3464 * g_variant_builder_close:
3465 * @builder: a #GVariantBuilder
3467 * Closes the subcontainer inside the given @builder that was opened by
3468 * the most recent call to g_variant_builder_open().
3470 * It is an error to call this function in any way that would create an
3471 * inconsistent value to be constructed (ie: too few values added to the
3477 g_variant_builder_close (GVariantBuilder
*builder
)
3479 GVariantBuilder
*parent
;
3481 g_return_if_fail (is_valid_builder (builder
));
3482 g_return_if_fail (GVSB(builder
)->parent
!= NULL
);
3484 parent
= GVSB(builder
)->parent
;
3485 GVSB(builder
)->parent
= NULL
;
3487 g_variant_builder_add_value (parent
, g_variant_builder_end (builder
));
3490 g_slice_free (GVariantBuilder
, parent
);
3494 * g_variant_make_maybe_type:
3495 * @element: a #GVariant
3497 * Return the type of a maybe containing @element.
3499 static GVariantType
*
3500 g_variant_make_maybe_type (GVariant
*element
)
3502 return g_variant_type_new_maybe (g_variant_get_type (element
));
3506 * g_variant_make_array_type:
3507 * @element: a #GVariant
3509 * Return the type of an array containing @element.
3511 static GVariantType
*
3512 g_variant_make_array_type (GVariant
*element
)
3514 return g_variant_type_new_array (g_variant_get_type (element
));
3518 * g_variant_builder_end:
3519 * @builder: a #GVariantBuilder
3521 * Ends the builder process and returns the constructed value.
3523 * It is not permissible to use @builder in any way after this call
3524 * except for reference counting operations (in the case of a
3525 * heap-allocated #GVariantBuilder) or by reinitialising it with
3526 * g_variant_builder_init() (in the case of stack-allocated).
3528 * It is an error to call this function in any way that would create an
3529 * inconsistent value to be constructed (ie: insufficient number of
3530 * items added to a container with a specific number of children
3531 * required). It is also an error to call this function if the builder
3532 * was created with an indefinite array or maybe type and no children
3533 * have been added; in this case it is impossible to infer the type of
3536 * Returns: (transfer none): a new, floating, #GVariant
3541 g_variant_builder_end (GVariantBuilder
*builder
)
3543 GVariantType
*my_type
;
3546 g_return_val_if_fail (is_valid_builder (builder
), NULL
);
3547 g_return_val_if_fail (GVSB(builder
)->offset
>= GVSB(builder
)->min_items
,
3549 g_return_val_if_fail (!GVSB(builder
)->uniform_item_types
||
3550 GVSB(builder
)->prev_item_type
!= NULL
||
3551 g_variant_type_is_definite (GVSB(builder
)->type
),
3554 if (g_variant_type_is_definite (GVSB(builder
)->type
))
3555 my_type
= g_variant_type_copy (GVSB(builder
)->type
);
3557 else if (g_variant_type_is_maybe (GVSB(builder
)->type
))
3558 my_type
= g_variant_make_maybe_type (GVSB(builder
)->children
[0]);
3560 else if (g_variant_type_is_array (GVSB(builder
)->type
))
3561 my_type
= g_variant_make_array_type (GVSB(builder
)->children
[0]);
3563 else if (g_variant_type_is_tuple (GVSB(builder
)->type
))
3564 my_type
= g_variant_make_tuple_type (GVSB(builder
)->children
,
3565 GVSB(builder
)->offset
);
3567 else if (g_variant_type_is_dict_entry (GVSB(builder
)->type
))
3568 my_type
= g_variant_make_dict_entry_type (GVSB(builder
)->children
[0],
3569 GVSB(builder
)->children
[1]);
3571 g_assert_not_reached ();
3573 value
= g_variant_new_from_children (my_type
,
3574 g_renew (GVariant
*,
3575 GVSB(builder
)->children
,
3576 GVSB(builder
)->offset
),
3577 GVSB(builder
)->offset
,
3578 GVSB(builder
)->trusted
);
3579 GVSB(builder
)->children
= NULL
;
3580 GVSB(builder
)->offset
= 0;
3582 g_variant_builder_clear (builder
);
3583 g_variant_type_free (my_type
);
3588 /* Format strings {{{1 */
3590 * g_variant_format_string_scan:
3591 * @string: a string that may be prefixed with a format string
3592 * @limit: (allow-none) (default NULL): a pointer to the end of @string,
3594 * @endptr: (allow-none) (default NULL): location to store the end pointer,
3597 * Checks the string pointed to by @string for starting with a properly
3598 * formed #GVariant varargs format string. If no valid format string is
3599 * found then %FALSE is returned.
3601 * If @string does start with a valid format string then %TRUE is
3602 * returned. If @endptr is non-%NULL then it is updated to point to the
3603 * first character after the format string.
3605 * If @limit is non-%NULL then @limit (and any charater after it) will
3606 * not be accessed and the effect is otherwise equivalent to if the
3607 * character at @limit were nul.
3609 * See the section on <link linkend='gvariant-format-strings'>GVariant
3610 * Format Strings</link>.
3612 * Returns: %TRUE if there was a valid format string
3617 g_variant_format_string_scan (const gchar
*string
,
3619 const gchar
**endptr
)
3621 #define next_char() (string == limit ? '\0' : *string++)
3622 #define peek_char() (string == limit ? '\0' : *string)
3625 switch (next_char())
3627 case 'b': case 'y': case 'n': case 'q': case 'i': case 'u':
3628 case 'x': case 't': case 'h': case 'd': case 's': case 'o':
3629 case 'g': case 'v': case '*': case '?': case 'r':
3633 return g_variant_format_string_scan (string
, limit
, endptr
);
3637 return g_variant_type_string_scan (string
, limit
, endptr
);
3640 while (peek_char() != ')')
3641 if (!g_variant_format_string_scan (string
, limit
, &string
))
3644 next_char(); /* consume ')' */
3654 if (c
!= 's' && c
!= 'o' && c
!= 'g')
3662 /* ISO/IEC 9899:1999 (C99) §7.21.5.2:
3663 * The terminating null character is considered to be
3664 * part of the string.
3666 if (c
!= '\0' && strchr ("bynqiuxthdsog?", c
) == NULL
)
3670 if (!g_variant_format_string_scan (string
, limit
, &string
))
3673 if (next_char() != '}')
3679 if ((c
= next_char()) == 'a')
3681 if ((c
= next_char()) == '&')
3683 if ((c
= next_char()) == 'a')
3685 if ((c
= next_char()) == 'y')
3686 break; /* '^a&ay' */
3689 else if (c
== 's' || c
== 'o')
3690 break; /* '^a&s', '^a&o' */
3695 if ((c
= next_char()) == 'y')
3699 else if (c
== 's' || c
== 'o')
3700 break; /* '^as', '^ao' */
3707 if ((c
= next_char()) == 'a')
3709 if ((c
= next_char()) == 'y')
3719 if (c
!= 's' && c
!= 'o' && c
!= 'g')
3738 * g_variant_format_string_scan_type:
3739 * @string: a string that may be prefixed with a format string
3740 * @limit: (allow-none) (default NULL): a pointer to the end of @string,
3742 * @endptr: (allow-none) (default NULL): location to store the end pointer,
3745 * If @string starts with a valid format string then this function will
3746 * return the type that the format string corresponds to. Otherwise
3747 * this function returns %NULL.
3749 * Use g_variant_type_free() to free the return value when you no longer
3752 * This function is otherwise exactly like
3753 * g_variant_format_string_scan().
3755 * Returns: (allow-none): a #GVariantType if there was a valid format string
3760 g_variant_format_string_scan_type (const gchar
*string
,
3762 const gchar
**endptr
)
3764 const gchar
*my_end
;
3771 if (!g_variant_format_string_scan (string
, limit
, endptr
))
3774 dest
= new = g_malloc (*endptr
- string
+ 1);
3775 while (string
!= *endptr
)
3777 if (*string
!= '@' && *string
!= '&' && *string
!= '^')
3783 return (GVariantType
*) G_VARIANT_TYPE (new);
3787 valid_format_string (const gchar
*format_string
,
3791 const gchar
*endptr
;
3794 type
= g_variant_format_string_scan_type (format_string
, NULL
, &endptr
);
3796 if G_UNLIKELY (type
== NULL
|| (single
&& *endptr
!= '\0'))
3799 g_critical ("`%s' is not a valid GVariant format string",
3802 g_critical ("`%s' does not have a valid GVariant format "
3803 "string as a prefix", format_string
);
3806 g_variant_type_free (type
);
3811 if G_UNLIKELY (value
&& !g_variant_is_of_type (value
, type
))
3816 fragment
= g_strndup (format_string
, endptr
- format_string
);
3817 typestr
= g_variant_type_dup_string (type
);
3819 g_critical ("the GVariant format string `%s' has a type of "
3820 "`%s' but the given value has a type of `%s'",
3821 fragment
, typestr
, g_variant_get_type_string (value
));
3823 g_variant_type_free (type
);
3828 g_variant_type_free (type
);
3833 /* Variable Arguments {{{1 */
3834 /* We consider 2 main classes of format strings:
3836 * - recursive format strings
3837 * these are ones that result in recursion and the collection of
3838 * possibly more than one argument. Maybe types, tuples,
3839 * dictionary entries.
3841 * - leaf format string
3842 * these result in the collection of a single argument.
3844 * Leaf format strings are further subdivided into two categories:
3846 * - single non-null pointer ("nnp")
3847 * these either collect or return a single non-null pointer.
3850 * these collect or return something else (bool, number, etc).
3852 * Based on the above, the varargs handling code is split into 4 main parts:
3854 * - nnp handling code
3855 * - leaf handling code (which may invoke nnp code)
3856 * - generic handling code (may be recursive, may invoke leaf code)
3857 * - user-facing API (which invokes the generic code)
3859 * Each section implements some of the following functions:
3862 * collect the arguments for the format string as if
3863 * g_variant_new() had been called, but do nothing with them. used
3864 * for skipping over arguments when constructing a Nothing maybe
3868 * create a GVariant *
3871 * unpack a GVariant *
3873 * - free (nnp only):
3874 * free a previously allocated item
3878 g_variant_format_string_is_leaf (const gchar
*str
)
3880 return str
[0] != 'm' && str
[0] != '(' && str
[0] != '{';
3884 g_variant_format_string_is_nnp (const gchar
*str
)
3886 return str
[0] == 'a' || str
[0] == 's' || str
[0] == 'o' || str
[0] == 'g' ||
3887 str
[0] == '^' || str
[0] == '@' || str
[0] == '*' || str
[0] == '?' ||
3888 str
[0] == 'r' || str
[0] == 'v' || str
[0] == '&';
3891 /* Single non-null pointer ("nnp") {{{2 */
3893 g_variant_valist_free_nnp (const gchar
*str
,
3899 g_variant_iter_free (ptr
);
3903 if (str
[2] != '&') /* '^as', '^ao' */
3905 else /* '^a&s', '^a&o' */
3919 g_variant_unref (ptr
);
3926 g_assert_not_reached ();
3931 g_variant_scan_convenience (const gchar
**str
,
3954 g_variant_valist_new_nnp (const gchar
**str
,
3965 const GVariantType
*type
;
3968 value
= g_variant_builder_end (ptr
);
3969 type
= g_variant_get_type (value
);
3971 if G_UNLIKELY (!g_variant_type_is_array (type
))
3972 g_error ("g_variant_new: expected array GVariantBuilder but "
3973 "the built value has type `%s'",
3974 g_variant_get_type_string (value
));
3976 type
= g_variant_type_element (type
);
3978 if G_UNLIKELY (!g_variant_type_is_subtype_of (type
, (GVariantType
*) *str
))
3979 g_error ("g_variant_new: expected GVariantBuilder array element "
3980 "type `%s' but the built value has element type `%s'",
3981 g_variant_type_dup_string ((GVariantType
*) *str
),
3982 g_variant_get_type_string (value
) + 1);
3984 g_variant_type_string_scan (*str
, NULL
, str
);
3990 /* special case: NULL pointer for empty array */
3992 const GVariantType
*type
= (GVariantType
*) *str
;
3994 g_variant_type_string_scan (*str
, NULL
, str
);
3996 if G_UNLIKELY (!g_variant_type_is_definite (type
))
3997 g_error ("g_variant_new: NULL pointer given with indefinite "
3998 "array type; unable to determine which type of empty "
3999 "array to construct.");
4001 return g_variant_new_array (type
, NULL
, 0);
4008 value
= g_variant_new_string (ptr
);
4011 value
= g_variant_new_string ("[Invalid UTF-8]");
4017 return g_variant_new_object_path (ptr
);
4020 return g_variant_new_signature (ptr
);
4028 type
= g_variant_scan_convenience (str
, &constant
, &arrays
);
4031 return g_variant_new_strv (ptr
, -1);
4034 return g_variant_new_objv (ptr
, -1);
4037 return g_variant_new_bytestring_array (ptr
, -1);
4039 return g_variant_new_bytestring (ptr
);
4043 if G_UNLIKELY (!g_variant_is_of_type (ptr
, (GVariantType
*) *str
))
4044 g_error ("g_variant_new: expected GVariant of type `%s' but "
4045 "received value has type `%s'",
4046 g_variant_type_dup_string ((GVariantType
*) *str
),
4047 g_variant_get_type_string (ptr
));
4049 g_variant_type_string_scan (*str
, NULL
, str
);
4057 if G_UNLIKELY (!g_variant_type_is_basic (g_variant_get_type (ptr
)))
4058 g_error ("g_variant_new: format string `?' expects basic-typed "
4059 "GVariant, but received value has type `%s'",
4060 g_variant_get_type_string (ptr
));
4065 if G_UNLIKELY (!g_variant_type_is_tuple (g_variant_get_type (ptr
)))
4066 g_error ("g_variant_new: format string `r` expects tuple-typed "
4067 "GVariant, but received value has type `%s'",
4068 g_variant_get_type_string (ptr
));
4073 return g_variant_new_variant (ptr
);
4076 g_assert_not_reached ();
4081 g_variant_valist_get_nnp (const gchar
**str
,
4087 g_variant_type_string_scan (*str
, NULL
, str
);
4088 return g_variant_iter_new (value
);
4092 return (gchar
*) g_variant_get_string (value
, NULL
);
4097 return g_variant_dup_string (value
, NULL
);
4105 type
= g_variant_scan_convenience (str
, &constant
, &arrays
);
4110 return g_variant_get_strv (value
, NULL
);
4112 return g_variant_dup_strv (value
, NULL
);
4115 else if (type
== 'o')
4118 return g_variant_get_objv (value
, NULL
);
4120 return g_variant_dup_objv (value
, NULL
);
4123 else if (arrays
> 1)
4126 return g_variant_get_bytestring_array (value
, NULL
);
4128 return g_variant_dup_bytestring_array (value
, NULL
);
4134 return (gchar
*) g_variant_get_bytestring (value
);
4136 return g_variant_dup_bytestring (value
, NULL
);
4141 g_variant_type_string_scan (*str
, NULL
, str
);
4147 return g_variant_ref (value
);
4150 return g_variant_get_variant (value
);
4153 g_assert_not_reached ();
4159 g_variant_valist_skip_leaf (const gchar
**str
,
4162 if (g_variant_format_string_is_nnp (*str
))
4164 g_variant_format_string_scan (*str
, NULL
, str
);
4165 va_arg (*app
, gpointer
);
4183 va_arg (*app
, guint64
);
4187 va_arg (*app
, gdouble
);
4191 g_assert_not_reached ();
4196 g_variant_valist_new_leaf (const gchar
**str
,
4199 if (g_variant_format_string_is_nnp (*str
))
4200 return g_variant_valist_new_nnp (str
, va_arg (*app
, gpointer
));
4205 return g_variant_new_boolean (va_arg (*app
, gboolean
));
4208 return g_variant_new_byte (va_arg (*app
, guint
));
4211 return g_variant_new_int16 (va_arg (*app
, gint
));
4214 return g_variant_new_uint16 (va_arg (*app
, guint
));
4217 return g_variant_new_int32 (va_arg (*app
, gint
));
4220 return g_variant_new_uint32 (va_arg (*app
, guint
));
4223 return g_variant_new_int64 (va_arg (*app
, gint64
));
4226 return g_variant_new_uint64 (va_arg (*app
, guint64
));
4229 return g_variant_new_handle (va_arg (*app
, gint
));
4232 return g_variant_new_double (va_arg (*app
, gdouble
));
4235 g_assert_not_reached ();
4239 /* The code below assumes this */
4240 G_STATIC_ASSERT (sizeof (gboolean
) == sizeof (guint32
));
4241 G_STATIC_ASSERT (sizeof (gdouble
) == sizeof (guint64
));
4244 g_variant_valist_get_leaf (const gchar
**str
,
4249 gpointer ptr
= va_arg (*app
, gpointer
);
4253 g_variant_format_string_scan (*str
, NULL
, str
);
4257 if (g_variant_format_string_is_nnp (*str
))
4259 gpointer
*nnp
= (gpointer
*) ptr
;
4261 if (free
&& *nnp
!= NULL
)
4262 g_variant_valist_free_nnp (*str
, *nnp
);
4267 *nnp
= g_variant_valist_get_nnp (str
, value
);
4269 g_variant_format_string_scan (*str
, NULL
, str
);
4279 *(gboolean
*) ptr
= g_variant_get_boolean (value
);
4283 *(guchar
*) ptr
= g_variant_get_byte (value
);
4287 *(gint16
*) ptr
= g_variant_get_int16 (value
);
4291 *(guint16
*) ptr
= g_variant_get_uint16 (value
);
4295 *(gint32
*) ptr
= g_variant_get_int32 (value
);
4299 *(guint32
*) ptr
= g_variant_get_uint32 (value
);
4303 *(gint64
*) ptr
= g_variant_get_int64 (value
);
4307 *(guint64
*) ptr
= g_variant_get_uint64 (value
);
4311 *(gint32
*) ptr
= g_variant_get_handle (value
);
4315 *(gdouble
*) ptr
= g_variant_get_double (value
);
4324 *(guchar
*) ptr
= 0;
4329 *(guint16
*) ptr
= 0;
4336 *(guint32
*) ptr
= 0;
4342 *(guint64
*) ptr
= 0;
4347 g_assert_not_reached ();
4350 /* Generic (recursive) {{{2 */
4352 g_variant_valist_skip (const gchar
**str
,
4355 if (g_variant_format_string_is_leaf (*str
))
4356 g_variant_valist_skip_leaf (str
, app
);
4358 else if (**str
== 'm') /* maybe */
4362 if (!g_variant_format_string_is_nnp (*str
))
4363 va_arg (*app
, gboolean
);
4365 g_variant_valist_skip (str
, app
);
4367 else /* tuple, dictionary entry */
4369 g_assert (**str
== '(' || **str
== '{');
4371 while (**str
!= ')' && **str
!= '}')
4372 g_variant_valist_skip (str
, app
);
4378 g_variant_valist_new (const gchar
**str
,
4381 if (g_variant_format_string_is_leaf (*str
))
4382 return g_variant_valist_new_leaf (str
, app
);
4384 if (**str
== 'm') /* maybe */
4386 GVariantType
*type
= NULL
;
4387 GVariant
*value
= NULL
;
4391 if (g_variant_format_string_is_nnp (*str
))
4393 gpointer nnp
= va_arg (*app
, gpointer
);
4396 value
= g_variant_valist_new_nnp (str
, nnp
);
4398 type
= g_variant_format_string_scan_type (*str
, NULL
, str
);
4402 gboolean just
= va_arg (*app
, gboolean
);
4405 value
= g_variant_valist_new (str
, app
);
4408 type
= g_variant_format_string_scan_type (*str
, NULL
, NULL
);
4409 g_variant_valist_skip (str
, app
);
4413 value
= g_variant_new_maybe (type
, value
);
4416 g_variant_type_free (type
);
4420 else /* tuple, dictionary entry */
4425 g_variant_builder_init (&b
, G_VARIANT_TYPE_TUPLE
);
4428 g_assert (**str
== '{');
4429 g_variant_builder_init (&b
, G_VARIANT_TYPE_DICT_ENTRY
);
4433 while (**str
!= ')' && **str
!= '}')
4434 g_variant_builder_add_value (&b
, g_variant_valist_new (str
, app
));
4437 return g_variant_builder_end (&b
);
4442 g_variant_valist_get (const gchar
**str
,
4447 if (g_variant_format_string_is_leaf (*str
))
4448 g_variant_valist_get_leaf (str
, value
, free
, app
);
4450 else if (**str
== 'm')
4455 value
= g_variant_get_maybe (value
);
4457 if (!g_variant_format_string_is_nnp (*str
))
4459 gboolean
*ptr
= va_arg (*app
, gboolean
*);
4462 *ptr
= value
!= NULL
;
4465 g_variant_valist_get (str
, value
, free
, app
);
4468 g_variant_unref (value
);
4471 else /* tuple, dictionary entry */
4475 g_assert (**str
== '(' || **str
== '{');
4478 while (**str
!= ')' && **str
!= '}')
4482 GVariant
*child
= g_variant_get_child_value (value
, index
++);
4483 g_variant_valist_get (str
, child
, free
, app
);
4484 g_variant_unref (child
);
4487 g_variant_valist_get (str
, NULL
, free
, app
);
4493 /* User-facing API {{{2 */
4495 * g_variant_new: (skip)
4496 * @format_string: a #GVariant format string
4497 * @...: arguments, as per @format_string
4499 * Creates a new #GVariant instance.
4501 * Think of this function as an analogue to g_strdup_printf().
4503 * The type of the created instance and the arguments that are
4504 * expected by this function are determined by @format_string. See the
4505 * section on <link linkend='gvariant-format-strings'>GVariant Format
4506 * Strings</link>. Please note that the syntax of the format string is
4507 * very likely to be extended in the future.
4509 * The first character of the format string must not be '*' '?' '@' or
4510 * 'r'; in essence, a new #GVariant must always be constructed by this
4511 * function (and not merely passed through it unmodified).
4513 * Returns: a new floating #GVariant instance
4518 g_variant_new (const gchar
*format_string
,
4524 g_return_val_if_fail (valid_format_string (format_string
, TRUE
, NULL
) &&
4525 format_string
[0] != '?' && format_string
[0] != '@' &&
4526 format_string
[0] != '*' && format_string
[0] != 'r',
4529 va_start (ap
, format_string
);
4530 value
= g_variant_new_va (format_string
, NULL
, &ap
);
4537 * g_variant_new_va: (skip)
4538 * @format_string: a string that is prefixed with a format string
4539 * @endptr: (allow-none) (default NULL): location to store the end pointer,
4541 * @app: a pointer to a #va_list
4543 * This function is intended to be used by libraries based on
4544 * #GVariant that want to provide g_variant_new()-like functionality
4547 * The API is more general than g_variant_new() to allow a wider range
4550 * @format_string must still point to a valid format string, but it only
4551 * needs to be nul-terminated if @endptr is %NULL. If @endptr is
4552 * non-%NULL then it is updated to point to the first character past the
4553 * end of the format string.
4555 * @app is a pointer to a #va_list. The arguments, according to
4556 * @format_string, are collected from this #va_list and the list is left
4557 * pointing to the argument following the last.
4559 * These two generalisations allow mixing of multiple calls to
4560 * g_variant_new_va() and g_variant_get_va() within a single actual
4561 * varargs call by the user.
4563 * The return value will be floating if it was a newly created GVariant
4564 * instance (for example, if the format string was "(ii)"). In the case
4565 * that the format_string was '*', '?', 'r', or a format starting with
4566 * '@' then the collected #GVariant pointer will be returned unmodified,
4567 * without adding any additional references.
4569 * In order to behave correctly in all cases it is necessary for the
4570 * calling function to g_variant_ref_sink() the return result before
4571 * returning control to the user that originally provided the pointer.
4572 * At this point, the caller will have their own full reference to the
4573 * result. This can also be done by adding the result to a container,
4574 * or by passing it to another g_variant_new() call.
4576 * Returns: a new, usually floating, #GVariant
4581 g_variant_new_va (const gchar
*format_string
,
4582 const gchar
**endptr
,
4587 g_return_val_if_fail (valid_format_string (format_string
, !endptr
, NULL
),
4589 g_return_val_if_fail (app
!= NULL
, NULL
);
4591 value
= g_variant_valist_new (&format_string
, app
);
4594 *endptr
= format_string
;
4600 * g_variant_get: (skip)
4601 * @value: a #GVariant instance
4602 * @format_string: a #GVariant format string
4603 * @...: arguments, as per @format_string
4605 * Deconstructs a #GVariant instance.
4607 * Think of this function as an analogue to scanf().
4609 * The arguments that are expected by this function are entirely
4610 * determined by @format_string. @format_string also restricts the
4611 * permissible types of @value. It is an error to give a value with
4612 * an incompatible type. See the section on <link
4613 * linkend='gvariant-format-strings'>GVariant Format Strings</link>.
4614 * Please note that the syntax of the format string is very likely to be
4615 * extended in the future.
4620 g_variant_get (GVariant
*value
,
4621 const gchar
*format_string
,
4626 g_return_if_fail (valid_format_string (format_string
, TRUE
, value
));
4628 /* if any direct-pointer-access formats are in use, flatten first */
4629 if (strchr (format_string
, '&'))
4630 g_variant_get_data (value
);
4632 va_start (ap
, format_string
);
4633 g_variant_get_va (value
, format_string
, NULL
, &ap
);
4638 * g_variant_get_va: (skip)
4639 * @value: a #GVariant
4640 * @format_string: a string that is prefixed with a format string
4641 * @endptr: (allow-none) (default NULL): location to store the end pointer,
4643 * @app: a pointer to a #va_list
4645 * This function is intended to be used by libraries based on #GVariant
4646 * that want to provide g_variant_get()-like functionality to their
4649 * The API is more general than g_variant_get() to allow a wider range
4652 * @format_string must still point to a valid format string, but it only
4653 * need to be nul-terminated if @endptr is %NULL. If @endptr is
4654 * non-%NULL then it is updated to point to the first character past the
4655 * end of the format string.
4657 * @app is a pointer to a #va_list. The arguments, according to
4658 * @format_string, are collected from this #va_list and the list is left
4659 * pointing to the argument following the last.
4661 * These two generalisations allow mixing of multiple calls to
4662 * g_variant_new_va() and g_variant_get_va() within a single actual
4663 * varargs call by the user.
4668 g_variant_get_va (GVariant
*value
,
4669 const gchar
*format_string
,
4670 const gchar
**endptr
,
4673 g_return_if_fail (valid_format_string (format_string
, !endptr
, value
));
4674 g_return_if_fail (value
!= NULL
);
4675 g_return_if_fail (app
!= NULL
);
4677 /* if any direct-pointer-access formats are in use, flatten first */
4678 if (strchr (format_string
, '&'))
4679 g_variant_get_data (value
);
4681 g_variant_valist_get (&format_string
, value
, FALSE
, app
);
4684 *endptr
= format_string
;
4687 /* Varargs-enabled Utility Functions {{{1 */
4690 * g_variant_builder_add: (skp)
4691 * @builder: a #GVariantBuilder
4692 * @format_string: a #GVariant varargs format string
4693 * @...: arguments, as per @format_string
4695 * Adds to a #GVariantBuilder.
4697 * This call is a convenience wrapper that is exactly equivalent to
4698 * calling g_variant_new() followed by g_variant_builder_add_value().
4700 * This function might be used as follows:
4704 * make_pointless_dictionary (void)
4706 * GVariantBuilder *builder;
4709 * builder = g_variant_builder_new (G_VARIANT_TYPE_ARRAY);
4710 * for (i = 0; i < 16; i++)
4714 * sprintf (buf, "%d", i);
4715 * g_variant_builder_add (builder, "{is}", i, buf);
4718 * return g_variant_builder_end (builder);
4725 g_variant_builder_add (GVariantBuilder
*builder
,
4726 const gchar
*format_string
,
4732 va_start (ap
, format_string
);
4733 variant
= g_variant_new_va (format_string
, NULL
, &ap
);
4736 g_variant_builder_add_value (builder
, variant
);
4740 * g_variant_get_child: (skip)
4741 * @value: a container #GVariant
4742 * @index_: the index of the child to deconstruct
4743 * @format_string: a #GVariant format string
4744 * @...: arguments, as per @format_string
4746 * Reads a child item out of a container #GVariant instance and
4747 * deconstructs it according to @format_string. This call is
4748 * essentially a combination of g_variant_get_child_value() and
4754 g_variant_get_child (GVariant
*value
,
4756 const gchar
*format_string
,
4762 child
= g_variant_get_child_value (value
, index_
);
4763 g_return_if_fail (valid_format_string (format_string
, TRUE
, child
));
4765 va_start (ap
, format_string
);
4766 g_variant_get_va (child
, format_string
, NULL
, &ap
);
4769 g_variant_unref (child
);
4773 * g_variant_iter_next: (skip)
4774 * @iter: a #GVariantIter
4775 * @format_string: a GVariant format string
4776 * @...: the arguments to unpack the value into
4778 * Gets the next item in the container and unpacks it into the variable
4779 * argument list according to @format_string, returning %TRUE.
4781 * If no more items remain then %FALSE is returned.
4783 * All of the pointers given on the variable arguments list of this
4784 * function are assumed to point at uninitialised memory. It is the
4785 * responsibility of the caller to free all of the values returned by
4786 * the unpacking process.
4788 * See the section on <link linkend='gvariant-format-strings'>GVariant
4789 * Format Strings</link>.
4792 * <title>Memory management with g_variant_iter_next()</title>
4794 * /<!-- -->* Iterates a dictionary of type 'a{sv}' *<!-- -->/
4796 * iterate_dictionary (GVariant *dictionary)
4798 * GVariantIter iter;
4802 * g_variant_iter_init (&iter, dictionary);
4803 * while (g_variant_iter_next (&iter, "{sv}", &key, &value))
4805 * g_print ("Item '%s' has type '%s'\n", key,
4806 * g_variant_get_type_string (value));
4808 * /<!-- -->* must free data for ourselves *<!-- -->/
4809 * g_variant_unref (value);
4816 * For a solution that is likely to be more convenient to C programmers
4817 * when dealing with loops, see g_variant_iter_loop().
4819 * Returns: %TRUE if a value was unpacked, or %FALSE if there as no value
4824 g_variant_iter_next (GVariantIter
*iter
,
4825 const gchar
*format_string
,
4830 value
= g_variant_iter_next_value (iter
);
4832 g_return_val_if_fail (valid_format_string (format_string
, TRUE
, value
),
4839 va_start (ap
, format_string
);
4840 g_variant_valist_get (&format_string
, value
, FALSE
, &ap
);
4843 g_variant_unref (value
);
4846 return value
!= NULL
;
4850 * g_variant_iter_loop: (skip)
4851 * @iter: a #GVariantIter
4852 * @format_string: a GVariant format string
4853 * @...: the arguments to unpack the value into
4855 * Gets the next item in the container and unpacks it into the variable
4856 * argument list according to @format_string, returning %TRUE.
4858 * If no more items remain then %FALSE is returned.
4860 * On the first call to this function, the pointers appearing on the
4861 * variable argument list are assumed to point at uninitialised memory.
4862 * On the second and later calls, it is assumed that the same pointers
4863 * will be given and that they will point to the memory as set by the
4864 * previous call to this function. This allows the previous values to
4865 * be freed, as appropriate.
4867 * This function is intended to be used with a while loop as
4868 * demonstrated in the following example. This function can only be
4869 * used when iterating over an array. It is only valid to call this
4870 * function with a string constant for the format string and the same
4871 * string constant must be used each time. Mixing calls to this
4872 * function and g_variant_iter_next() or g_variant_iter_next_value() on
4873 * the same iterator causes undefined behavior.
4875 * If you break out of a such a while loop using g_variant_iter_loop() then
4876 * you must free or unreference all the unpacked values as you would with
4877 * g_variant_get(). Failure to do so will cause a memory leak.
4879 * See the section on <link linkend='gvariant-format-strings'>GVariant
4880 * Format Strings</link>.
4883 * <title>Memory management with g_variant_iter_loop()</title>
4885 * /<!-- -->* Iterates a dictionary of type 'a{sv}' *<!-- -->/
4887 * iterate_dictionary (GVariant *dictionary)
4889 * GVariantIter iter;
4893 * g_variant_iter_init (&iter, dictionary);
4894 * while (g_variant_iter_loop (&iter, "{sv}", &key, &value))
4896 * g_print ("Item '%s' has type '%s'\n", key,
4897 * g_variant_get_type_string (value));
4899 * /<!-- -->* no need to free 'key' and 'value' here *<!-- -->/
4900 * /<!-- -->* unless breaking out of this loop *<!-- -->/
4906 * For most cases you should use g_variant_iter_next().
4908 * This function is really only useful when unpacking into #GVariant or
4909 * #GVariantIter in order to allow you to skip the call to
4910 * g_variant_unref() or g_variant_iter_free().
4912 * For example, if you are only looping over simple integer and string
4913 * types, g_variant_iter_next() is definitely preferred. For string
4914 * types, use the '&' prefix to avoid allocating any memory at all (and
4915 * thereby avoiding the need to free anything as well).
4917 * Returns: %TRUE if a value was unpacked, or %FALSE if there was no
4923 g_variant_iter_loop (GVariantIter
*iter
,
4924 const gchar
*format_string
,
4927 gboolean first_time
= GVSI(iter
)->loop_format
== NULL
;
4931 g_return_val_if_fail (first_time
||
4932 format_string
== GVSI(iter
)->loop_format
,
4937 TYPE_CHECK (GVSI(iter
)->value
, G_VARIANT_TYPE_ARRAY
, FALSE
);
4938 GVSI(iter
)->loop_format
= format_string
;
4940 if (strchr (format_string
, '&'))
4941 g_variant_get_data (GVSI(iter
)->value
);
4944 value
= g_variant_iter_next_value (iter
);
4946 g_return_val_if_fail (!first_time
||
4947 valid_format_string (format_string
, TRUE
, value
),
4950 va_start (ap
, format_string
);
4951 g_variant_valist_get (&format_string
, value
, !first_time
, &ap
);
4955 g_variant_unref (value
);
4957 return value
!= NULL
;
4960 /* Serialised data {{{1 */
4962 g_variant_deep_copy (GVariant
*value
)
4964 switch (g_variant_classify (value
))
4966 case G_VARIANT_CLASS_MAYBE
:
4967 case G_VARIANT_CLASS_ARRAY
:
4968 case G_VARIANT_CLASS_TUPLE
:
4969 case G_VARIANT_CLASS_DICT_ENTRY
:
4970 case G_VARIANT_CLASS_VARIANT
:
4972 GVariantBuilder builder
;
4976 g_variant_builder_init (&builder
, g_variant_get_type (value
));
4977 g_variant_iter_init (&iter
, value
);
4979 while ((child
= g_variant_iter_next_value (&iter
)))
4981 g_variant_builder_add_value (&builder
, g_variant_deep_copy (child
));
4982 g_variant_unref (child
);
4985 return g_variant_builder_end (&builder
);
4988 case G_VARIANT_CLASS_BOOLEAN
:
4989 return g_variant_new_boolean (g_variant_get_boolean (value
));
4991 case G_VARIANT_CLASS_BYTE
:
4992 return g_variant_new_byte (g_variant_get_byte (value
));
4994 case G_VARIANT_CLASS_INT16
:
4995 return g_variant_new_int16 (g_variant_get_int16 (value
));
4997 case G_VARIANT_CLASS_UINT16
:
4998 return g_variant_new_uint16 (g_variant_get_uint16 (value
));
5000 case G_VARIANT_CLASS_INT32
:
5001 return g_variant_new_int32 (g_variant_get_int32 (value
));
5003 case G_VARIANT_CLASS_UINT32
:
5004 return g_variant_new_uint32 (g_variant_get_uint32 (value
));
5006 case G_VARIANT_CLASS_INT64
:
5007 return g_variant_new_int64 (g_variant_get_int64 (value
));
5009 case G_VARIANT_CLASS_UINT64
:
5010 return g_variant_new_uint64 (g_variant_get_uint64 (value
));
5012 case G_VARIANT_CLASS_HANDLE
:
5013 return g_variant_new_handle (g_variant_get_handle (value
));
5015 case G_VARIANT_CLASS_DOUBLE
:
5016 return g_variant_new_double (g_variant_get_double (value
));
5018 case G_VARIANT_CLASS_STRING
:
5019 return g_variant_new_string (g_variant_get_string (value
, NULL
));
5021 case G_VARIANT_CLASS_OBJECT_PATH
:
5022 return g_variant_new_object_path (g_variant_get_string (value
, NULL
));
5024 case G_VARIANT_CLASS_SIGNATURE
:
5025 return g_variant_new_signature (g_variant_get_string (value
, NULL
));
5028 g_assert_not_reached ();
5032 * g_variant_get_normal_form:
5033 * @value: a #GVariant
5035 * Gets a #GVariant instance that has the same value as @value and is
5036 * trusted to be in normal form.
5038 * If @value is already trusted to be in normal form then a new
5039 * reference to @value is returned.
5041 * If @value is not already trusted, then it is scanned to check if it
5042 * is in normal form. If it is found to be in normal form then it is
5043 * marked as trusted and a new reference to it is returned.
5045 * If @value is found not to be in normal form then a new trusted
5046 * #GVariant is created with the same value as @value.
5048 * It makes sense to call this function if you've received #GVariant
5049 * data from untrusted sources and you want to ensure your serialised
5050 * output is definitely in normal form.
5052 * Returns: (transfer full): a trusted #GVariant
5057 g_variant_get_normal_form (GVariant
*value
)
5061 if (g_variant_is_normal_form (value
))
5062 return g_variant_ref (value
);
5064 trusted
= g_variant_deep_copy (value
);
5065 g_assert (g_variant_is_trusted (trusted
));
5067 return g_variant_ref_sink (trusted
);
5071 * g_variant_byteswap:
5072 * @value: a #GVariant
5074 * Performs a byteswapping operation on the contents of @value. The
5075 * result is that all multi-byte numeric data contained in @value is
5076 * byteswapped. That includes 16, 32, and 64bit signed and unsigned
5077 * integers as well as file handles and double precision floating point
5080 * This function is an identity mapping on any value that does not
5081 * contain multi-byte numeric data. That include strings, booleans,
5082 * bytes and containers containing only these things (recursively).
5084 * The returned value is always in normal form and is marked as trusted.
5086 * Returns: (transfer full): the byteswapped form of @value
5091 g_variant_byteswap (GVariant
*value
)
5093 GVariantTypeInfo
*type_info
;
5097 type_info
= g_variant_get_type_info (value
);
5099 g_variant_type_info_query (type_info
, &alignment
, NULL
);
5102 /* (potentially) contains multi-byte numeric data */
5104 GVariantSerialised serialised
;
5108 trusted
= g_variant_get_normal_form (value
);
5109 serialised
.type_info
= g_variant_get_type_info (trusted
);
5110 serialised
.size
= g_variant_get_size (trusted
);
5111 serialised
.data
= g_malloc (serialised
.size
);
5112 g_variant_store (trusted
, serialised
.data
);
5113 g_variant_unref (trusted
);
5115 g_variant_serialised_byteswap (serialised
);
5117 bytes
= g_bytes_new_take (serialised
.data
, serialised
.size
);
5118 new = g_variant_new_from_bytes (g_variant_get_type (value
), bytes
, TRUE
);
5119 g_bytes_unref (bytes
);
5122 /* contains no multi-byte data */
5125 return g_variant_ref_sink (new);
5129 * g_variant_new_from_data:
5130 * @type: a definite #GVariantType
5131 * @data: (array length=size) (element-type guint8): the serialised data
5132 * @size: the size of @data
5133 * @trusted: %TRUE if @data is definitely in normal form
5134 * @notify: (scope async): function to call when @data is no longer needed
5135 * @user_data: data for @notify
5137 * Creates a new #GVariant instance from serialised data.
5139 * @type is the type of #GVariant instance that will be constructed.
5140 * The interpretation of @data depends on knowing the type.
5142 * @data is not modified by this function and must remain valid with an
5143 * unchanging value until such a time as @notify is called with
5144 * @user_data. If the contents of @data change before that time then
5145 * the result is undefined.
5147 * If @data is trusted to be serialised data in normal form then
5148 * @trusted should be %TRUE. This applies to serialised data created
5149 * within this process or read from a trusted location on the disk (such
5150 * as a file installed in /usr/lib alongside your application). You
5151 * should set trusted to %FALSE if @data is read from the network, a
5152 * file in the user's home directory, etc.
5154 * If @data was not stored in this machine's native endianness, any multi-byte
5155 * numeric values in the returned variant will also be in non-native
5156 * endianness. g_variant_byteswap() can be used to recover the original values.
5158 * @notify will be called with @user_data when @data is no longer
5159 * needed. The exact time of this call is unspecified and might even be
5160 * before this function returns.
5162 * Returns: (transfer none): a new floating #GVariant of type @type
5167 g_variant_new_from_data (const GVariantType
*type
,
5171 GDestroyNotify notify
,
5177 g_return_val_if_fail (g_variant_type_is_definite (type
), NULL
);
5178 g_return_val_if_fail (data
!= NULL
|| size
== 0, NULL
);
5181 bytes
= g_bytes_new_with_free_func (data
, size
, notify
, user_data
);
5183 bytes
= g_bytes_new_static (data
, size
);
5185 value
= g_variant_new_from_bytes (type
, bytes
, trusted
);
5186 g_bytes_unref (bytes
);
5192 /* vim:set foldmethod=marker: */