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>
25 #include <glib/gvariant-serialiser.h>
26 #include <glib/gvariant-core.h>
27 #include <glib/gtestutils.h>
28 #include <glib/gstrfuncs.h>
29 #include <glib/ghash.h>
30 #include <glib/gmem.h>
39 * @short_description: strongly typed value datatype
40 * @see_also: GVariantType
42 * #GVariant is a variant datatype; it stores a value along with
43 * information about the type of that value. The range of possible
44 * values is determined by the type. The type system used by #GVariant
47 * #GVariant instances always have a type and a value (which are given
48 * at construction time). The type and value of a #GVariant instance
49 * can never change other than by the #GVariant itself being
50 * destroyed. A #GVariant can not contain a pointer.
52 * #GVariant is reference counted using g_variant_ref() and
53 * g_variant_unref(). #GVariant also has floating reference counts --
54 * see g_variant_ref_sink().
56 * #GVariant is completely threadsafe. A #GVariant instance can be
57 * concurrently accessed in any way from any number of threads without
60 * #GVariant is heavily optimised for dealing with data in serialised
61 * form. It works particularly well with data located in memory-mapped
62 * files. It can perform nearly all deserialisation operations in a
63 * small constant time, usually touching only a single memory page.
64 * Serialised #GVariant data can also be sent over the network.
66 * #GVariant is largely compatible with DBus. Almost all types of
67 * #GVariant instances can be sent over DBus. See #GVariantType for
70 * For convenience to C programmers, #GVariant features powerful
71 * varargs-based value construction and destruction. This feature is
72 * designed to be embedded in other libraries.
74 * There is a Python-inspired text language for describing #GVariant
75 * values. #GVariant includes a printer for this language and a parser
76 * with type inferencing.
79 * <title>Memory Use</title>
81 * #GVariant tries to be quite efficient with respect to memory use.
82 * This section gives a rough idea of how much memory is used by the
83 * current implementation. The information here is subject to change
87 * The memory allocated by #GVariant can be grouped into 4 broad
88 * purposes: memory for serialised data, memory for the type
89 * information cache, buffer management memory and memory for the
90 * #GVariant structure itself.
93 * <title>Serialised Data Memory</title>
95 * This is the memory that is used for storing GVariant data in
96 * serialised form. This is what would be sent over the network or
97 * what would end up on disk.
100 * The amount of memory required to store a boolean is 1 byte. 16,
101 * 32 and 64 bit integers and double precision floating point numbers
102 * use their "natural" size. Strings (including object path and
103 * signature strings) are stored with a nul terminator, and as such
104 * use the length of the string plus 1 byte.
107 * Maybe types use no space at all to represent the null value and
108 * use the same amount of space (sometimes plus one byte) as the
109 * equivalent non-maybe-typed value to represent the non-null case.
112 * Arrays use the amount of space required to store each of their
113 * members, concatenated. Additionally, if the items stored in an
114 * array are not of a fixed-size (ie: strings, other arrays, etc)
115 * then an additional framing offset is stored for each item. The
116 * size of this offset is either 1, 2 or 4 bytes depending on the
117 * overall size of the container. Additionally, extra padding bytes
118 * are added as required for alignment of child values.
121 * Tuples (including dictionary entries) use the amount of space
122 * required to store each of their members, concatenated, plus one
123 * framing offset (as per arrays) for each non-fixed-sized item in
124 * the tuple, except for the last one. Additionally, extra padding
125 * bytes are added as required for alignment of child values.
128 * Variants use the same amount of space as the item inside of the
129 * variant, plus 1 byte, plus the length of the type string for the
130 * item inside the variant.
133 * As an example, consider a dictionary mapping strings to variants.
134 * In the case that the dictionary is empty, 0 bytes are required for
138 * If we add an item "width" that maps to the int32 value of 500 then
139 * we will use 4 byte to store the int32 (so 6 for the variant
140 * containing it) and 6 bytes for the string. The variant must be
141 * aligned to 8 after the 6 bytes of the string, so that's 2 extra
142 * bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used
143 * for the dictionary entry. An additional 1 byte is added to the
144 * array as a framing offset making a total of 15 bytes.
147 * If we add another entry, "title" that maps to a nullable string
148 * that happens to have a value of null, then we use 0 bytes for the
149 * null value (and 3 bytes for the variant to contain it along with
150 * its type string) plus 6 bytes for the string. Again, we need 2
151 * padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes.
154 * We now require extra padding between the two items in the array.
155 * After the 14 bytes of the first item, that's 2 bytes required. We
156 * now require 2 framing offsets for an extra two bytes. 14 + 2 + 11
157 * + 2 = 29 bytes to encode the entire two-item dictionary.
161 * <title>Type Information Cache</title>
163 * For each GVariant type that currently exists in the program a type
164 * information structure is kept in the type information cache. The
165 * type information structure is required for rapid deserialisation.
168 * Continuing with the above example, if a #GVariant exists with the
169 * type "a{sv}" then a type information struct will exist for
170 * "a{sv}", "{sv}", "s", and "v". Multiple uses of the same type
171 * will share the same type information. Additionally, all
172 * single-digit types are stored in read-only static memory and do
173 * not contribute to the writable memory footprint of a program using
177 * Aside from the type information structures stored in read-only
178 * memory, there are two forms of type information. One is used for
179 * container types where there is a single element type: arrays and
180 * maybe types. The other is used for container types where there
181 * are multiple element types: tuples and dictionary entries.
184 * Array type info structures are 6 * sizeof (void *), plus the
185 * memory required to store the type string itself. This means that
186 * on 32bit systems, the cache entry for "a{sv}" would require 30
187 * bytes of memory (plus malloc overhead).
190 * Tuple type info structures are 6 * sizeof (void *), plus 4 *
191 * sizeof (void *) for each item in the tuple, plus the memory
192 * required to store the type string itself. A 2-item tuple, for
193 * example, would have a type information structure that consumed
194 * writable memory in the size of 14 * sizeof (void *) (plus type
195 * string) This means that on 32bit systems, the cache entry for
196 * "{sv}" would require 61 bytes of memory (plus malloc overhead).
199 * This means that in total, for our "a{sv}" example, 91 bytes of
200 * type information would be allocated.
203 * The type information cache, additionally, uses a #GHashTable to
204 * store and lookup the cached items and stores a pointer to this
205 * hash table in static storage. The hash table is freed when there
206 * are zero items in the type cache.
209 * Although these sizes may seem large it is important to remember
210 * that a program will probably only have a very small number of
211 * different types of values in it and that only one type information
212 * structure is required for many different values of the same type.
216 * <title>Buffer Management Memory</title>
218 * #GVariant uses an internal buffer management structure to deal
219 * with the various different possible sources of serialised data
220 * that it uses. The buffer is responsible for ensuring that the
221 * correct call is made when the data is no longer in use by
222 * #GVariant. This may involve a g_free() or a g_slice_free() or
223 * even g_mapped_file_unref().
226 * One buffer management structure is used for each chunk of
227 * serialised data. The size of the buffer management structure is 4
228 * * (void *). On 32bit systems, that's 16 bytes.
232 * <title>GVariant structure</title>
234 * The size of a #GVariant structure is 6 * (void *). On 32 bit
235 * systems, that's 24 bytes.
238 * #GVariant structures only exist if they are explicitly created
239 * with API calls. For example, if a #GVariant is constructed out of
240 * serialised data for the example given above (with the dictionary)
241 * then although there are 9 individual values that comprise the
242 * entire dictionary (two keys, two values, two variants containing
243 * the values, two dictionary entries, plus the dictionary itself),
244 * only 1 #GVariant instance exists -- the one refering to the
248 * If calls are made to start accessing the other values then
249 * #GVariant instances will exist for those values only for as long
250 * as they are in use (ie: until you call g_variant_unref()). The
251 * type information is shared. The serialised data and the buffer
252 * management structure for that serialised data is shared by the
257 * <title>Summary</title>
259 * To put the entire example together, for our dictionary mapping
260 * strings to variants (with two entries, as given above), we are
261 * using 91 bytes of memory for type information, 29 byes of memory
262 * for the serialised data, 16 bytes for buffer management and 24
263 * bytes for the #GVariant instance, or a total of 160 bytes, plus
264 * malloc overhead. If we were to use g_variant_get_child_value() to
265 * access the two dictionary entries, we would use an additional 48
266 * bytes. If we were to have other dictionaries of the same type, we
267 * would use more memory for the serialised data and buffer
268 * management for those dictionaries, but the type information would
275 /* definition of GVariant structure is in gvariant-core.c */
277 /* this is a g_return_val_if_fail() for making
278 * sure a (GVariant *) has the required type.
280 #define TYPE_CHECK(value, TYPE, val) \
281 if G_UNLIKELY (!g_variant_is_of_type (value, TYPE)) { \
282 g_return_if_fail_warning (G_LOG_DOMAIN, __PRETTY_FUNCTION__, \
283 "g_variant_is_of_type (" #value \
289 * g_variant_new_from_trusted:
290 * @type: the #GVariantType
291 * @data: the data to use
292 * @size: the size of @data
293 * @returns: a new floating #GVariant
295 * Constructs a new trusted #GVariant instance from the provided data.
296 * This is used to implement g_variant_new_* for all the basic types.
299 g_variant_new_from_trusted (const GVariantType *type,
306 buffer = g_buffer_new_from_data (data, size);
307 value = g_variant_new_from_buffer (type, buffer, TRUE);
308 g_buffer_unref (buffer);
314 * g_variant_new_boolean:
315 * @boolean: a #gboolean value
316 * @returns: a new boolean #GVariant instance
318 * Creates a new boolean #GVariant instance -- either %TRUE or %FALSE.
323 g_variant_new_boolean (gboolean value)
327 return g_variant_new_from_trusted (G_VARIANT_TYPE_BOOLEAN, &v, 1);
331 * g_variant_get_boolean:
332 * @value: a boolean #GVariant instance
333 * @returns: %TRUE or %FALSE
335 * Returns the boolean value of @value.
337 * It is an error to call this function with a @value of any type
338 * other than %G_VARIANT_TYPE_BOOLEAN.
343 g_variant_get_boolean (GVariant *value)
347 TYPE_CHECK (value, G_VARIANT_TYPE_BOOLEAN, FALSE);
349 data = g_variant_get_data (value);
351 return data != NULL ? *data != 0 : FALSE;
354 /* the constructors and accessors for byte, int{16,32,64}, handles and
355 * doubles all look pretty much exactly the same, so we reduce
358 #define NUMERIC_TYPE(TYPE, type, ctype) \
359 GVariant *g_variant_new_##type (ctype value) { \
360 return g_variant_new_from_trusted (G_VARIANT_TYPE_##TYPE, \
361 &value, sizeof value); \
363 ctype g_variant_get_##type (GVariant *value) { \
365 TYPE_CHECK (value, G_VARIANT_TYPE_ ## TYPE, 0); \
366 data = g_variant_get_data (value); \
367 return data != NULL ? *data : 0; \
372 * g_variant_new_byte:
373 * @byte: a #guint8 value
374 * @returns: a new byte #GVariant instance
376 * Creates a new byte #GVariant instance.
381 * g_variant_get_byte:
382 * @value: a byte #GVariant instance
383 * @returns: a #guchar
385 * Returns the byte value of @value.
387 * It is an error to call this function with a @value of any type
388 * other than %G_VARIANT_TYPE_BYTE.
392 NUMERIC_TYPE (BYTE, byte, guchar)
395 * g_variant_new_int16:
396 * @int16: a #gint16 value
397 * @returns: a new int16 #GVariant instance
399 * Creates a new int16 #GVariant instance.
404 * g_variant_get_int16:
405 * @value: a int16 #GVariant instance
406 * @returns: a #gint16
408 * Returns the 16-bit signed integer value of @value.
410 * It is an error to call this function with a @value of any type
411 * other than %G_VARIANT_TYPE_INT16.
415 NUMERIC_TYPE (INT16, int16, gint16)
418 * g_variant_new_uint16:
419 * @uint16: a #guint16 value
420 * @returns: a new uint16 #GVariant instance
422 * Creates a new uint16 #GVariant instance.
427 * g_variant_get_uint16:
428 * @value: a uint16 #GVariant instance
429 * @returns: a #guint16
431 * Returns the 16-bit unsigned integer value of @value.
433 * It is an error to call this function with a @value of any type
434 * other than %G_VARIANT_TYPE_UINT16.
438 NUMERIC_TYPE (UINT16, uint16, guint16)
441 * g_variant_new_int32:
442 * @int32: a #gint32 value
443 * @returns: a new int32 #GVariant instance
445 * Creates a new int32 #GVariant instance.
450 * g_variant_get_int32:
451 * @value: a int32 #GVariant instance
452 * @returns: a #gint32
454 * Returns the 32-bit signed integer value of @value.
456 * It is an error to call this function with a @value of any type
457 * other than %G_VARIANT_TYPE_INT32.
461 NUMERIC_TYPE (INT32, int32, gint32)
464 * g_variant_new_uint32:
465 * @uint32: a #guint32 value
466 * @returns: a new uint32 #GVariant instance
468 * Creates a new uint32 #GVariant instance.
473 * g_variant_get_uint32:
474 * @value: a uint32 #GVariant instance
475 * @returns: a #guint32
477 * Returns the 32-bit unsigned integer value of @value.
479 * It is an error to call this function with a @value of any type
480 * other than %G_VARIANT_TYPE_UINT32.
484 NUMERIC_TYPE (UINT32, uint32, guint32)
487 * g_variant_new_int64:
488 * @int64: a #gint64 value
489 * @returns: a new int64 #GVariant instance
491 * Creates a new int64 #GVariant instance.
496 * g_variant_get_int64:
497 * @value: a int64 #GVariant instance
498 * @returns: a #gint64
500 * Returns the 64-bit signed integer value of @value.
502 * It is an error to call this function with a @value of any type
503 * other than %G_VARIANT_TYPE_INT64.
507 NUMERIC_TYPE (INT64, int64, gint64)
510 * g_variant_new_uint64:
511 * @uint64: a #guint64 value
512 * @returns: a new uint64 #GVariant instance
514 * Creates a new uint64 #GVariant instance.
519 * g_variant_get_uint64:
520 * @value: a uint64 #GVariant instance
521 * @returns: a #guint64
523 * Returns the 64-bit unsigned integer value of @value.
525 * It is an error to call this function with a @value of any type
526 * other than %G_VARIANT_TYPE_UINT64.
530 NUMERIC_TYPE (UINT64, uint64, guint64)
533 * g_variant_new_handle:
534 * @handle: a #gint32 value
535 * @returns: a new handle #GVariant instance
537 * Creates a new handle #GVariant instance.
539 * By convention, handles are indexes into an array of file descriptors
540 * that are sent alongside a DBus message. If you're not interacting
541 * with DBus, you probably don't need them.
546 * g_variant_get_handle:
547 * @value: a handle #GVariant instance
548 * @returns: a #gint32
550 * Returns the 32-bit signed integer value of @value.
552 * It is an error to call this function with a @value of any type other
553 * than %G_VARIANT_TYPE_HANDLE.
555 * By convention, handles are indexes into an array of file descriptors
556 * that are sent alongside a DBus message. If you're not interacting
557 * with DBus, you probably don't need them.
561 NUMERIC_TYPE (HANDLE, handle, gint32)
564 * g_variant_new_double:
565 * @floating: a #gdouble floating point value
566 * @returns: a new double #GVariant instance
568 * Creates a new double #GVariant instance.
573 * g_variant_get_double:
574 * @value: a double #GVariant instance
575 * @returns: a #gdouble
577 * Returns the double precision floating point value of @value.
579 * It is an error to call this function with a @value of any type
580 * other than %G_VARIANT_TYPE_DOUBLE.
584 NUMERIC_TYPE (DOUBLE, double, gdouble)
587 * g_variant_get_type:
588 * @value: a #GVariant
589 * @returns: a #GVariantType
591 * Determines the type of @value.
593 * The return value is valid for the lifetime of @value and must not
599 g_variant_get_type (GVariant *value)
601 GVariantTypeInfo *type_info;
603 g_return_val_if_fail (value != NULL, NULL);
605 type_info = g_variant_get_type_info (value);
607 return (GVariantType *) g_variant_type_info_get_type_string (type_info);
611 * g_variant_get_type_string:
612 * @value: a #GVariant
613 * @returns: the type string for the type of @value
615 * Returns the type string of @value. Unlike the result of calling
616 * g_variant_type_peek_string(), this string is nul-terminated. This
617 * string belongs to #GVariant and must not be freed.
622 g_variant_get_type_string (GVariant *value)
624 GVariantTypeInfo *type_info;
626 g_return_val_if_fail (value != NULL, NULL);
628 type_info = g_variant_get_type_info (value);
630 return g_variant_type_info_get_type_string (type_info);
634 * g_variant_is_of_type:
635 * @value: a #GVariant instance
636 * @type: a #GVariantType
637 * @returns: %TRUE if the type of @value matches @type
639 * Checks if a value has a type matching the provided type.
644 g_variant_is_of_type (GVariant *value,
645 const GVariantType *type)
647 return g_variant_type_is_subtype_of (g_variant_get_type (value), type);
651 * g_variant_is_container:
652 * @value: a #GVariant instance
653 * @returns: %TRUE if @value is a container
655 * Checks if @value is a container.
658 g_variant_is_container (GVariant *value)
660 return g_variant_type_is_container (g_variant_get_type (value));
664 * g_variant_new_maybe:
665 * @child_type: the #GVariantType of the child
666 * @child: the child value, or %NULL
667 * @returns: a new #GVariant maybe instance
669 * Depending on if @value is %NULL, either wraps @value inside of a
670 * maybe container or creates a Nothing instance for the given @type.
672 * At least one of @type and @value must be non-%NULL. If @type is
673 * non-%NULL then it must be a definite type. If they are both
674 * non-%NULL then @type must be the type of @value.
679 g_variant_new_maybe (const GVariantType *child_type,
682 GVariantType *maybe_type;
685 g_return_val_if_fail (child_type == NULL || g_variant_type_is_definite
687 g_return_val_if_fail (child_type != NULL || child != NULL, NULL);
688 g_return_val_if_fail (child_type == NULL || child == NULL ||
689 g_variant_is_of_type (child, child_type),
692 if (child_type == NULL)
693 child_type = g_variant_get_type (child);
695 maybe_type = g_variant_type_new_maybe (child_type);
702 children = g_new (GVariant *, 1);
703 children[0] = g_variant_ref_sink (child);
704 trusted = g_variant_is_trusted (children[0]);
706 value = g_variant_new_from_children (maybe_type, children, 1, trusted);
709 value = g_variant_new_from_children (maybe_type, NULL, 0, TRUE);
711 g_variant_type_free (maybe_type);
717 * g_variant_get_maybe:
718 * @value: a maybe-typed value
719 * @returns: the contents of @value, or %NULL
721 * Given a maybe-typed #GVariant instance, extract its value. If the
722 * value is Nothing, then this function returns %NULL.
727 g_variant_get_maybe (GVariant *value)
729 TYPE_CHECK (value, G_VARIANT_TYPE_MAYBE, NULL);
731 if (g_variant_n_children (value))
732 return g_variant_get_child_value (value, 0);
738 * g_variant_new_variant:
739 * @value: a #GVariance instance
740 * @returns: a new variant #GVariant instance
742 * Boxes @value. The result is a #GVariant instance representing a
743 * variant containing the original value.
748 g_variant_new_variant (GVariant *value)
750 g_return_val_if_fail (value != NULL, NULL);
752 return g_variant_new_from_children (G_VARIANT_TYPE_VARIANT,
753 g_memdup (&value, sizeof value),
754 1, g_variant_is_trusted (value));
758 * g_variant_get_variant:
759 * @value: a variant #GVariance instance
760 * @returns: the item contained in the variant
762 * Unboxes @value. The result is the #GVariant instance that was
763 * contained in @value.
768 g_variant_get_variant (GVariant *value)
770 TYPE_CHECK (value, G_VARIANT_TYPE_VARIANT, NULL);
772 return g_variant_get_child_value (value, 0);
776 * g_variant_new_string:
777 * @string: a normal C nul-terminated string
778 * @returns: a new string #GVariant instance
780 * Creates a string #GVariant with the contents of @string.
785 g_variant_new_string (const gchar *string)
787 g_return_val_if_fail (string != NULL, NULL);
789 return g_variant_new_from_trusted (G_VARIANT_TYPE_STRING,
790 string, strlen (string) + 1);
794 * g_variant_new_object_path:
795 * @object_path: a normal C nul-terminated string
796 * @returns: a new object path #GVariant instance
798 * Creates a DBus object path #GVariant with the contents of @string.
799 * @string must be a valid DBus object path. Use
800 * g_variant_is_object_path() if you're not sure.
805 g_variant_new_object_path (const gchar *object_path)
807 g_return_val_if_fail (g_variant_is_object_path (object_path), NULL);
809 return g_variant_new_from_trusted (G_VARIANT_TYPE_OBJECT_PATH,
810 object_path, strlen (object_path) + 1);
814 * g_variant_is_object_path:
815 * @string: a normal C nul-terminated string
816 * @returns: %TRUE if @string is a DBus object path
818 * Determines if a given string is a valid DBus object path. You
819 * should ensure that a string is a valid DBus object path before
820 * passing it to g_variant_new_object_path().
822 * A valid object path starts with '/' followed by zero or more
823 * sequences of characters separated by '/' characters. Each sequence
824 * must contain only the characters "[A-Z][a-z][0-9]_". No sequence
825 * (including the one following the final '/' character) may be empty.
830 g_variant_is_object_path (const gchar *string)
832 g_return_val_if_fail (string != NULL, FALSE);
834 return g_variant_serialiser_is_object_path (string, strlen (string) + 1);
839 * g_variant_new_signature:
840 * @signature: a normal C nul-terminated string
841 * @returns: a new signature #GVariant instance
843 * Creates a DBus type signature #GVariant with the contents of
844 * @string. @string must be a valid DBus type signature. Use
845 * g_variant_is_signature() if you're not sure.
850 g_variant_new_signature (const gchar *signature)
852 g_return_val_if_fail (g_variant_is_signature (signature), NULL);
854 return g_variant_new_from_trusted (G_VARIANT_TYPE_SIGNATURE,
855 signature, strlen (signature) + 1);
859 * g_variant_is_signature:
860 * @string: a normal C nul-terminated string
861 * @returns: %TRUE if @string is a DBus type signature
863 * Determines if a given string is a valid DBus type signature. You
864 * should ensure that a string is a valid DBus object path before
865 * passing it to g_variant_new_signature().
867 * DBus type signatures consist of zero or more definite #GVariantType
868 * strings in sequence.
873 g_variant_is_signature (const gchar *string)
875 g_return_val_if_fail (string != NULL, FALSE);
877 return g_variant_serialiser_is_signature (string, strlen (string) + 1);
881 * g_variant_get_string:
882 * @value: a string #GVariant instance
883 * @length: a pointer to a #gsize, to store the length
884 * @returns: the constant string
886 * Returns the string value of a #GVariant instance with a string
887 * type. This includes the types %G_VARIANT_TYPE_STRING,
888 * %G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE.
890 * If @length is non-%NULL then the length of the string (in bytes) is
891 * returned there. For trusted values, this information is already
892 * known. For untrusted values, a strlen() will be performed.
894 * It is an error to call this function with a @value of any type
895 * other than those three.
897 * The return value remains valid as long as @value exists.
902 g_variant_get_string (GVariant *value,
905 g_return_val_if_fail (value != NULL, NULL);
906 g_return_val_if_fail (
907 g_variant_is_of_type (value, G_VARIANT_TYPE_STRING) ||
908 g_variant_is_of_type (value, G_VARIANT_TYPE_OBJECT_PATH) ||
909 g_variant_is_of_type (value, G_VARIANT_TYPE_SIGNATURE), NULL);
910 gconstpointer data = g_variant_get_data (value);
911 gsize size = g_variant_get_size (value);
913 if (!g_variant_is_trusted (value))
915 switch (g_variant_classify (value))
917 case G_VARIANT_CLASS_STRING:
918 if (g_variant_serialiser_is_string (data, size))
925 case G_VARIANT_CLASS_OBJECT_PATH:
926 if (g_variant_serialiser_is_object_path (data, size))
933 case G_VARIANT_CLASS_SIGNATURE:
934 if (g_variant_serialiser_is_signature (data, size))
942 g_assert_not_reached ();
953 * g_variant_dup_string:
954 * @value: a string #GVariant instance
955 * @length: a pointer to a #gsize, to store the length
956 * @returns: a newly allocated string
958 * Similar to g_variant_get_string() except that instead of returning
959 * a constant string, the string is duplicated.
961 * The return value must be freed using g_free().
966 g_variant_dup_string (GVariant *value,
969 return g_strdup (g_variant_get_string (value, length));
973 * g_variant_new_strv:
974 * @strv: an array of strings
975 * @length: the length of @strv, or -1
976 * @returns: a new floating #GVariant instance
978 * Constructs an array of strings #GVariant from the given array of
981 * If @length is not -1 then it gives the maximum length of @strv. In
982 * any case, a %NULL pointer in @strv is taken as a terminator.
987 g_variant_new_strv (const gchar * const *strv,
993 g_return_val_if_fail (length == 0 || strv != NULL, NULL);
996 for (length = 0; strv[length]; length++);
998 strings = g_new (GVariant *, length);
999 for (i = 0; i < length; i++)
1000 strings[i] = g_variant_new_string (strv[i]);
1002 return g_variant_new_from_children (G_VARIANT_TYPE ("as"),
1003 strings, length, TRUE);
1007 * g_variant_get_strv:
1008 * @value: an array of strings #GVariant
1009 * @length: the length of the result, or %NULL
1010 * @returns: an array of constant strings
1012 * Gets the contents of an array of strings #GVariant. This call
1013 * makes a shallow copy; the return result should be released with
1014 * g_free(), but the individual strings must not be modified.
1016 * If @length is non-%NULL then the number of elements in the result
1017 * is stored there. In any case, the resulting array will be
1020 * For an empty array, @length will be set to 0 and a pointer to a
1021 * %NULL pointer will be returned.
1026 g_variant_get_strv (GVariant *value,
1033 TYPE_CHECK (value, G_VARIANT_TYPE ("as"), NULL);
1035 g_variant_get_data (value);
1036 n = g_variant_n_children (value);
1037 strv = g_new (const gchar *, n + 1);
1039 for (i = 0; i < n; i++)
1043 string = g_variant_get_child_value (value, i);
1044 strv[i] = g_variant_get_string (string, NULL);
1045 g_variant_unref (string);
1056 * g_variant_dup_strv:
1057 * @value: an array of strings #GVariant
1058 * @length: the length of the result, or %NULL
1059 * @returns: an array of constant strings
1061 * Gets the contents of an array of strings #GVariant. This call
1062 * makes a deep copy; the return result should be released with
1065 * If @length is non-%NULL then the number of elements in the result
1066 * is stored there. In any case, the resulting array will be
1069 * For an empty array, @length will be set to 0 and a pointer to a
1070 * %NULL pointer will be returned.
1075 g_variant_dup_strv (GVariant *value,
1082 TYPE_CHECK (value, G_VARIANT_TYPE ("as"), NULL);
1084 n = g_variant_n_children (value);
1085 strv = g_new (gchar *, n + 1);
1087 for (i = 0; i < n; i++)
1091 string = g_variant_get_child_value (value, i);
1092 strv[i] = g_variant_dup_string (string, NULL);
1093 g_variant_unref (string);
1104 * g_variant_new_array:
1105 * @child_type: the element type of the new array
1106 * @children: an array of #GVariant pointers, the children
1107 * @n_children: the length of @children
1108 * @returns: a new #GVariant array
1110 * Creates a new #GVariant array from @children.
1112 * @child_type must be non-%NULL if @n_children is zero. Otherwise, the
1113 * child type is determined by inspecting the first element of the
1114 * @children array. If @child_type is non-%NULL then it must be a
1117 * The items of the array are taken from the @children array. No entry
1118 * in the @children array may be %NULL.
1120 * All items in the array must have the same type, which must be the
1121 * same as @child_type, if given.
1126 g_variant_new_array (const GVariantType *child_type,
1127 GVariant * const *children,
1130 GVariantType *array_type;
1131 GVariant **my_children;
1136 g_return_val_if_fail (n_children > 0 || child_type != NULL, NULL);
1137 g_return_val_if_fail (n_children == 0 || children != NULL, NULL);
1138 g_return_val_if_fail (child_type == NULL ||
1139 g_variant_type_is_definite (child_type), NULL);
1141 my_children = g_new (GVariant *, n_children);
1144 if (child_type == NULL)
1145 child_type = g_variant_get_type (children[0]);
1146 array_type = g_variant_type_new_array (child_type);
1148 for (i = 0; i < n_children; i++)
1150 TYPE_CHECK (children[i], child_type, NULL);
1151 my_children[i] = g_variant_ref_sink (children[i]);
1152 trusted &= g_variant_is_trusted (children[i]);
1155 value = g_variant_new_from_children (array_type, my_children,
1156 n_children, trusted);
1157 g_variant_type_free (array_type);
1163 * g_variant_new_tuple:
1164 * @children: the items to make the tuple out of
1165 * @n_children: the length of @children
1166 * @returns: a new #GVariant tuple
1168 * Creates a new tuple #GVariant out of the items in @children. The
1169 * type is determined from the types of @children. No entry in the
1170 * @children array may be %NULL.
1172 * If @n_children is 0 then the unit tuple is constructed.
1177 g_variant_new_tuple (GVariant * const *children,
1180 const GVariantType **types;
1181 GVariantType *tuple_type;
1182 GVariant **my_children;
1187 g_return_val_if_fail (n_children == 0 || children != NULL, NULL);
1189 types = g_new (const GVariantType *, n_children);
1190 my_children = g_new (GVariant *, n_children);
1193 for (i = 0; i < n_children; i++)
1195 types[i] = g_variant_get_type (children[i]);
1196 my_children[i] = g_variant_ref_sink (children[i]);
1197 trusted &= g_variant_is_trusted (children[i]);
1200 tuple_type = g_variant_type_new_tuple (types, n_children);
1201 value = g_variant_new_from_children (tuple_type, my_children,
1202 n_children, trusted);
1203 g_variant_type_free (tuple_type);
1210 * g_variant_new_dict_entry:
1211 * @key: a basic #GVariant, the key
1212 * @value: a #GVariant, the value
1213 * @returns: a new dictionary entry #GVariant
1215 * Creates a new dictionary entry #GVariant. @key and @value must be
1218 * @key must be a value of a basic type (ie: not a container).
1223 g_variant_new_dict_entry (GVariant *key,
1226 GVariantType *dict_type;
1227 GVariant **children;
1230 g_return_val_if_fail (key != NULL && value != NULL, NULL);
1231 g_return_val_if_fail (!g_variant_is_container (key), NULL);
1233 children = g_new (GVariant *, 2);
1234 children[0] = g_variant_ref_sink (key);
1235 children[1] = g_variant_ref_sink (value);
1236 trusted = g_variant_is_trusted (key) && g_variant_is_trusted (value);
1238 dict_type = g_variant_type_new_dict_entry (g_variant_get_type (key),
1239 g_variant_get_type (value));
1240 value = g_variant_new_from_children (dict_type, children, 2, trusted);
1241 g_variant_type_free (dict_type);
1247 * g_variant_get_fixed_array:
1248 * @value: a #GVariant array with fixed-sized elements
1249 * @n_elements: a pointer to the location to store the number of items
1250 * @element_size: the size of each element
1251 * @returns: a pointer to the fixed array
1253 * Provides access to the serialised data for an array of fixed-sized
1256 * @value must be an array with fixed-sized elements. Numeric types are
1257 * fixed-size as are tuples containing only other fixed-sized types.
1259 * @element_size must be the size of a single element in the array. For
1260 * example, if calling this function for an array of 32 bit integers,
1261 * you might say <code>sizeof (gint32)</code>. This value isn't used
1262 * except for the purpose of a double-check that the form of the
1263 * seralised data matches the caller's expectation.
1265 * @n_elements, which must be non-%NULL is set equal to the number of
1266 * items in the array.
1271 g_variant_get_fixed_array (GVariant *value,
1275 GVariantTypeInfo *array_info;
1276 gsize array_element_size;
1280 TYPE_CHECK (value, G_VARIANT_TYPE_ARRAY, NULL);
1282 g_return_val_if_fail (n_elements != NULL, NULL);
1283 g_return_val_if_fail (element_size > 0, NULL);
1285 array_info = g_variant_get_type_info (value);
1286 g_variant_type_info_query_element (array_info, NULL, &array_element_size);
1288 g_return_val_if_fail (array_element_size, NULL);
1290 if G_UNLIKELY (array_element_size != element_size)
1292 if (array_element_size)
1293 g_critical ("g_variant_get_fixed_array: assertion "
1294 "`g_variant_array_has_fixed_size (value, element_size)' "
1295 "failed: array size %"G_GSIZE_FORMAT" does not match "
1296 "given element_size %"G_GSIZE_FORMAT".",
1297 array_element_size, element_size);
1299 g_critical ("g_variant_get_fixed_array: assertion "
1300 "`g_variant_array_has_fixed_size (value, element_size)' "
1301 "failed: array does not have fixed size.");
1304 data = g_variant_get_data (value);
1305 size = g_variant_get_size (value);
1307 if (size % element_size)
1310 *n_elements = size / element_size;
1319 * g_variant_classify:
1320 * @value: a #GVariant
1321 * @returns: the #GVariantClass of @value
1323 * Classifies @value according to its top-level type.
1329 * @G_VARIANT_CLASS_BOOLEAN: The #GVariant is a boolean.
1330 * @G_VARIANT_CLASS_BYTE: The #GVariant is a byte.
1331 * @G_VARIANT_CLASS_INT16: The #GVariant is a signed 16 bit integer.
1332 * @G_VARIANT_CLASS_UINT16: The #GVariant is an unsigned 16 bit integer.
1333 * @G_VARIANT_CLASS_INT32: The #GVariant is a signed 32 bit integer.
1334 * @G_VARIANT_CLASS_UINT32: The #GVariant is an unsigned 32 bit integer.
1335 * @G_VARIANT_CLASS_INT64: The #GVariant is a signed 64 bit integer.
1336 * @G_VARIANT_CLASS_UINT64: The #GVariant is an unsigned 64 bit integer.
1337 * @G_VARIANT_CLASS_HANDLE: The #GVariant is a file handle index.
1338 * @G_VARIANT_CLASS_DOUBLE: The #GVariant is a double precision floating
1340 * @G_VARIANT_CLASS_STRING: The #GVariant is a normal string.
1341 * @G_VARIANT_CLASS_OBJECT_PATH: The #GVariant is a DBus object path
1343 * @G_VARIANT_CLASS_SIGNATURE: The #GVariant is a DBus signature string.
1344 * @G_VARIANT_CLASS_VARIANT: The #GVariant is a variant.
1345 * @G_VARIANT_CLASS_MAYBE: The #GVariant is a maybe-typed value.
1346 * @G_VARIANT_CLASS_ARRAY: The #GVariant is an array.
1347 * @G_VARIANT_CLASS_TUPLE: The #GVariant is a tuple.
1348 * @G_VARIANT_CLASS_DICT_ENTRY: The #GVariant is a dictionary entry.
1350 * The range of possible top-level types of #GVariant instances.
1355 g_variant_classify (GVariant *value)
1357 g_return_val_if_fail (value != NULL, 0);
1359 return *g_variant_get_type_string (value);
1363 * g_variant_print_string:
1364 * @value: a #GVariant
1365 * @string: a #GString, or %NULL
1366 * @type_annotate: %TRUE if type information should be included in
1368 * @returns: a #GString containing the string
1370 * Behaves as g_variant_print(), but operates on a #GString.
1372 * If @string is non-%NULL then it is appended to and returned. Else,
1373 * a new empty #GString is allocated and it is returned.
1378 g_variant_print_string (GVariant *value,
1380 gboolean type_annotate)
1382 if G_UNLIKELY (string == NULL)
1383 string = g_string_new (NULL);
1385 switch (g_variant_classify (value))
1387 case G_VARIANT_CLASS_MAYBE:
1389 g_string_append_printf (string, "@%s ",
1390 g_variant_get_type_string (value));
1392 if (g_variant_n_children (value))
1394 gchar *printed_child;
1399 * Consider the case of the type "mmi". In this case we could
1400 * write "Just Just 4", but "4" alone is totally unambiguous,
1401 * so we try to drop "Just" where possible.
1403 * We have to be careful not to always drop "Just", though,
1404 * since "Nothing" needs to be distinguishable from "Just
1405 * Nothing". The case where we need to ensure we keep the
1406 * "Just" is actually exactly the case where we have a nested
1409 * Instead of searching for that nested Nothing, we just print
1410 * the contained value into a separate string and see if we
1411 * end up with "Nothing" at the end of it. If so, we need to
1412 * add "Just" at our level.
1414 element = g_variant_get_child_value (value, 0);
1415 printed_child = g_variant_print (element, FALSE);
1416 g_variant_unref (element);
1418 if (g_str_has_suffix (printed_child, "Nothing"))
1419 g_string_append (string, "Just ");
1420 g_string_append (string, printed_child);
1421 g_free (printed_child);
1424 g_string_append (string, "Nothing");
1428 case G_VARIANT_CLASS_ARRAY:
1429 /* it's an array so the first character of the type string is 'a'
1431 * if the first two characters are 'a{' then it's an array of
1432 * dictionary entries (ie: a dictionary) so we print that
1435 if (g_variant_get_type_string (value)[1] == '{')
1438 const gchar *comma = "";
1441 if ((n = g_variant_n_children (value)) == 0)
1444 g_string_append_printf (string, "@%s ",
1445 g_variant_get_type_string (value));
1446 g_string_append (string, "{}");
1450 g_string_append_c (string, '{');
1451 for (i = 0; i < n; i++)
1453 GVariant *entry, *key, *val;
1455 g_string_append (string, comma);
1458 entry = g_variant_get_child_value (value, i);
1459 key = g_variant_get_child_value (entry, 0);
1460 val = g_variant_get_child_value (entry, 1);
1461 g_variant_unref (entry);
1463 g_variant_print_string (key, string, type_annotate);
1464 g_variant_unref (key);
1465 g_string_append (string, ": ");
1466 g_variant_print_string (val, string, type_annotate);
1467 g_variant_unref (val);
1468 type_annotate = FALSE;
1470 g_string_append_c (string, '}');
1473 /* normal (non-dictionary) array */
1475 const gchar *comma = "";
1478 if ((n = g_variant_n_children (value)) == 0)
1481 g_string_append_printf (string, "@%s ",
1482 g_variant_get_type_string (value));
1483 g_string_append (string, "[]");
1487 g_string_append_c (string, '[');
1488 for (i = 0; i < n; i++)
1492 g_string_append (string, comma);
1495 element = g_variant_get_child_value (value, i);
1497 g_variant_print_string (element, string, type_annotate);
1498 g_variant_unref (element);
1499 type_annotate = FALSE;
1501 g_string_append_c (string, ']');
1506 case G_VARIANT_CLASS_TUPLE:
1510 n = g_variant_n_children (value);
1512 g_string_append_c (string, '(');
1513 for (i = 0; i < n; i++)
1517 element = g_variant_get_child_value (value, i);
1518 g_variant_print_string (element, string, type_annotate);
1519 g_string_append (string, ", ");
1522 /* for >1 item: remove final ", "
1523 * for 1 item: remove final " ", but leave the ","
1524 * for 0 items: there is only "(", so remove nothing
1526 g_string_truncate (string, string->len - (n > 0) - (n > 1));
1527 g_string_append_c (string, ')');
1531 case G_VARIANT_CLASS_DICT_ENTRY:
1535 g_string_append_c (string, '{');
1537 element = g_variant_get_child_value (value, 0);
1538 g_variant_print_string (element, string, type_annotate);
1539 g_variant_unref (element);
1541 g_string_append (string, ", ");
1543 element = g_variant_get_child_value (value, 1);
1544 g_variant_print_string (element, string, type_annotate);
1545 g_variant_unref (element);
1547 g_string_append_c (string, '}');
1551 case G_VARIANT_CLASS_VARIANT:
1553 GVariant *child = g_variant_get_variant (value);
1555 /* Always annotate types in nested variants, because they are
1556 * (by nature) of variable type.
1558 g_string_append_c (string, '<');
1559 g_variant_print_string (child, string, TRUE);
1560 g_string_append_c (string, '>');
1562 g_variant_unref (child);
1566 case G_VARIANT_CLASS_BOOLEAN:
1567 if (g_variant_get_boolean (value))
1568 g_string_append (string, "true");
1570 g_string_append (string, "false");
1573 case G_VARIANT_CLASS_STRING:
1575 const gchar *str = g_variant_get_string (value, NULL);
1576 gchar *escaped = g_strescape (str, NULL);
1578 g_string_append_printf (string, "\"%s\"", escaped);
1584 case G_VARIANT_CLASS_BYTE:
1586 g_string_append (string, "byte ");
1587 g_string_append_printf (string, "0x%02x",
1588 g_variant_get_byte (value));
1591 case G_VARIANT_CLASS_INT16:
1593 g_string_append (string, "int16 ");
1594 g_string_append_printf (string, "%"G_GINT16_FORMAT,
1595 g_variant_get_int16 (value));
1598 case G_VARIANT_CLASS_UINT16:
1600 g_string_append (string, "uint16 ");
1601 g_string_append_printf (string, "%"G_GUINT16_FORMAT,
1602 g_variant_get_uint16 (value));
1605 case G_VARIANT_CLASS_INT32:
1606 /* Never annotate this type because it is the default for numbers
1607 * (and this is a *pretty* printer)
1609 g_string_append_printf (string, "%"G_GINT32_FORMAT,
1610 g_variant_get_int32 (value));
1613 case G_VARIANT_CLASS_HANDLE:
1615 g_string_append (string, "handle ");
1616 g_string_append_printf (string, "%"G_GINT32_FORMAT,
1617 g_variant_get_handle (value));
1620 case G_VARIANT_CLASS_UINT32:
1622 g_string_append (string, "uint32 ");
1623 g_string_append_printf (string, "%"G_GUINT32_FORMAT,
1624 g_variant_get_uint32 (value));
1627 case G_VARIANT_CLASS_INT64:
1629 g_string_append (string, "int64 ");
1630 g_string_append_printf (string, "%"G_GINT64_FORMAT,
1631 g_variant_get_int64 (value));
1634 case G_VARIANT_CLASS_UINT64:
1636 g_string_append (string, "uint64 ");
1637 g_string_append_printf (string, "%"G_GUINT64_FORMAT,
1638 g_variant_get_uint64 (value));
1641 case G_VARIANT_CLASS_DOUBLE:
1646 g_ascii_dtostr (buffer, sizeof buffer, g_variant_get_double (value));
1648 for (i = 0; buffer[i]; i++)
1649 if (buffer[i] == '.' || buffer[i] == 'e' ||
1650 buffer[i] == 'n' || buffer[i] == 'N')
1653 /* if there is no '.' or 'e' in the float then add one */
1654 if (buffer[i] == '\0')
1661 g_string_append (string, buffer);
1665 case G_VARIANT_CLASS_OBJECT_PATH:
1667 g_string_append (string, "objectpath ");
1668 g_string_append_printf (string, "\"%s\"",
1669 g_variant_get_string (value, NULL));
1672 case G_VARIANT_CLASS_SIGNATURE:
1674 g_string_append (string, "signature ");
1675 g_string_append_printf (string, "\"%s\"",
1676 g_variant_get_string (value, NULL));
1680 g_assert_not_reached ();
1688 * @value: a #GVariant
1689 * @type_annotate: %TRUE if type information should be included in
1691 * @returns: a newly-allocated string holding the result.
1693 * Pretty-prints @value in the format understood by g_variant_parse().
1695 * If @type_annotate is %TRUE, then type information is included in
1699 g_variant_print (GVariant *value,
1700 gboolean type_annotate)
1702 return g_string_free (g_variant_print_string (value, NULL, type_annotate),
1708 * @value: a basic #GVariant value as a #gconstpointer
1709 * @returns: a hash value corresponding to @value
1711 * Generates a hash value for a #GVariant instance.
1713 * The output of this function is guaranteed to be the same for a given
1714 * value only per-process. It may change between different processor
1715 * architectures or even different versions of GLib. Do not use this
1716 * function as a basis for building protocols or file formats.
1718 * The type of @value is #gconstpointer only to allow use of this
1719 * function with #GHashTable. @value must be a #GVariant.
1724 g_variant_hash (gconstpointer value_)
1726 GVariant *value = (GVariant *) value_;
1728 switch (g_variant_classify (value))
1730 case G_VARIANT_CLASS_STRING:
1731 case G_VARIANT_CLASS_OBJECT_PATH:
1732 case G_VARIANT_CLASS_SIGNATURE:
1733 return g_str_hash (g_variant_get_string (value, NULL));
1735 case G_VARIANT_CLASS_BOOLEAN:
1736 /* this is a very odd thing to hash... */
1737 return g_variant_get_boolean (value);
1739 case G_VARIANT_CLASS_BYTE:
1740 return g_variant_get_byte (value);
1742 case G_VARIANT_CLASS_INT16:
1743 case G_VARIANT_CLASS_UINT16:
1747 ptr = g_variant_get_data (value);
1755 case G_VARIANT_CLASS_INT32:
1756 case G_VARIANT_CLASS_UINT32:
1757 case G_VARIANT_CLASS_HANDLE:
1761 ptr = g_variant_get_data (value);
1769 case G_VARIANT_CLASS_INT64:
1770 case G_VARIANT_CLASS_UINT64:
1771 case G_VARIANT_CLASS_DOUBLE:
1772 /* need a separate case for these guys because otherwise
1773 * performance could be quite bad on big endian systems
1778 ptr = g_variant_get_data (value);
1781 return ptr[0] + ptr[1];
1787 g_return_val_if_fail (!g_variant_is_container (value), 0);
1788 g_assert_not_reached ();
1794 * @one: a #GVariant instance
1795 * @two: a #GVariant instance
1796 * @returns: %TRUE if @one and @two are equal
1798 * Checks if @one and @two have the same type and value.
1800 * The types of @one and @two are #gconstpointer only to allow use of
1801 * this function with #GHashTable. They must each be a #GVariant.
1806 g_variant_equal (gconstpointer one,
1811 g_return_val_if_fail (one != NULL && two != NULL, FALSE);
1813 if (g_variant_get_type_info ((GVariant *) one) !=
1814 g_variant_get_type_info ((GVariant *) two))
1817 /* if both values are trusted to be in their canonical serialised form
1818 * then a simple memcmp() of their serialised data will answer the
1821 * if not, then this might generate a false negative (since it is
1822 * possible for two different byte sequences to represent the same
1823 * value). for now we solve this by pretty-printing both values and
1824 * comparing the result.
1826 if (g_variant_is_trusted ((GVariant *) one) &&
1827 g_variant_is_trusted ((GVariant *) two))
1829 gconstpointer data_one, data_two;
1830 gsize size_one, size_two;
1832 size_one = g_variant_get_size ((GVariant *) one);
1833 size_two = g_variant_get_size ((GVariant *) two);
1835 if (size_one != size_two)
1838 data_one = g_variant_get_data ((GVariant *) one);
1839 data_two = g_variant_get_data ((GVariant *) two);
1841 equal = memcmp (data_one, data_two, size_one) == 0;
1845 gchar *strone, *strtwo;
1847 strone = g_variant_print ((GVariant *) one, FALSE);
1848 strtwo = g_variant_print ((GVariant *) two, FALSE);
1849 equal = strcmp (strone, strtwo) == 0;
1857 #define __G_VARIANT_C__
1858 #include "galiasdef.c"