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       value->state |= STATE_LOCKED;
 599
 600       g_variant_type_info_unref (value->type_info);
 601
 602       if (value->state & STATE_SERIALISED)
 603         g_buffer_unref (value->contents.serialised.buffer);
 604       else
 605         g_variant_release_children (value);
 606
 607       g_slice_free (GVariant, value);
 608     }
 609 }
 610
 611 /**
 612  * g_variant_ref:
 613  * @value: a #GVariant
 614  * @returns: the same @value
 615  *
 616  * Increases the reference count of @value.
 617  **/
 618 GVariant *
 619 g_variant_ref (GVariant *value)
 620 {
 621   g_atomic_int_inc (&value->ref_count);
 622
 623   return value;
 624 }
 625
 626 /**
 627  * g_variant_ref_sink:
 628  * @value: a #GVariant
 629  * @returns: the same @value
 630  *
 631  * #GVariant uses a floating reference count system.  All functions with
 632  * names starting with <literal>g_variant_new_</literal> return floating
 633  * references.
 634  *
 635  * Calling g_variant_ref_sink() on a #GVariant with a floating reference
 636  * will convert the floating reference into a full reference.  Calling
 637  * g_variant_ref_sink() on a non-floating #GVariant results in an
 638  * additional normal reference being added.
 639  *
 640  * In other words, if the @value is floating, then this call "assumes
 641  * ownership" of the floating reference, converting it to a normal
 642  * reference.  If the @value is not floating, then this call adds a
 643  * new normal reference increasing the reference count by one.
 644  *
 645  * All calls that result in a #GVariant instance being inserted into a
 646  * container will call g_variant_ref_sink() on the instance.  This means
 647  * that if the value was just created (and has only its floating
 648  * reference) then the container will assume sole ownership of the value
 649  * at that point and the caller will not need to unreference it.  This
 650  * makes certain common styles of programming much easier while still
 651  * maintaining normal refcounting semantics in situations where values
 652  * are not floating.
 653  **/
 654 GVariant *
 655 g_variant_ref_sink (GVariant *value)
 656 {
 657   g_variant_lock (value);
 658
 659   if (~value->state & STATE_FLOATING)
 660     g_variant_ref (value);
 661   else
 662     value->state &= ~STATE_FLOATING;
 663
 664   g_variant_unlock (value);
 665
 666   return value;
 667 }
 668
 669 /**
 670  * g_variant_get_size:
 671  * @value: a #GVariant instance
 672  * @returns: the serialised size of @value
 673  *
 674  * Determines the number of bytes that would be required to store @value
 675  * with g_variant_store().
 676  *
 677  * If @value has a fixed-sized type then this function always returned
 678  * that fixed size.
 679  *
 680  * In the case that @value is already in serialised form or the size has
 681  * already been calculated (ie: this function has been called before)
 682  * then this function is O(1).  Otherwise, the size is calculated, an
 683  * operation which is approximately O(n) in the number of values
 684  * involved.
 685  **/
 686 gsize
 687 g_variant_get_size (GVariant *value)
 688 {
 689   g_variant_lock (value);
 690   g_variant_ensure_size (value);
 691   g_variant_unlock (value);
 692
 693   return value->size;
 694 }
 695
 696 /**
 697  * g_variant_get_data:
 698  * @value: a #GVariant instance
 699  * @returns: the serialised form of @value, or %NULL
 700  *
 701  * Returns a pointer to the serialised form of a #GVariant instance.
 702  * The returned data is in machine native byte order but may not be in
 703  * fully-normalised form if read from an untrusted source.  The returned
 704  * data must not be freed; it remains valid for as long as @value
 705  * exists.
 706  *
 707  * If @value is a fixed-sized value that was deserialised from a
 708  * corrupted serialised container then %NULL may be returned.  In this
 709  * case, the proper thing to do is typically to use the appropriate
 710  * number of nul bytes in place of @value.  If @value is not fixed-sized
 711  * then %NULL is never returned.
 712  *
 713  * In the case that @value is already in serialised form, this function
 714  * is O(1).  If the value is not already in serialised form,
 715  * serialisation occurs implicitly and is approximately O(n) in the size
 716  * of the result.
 717  **/
 718 gconstpointer
 719 g_variant_get_data (GVariant *value)
 720 {
 721   g_variant_lock (value);
 722   g_variant_ensure_serialised (value);
 723   g_variant_unlock (value);
 724
 725   return value->contents.serialised.data;
 726 }
 727
 728 /**
 729  * g_variant_n_children:
 730  * @value: a container #GVariant
 731  * @returns: the number of children in the container
 732  *
 733  * Determines the number of children in a container #GVariant instance.
 734  * This includes variants, maybes, arrays, tuples and dictionary
 735  * entries.  It is an error to call this function on any other type of
 736  * #GVariant.
 737  *
 738  * For variants, the return value is always 1.  For values with maybe
 739  * types, it is always zero or one.  For arrays, it is the length of the
 740  * array.  For tuples it is the number of tuple items (which depends
 741  * only on the type).  For dictionary entries, it is always 2
 742  *
 743  * This function is O(1).
 744  **/
 745 gsize
 746 g_variant_n_children (GVariant *value)
 747 {
 748   gsize n_children;
 749
 750   g_variant_lock (value);
 751
 752   if (value->state & STATE_SERIALISED)
 753     {
 754       GVariantSerialised serialised = {
 755         value->type_info,
 756         (gpointer) value->contents.serialised.data,
 757         value->size
 758       };
 759
 760       n_children = g_variant_serialised_n_children (serialised);
 761     }
 762   else
 763     n_children = value->contents.tree.n_children;
 764
 765   g_variant_unlock (value);
 766
 767   return n_children;
 768 }
 769
 770 /**
 771  * g_variant_get_child_value:
 772  * @value: a container #GVariant
 773  * @index_: the index of the child to fetch
 774  * @returns: the child at the specified index
 775  *
 776  * Reads a child item out of a container #GVariant instance.  This
 777  * includes variants, maybes, arrays, tuples and dictionary
 778  * entries.  It is an error to call this function on any other type of
 779  * #GVariant.
 780  *
 781  * It is an error if @index_ is greater than the number of child items
 782  * in the container.  See g_variant_n_children().
 783  *
 784  * This function is O(1).
 785  **/
 786 GVariant *
 787 g_variant_get_child_value (GVariant *value,
 788                            gsize     index_)
 789 {
 790   GVariant *child = NULL;
 791
 792   g_variant_lock (value);
 793
 794   if (value->state & STATE_SERIALISED)
 795     {
 796       GVariantSerialised serialised = {
 797         value->type_info,
 798         (gpointer) value->contents.serialised.data,
 799         value->size
 800       };
 801       GVariantSerialised s_child;
 802
 803       s_child = g_variant_serialised_get_child (serialised, index_);
 804
 805       child = g_slice_new (GVariant);
 806       child->type_info = s_child.type_info;
 807       child->state = (value->state & STATE_TRUSTED) |
 808                      STATE_SERIALISED;
 809       child->size = serialised.size;
 810       child->ref_count = 1;
 811       child->contents.serialised.buffer =
 812         g_buffer_ref (value->contents.serialised.buffer);
 813       child->contents.serialised.data = serialised.data;
 814      }
 815   else
 816     child = g_variant_ref (value->contents.tree.children[index_]);
 817
 818   g_variant_unlock (value);
 819
 820   return child;
 821 }
 822
 823 /**
 824  * g_variant_store:
 825  * @value: the #GVariant to store
 826  * @data: the location to store the serialised data at
 827  *
 828  * Stores the serialised form of @value at @data.  @data should be
 829  * large enough.  See g_variant_get_size().
 830  *
 831  * The stored data is in machine native byte order but may not be in
 832  * fully-normalised form if read from an untrusted source.  See
 833  * g_variant_normalise() for a solution.
 834  *
 835  * This function is approximately O(n) in the size of @data.
 836  **/
 837 void
 838 g_variant_store (GVariant *value,
 839                  gpointer  data)
 840 {
 841   g_variant_lock (value);
 842
 843   if (value->state & STATE_SERIALISED)
 844     {
 845       if (value->contents.serialised.data != NULL)
 846         memcpy (data, value->contents.serialised.data, value->size);
 847       else
 848         memset (data, 0, value->size);
 849     }
 850   else
 851     g_variant_serialise (value, data);
 852
 853   g_variant_unlock (value);
 854 }
 855
 856 #define __G_VARIANT_CORE_C__
 857 #include "galiasdef.c"