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 License, 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.
21 #include <glib/gvariant-core.h>
23 #include <glib/gvariant-serialiser.h>
24 #include <glib/gtestutils.h>
25 #include <glib/gbitlock.h>
26 #include <glib/gatomic.h>
27 #include <glib/gbuffer.h>
28 #include <glib/gslice.h>
29 #include <glib/gmem.h>
35 * This file includes the structure definition for GVariant and a small
36 * set of functions that are allowed to access the structure directly.
38 * This minimises the amount of code that can possibly touch a GVariant
39 * structure directly to a few simple fundamental operations. These few
40 * operations are written to be completely threadsafe with respect to
41 * all possible outside access. This means that we only need to be
42 * concerned about thread safety issues in this one small file.
44 * Most GVariant API functions are in gvariant.c.
50 * #GVariant is an opaque data structure and can only be accessed
51 * using the following functions.
56 /* see below for field member documentation */
58 GVariantTypeInfo
*type_info
;
82 * There are two primary forms of GVariant instances: "serialised form"
85 * "serialised form": A serialised GVariant instance stores its value in
86 * the GVariant serialisation format. All
87 * basic-typed instances (ie: non-containers) are in
88 * serialised format, as are some containers.
90 * "tree form": Some containers are in "tree form". In this case,
91 * instead of containing the serialised data for the
92 * container, the instance contains an array of pointers to
93 * the child values of the container (thus forming a tree).
95 * It is possible for an instance to transition from tree form to
96 * serialised form. This happens, implicitly, if the serialised data is
97 * requested (eg: via g_variant_get_data()). Serialised form instances
98 * never transition into tree form.
101 * The fields of the structure are documented here:
103 * type_info: this is a reference to a GVariantTypeInfo describing the
104 * type of the instance. When the instance is freed, this
105 * reference must be released with g_variant_type_info_unref().
107 * The type_info field never changes during the life of the
108 * instance, so it can be accessed without a lock.
110 * size: this is the size of the serialised form for the instance, if it
111 * is known. If the instance is in serialised form then it is, by
112 * definition, known. If the instance is in tree form then it may
113 * be unknown (in which case it is -1). It is possible for the
114 * size to be known when in tree form if, for example, the user
115 * has called g_variant_get_size() without calling
116 * g_variant_get_data(). Additionally, even when the user calls
117 * g_variant_get_data() the size of the data must first be
118 * determined so that a large enough buffer can be allocated for
121 * Once the size is known, it can never become unknown again.
122 * g_variant_ensure_size() is used to ensure that the size is in
123 * the known state -- it calculates the size if needed. After
124 * that, the size field can be accessed without a lock.
126 * contents: a union containing either the information associated with
127 * holding a value in serialised form or holding a value in
130 * .serialised: Only valid when the instance is in serialised form.
132 * Since an instance can never transition away from
133 * serialised form, once these fields are set, they will
134 * never be changed. It is therefore valid to access
135 * them without holding a lock.
137 * .buffer: the #GBuffer that contains the memory pointed to by
138 * .data, or %NULL if .data is %NULL. In the event that
139 * the instance was deserialised from another instance,
140 * then the buffer will be shared by both of them. When
141 * the instance is freed, this reference must be released
142 * with g_buffer_unref().
144 * .data: the serialised data (of size 'size') of the instance.
145 * This pointer should not be freed or modified in any way.
146 * #GBuffer is responsible for memory management.
148 * This pointer may be %NULL in two cases:
150 * - if the serialised size of the instance is 0
152 * - if the instance is of a fixed-sized type and was
153 * deserialised out of a corrupted container such that
154 * the container contains too few bytes to point to the
155 * entire proper fixed-size of this instance. In this
156 * case, 'size' will still be equal to the proper fixed
157 * size, but this pointer will be %NULL. This is exactly
158 * the reason that g_variant_get_data() sometimes returns
159 * %NULL. For all other calls, the effect should be as
160 * if .data pointed to the appropriate number of nul
163 * .tree: Only valid when the instance is in tree form.
165 * Note that accesses from other threads could result in
166 * conversion of the instance from tree form to serialised form
167 * at any time. For this reason, the instance lock must always
168 * be held while performing any operations on 'contents.tree'.
170 * .children: the array of the child instances of this instance.
171 * When the instance is freed (or converted to serialised
172 * form) then each child must have g_variant_unref()
173 * called on it and the array must be freed using
176 * .n_children: the number of items in the .children array.
178 * state: a bitfield describing the state of the instance. It is a
179 * bitwise-or of the following STATE_* constants:
181 * STATE_LOCKED: the instance lock is held. This is the bit used by
184 * STATE_SERIALISED: the instance is in serialised form. If this
185 * flag is not set then the instance is in tree
188 * STATE_TRUSTED: for serialised form instances, this means that the
189 * serialised data is known to be in normal form (ie:
192 * For tree form instances, this means that all of the
193 * child instances in the contents.tree.children array
194 * are trusted. This means that if the container is
195 * serialised then the resulting data will be in
198 * If this flag is unset it does not imply that the
199 * data is corrupted. It merely means that we're not
200 * sure that it's valid. See g_variant_is_trusted().
202 * STATE_FLOATING: if this flag is set then the object has a floating
203 * reference. See g_variant_ref_sink().
205 * ref_count: the reference count of the instance
207 #define STATE_LOCKED 1
208 #define STATE_SERIALISED 2
209 #define STATE_TRUSTED 4
210 #define STATE_FLOATING 8
215 * @value: a #GVariant
217 * Locks @value for performing sensitive operations.
220 g_variant_lock (GVariant
*value
)
222 g_bit_lock (&value
->state
, 0);
227 * @value: a #GVariant
229 * Unlocks @value after performing sensitive operations.
232 g_variant_unlock (GVariant
*value
)
234 g_bit_unlock (&value
->state
, 0);
238 * g_variant_release_children:
239 * @value: a #GVariant
241 * Releases the reference held on each child in the 'children' array of
242 * @value and frees the array itself. @value must be in tree form.
244 * This is done when freeing a tree-form instance or converting it to
247 * The current thread must hold the lock on @value.
250 g_variant_release_children (GVariant
*value
)
254 g_assert (value
->state
& STATE_LOCKED
);
255 g_assert (~value
->state
& STATE_SERIALISED
);
257 for (i
= 0; i
< value
->contents
.tree
.n_children
; i
++)
258 g_variant_unref (value
->contents
.tree
.children
[i
]);
260 g_free (value
->contents
.tree
.children
);
263 /* This begins the main body of the recursive serialiser.
265 * There are 3 functions here that work as a team with the serialiser to
266 * get things done. g_variant_store() has a trivial role, but as a
267 * public API function, it has its definition elsewhere.
269 * Note that "serialisation" of an instance does not mean that the
270 * instance is converted to serialised form -- it means that the
271 * serialised form of an instance is written to an external buffer.
272 * g_variant_ensure_serialised() (which is not part of this set of
273 * functions) is the function that is responsible for converting an
274 * instance to serialised form.
276 * We are only concerned here with container types since non-container
277 * instances are always in serialised form. For these instances,
278 * storing their serialised form merely involves a memcpy().
280 * Serialisation is a two-step process. First, the size of the
281 * serialised data must be calculated so that an appropriately-sized
282 * buffer can be allocated. Second, the data is written into the
285 * Determining the size:
286 * The process of determining the size is triggered by a call to
287 * g_variant_ensure_size() on a container. This invokes the
288 * serialiser code to determine the size. The serialiser is passed
289 * g_variant_fill_gvs() as a callback.
291 * g_variant_fill_gvs() is called by the serialiser on each child of
292 * the container which, in turn, calls g_variant_ensure_size() on
293 * itself and fills in the result of its own size calculation.
295 * The serialiser uses the size information from the children to
296 * calculate the size needed for the entire container.
299 * After the buffer has been allocated, g_variant_serialise() is
300 * called on the container. This invokes the serialiser code to write
301 * the bytes to the container. The serialiser is, again, passed
302 * g_variant_fill_gvs() as a callback.
304 * This time, when g_variant_fill_gvs() is called for each child, the
305 * child is given a pointer to a sub-region of the allocated buffer
306 * where it should write its data. This is done by calling
307 * g_variant_store(). In the event that the instance is in serialised
308 * form this means a memcpy() of the serialised data into the
309 * allocated buffer. In the event that the instance is in tree form
310 * this means a recursive call back into g_variant_serialise().
313 * The forward declaration here allows corecursion via callback:
315 static void g_variant_fill_gvs (GVariantSerialised
*, gpointer
);
318 * g_variant_ensure_size:
319 * @value: a #GVariant
321 * Ensures that the ->size field of @value is filled in properly. This
322 * must be done as a precursor to any serialisation of the value in
323 * order to know how large of a buffer is needed to store the data.
325 * The current thread must hold the lock on @value.
328 g_variant_ensure_size (GVariant
*value
)
330 g_assert (value
->state
& STATE_LOCKED
);
332 if (value
->size
== (gssize
) -1)
337 children
= (gpointer
*) value
->contents
.tree
.children
;
338 n_children
= value
->contents
.tree
.n_children
;
339 value
->size
= g_variant_serialiser_needed_size (value
->type_info
,
341 children
, n_children
);
346 * g_variant_serialise:
347 * @value: a #GVariant
348 * @data: an appropriately-sized buffer
350 * Serialises @value into @data. @value must be in tree form.
352 * No change is made to @value.
354 * The current thread must hold the lock on @value.
357 g_variant_serialise (GVariant
*value
,
360 GVariantSerialised serialised
= { 0, };
364 g_assert (~value
->state
& STATE_SERIALISED
);
365 g_assert (value
->state
& STATE_LOCKED
);
367 serialised
.type_info
= value
->type_info
;
368 serialised
.size
= value
->size
;
369 serialised
.data
= data
;
371 children
= (gpointer
*) value
->contents
.tree
.children
;
372 n_children
= value
->contents
.tree
.n_children
;
374 g_variant_serialiser_serialise (serialised
, g_variant_fill_gvs
,
375 children
, n_children
);
379 * g_variant_fill_gvs:
380 * @serialised: a pointer to a #GVariantSerialised
381 * @data: a #GVariant instance
383 * This is the callback that is passed by a tree-form container instance
384 * to the serialiser. This callback gets called on each child of the
385 * container. Each child is responsible for performing the following
388 * - reporting its type
390 * - reporting its serialised size (requires knowing the size first)
392 * - possibly storing its serialised form into the provided buffer
395 g_variant_fill_gvs (GVariantSerialised
*serialised
,
398 GVariant
*value
= data
;
400 g_variant_lock (value
);
401 g_variant_ensure_size (value
);
402 g_variant_unlock (value
);
404 if (serialised
->type_info
== NULL
)
405 serialised
->type_info
= value
->type_info
;
406 g_assert (serialised
->type_info
== value
->type_info
);
408 if (serialised
->size
== 0)
409 serialised
->size
= value
->size
;
410 g_assert (serialised
->size
== value
->size
);
412 if (serialised
->data
)
413 /* g_variant_store() is a public API, so it
414 * it will reacquire the lock if it needs to.
416 g_variant_store (value
, serialised
->data
);
419 /* this ends the main body of the recursive serialiser */
422 * g_variant_ensure_serialised:
423 * @value: a #GVariant
425 * Ensures that @value is in serialised form.
427 * If @value is in tree form then this function ensures that the
428 * serialised size is known and then allocates a buffer of that size and
429 * serialises the instance into the buffer. The 'children' array is
430 * then released and the instance is set to serialised form based on the
431 * contents of the buffer.
433 * The current thread must hold the lock on @value.
436 g_variant_ensure_serialised (GVariant
*value
)
438 g_assert (value
->state
& STATE_LOCKED
);
440 if (~value
->state
& STATE_SERIALISED
)
445 g_variant_ensure_size (value
);
446 data
= g_malloc (value
->size
);
447 g_variant_serialise (value
, data
);
449 g_variant_release_children (value
);
451 buffer
= g_buffer_new_take_data (data
, value
->size
);
452 value
->contents
.serialised
.data
= buffer
->data
;
453 value
->contents
.serialised
.buffer
= buffer
;
454 value
->state
|= STATE_SERIALISED
;
460 * @type: the type of the new instance
461 * @serialised: if the instance will be in serialised form
462 * @trusted: if the instance will be trusted
463 * @returns: a new #GVariant with a floating reference
465 * Allocates a #GVariant instance and does some common work (such as
466 * looking up and filling in the type info), setting the state field,
467 * and setting the ref_count to 1.
470 g_variant_alloc (const GVariantType
*type
,
476 value
= g_slice_new (GVariant
);
477 value
->type_info
= g_variant_type_info_get (type
);
478 value
->state
= (serialised
? STATE_SERIALISED
: 0) |
479 (trusted
? STATE_TRUSTED
: 0) |
481 value
->size
= (gssize
) -1;
482 value
->ref_count
= 1;
489 * g_variant_new_from_buffer:
490 * @type: a #GVariantType
491 * @buffer: a #GBuffer
492 * @trusted: if the contents of @buffer are trusted
493 * @returns: a new #GVariant with a floating reference
495 * Constructs a new serialised-mode #GVariant instance. This is the
496 * inner interface for creation of new serialised values that gets
497 * called from various functions in gvariant.c.
499 * A reference is taken on @buffer.
502 g_variant_new_from_buffer (const GVariantType
*type
,
508 value
= g_variant_alloc (type
, TRUE
, trusted
);
509 value
->contents
.serialised
.buffer
= g_buffer_ref (buffer
);
510 value
->contents
.serialised
.data
= buffer
->data
;
511 value
->size
= buffer
->size
;
517 * g_variant_new_from_children:
518 * @type: a #GVariantType
519 * @children: an array of #GVariant pointers. Consumed.
520 * @n_children: the length of @children
521 * @trusted: %TRUE if every child in @children in trusted
522 * @returns: a new #GVariant with a floating reference
524 * Constructs a new tree-mode #GVariant instance. This is the inner
525 * interface for creation of new serialised values that gets called from
526 * various functions in gvariant.c.
528 * @children is consumed by this function. g_free() will be called on
529 * it some time later.
532 g_variant_new_from_children (const GVariantType
*type
,
539 value
= g_variant_alloc (type
, FALSE
, trusted
);
540 value
->contents
.tree
.children
= children
;
541 value
->contents
.tree
.n_children
= n_children
;
547 * g_variant_get_type_info:
548 * @value: a #GVariant
549 * @returns: the #GVariantTypeInfo for @value
551 * Returns the #GVariantTypeInfo corresponding to the type of @value. A
552 * reference is not added, so the return value is only good for the
553 * duration of the life of @value.
556 g_variant_get_type_info (GVariant
*value
)
558 return value
->type_info
;
562 * g_variant_is_trusted:
563 * @value: a #GVariant
564 * @returns: if @value is trusted
566 * Determines if @value is trusted by #GVariant to contain only
567 * fully-valid data. All values constructed solely via #GVariant APIs
568 * are trusted, but values containing data read in from other sources
569 * are usually not trusted.
571 * The main advantage of trusted data is that certain checks can be
572 * skipped. For example, we don't need to check that a string is
573 * properly nul-terminated or that an object path is actually a
574 * properly-formatted object path.
577 g_variant_is_trusted (GVariant
*value
)
579 return (value
->state
& STATE_TRUSTED
) != 0;
586 * @value: a #GVariant
588 * Decreases the reference count of @value. When its reference count
589 * drops to 0, the memory used by the variant is freed.
594 g_variant_unref (GVariant
*value
)
596 if (g_atomic_int_dec_and_test (&value
->ref_count
))
598 if G_UNLIKELY (value
->state
& STATE_LOCKED
)
599 g_critical ("attempting to free a locked GVariant instance. "
600 "This should never happen.");
602 value
->state
|= STATE_LOCKED
;
604 g_variant_type_info_unref (value
->type_info
);
606 if (value
->state
& STATE_SERIALISED
)
607 g_buffer_unref (value
->contents
.serialised
.buffer
);
609 g_variant_release_children (value
);
611 g_slice_free (GVariant
, value
);
617 * @value: a #GVariant
618 * @returns: the same @value
620 * Increases the reference count of @value.
625 g_variant_ref (GVariant
*value
)
627 g_atomic_int_inc (&value
->ref_count
);
633 * g_variant_ref_sink:
634 * @value: a #GVariant
635 * @returns: the same @value
637 * #GVariant uses a floating reference count system. All functions with
638 * names starting with <literal>g_variant_new_</literal> return floating
641 * Calling g_variant_ref_sink() on a #GVariant with a floating reference
642 * will convert the floating reference into a full reference. Calling
643 * g_variant_ref_sink() on a non-floating #GVariant results in an
644 * additional normal reference being added.
646 * In other words, if the @value is floating, then this call "assumes
647 * ownership" of the floating reference, converting it to a normal
648 * reference. If the @value is not floating, then this call adds a
649 * new normal reference increasing the reference count by one.
651 * All calls that result in a #GVariant instance being inserted into a
652 * container will call g_variant_ref_sink() on the instance. This means
653 * that if the value was just created (and has only its floating
654 * reference) then the container will assume sole ownership of the value
655 * at that point and the caller will not need to unreference it. This
656 * makes certain common styles of programming much easier while still
657 * maintaining normal refcounting semantics in situations where values
663 g_variant_ref_sink (GVariant
*value
)
665 g_variant_lock (value
);
667 if (~value
->state
& STATE_FLOATING
)
668 g_variant_ref (value
);
670 value
->state
&= ~STATE_FLOATING
;
672 g_variant_unlock (value
);
678 * g_variant_get_size:
679 * @value: a #GVariant instance
680 * @returns: the serialised size of @value
682 * Determines the number of bytes that would be required to store @value
683 * with g_variant_store().
685 * If @value has a fixed-sized type then this function always returned
688 * In the case that @value is already in serialised form or the size has
689 * already been calculated (ie: this function has been called before)
690 * then this function is O(1). Otherwise, the size is calculated, an
691 * operation which is approximately O(n) in the number of values
697 g_variant_get_size (GVariant
*value
)
699 g_variant_lock (value
);
700 g_variant_ensure_size (value
);
701 g_variant_unlock (value
);
707 * g_variant_get_data:
708 * @value: a #GVariant instance
709 * @returns: the serialised form of @value, or %NULL
711 * Returns a pointer to the serialised form of a #GVariant instance.
712 * The returned data may not be in fully-normalised form if read from an
713 * untrusted source. The returned data must not be freed; it remains
714 * valid for as long as @value exists.
716 * If @value is a fixed-sized value that was deserialised from a
717 * corrupted serialised container then %NULL may be returned. In this
718 * case, the proper thing to do is typically to use the appropriate
719 * number of nul bytes in place of @value. If @value is not fixed-sized
720 * then %NULL is never returned.
722 * In the case that @value is already in serialised form, this function
723 * is O(1). If the value is not already in serialised form,
724 * serialisation occurs implicitly and is approximately O(n) in the size
730 g_variant_get_data (GVariant
*value
)
732 g_variant_lock (value
);
733 g_variant_ensure_serialised (value
);
734 g_variant_unlock (value
);
736 return value
->contents
.serialised
.data
;
740 * g_variant_n_children:
741 * @value: a container #GVariant
742 * @returns: the number of children in the container
744 * Determines the number of children in a container #GVariant instance.
745 * This includes variants, maybes, arrays, tuples and dictionary
746 * entries. It is an error to call this function on any other type of
749 * For variants, the return value is always 1. For values with maybe
750 * types, it is always zero or one. For arrays, it is the length of the
751 * array. For tuples it is the number of tuple items (which depends
752 * only on the type). For dictionary entries, it is always 2
754 * This function is O(1).
759 g_variant_n_children (GVariant
*value
)
763 g_variant_lock (value
);
765 if (value
->state
& STATE_SERIALISED
)
767 GVariantSerialised serialised
= {
769 (gpointer
) value
->contents
.serialised
.data
,
773 n_children
= g_variant_serialised_n_children (serialised
);
776 n_children
= value
->contents
.tree
.n_children
;
778 g_variant_unlock (value
);
784 * g_variant_get_child_value:
785 * @value: a container #GVariant
786 * @index_: the index of the child to fetch
787 * @returns: the child at the specified index
789 * Reads a child item out of a container #GVariant instance. This
790 * includes variants, maybes, arrays, tuples and dictionary
791 * entries. It is an error to call this function on any other type of
794 * It is an error if @index_ is greater than the number of child items
795 * in the container. See g_variant_n_children().
797 * This function is O(1).
802 g_variant_get_child_value (GVariant
*value
,
805 GVariant
*child
= NULL
;
807 g_variant_lock (value
);
809 if (value
->state
& STATE_SERIALISED
)
811 GVariantSerialised serialised
= {
813 (gpointer
) value
->contents
.serialised
.data
,
816 GVariantSerialised s_child
;
818 /* get the serialiser to extract the serialised data for the child
819 * from the serialised data for the container
821 s_child
= g_variant_serialised_get_child (serialised
, index_
);
823 /* create a new serialised instance out of it */
824 child
= g_slice_new (GVariant
);
825 child
->type_info
= s_child
.type_info
;
826 child
->state
= (value
->state
& STATE_TRUSTED
) |
828 child
->size
= s_child
.size
;
829 child
->ref_count
= 1;
830 child
->contents
.serialised
.buffer
=
831 g_buffer_ref (value
->contents
.serialised
.buffer
);
832 child
->contents
.serialised
.data
= s_child
.data
;
835 child
= g_variant_ref (value
->contents
.tree
.children
[index_
]);
837 g_variant_unlock (value
);
844 * @value: the #GVariant to store
845 * @data: the location to store the serialised data at
847 * Stores the serialised form of @value at @data. @data should be
848 * large enough. See g_variant_get_size().
850 * The stored data is in machine native byte order but may not be in
851 * fully-normalised form if read from an untrusted source. See
852 * g_variant_normalise() for a solution.
854 * This function is approximately O(n) in the size of @data.
859 g_variant_store (GVariant
*value
,
862 g_variant_lock (value
);
864 if (value
->state
& STATE_SERIALISED
)
866 if (value
->contents
.serialised
.data
!= NULL
)
867 memcpy (data
, value
->contents
.serialised
.data
, value
->size
);
869 memset (data
, 0, value
->size
);
872 g_variant_serialise (value
, data
);
874 g_variant_unlock (value
);
878 * g_variant_is_normal_form:
879 * @value: a #GVariant instance
880 * @returns: %TRUE if @value is in normal form
882 * Checks if @value is in normal form.
884 * The main reason to do this is to detect if a given chunk of
885 * serialised data is in normal form: load the data into a #GVariant
886 * using g_variant_create_from_data() and then use this function to
889 * If @value is found to be in normal form then it will be marked as
890 * being trusted. If the value was already marked as being trusted then
891 * this function will immediately return %TRUE.
896 g_variant_is_normal_form (GVariant
*value
)
898 if (value
->state
& STATE_TRUSTED
)
901 g_variant_lock (value
);
903 if (value
->state
& STATE_SERIALISED
)
905 GVariantSerialised serialised
= {
907 (gpointer
) value
->contents
.serialised
.data
,
911 if (g_variant_serialised_is_normal (serialised
))
912 value
->state
|= STATE_TRUSTED
;
916 gboolean normal
= TRUE
;
919 for (i
= 0; i
< value
->contents
.tree
.n_children
; i
++)
920 normal
&= g_variant_is_normal_form (value
->contents
.tree
.children
[i
]);
923 value
->state
|= STATE_TRUSTED
;
926 g_variant_unlock (value
);
928 return (value
->state
& STATE_TRUSTED
) != 0;
931 #define __G_VARIANT_CORE_C__
932 #include "galiasdef.c"