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.
54 /* see below for field member documentation */
56 GVariantTypeInfo *type_info;
80 * There are two primary forms of GVariant instances: "serialised form"
83 * "serialised form": A serialised GVariant instance stores its value in
84 * the GVariant serialisation format. All
85 * basic-typed instances (ie: non-containers) are in
86 * serialised format, as are some containers.
88 * "tree form": Some containers are in "tree form". In this case,
89 * instead of containing the serialised data for the
90 * container, the instance contains an array of pointers to
91 * the child values of the container (thus forming a tree).
93 * It is possible for an instance to transition from tree form to
94 * serialised form. This happens, implicitly, if the serialised data is
95 * requested (eg: via g_variant_get_data()). Serialised form instances
96 * never transition into tree form.
99 * The fields of the structure are documented here:
101 * type_info: this is a reference to a GVariantTypeInfo describing the
102 * type of the instance. When the instance is freed, this
103 * reference must be released with g_variant_type_info_unref().
105 * The type_info field never changes during the life of the
106 * instance, so it can be accessed without a lock.
108 * size: this is the size of the serialised form for the instance, if it
109 * is known. If the instance is in serialised form then it is, by
110 * definition, known. If the instance is in tree form then it may
111 * be unknown (in which case it is -1). It is possible for the
112 * size to be known when in tree form if, for example, the user
113 * has called g_variant_get_size() without calling
114 * g_variant_get_data(). Additionally, even when the user calls
115 * g_variant_get_data() the size of the data must first be
116 * determined so that a large enough buffer can be allocated for
119 * Once the size is known, it can never become unknown again.
120 * g_variant_ensure_size() is used to ensure that the size is in
121 * the known state -- it calculates the size if needed. After
122 * that, the size field can be accessed without a lock.
124 * contents: a union containing either the information associated with
125 * holding a value in serialised form or holding a value in
128 * .serialised: Only valid when the instance is in serialised form.
130 * Since an instance can never transition away from
131 * serialised form, once these fields are set, they will
132 * never be changed. It is therefore valid to access
133 * them without holding a lock.
135 * .buffer: the #GBuffer that contains the memory pointed to by
136 * .data, or %NULL if .data is %NULL. In the event that
137 * the instance was deserialised from another instance,
138 * then the buffer will be shared by both of them. When
139 * the instance is freed, this reference must be released
140 * with g_buffer_unref().
142 * .data: the serialised data (of size 'size') of the instance.
143 * This pointer should not be freed or modified in any way.
144 * #GBuffer is responsible for memory management.
146 * This pointer may be %NULL in two cases:
148 * - if the serialised size of the instance is 0
150 * - if the instance is of a fixed-sized type and was
151 * deserialised out of a corrupted container such that
152 * the container contains too few bytes to point to the
153 * entire proper fixed-size of this instance. In this
154 * case, 'size' will still be equal to the proper fixed
155 * size, but this pointer will be %NULL. This is exactly
156 * the reason that g_variant_get_data() sometimes returns
157 * %NULL. For all other calls, the effect should be as
158 * if .data pointed to the appropriate number of nul
161 * .tree: Only valid when the instance is in tree form.
163 * Note that accesses from other threads could result in
164 * conversion of the instance from tree form to serialised form
165 * at any time. For this reason, the instance lock must always
166 * be held while performing any operations on 'contents.tree'.
168 * .children: the array of the child instances of this instance.
169 * When the instance is freed (or converted to serialised
170 * form) then each child must have g_variant_unref()
171 * called on it and the array must be freed using
174 * .n_children: the number of items in the .children array.
176 * state: a bitfield describing the state of the instance. It is a
177 * bitwise-or of the following STATE_* constants:
179 * STATE_LOCKED: the instance lock is held. This is the bit used by
182 * STATE_SERIALISED: the instance is in serialised form. If this
183 * flag is not set then the instance is in tree
186 * STATE_TRUSTED: for serialised form instances, this means that the
187 * serialised data is known to be in normal form (ie:
190 * For tree form instances, this means that all of the
191 * child instances in the contents.tree.children array
192 * are trusted. This means that if the container is
193 * serialised then the resulting data will be in
196 * If this flag is unset it does not imply that the
197 * data is corrupted. It merely means that we're not
198 * sure that it's valid. See g_variant_is_trusted().
200 * STATE_FLOATING: if this flag is set then the object has a floating
201 * reference. See g_variant_ref_sink().
203 * ref_count: the reference count of the instance
205 #define STATE_LOCKED 1
206 #define STATE_SERIALISED 2
207 #define STATE_TRUSTED 4
208 #define STATE_FLOATING 8
213 * @value: a #GVariant
215 * Locks @value for performing sensitive operations.
218 g_variant_lock (GVariant *value)
220 g_bit_lock (&value->state, 0);
225 * @value: a #GVariant
227 * Unlocks @value after performing sensitive operations.
230 g_variant_unlock (GVariant *value)
232 g_bit_unlock (&value->state, 0);
236 * g_variant_release_children:
237 * @value: a #GVariant
239 * Releases the reference held on each child in the 'children' array of
240 * @value and frees the array itself. @value must be in tree form.
242 * This is done when freeing a tree-form instance or converting it to
245 * The current thread must hold the lock on @value.
248 g_variant_release_children (GVariant *value)
252 g_assert (value->state & STATE_LOCKED);
253 g_assert (~value->state & STATE_SERIALISED);
255 for (i = 0; i < value->contents.tree.n_children; i++)
256 g_variant_unref (value->contents.tree.children[i]);
258 g_free (value->contents.tree.children);
261 /* This begins the main body of the recursive serialiser.
263 * There are 3 functions here that work as a team with the serialiser to
264 * get things done. g_variant_store() has a trivial role, but as a
265 * public API function, it has its definition elsewhere.
267 * Note that "serialisation" of an instance does not mean that the
268 * instance is converted to serialised form -- it means that the
269 * serialised form of an instance is written to an external buffer.
270 * g_variant_ensure_serialised() (which is not part of this set of
271 * functions) is the function that is responsible for converting an
272 * instance to serialised form.
274 * We are only concerned here with container types since non-container
275 * instances are always in serialised form. For these instances,
276 * storing their serialised form merely involves a memcpy().
278 * Serialisation is a two-step process. First, the size of the
279 * serialised data must be calculated so that an appropriately-sized
280 * buffer can be allocated. Second, the data is written into the
283 * Determining the size:
284 * The process of determining the size is triggered by a call to
285 * g_variant_ensure_size() on a container. This invokes the
286 * serialiser code to determine the size. The serialiser is passed
287 * g_variant_fill_gvs() as a callback.
289 * g_variant_fill_gvs() is called by the serialiser on each child of
290 * the container which, in turn, calls g_variant_ensure_size() on
291 * itself and fills in the result of its own size calculation.
293 * The serialiser uses the size information from the children to
294 * calculate the size needed for the entire container.
297 * After the buffer has been allocated, g_variant_serialise() is
298 * called on the container. This invokes the serialiser code to write
299 * the bytes to the container. The serialiser is, again, passed
300 * g_variant_fill_gvs() as a callback.
302 * This time, when g_variant_fill_gvs() is called for each child, the
303 * child is given a pointer to a sub-region of the allocated buffer
304 * where it should write its data. This is done by calling
305 * g_variant_store(). In the event that the instance is in serialised
306 * form this means a memcpy() of the serialised data into the
307 * allocated buffer. In the event that the instance is in tree form
308 * this means a recursive call back into g_variant_serialise().
311 * The forward declaration here allows corecursion via callback:
313 static void g_variant_fill_gvs (GVariantSerialised *, gpointer);
316 * g_variant_ensure_size:
317 * @value: a #GVariant
319 * Ensures that the ->size field of @value is filled in properly. This
320 * must be done as a precursor to any serialisation of the value in
321 * order to know how large of a buffer is needed to store the data.
323 * The current thread must hold the lock on @value.
326 g_variant_ensure_size (GVariant *value)
328 g_assert (value->state & STATE_LOCKED);
330 if (value->size == (gssize) -1)
335 children = (gpointer *) value->contents.tree.children;
336 n_children = value->contents.tree.n_children;
337 value->size = g_variant_serialiser_needed_size (value->type_info,
339 children, n_children);
344 * g_variant_serialise:
345 * @value: a #GVariant
346 * @data: an appropriately-sized buffer
348 * Serialises @value into @data. @value must be in tree form.
350 * No change is made to @value.
352 * The current thread must hold the lock on @value.
355 g_variant_serialise (GVariant *value,
358 GVariantSerialised serialised = { };
362 g_assert (~value->state & STATE_SERIALISED);
363 g_assert (value->state & STATE_LOCKED);
365 serialised.type_info = value->type_info;
366 serialised.size = value->size;
367 serialised.data = data;
369 children = (gpointer *) value->contents.tree.children;
370 n_children = value->contents.tree.n_children;
372 g_variant_serialiser_serialise (serialised, g_variant_fill_gvs,
373 children, n_children);
377 * g_variant_fill_gvs:
378 * @serialised: a pointer to a #GVariantSerialised
379 * @data: a #GVariant instance
381 * This is the callback that is passed by a tree-form container instance
382 * to the serialiser. This callback gets called on each child of the
383 * container. Each child is responsible for performing the following
386 * - reporting its type
388 * - reporting its serialised size (requires knowing the size first)
390 * - possibly storing its serialised form into the provided buffer
393 g_variant_fill_gvs (GVariantSerialised *serialised,
396 GVariant *value = data;
398 g_variant_lock (value);
399 g_variant_ensure_size (value);
400 g_variant_unlock (value);
402 if (serialised->type_info == NULL)
403 serialised->type_info = value->type_info;
404 g_assert (serialised->type_info == value->type_info);
406 if (serialised->size == 0)
407 serialised->size = value->size;
408 g_assert (serialised->size == value->size);
410 if (serialised->data)
411 /* g_variant_store() is a public API, so it
412 * it will reacquire the lock if it needs to.
414 g_variant_store (value, serialised->data);
417 /* this ends the main body of the recursive serialiser */
420 * g_variant_ensure_serialised:
421 * @value: a #GVariant
423 * Ensures that @value is in serialised form.
425 * If @value is in tree form then this function ensures that the
426 * serialised size is known and then allocates a buffer of that size and
427 * serialises the instance into the buffer. The 'children' array is
428 * then released and the instance is set to serialised form based on the
429 * contents of the buffer.
431 * The current thread must hold the lock on @value.
434 g_variant_ensure_serialised (GVariant *value)
436 g_assert (value->state & STATE_LOCKED);
438 if (~value->state & STATE_SERIALISED)
443 g_variant_ensure_size (value);
444 data = g_malloc (value->size);
445 g_variant_serialise (value, data);
447 g_variant_release_children (value);
449 buffer = g_buffer_new_take_data (data, value->size);
450 value->contents.serialised.data = buffer->data;
451 value->contents.serialised.buffer = buffer;
452 value->state |= STATE_SERIALISED;
458 * @type: the type of the new instance
459 * @serialised: if the instance will be in serialised form
460 * @trusted: if the instance will be trusted
461 * @returns: a new #GVariant with a floating reference
463 * Allocates a #GVariant instance and does some common work (such as
464 * looking up and filling in the type info), setting the state field,
465 * and setting the ref_count to 1.
468 g_variant_alloc (const GVariantType *type,
474 value = g_slice_new (GVariant);
475 value->type_info = g_variant_type_info_get (type);
476 value->state = (serialised ? STATE_SERIALISED : 0) |
477 (trusted ? STATE_TRUSTED : 0) |
479 value->size = (gssize) -1;
480 value->ref_count = 1;
487 * g_variant_new_from_buffer:
488 * @type: a #GVariantType
489 * @buffer: a #GBuffer
490 * @trusted: if the contents of @buffer are trusted
491 * @returns: a new #GVariant with a floating reference
493 * Constructs a new serialised-mode #GVariant instance. This is the
494 * inner interface for creation of new serialised values that gets
495 * called from various functions in gvariant.c.
497 * A reference is taken on @buffer.
500 g_variant_new_from_buffer (const GVariantType *type,
506 value = g_variant_alloc (type, TRUE, trusted);
507 value->contents.serialised.buffer = g_buffer_ref (buffer);
508 value->contents.serialised.data = buffer->data;
509 value->size = buffer->size;
515 * g_variant_new_from_children:
516 * @type: a #GVariantType
517 * @children: an array of #GVariant pointers. Consumed.
518 * @n_children: the length of @children
519 * @trusted: %TRUE if every child in @children in trusted
520 * @returns: a new #GVariant with a floating reference
522 * Constructs a new tree-mode #GVariant instance. This is the inner
523 * interface for creation of new serialised values that gets called from
524 * various functions in gvariant.c.
526 * @children is consumed by this function. g_free() will be called on
527 * it some time later.
530 g_variant_new_from_children (const GVariantType *type,
537 value = g_variant_alloc (type, FALSE, trusted);
538 value->contents.tree.children = children;
539 value->contents.tree.n_children = n_children;
545 * g_variant_get_type_info:
546 * @value: a #GVariant
547 * @returns: the #GVariantTypeInfo for @value
549 * Returns the #GVariantTypeInfo corresponding to the type of @value. A
550 * reference is not added, so the return value is only good for the
551 * duration of the life of @value.
554 g_variant_get_type_info (GVariant *value)
556 return value->type_info;
560 * g_variant_is_trusted:
561 * @value: a #GVariant
562 * @returns: if @value is trusted
564 * Determines if @value is trusted by #GVariant to contain only
565 * fully-valid data. All values constructed solely via #GVariant APIs
566 * are trusted, but values containing data read in from other sources
567 * are usually not trusted.
569 * The main advantage of trusted data is that certain checks can be
570 * skipped. For example, we don't need to check that a string is
571 * properly nul-terminated or that an object path is actually a
572 * properly-formatted object path.
575 g_variant_is_trusted (GVariant *value)
577 return (value->state & STATE_TRUSTED) != 0;
584 * @value: a #GVariant
586 * Decreases the reference count of @value. When its reference count
587 * drops to 0, the memory used by the variant is freed.
590 g_variant_unref (GVariant *value)
592 if (g_atomic_int_dec_and_test (&value->ref_count))
594 if G_UNLIKELY (value->state & STATE_LOCKED)
595 g_critical ("attempting to free a locked GVariant instance. "
596 "This should never happen.");
598 g_variant_type_info_unref (value->type_info);
600 if (value->state & STATE_SERIALISED)
601 g_buffer_unref (value->contents.serialised.buffer);
603 g_variant_release_children (value);
605 g_slice_free (GVariant, value);
611 * @value: a #GVariant
612 * @returns: the same @value
614 * Increases the reference count of @value.
617 g_variant_ref (GVariant *value)
619 g_atomic_int_inc (&value->ref_count);
625 * g_variant_ref_sink:
626 * @value: a #GVariant
627 * @returns: the same @value
629 * #GVariant uses a floating reference count system. All functions with
630 * names starting with <literal>g_variant_new_</literal> return floating
633 * Calling g_variant_ref_sink() on a #GVariant with a floating reference
634 * will convert the floating reference into a full reference. Calling
635 * g_variant_ref_sink() on a non-floating #GVariant results in an
636 * additional normal reference being added.
638 * In other words, if the @value is floating, then this call "assumes
639 * ownership" of the floating reference, converting it to a normal
640 * reference. If the @value is not floating, then this call adds a
641 * new normal reference increasing the reference count by one.
643 * All calls that result in a #GVariant instance being inserted into a
644 * container will call g_variant_ref_sink() on the instance. This means
645 * that if the value was just created (and has only its floating
646 * reference) then the container will assume sole ownership of the value
647 * at that point and the caller will not need to unreference it. This
648 * makes certain common styles of programming much easier while still
649 * maintaining normal refcounting semantics in situations where values
653 g_variant_ref_sink (GVariant *value)
655 g_variant_lock (value);
657 if (~value->state & STATE_FLOATING)
658 g_variant_ref (value);
660 value->state &= ~STATE_FLOATING;
662 g_variant_unlock (value);
668 * g_variant_get_size:
669 * @value: a #GVariant instance
670 * @returns: the serialised size of @value
672 * Determines the number of bytes that would be required to store @value
673 * with g_variant_store().
675 * If @value has a fixed-sized type then this function always returned
678 * In the case that @value is already in serialised form or the size has
679 * already been calculated (ie: this function has been called before)
680 * then this function is O(1). Otherwise, the size is calculated, an
681 * operation which is approximately O(n) in the number of values
685 g_variant_get_size (GVariant *value)
687 g_variant_lock (value);
688 g_variant_ensure_size (value);
689 g_variant_unlock (value);
695 * g_variant_get_data:
696 * @value: a #GVariant instance
697 * @returns: the serialised form of @value, or %NULL
699 * Returns a pointer to the serialised form of a #GVariant instance.
700 * The returned data is in machine native byte order but may not be in
701 * fully-normalised form if read from an untrusted source. The returned
702 * data must not be freed; it remains valid for as long as @value
705 * If @value is a fixed-sized value that was deserialised from a
706 * corrupted serialised container then %NULL may be returned. In this
707 * case, the proper thing to do is typically to use the appropriate
708 * number of nul bytes in place of @value. If @value is not fixed-sized
709 * then %NULL is never returned.
711 * In the case that @value is already in serialised form, this function
712 * is O(1). If the value is not already in serialised form,
713 * serialisation occurs implicitly and is approximately O(n) in the size
717 g_variant_get_data (GVariant *value)
719 g_variant_lock (value);
720 g_variant_ensure_serialised (value);
721 g_variant_unlock (value);
723 return value->contents.serialised.data;
727 * g_variant_n_children:
728 * @value: a container #GVariant
729 * @returns: the number of children in the container
731 * Determines the number of children in a container #GVariant instance.
732 * This includes variants, maybes, arrays, tuples and dictionary
733 * entries. It is an error to call this function on any other type of
736 * For variants, the return value is always 1. For values with maybe
737 * types, it is always zero or one. For arrays, it is the length of the
738 * array. For tuples it is the number of tuple items (which depends
739 * only on the type). For dictionary entries, it is always 2
741 * This function is O(1).
744 g_variant_n_children (GVariant *value)
748 g_variant_lock (value);
750 if (value->state & STATE_SERIALISED)
752 GVariantSerialised serialised = {
754 (gpointer) value->contents.serialised.data,
758 n_children = g_variant_serialised_n_children (serialised);
761 n_children = value->contents.tree.n_children;
763 g_variant_unlock (value);
769 * g_variant_get_child_value:
770 * @value: a container #GVariant
771 * @index_: the index of the child to fetch
772 * @returns: the child at the specified index
774 * Reads a child item out of a container #GVariant instance. This
775 * includes variants, maybes, arrays, tuples and dictionary
776 * entries. It is an error to call this function on any other type of
779 * It is an error if @index_ is greater than the number of child items
780 * in the container. See g_variant_n_children().
782 * This function is O(1).
785 g_variant_get_child_value (GVariant *value,
788 GVariant *child = NULL;
790 g_variant_lock (value);
792 if (value->state & STATE_SERIALISED)
794 GVariantSerialised serialised = {
796 (gpointer) value->contents.serialised.data,
799 GVariantSerialised s_child;
801 s_child = g_variant_serialised_get_child (serialised, index_);
803 child = g_slice_new (GVariant);
804 child->type_info = s_child.type_info;
805 child->state = (value->state & STATE_TRUSTED) |
807 child->size = serialised.size;
808 child->ref_count = 1;
809 child->contents.serialised.buffer =
810 g_buffer_ref (value->contents.serialised.buffer);
811 child->contents.serialised.data = serialised.data;
814 child = g_variant_ref (value->contents.tree.children[index_]);
816 g_variant_unlock (value);
823 * @value: the #GVariant to store
824 * @data: the location to store the serialised data at
826 * Stores the serialised form of @value at @data. @data should be
827 * large enough. See g_variant_get_size().
829 * The stored data is in machine native byte order but may not be in
830 * fully-normalised form if read from an untrusted source. See
831 * g_variant_normalise() for a solution.
833 * This function is approximately O(n) in the size of @data.
836 g_variant_store (GVariant *value,
839 g_variant_lock (value);
841 if (value->state & STATE_SERIALISED)
843 if (value->contents.serialised.data != NULL)
844 memcpy (data, value->contents.serialised.data, value->size);
846 memset (data, 0, value->size);
849 g_variant_serialise (value, data);
851 g_variant_unlock (value);
854 #define __G_VARIANT_CORE_C__
855 #include "galiasdef.c"