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  * Since: 2.24
  54  **/
  55 struct _GVariant
  56 /* see below for field member documentation */
  57 {
  58   GVariantTypeInfo *type_info;
  59   gsize size;
  60
  61   union
  62   {
  63     struct
  64     {
  65       GBuffer *buffer;
  66       gconstpointer data;
  67     } serialised;
  68
  69     struct
  70     {
  71       GVariant **children;
  72       gsize n_children;
  73     } tree;
  74   } contents;
  75
  76   gint state;
  77   gint ref_count;
  78 };
  79
  80 /* struct GVariant:
  81  *
  82  * There are two primary forms of GVariant instances: "serialised form"
  83  * and "tree form".
  84  *
  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.
  89  *
  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).
  94  *
  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.
  99  *
 100  *
 101  * The fields of the structure are documented here:
 102  *
 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().
 106  *
 107  *            The type_info field never changes during the life of the
 108  *            instance, so it can be accessed without a lock.
 109  *
 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
 119  *       the data.
 120  *
 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.
 125  *
 126  * contents: a union containing either the information associated with
 127  *           holding a value in serialised form or holding a value in
 128  *           tree form.
 129  *
 130  *   .serialised: Only valid when the instance is in serialised form.
 131  *
 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.
 136  *
 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().
 143  *
 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.
 147  *
 148  *            This pointer may be %NULL in two cases:
 149  *
 150  *              - if the serialised size of the instance is 0
 151  *
 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
 161  *                bytes.
 162  *
 163  *   .tree: Only valid when the instance is in tree form.
 164  *
 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'.
 169  *
 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
 174  *                g_free().
 175  *
 176  *     .n_children: the number of items in the .children array.
 177  *
 178  * state: a bitfield describing the state of the instance.  It is a
 179  *        bitwise-or of the following STATE_* constants:
 180  *
 181  *    STATE_LOCKED: the instance lock is held.  This is the bit used by
 182  *                  g_bit_lock().
 183  *
 184  *    STATE_SERIALISED: the instance is in serialised form.  If this
 185  *                      flag is not set then the instance is in tree
 186  *                      form.
 187  *
 188  *    STATE_TRUSTED: for serialised form instances, this means that the
 189  *                   serialised data is known to be in normal form (ie:
 190  *                   not corrupted).
 191  *
 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
 196  *                   normal form.
 197  *
 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().
 201  *
 202  *    STATE_FLOATING: if this flag is set then the object has a floating
 203  *                    reference.  See g_variant_ref_sink().
 204  *
 205  * ref_count: the reference count of the instance
 206  */
 207 #define STATE_LOCKED     1
 208 #define STATE_SERIALISED 2
 209 #define STATE_TRUSTED    4
 210 #define STATE_FLOATING   8
 211
 212 /* -- private -- */
 213 /* < private >
 214  * g_variant_lock:
 215  * @value: a #GVariant
 216  *
 217  * Locks @value for performing sensitive operations.
 218  */
 219 static void
 220 g_variant_lock (GVariant *value)
 221 {
 222   g_bit_lock (&value->state, 0);
 223 }
 224
 225 /* < private >
 226  * g_variant_unlock:
 227  * @value: a #GVariant
 228  *
 229  * Unlocks @value after performing sensitive operations.
 230  */
 231 static void
 232 g_variant_unlock (GVariant *value)
 233 {
 234   g_bit_unlock (&value->state, 0);
 235 }
 236
 237 /* < private >
 238  * g_variant_release_children:
 239  * @value: a #GVariant
 240  *
 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.
 243  *
 244  * This is done when freeing a tree-form instance or converting it to
 245  * serialised form.
 246  *
 247  * The current thread must hold the lock on @value.
 248  */
 249 static void
 250 g_variant_release_children (GVariant *value)
 251 {
 252   gsize i;
 253
 254   g_assert (value->state & STATE_LOCKED);
 255   g_assert (~value->state & STATE_SERIALISED);
 256
 257   for (i = 0; i < value->contents.tree.n_children; i++)
 258     g_variant_unref (value->contents.tree.children[i]);
 259
 260   g_free (value->contents.tree.children);
 261 }
 262
 263 /* This begins the main body of the recursive serialiser.
 264  *
 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.
 268  *
 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.
 275  *
 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().
 279  *
 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
 283  * buffer.
 284  *
 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.
 290  *
 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.
 294  *
 295  *   The serialiser uses the size information from the children to
 296  *   calculate the size needed for the entire container.
 297  *
 298  * Writing the data:
 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.
 303  *
 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().
 311  *
 312  *
 313  * The forward declaration here allows corecursion via callback:
 314  */
 315 static void g_variant_fill_gvs (GVariantSerialised *, gpointer);
 316
 317 /* < private >
 318  * g_variant_ensure_size:
 319  * @value: a #GVariant
 320  *
 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.
 324  *
 325  * The current thread must hold the lock on @value.
 326  */
 327 static void
 328 g_variant_ensure_size (GVariant *value)
 329 {
 330   g_assert (value->state & STATE_LOCKED);
 331
 332   if (value->size == (gssize) -1)
 333     {
 334       gpointer *children;
 335       gsize n_children;
 336
 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,
 340                                                       g_variant_fill_gvs,
 341                                                       children, n_children);
 342     }
 343 }
 344
 345 /* < private >
 346  * g_variant_serialise:
 347  * @value: a #GVariant
 348  * @data: an appropriately-sized buffer
 349  *
 350  * Serialises @value into @data.  @value must be in tree form.
 351  *
 352  * No change is made to @value.
 353  *
 354  * The current thread must hold the lock on @value.
 355  */
 356 static void
 357 g_variant_serialise (GVariant *value,
 358                      gpointer  data)
 359 {
 360   GVariantSerialised serialised = {  };
 361   gpointer *children;
 362   gsize n_children;
 363
 364   g_assert (~value->state & STATE_SERIALISED);
 365   g_assert (value->state & STATE_LOCKED);
 366
 367   serialised.type_info = value->type_info;
 368   serialised.size = value->size;
 369   serialised.data = data;
 370
 371   children = (gpointer *) value->contents.tree.children;
 372   n_children = value->contents.tree.n_children;
 373
 374   g_variant_serialiser_serialise (serialised, g_variant_fill_gvs,
 375                                   children, n_children);
 376 }
 377
 378 /* < private >
 379  * g_variant_fill_gvs:
 380  * @serialised: a pointer to a #GVariantSerialised
 381  * @data: a #GVariant instance
 382  *
 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
 386  * actions:
 387  *
 388  *  - reporting its type
 389  *
 390  *  - reporting its serialised size (requires knowing the size first)
 391  *
 392  *  - possibly storing its serialised form into the provided buffer
 393  */
 394 static void
 395 g_variant_fill_gvs (GVariantSerialised *serialised,
 396                     gpointer            data)
 397 {
 398   GVariant *value = data;
 399
 400   g_variant_lock (value);
 401   g_variant_ensure_size (value);
 402   g_variant_unlock (value);
 403
 404   if (serialised->type_info == NULL)
 405     serialised->type_info = value->type_info;
 406   g_assert (serialised->type_info == value->type_info);
 407
 408   if (serialised->size == 0)
 409     serialised->size = value->size;
 410   g_assert (serialised->size == value->size);
 411
 412   if (serialised->data)
 413     /* g_variant_store() is a public API, so it
 414      * it will reacquire the lock if it needs to.
 415      */
 416     g_variant_store (value, serialised->data);
 417 }
 418
 419 /* this ends the main body of the recursive serialiser */
 420
 421 /* < private >
 422  * g_variant_ensure_serialised:
 423  * @value: a #GVariant
 424  *
 425  * Ensures that @value is in serialised form.
 426  *
 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.
 432  *
 433  * The current thread must hold the lock on @value.
 434  */
 435 static void
 436 g_variant_ensure_serialised (GVariant *value)
 437 {
 438   g_assert (value->state & STATE_LOCKED);
 439
 440   if (~value->state & STATE_SERIALISED)
 441     {
 442       GBuffer *buffer;
 443       gpointer data;
 444
 445       g_variant_ensure_size (value);
 446       data = g_malloc (value->size);
 447       g_variant_serialise (value, data);
 448
 449       g_variant_release_children (value);
 450
 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;
 455     }
 456 }
 457
 458 /* < private >
 459  * g_variant_alloc:
 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
 464  *
 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.
 468  */
 469 static GVariant *
 470 g_variant_alloc (const GVariantType *type,
 471                  gboolean            serialised,
 472                  gboolean            trusted)
 473 {
 474   GVariant *value;
 475
 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) |
 480                  STATE_FLOATING;
 481   value->size = (gssize) -1;
 482   value->ref_count = 1;
 483
 484   return value;
 485 }
 486
 487 /* -- internal -- */
 488 /* < internal >
 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
 494  *
 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.
 498  *
 499  * A reference is taken on @buffer.
 500  */
 501 GVariant *
 502 g_variant_new_from_buffer (const GVariantType *type,
 503                            GBuffer            *buffer,
 504                            gboolean            trusted)
 505 {
 506   GVariant *value;
 507
 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;
 512
 513   return value;
 514 }
 515
 516 /* < internal >
 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
 523  *
 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.
 527  *
 528  * @children is consumed by this function.  g_free() will be called on
 529  * it some time later.
 530  */
 531 GVariant *
 532 g_variant_new_from_children (const GVariantType  *type,
 533                              GVariant           **children,
 534                              gsize                n_children,
 535                              gboolean             trusted)
 536 {
 537   GVariant *value;
 538
 539   value = g_variant_alloc (type, FALSE, trusted);
 540   value->contents.tree.children = children;
 541   value->contents.tree.n_children = n_children;
 542
 543   return value;
 544 }
 545
 546 /* < internal >
 547  * g_variant_get_type_info:
 548  * @value: a #GVariant
 549  * @returns: the #GVariantTypeInfo for @value
 550  *
 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.
 554  */
 555 GVariantTypeInfo *
 556 g_variant_get_type_info (GVariant *value)
 557 {
 558   return value->type_info;
 559 }
 560
 561 /* < internal >
 562  * g_variant_is_trusted:
 563  * @value: a #GVariant
 564  * @returns: if @value is trusted
 565  *
 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.
 570  *
 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.
 575  */
 576 gboolean
 577 g_variant_is_trusted (GVariant *value)
 578 {
 579   return (value->state & STATE_TRUSTED) != 0;
 580 }
 581
 582 /* -- public -- */
 583
 584 /**
 585  * g_variant_unref:
 586  * @value: a #GVariant
 587  *
 588  * Decreases the reference count of @value.  When its reference count
 589  * drops to 0, the memory used by the variant is freed.
 590  *
 591  * Since: 2.24
 592  **/
 593 void
 594 g_variant_unref (GVariant *value)
 595 {
 596   if (g_atomic_int_dec_and_test (&value->ref_count))
 597     {
 598       if G_UNLIKELY (value->state & STATE_LOCKED)
 599         g_critical ("attempting to free a locked GVariant instance.  "
 600                     "This should never happen.");
 601
 602       value->state |= STATE_LOCKED;
 603
 604       g_variant_type_info_unref (value->type_info);
 605
 606       if (value->state & STATE_SERIALISED)
 607         g_buffer_unref (value->contents.serialised.buffer);
 608       else
 609         g_variant_release_children (value);
 610
 611       g_slice_free (GVariant, value);
 612     }
 613 }
 614
 615 /**
 616  * g_variant_ref:
 617  * @value: a #GVariant
 618  * @returns: the same @value
 619  *
 620  * Increases the reference count of @value.
 621  *
 622  * Since: 2.24
 623  **/
 624 GVariant *
 625 g_variant_ref (GVariant *value)
 626 {
 627   g_atomic_int_inc (&value->ref_count);
 628
 629   return value;
 630 }
 631
 632 /**
 633  * g_variant_ref_sink:
 634  * @value: a #GVariant
 635  * @returns: the same @value
 636  *
 637  * #GVariant uses a floating reference count system.  All functions with
 638  * names starting with <literal>g_variant_new_</literal> return floating
 639  * references.
 640  *
 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.
 645  *
 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.
 650  *
 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
 658  * are not floating.
 659  *
 660  * Since: 2.24
 661  **/
 662 GVariant *
 663 g_variant_ref_sink (GVariant *value)
 664 {
 665   g_variant_lock (value);
 666
 667   if (~value->state & STATE_FLOATING)
 668     g_variant_ref (value);
 669   else
 670     value->state &= ~STATE_FLOATING;
 671
 672   g_variant_unlock (value);
 673
 674   return value;
 675 }
 676
 677 /**
 678  * g_variant_get_size:
 679  * @value: a #GVariant instance
 680  * @returns: the serialised size of @value
 681  *
 682  * Determines the number of bytes that would be required to store @value
 683  * with g_variant_store().
 684  *
 685  * If @value has a fixed-sized type then this function always returned
 686  * that fixed size.
 687  *
 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
 692  * involved.
 693  *
 694  * Since: 2.24
 695  **/
 696 gsize
 697 g_variant_get_size (GVariant *value)
 698 {
 699   g_variant_lock (value);
 700   g_variant_ensure_size (value);
 701   g_variant_unlock (value);
 702
 703   return value->size;
 704 }
 705
 706 /**
 707  * g_variant_get_data:
 708  * @value: a #GVariant instance
 709  * @returns: the serialised form of @value, or %NULL
 710  *
 711  * Returns a pointer to the serialised form of a #GVariant instance.
 712  * The returned data is in machine native byte order but may not be in
 713  * fully-normalised form if read from an untrusted source.  The returned
 714  * data must not be freed; it remains valid for as long as @value
 715  * exists.
 716  *
 717  * If @value is a fixed-sized value that was deserialised from a
 718  * corrupted serialised container then %NULL may be returned.  In this
 719  * case, the proper thing to do is typically to use the appropriate
 720  * number of nul bytes in place of @value.  If @value is not fixed-sized
 721  * then %NULL is never returned.
 722  *
 723  * In the case that @value is already in serialised form, this function
 724  * is O(1).  If the value is not already in serialised form,
 725  * serialisation occurs implicitly and is approximately O(n) in the size
 726  * of the result.
 727  *
 728  * Since: 2.24
 729  **/
 730 gconstpointer
 731 g_variant_get_data (GVariant *value)
 732 {
 733   g_variant_lock (value);
 734   g_variant_ensure_serialised (value);
 735   g_variant_unlock (value);
 736
 737   return value->contents.serialised.data;
 738 }
 739
 740 /**
 741  * g_variant_n_children:
 742  * @value: a container #GVariant
 743  * @returns: the number of children in the container
 744  *
 745  * Determines the number of children in a container #GVariant instance.
 746  * This includes variants, maybes, arrays, tuples and dictionary
 747  * entries.  It is an error to call this function on any other type of
 748  * #GVariant.
 749  *
 750  * For variants, the return value is always 1.  For values with maybe
 751  * types, it is always zero or one.  For arrays, it is the length of the
 752  * array.  For tuples it is the number of tuple items (which depends
 753  * only on the type).  For dictionary entries, it is always 2
 754  *
 755  * This function is O(1).
 756  *
 757  * Since: 2.24
 758  **/
 759 gsize
 760 g_variant_n_children (GVariant *value)
 761 {
 762   gsize n_children;
 763
 764   g_variant_lock (value);
 765
 766   if (value->state & STATE_SERIALISED)
 767     {
 768       GVariantSerialised serialised = {
 769         value->type_info,
 770         (gpointer) value->contents.serialised.data,
 771         value->size
 772       };
 773
 774       n_children = g_variant_serialised_n_children (serialised);
 775     }
 776   else
 777     n_children = value->contents.tree.n_children;
 778
 779   g_variant_unlock (value);
 780
 781   return n_children;
 782 }
 783
 784 /**
 785  * g_variant_get_child_value:
 786  * @value: a container #GVariant
 787  * @index_: the index of the child to fetch
 788  * @returns: the child at the specified index
 789  *
 790  * Reads a child item out of a container #GVariant instance.  This
 791  * includes variants, maybes, arrays, tuples and dictionary
 792  * entries.  It is an error to call this function on any other type of
 793  * #GVariant.
 794  *
 795  * It is an error if @index_ is greater than the number of child items
 796  * in the container.  See g_variant_n_children().
 797  *
 798  * This function is O(1).
 799  *
 800  * Since: 2.24
 801  **/
 802 GVariant *
 803 g_variant_get_child_value (GVariant *value,
 804                            gsize     index_)
 805 {
 806   GVariant *child = NULL;
 807
 808   g_variant_lock (value);
 809
 810   if (value->state & STATE_SERIALISED)
 811     {
 812       GVariantSerialised serialised = {
 813         value->type_info,
 814         (gpointer) value->contents.serialised.data,
 815         value->size
 816       };
 817       GVariantSerialised s_child;
 818
 819       /* get the serialiser to extract the serialised data for the child
 820        * from the serialised data for the container
 821        */
 822       s_child = g_variant_serialised_get_child (serialised, index_);
 823
 824       /* create a new serialised instance out of it */
 825       child = g_slice_new (GVariant);
 826       child->type_info = s_child.type_info;
 827       child->state = (value->state & STATE_TRUSTED) |
 828                      STATE_SERIALISED;
 829       child->size = s_child.size;
 830       child->ref_count = 1;
 831       child->contents.serialised.buffer =
 832         g_buffer_ref (value->contents.serialised.buffer);
 833       child->contents.serialised.data = s_child.data;
 834      }
 835   else
 836     child = g_variant_ref (value->contents.tree.children[index_]);
 837
 838   g_variant_unlock (value);
 839
 840   return child;
 841 }
 842
 843 /**
 844  * g_variant_store:
 845  * @value: the #GVariant to store
 846  * @data: the location to store the serialised data at
 847  *
 848  * Stores the serialised form of @value at @data.  @data should be
 849  * large enough.  See g_variant_get_size().
 850  *
 851  * The stored data is in machine native byte order but may not be in
 852  * fully-normalised form if read from an untrusted source.  See
 853  * g_variant_normalise() for a solution.
 854  *
 855  * This function is approximately O(n) in the size of @data.
 856  *
 857  * Since: 2.24
 858  **/
 859 void
 860 g_variant_store (GVariant *value,
 861                  gpointer  data)
 862 {
 863   g_variant_lock (value);
 864
 865   if (value->state & STATE_SERIALISED)
 866     {
 867       if (value->contents.serialised.data != NULL)
 868         memcpy (data, value->contents.serialised.data, value->size);
 869       else
 870         memset (data, 0, value->size);
 871     }
 872   else
 873     g_variant_serialise (value, data);
 874
 875   g_variant_unlock (value);
 876 }
 877
 878 #define __G_VARIANT_CORE_C__
 879 #include "galiasdef.c"