merge GVariant
[platform/upstream/glib.git] / glib / gvariant-core.c
1 /*
2  * Copyright © 2007, 2008 Ryan Lortie
3  * Copyright © 2010 Codethink Limited
4  *
5  * This library is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Lesser General Public
7  * License as published by the Free Software Foundation; either
8  * version 2 of the License, or (at your option) any later version.
9  *
10  * This library is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13  * Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public
16  * License along with this library; if not, write to the
17  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18  * Boston, MA 02111-1307, USA.
19  */
20
21 #include <glib/gvariant-core.h>
22
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>
30 #include <string.h>
31
32 #include "galias.h"
33
34 /*
35  * This file includes the structure definition for GVariant and a small
36  * set of functions that are allowed to access the structure directly.
37  *
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.
43  *
44  * Most GVariant API functions are in gvariant.c.
45  */
46
47 /**
48  * GVariant:
49  *
50  * #GVariant is an opaque data structure and can only be accessed
51  * using the following functions.
52  **/
53 struct _GVariant
54 /* see below for field member documentation */
55 {
56   GVariantTypeInfo *type_info;
57   gsize size;
58
59   union
60   {
61     struct
62     {
63       GBuffer *buffer;
64       gconstpointer data;
65     } serialised;
66
67     struct
68     {
69       GVariant **children;
70       gsize n_children;
71     } tree;
72   } contents;
73
74   gint state;
75   gint ref_count;
76 };
77
78 /* struct GVariant:
79  *
80  * There are two primary forms of GVariant instances: "serialised form"
81  * and "tree form".
82  *
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.
87  *
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).
92  *
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.
97  *
98  *
99  * The fields of the structure are documented here:
100  *
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().
104  *
105  *            The type_info field never changes during the life of the
106  *            instance, so it can be accessed without a lock.
107  *
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
117  *       the data.
118  *
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.
123  *
124  * contents: a union containing either the information associated with
125  *           holding a value in serialised form or holding a value in
126  *           tree form.
127  *
128  *   .serialised: Only valid when the instance is in serialised form.
129  *
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.
134  *
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().
141  *
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.
145  *
146  *            This pointer may be %NULL in two cases:
147  *
148  *              - if the serialised size of the instance is 0
149  *
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
159  *                bytes.
160  *
161  *   .tree: Only valid when the instance is in tree form.
162  *
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'.
167  *
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
172  *                g_free().
173  *
174  *     .n_children: the number of items in the .children array.
175  *
176  * state: a bitfield describing the state of the instance.  It is a
177  *        bitwise-or of the following STATE_* constants:
178  *
179  *    STATE_LOCKED: the instance lock is held.  This is the bit used by
180  *                  g_bit_lock().
181  *
182  *    STATE_SERIALISED: the instance is in serialised form.  If this
183  *                      flag is not set then the instance is in tree
184  *                      form.
185  *
186  *    STATE_TRUSTED: for serialised form instances, this means that the
187  *                   serialised data is known to be in normal form (ie:
188  *                   not corrupted).
189  *
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
194  *                   normal form.
195  *
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().
199  *
200  *    STATE_FLOATING: if this flag is set then the object has a floating
201  *                    reference.  See g_variant_ref_sink().
202  *
203  * ref_count: the reference count of the instance
204  */
205 #define STATE_LOCKED     1
206 #define STATE_SERIALISED 2
207 #define STATE_TRUSTED    4
208 #define STATE_FLOATING   8
209
210 /* -- private -- */
211 /* < private >
212  * g_variant_lock:
213  * @value: a #GVariant
214  *
215  * Locks @value for performing sensitive operations.
216  */
217 static void
218 g_variant_lock (GVariant *value)
219 {
220   g_bit_lock (&value->state, 0);
221 }
222
223 /* < private >
224  * g_variant_unlock:
225  * @value: a #GVariant
226  *
227  * Unlocks @value after performing sensitive operations.
228  */
229 static void
230 g_variant_unlock (GVariant *value)
231 {
232   g_bit_unlock (&value->state, 0);
233 }
234
235 /* < private >
236  * g_variant_release_children:
237  * @value: a #GVariant
238  *
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.
241  *
242  * This is done when freeing a tree-form instance or converting it to
243  * serialised form.
244  *
245  * The current thread must hold the lock on @value.
246  */
247 static void
248 g_variant_release_children (GVariant *value)
249 {
250   gsize i;
251
252   g_assert (value->state & STATE_LOCKED);
253   g_assert (~value->state & STATE_SERIALISED);
254
255   for (i = 0; i < value->contents.tree.n_children; i++)
256     g_variant_unref (value->contents.tree.children[i]);
257
258   g_free (value->contents.tree.children);
259 }
260
261 /* This begins the main body of the recursive serialiser.
262  *
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.
266  *
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.
273  *
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().
277  *
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
281  * buffer.
282  *
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.
288  *
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.
292  *
293  *   The serialiser uses the size information from the children to
294  *   calculate the size needed for the entire container.
295  *
296  * Writing the data:
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.
301  *
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().
309  *
310  *
311  * The forward declaration here allows corecursion via callback:
312  */
313 static void g_variant_fill_gvs (GVariantSerialised *, gpointer);
314
315 /* < private >
316  * g_variant_ensure_size:
317  * @value: a #GVariant
318  *
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.
322  *
323  * The current thread must hold the lock on @value.
324  */
325 static void
326 g_variant_ensure_size (GVariant *value)
327 {
328   g_assert (value->state & STATE_LOCKED);
329
330   if (value->size == (gssize) -1)
331     {
332       gpointer *children;
333       gsize n_children;
334
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,
338                                                       g_variant_fill_gvs,
339                                                       children, n_children);
340     }
341 }
342
343 /* < private >
344  * g_variant_serialise:
345  * @value: a #GVariant
346  * @data: an appropriately-sized buffer
347  *
348  * Serialises @value into @data.  @value must be in tree form.
349  *
350  * No change is made to @value.
351  *
352  * The current thread must hold the lock on @value.
353  */
354 static void
355 g_variant_serialise (GVariant *value,
356                      gpointer  data)
357 {
358   GVariantSerialised serialised = {  };
359   gpointer *children;
360   gsize n_children;
361
362   g_assert (~value->state & STATE_SERIALISED);
363   g_assert (value->state & STATE_LOCKED);
364
365   serialised.type_info = value->type_info;
366   serialised.size = value->size;
367   serialised.data = data;
368
369   children = (gpointer *) value->contents.tree.children;
370   n_children = value->contents.tree.n_children;
371
372   g_variant_serialiser_serialise (serialised, g_variant_fill_gvs,
373                                   children, n_children);
374 }
375
376 /* < private >
377  * g_variant_fill_gvs:
378  * @serialised: a pointer to a #GVariantSerialised
379  * @data: a #GVariant instance
380  *
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
384  * actions:
385  *
386  *  - reporting its type
387  *
388  *  - reporting its serialised size (requires knowing the size first)
389  *
390  *  - possibly storing its serialised form into the provided buffer
391  */
392 static void
393 g_variant_fill_gvs (GVariantSerialised *serialised,
394                     gpointer            data)
395 {
396   GVariant *value = data;
397
398   g_variant_lock (value);
399   g_variant_ensure_size (value);
400   g_variant_unlock (value);
401
402   if (serialised->type_info == NULL)
403     serialised->type_info = value->type_info;
404   g_assert (serialised->type_info == value->type_info);
405
406   if (serialised->size == 0)
407     serialised->size = value->size;
408   g_assert (serialised->size == value->size);
409
410   if (serialised->data)
411     /* g_variant_store() is a public API, so it
412      * it will reacquire the lock if it needs to.
413      */
414     g_variant_store (value, serialised->data);
415 }
416
417 /* this ends the main body of the recursive serialiser */
418
419 /* < private >
420  * g_variant_ensure_serialised:
421  * @value: a #GVariant
422  *
423  * Ensures that @value is in serialised form.
424  *
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.
430  *
431  * The current thread must hold the lock on @value.
432  */
433 static void
434 g_variant_ensure_serialised (GVariant *value)
435 {
436   g_assert (value->state & STATE_LOCKED);
437
438   if (~value->state & STATE_SERIALISED)
439     {
440       GBuffer *buffer;
441       gpointer data;
442
443       g_variant_ensure_size (value);
444       data = g_malloc (value->size);
445       g_variant_serialise (value, data);
446
447       g_variant_release_children (value);
448
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;
453     }
454 }
455
456 /* < private >
457  * g_variant_alloc:
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
462  *
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.
466  */
467 static GVariant *
468 g_variant_alloc (const GVariantType *type,
469                  gboolean            serialised,
470                  gboolean            trusted)
471 {
472   GVariant *value;
473
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) |
478                  STATE_FLOATING;
479   value->size = (gssize) -1;
480   value->ref_count = 1;
481
482   return value;
483 }
484
485 /* -- internal -- */
486 /* < internal >
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
492  *
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.
496  *
497  * A reference is taken on @buffer.
498  */
499 GVariant *
500 g_variant_new_from_buffer (const GVariantType *type,
501                            GBuffer            *buffer,
502                            gboolean            trusted)
503 {
504   GVariant *value;
505
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;
510
511   return value;
512 }
513
514 /* < internal >
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
521  *
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.
525  *
526  * @children is consumed by this function.  g_free() will be called on
527  * it some time later.
528  */
529 GVariant *
530 g_variant_new_from_children (const GVariantType  *type,
531                              GVariant           **children,
532                              gsize                n_children,
533                              gboolean             trusted)
534 {
535   GVariant *value;
536
537   value = g_variant_alloc (type, FALSE, trusted);
538   value->contents.tree.children = children;
539   value->contents.tree.n_children = n_children;
540
541   return value;
542 }
543
544 /* < internal >
545  * g_variant_get_type_info:
546  * @value: a #GVariant
547  * @returns: the #GVariantTypeInfo for @value
548  *
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.
552  */
553 GVariantTypeInfo *
554 g_variant_get_type_info (GVariant *value)
555 {
556   return value->type_info;
557 }
558
559 /* < internal >
560  * g_variant_is_trusted:
561  * @value: a #GVariant
562  * @returns: if @value is trusted
563  *
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.
568  *
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.
573  */
574 gboolean
575 g_variant_is_trusted (GVariant *value)
576 {
577   return (value->state & STATE_TRUSTED) != 0;
578 }
579
580 /* -- public -- */
581
582 /**
583  * g_variant_unref:
584  * @value: a #GVariant
585  *
586  * Decreases the reference count of @value.  When its reference count
587  * drops to 0, the memory used by the variant is freed.
588  **/
589 void
590 g_variant_unref (GVariant *value)
591 {
592   if (g_atomic_int_dec_and_test (&value->ref_count))
593     {
594       if G_UNLIKELY (value->state & STATE_LOCKED)
595         g_critical ("attempting to free a locked GVariant instance.  "
596                     "This should never happen.");
597
598       g_variant_type_info_unref (value->type_info);
599
600       if (value->state & STATE_SERIALISED)
601         g_buffer_unref (value->contents.serialised.buffer);
602       else
603         g_variant_release_children (value);
604
605       g_slice_free (GVariant, value);
606     }
607 }
608
609 /**
610  * g_variant_ref:
611  * @value: a #GVariant
612  * @returns: the same @value
613  *
614  * Increases the reference count of @value.
615  **/
616 GVariant *
617 g_variant_ref (GVariant *value)
618 {
619   g_atomic_int_inc (&value->ref_count);
620
621   return value;
622 }
623
624 /**
625  * g_variant_ref_sink:
626  * @value: a #GVariant
627  * @returns: the same @value
628  *
629  * #GVariant uses a floating reference count system.  All functions with
630  * names starting with <literal>g_variant_new_</literal> return floating
631  * references.
632  *
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.
637  *
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.
642  *
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
650  * are not floating.
651  **/
652 GVariant *
653 g_variant_ref_sink (GVariant *value)
654 {
655   g_variant_lock (value);
656
657   if (~value->state & STATE_FLOATING)
658     g_variant_ref (value);
659   else
660     value->state &= ~STATE_FLOATING;
661
662   g_variant_unlock (value);
663
664   return value;
665 }
666
667 /**
668  * g_variant_get_size:
669  * @value: a #GVariant instance
670  * @returns: the serialised size of @value
671  *
672  * Determines the number of bytes that would be required to store @value
673  * with g_variant_store().
674  *
675  * If @value has a fixed-sized type then this function always returned
676  * that fixed size.
677  *
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
682  * involved.
683  **/
684 gsize
685 g_variant_get_size (GVariant *value)
686 {
687   g_variant_lock (value);
688   g_variant_ensure_size (value);
689   g_variant_unlock (value);
690
691   return value->size;
692 }
693
694 /**
695  * g_variant_get_data:
696  * @value: a #GVariant instance
697  * @returns: the serialised form of @value, or %NULL
698  *
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
703  * exists.
704  *
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.
710  *
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
714  * of the result.
715  **/
716 gconstpointer
717 g_variant_get_data (GVariant *value)
718 {
719   g_variant_lock (value);
720   g_variant_ensure_serialised (value);
721   g_variant_unlock (value);
722
723   return value->contents.serialised.data;
724 }
725
726 /**
727  * g_variant_n_children:
728  * @value: a container #GVariant
729  * @returns: the number of children in the container
730  *
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
734  * #GVariant.
735  *
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
740  *
741  * This function is O(1).
742  **/
743 gsize
744 g_variant_n_children (GVariant *value)
745 {
746   gsize n_children;
747
748   g_variant_lock (value);
749
750   if (value->state & STATE_SERIALISED)
751     {
752       GVariantSerialised serialised = {
753         value->type_info,
754         (gpointer) value->contents.serialised.data,
755         value->size
756       };
757
758       n_children = g_variant_serialised_n_children (serialised);
759     }
760   else
761     n_children = value->contents.tree.n_children;
762
763   g_variant_unlock (value);
764
765   return n_children;
766 }
767
768 /**
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
773  *
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
777  * #GVariant.
778  *
779  * It is an error if @index_ is greater than the number of child items
780  * in the container.  See g_variant_n_children().
781  *
782  * This function is O(1).
783  **/
784 GVariant *
785 g_variant_get_child_value (GVariant *value,
786                            gsize     index_)
787 {
788   GVariant *child = NULL;
789
790   g_variant_lock (value);
791
792   if (value->state & STATE_SERIALISED)
793     {
794       GVariantSerialised serialised = {
795         value->type_info,
796         (gpointer) value->contents.serialised.data,
797         value->size
798       };
799       GVariantSerialised s_child;
800
801       s_child = g_variant_serialised_get_child (serialised, index_);
802
803       child = g_slice_new (GVariant);
804       child->type_info = s_child.type_info;
805       child->state = (value->state & STATE_TRUSTED) |
806                      STATE_SERIALISED;
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;
812      }
813   else
814     child = g_variant_ref (value->contents.tree.children[index_]);
815
816   g_variant_unlock (value);
817
818   return child;
819 }
820
821 /**
822  * g_variant_store:
823  * @value: the #GVariant to store
824  * @data: the location to store the serialised data at
825  *
826  * Stores the serialised form of @value at @data.  @data should be
827  * large enough.  See g_variant_get_size().
828  *
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.
832  *
833  * This function is approximately O(n) in the size of @data.
834  **/
835 void
836 g_variant_store (GVariant *value,
837                  gpointer  data)
838 {
839   g_variant_lock (value);
840
841   if (value->state & STATE_SERIALISED)
842     {
843       if (value->contents.serialised.data != NULL)
844         memcpy (data, value->contents.serialised.data, value->size);
845       else
846         memset (data, 0, value->size);
847     }
848   else
849     g_variant_serialise (value, data);
850
851   g_variant_unlock (value);
852 }
853
854 #define __G_VARIANT_CORE_C__
855 #include "galiasdef.c"