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
  33 /*
  34  * This file includes the structure definition for GVariant and a small
  35  * set of functions that are allowed to access the structure directly.
  36  *
  37  * This minimises the amount of code that can possibly touch a GVariant
  38  * structure directly to a few simple fundamental operations.  These few
  39  * operations are written to be completely threadsafe with respect to
  40  * all possible outside access.  This means that we only need to be
  41  * concerned about thread safety issues in this one small file.
  42  *
  43  * Most GVariant API functions are in gvariant.c.
  44  */
  45
  46 /**
  47  * GVariant:
  48  *
  49  * #GVariant is an opaque data structure and can only be accessed
  50  * using the following functions.
  51  *
  52  * Since: 2.24
  53  **/
  54 struct _GVariant
  55 /* see below for field member documentation */
  56 {
  57   GVariantTypeInfo *type_info;
  58   gsize size;
  59
  60   union
  61   {
  62     struct
  63     {
  64       GBuffer *buffer;
  65       gconstpointer data;
  66     } serialised;
  67
  68     struct
  69     {
  70       GVariant **children;
  71       gsize n_children;
  72     } tree;
  73   } contents;
  74
  75   gint state;
  76   gint ref_count;
  77 };
  78
  79 /* struct GVariant:
  80  *
  81  * There are two primary forms of GVariant instances: "serialised form"
  82  * and "tree form".
  83  *
  84  * "serialised form": A serialised GVariant instance stores its value in
  85  *                    the GVariant serialisation format.  All
  86  *                    basic-typed instances (ie: non-containers) are in
  87  *                    serialised format, as are some containers.
  88  *
  89  * "tree form": Some containers are in "tree form".  In this case,
  90  *              instead of containing the serialised data for the
  91  *              container, the instance contains an array of pointers to
  92  *              the child values of the container (thus forming a tree).
  93  *
  94  * It is possible for an instance to transition from tree form to
  95  * serialised form.  This happens, implicitly, if the serialised data is
  96  * requested (eg: via g_variant_get_data()).  Serialised form instances
  97  * never transition into tree form.
  98  *
  99  *
 100  * The fields of the structure are documented here:
 101  *
 102  * type_info: this is a reference to a GVariantTypeInfo describing the
 103  *            type of the instance.  When the instance is freed, this
 104  *            reference must be released with g_variant_type_info_unref().
 105  *
 106  *            The type_info field never changes during the life of the
 107  *            instance, so it can be accessed without a lock.
 108  *
 109  * size: this is the size of the serialised form for the instance, if it
 110  *       is known.  If the instance is in serialised form then it is, by
 111  *       definition, known.  If the instance is in tree form then it may
 112  *       be unknown (in which case it is -1).  It is possible for the
 113  *       size to be known when in tree form if, for example, the user
 114  *       has called g_variant_get_size() without calling
 115  *       g_variant_get_data().  Additionally, even when the user calls
 116  *       g_variant_get_data() the size of the data must first be
 117  *       determined so that a large enough buffer can be allocated for
 118  *       the data.
 119  *
 120  *       Once the size is known, it can never become unknown again.
 121  *       g_variant_ensure_size() is used to ensure that the size is in
 122  *       the known state -- it calculates the size if needed.  After
 123  *       that, the size field can be accessed without a lock.
 124  *
 125  * contents: a union containing either the information associated with
 126  *           holding a value in serialised form or holding a value in
 127  *           tree form.
 128  *
 129  *   .serialised: Only valid when the instance is in serialised form.
 130  *
 131  *                Since an instance can never transition away from
 132  *                serialised form, once these fields are set, they will
 133  *                never be changed.  It is therefore valid to access
 134  *                them without holding a lock.
 135  *
 136  *     .buffer: the #GBuffer that contains the memory pointed to by
 137  *              .data, or %NULL if .data is %NULL.  In the event that
 138  *              the instance was deserialised from another instance,
 139  *              then the buffer will be shared by both of them.  When
 140  *              the instance is freed, this reference must be released
 141  *              with g_buffer_unref().
 142  *
 143  *     .data: the serialised data (of size 'size') of the instance.
 144  *            This pointer should not be freed or modified in any way.
 145  *            #GBuffer is responsible for memory management.
 146  *
 147  *            This pointer may be %NULL in two cases:
 148  *
 149  *              - if the serialised size of the instance is 0
 150  *
 151  *              - if the instance is of a fixed-sized type and was
 152  *                deserialised out of a corrupted container such that
 153  *                the container contains too few bytes to point to the
 154  *                entire proper fixed-size of this instance.  In this
 155  *                case, 'size' will still be equal to the proper fixed
 156  *                size, but this pointer will be %NULL.  This is exactly
 157  *                the reason that g_variant_get_data() sometimes returns
 158  *                %NULL.  For all other calls, the effect should be as
 159  *                if .data pointed to the appropriate number of nul
 160  *                bytes.
 161  *
 162  *   .tree: Only valid when the instance is in tree form.
 163  *
 164  *          Note that accesses from other threads could result in
 165  *          conversion of the instance from tree form to serialised form
 166  *          at any time.  For this reason, the instance lock must always
 167  *          be held while performing any operations on 'contents.tree'.
 168  *
 169  *     .children: the array of the child instances of this instance.
 170  *                When the instance is freed (or converted to serialised
 171  *                form) then each child must have g_variant_unref()
 172  *                called on it and the array must be freed using
 173  *                g_free().
 174  *
 175  *     .n_children: the number of items in the .children array.
 176  *
 177  * state: a bitfield describing the state of the instance.  It is a
 178  *        bitwise-or of the following STATE_* constants:
 179  *
 180  *    STATE_LOCKED: the instance lock is held.  This is the bit used by
 181  *                  g_bit_lock().
 182  *
 183  *    STATE_SERIALISED: the instance is in serialised form.  If this
 184  *                      flag is not set then the instance is in tree
 185  *                      form.
 186  *
 187  *    STATE_TRUSTED: for serialised form instances, this means that the
 188  *                   serialised data is known to be in normal form (ie:
 189  *                   not corrupted).
 190  *
 191  *                   For tree form instances, this means that all of the
 192  *                   child instances in the contents.tree.children array
 193  *                   are trusted.  This means that if the container is
 194  *                   serialised then the resulting data will be in
 195  *                   normal form.
 196  *
 197  *                   If this flag is unset it does not imply that the
 198  *                   data is corrupted.  It merely means that we're not
 199  *                   sure that it's valid.  See g_variant_is_trusted().
 200  *
 201  *    STATE_FLOATING: if this flag is set then the object has a floating
 202  *                    reference.  See g_variant_ref_sink().
 203  *
 204  * ref_count: the reference count of the instance
 205  */
 206 #define STATE_LOCKED     1
 207 #define STATE_SERIALISED 2
 208 #define STATE_TRUSTED    4
 209 #define STATE_FLOATING   8
 210
 211 /* -- private -- */
 212 /* < private >
 213  * g_variant_lock:
 214  * @value: a #GVariant
 215  *
 216  * Locks @value for performing sensitive operations.
 217  */
 218 static void
 219 g_variant_lock (GVariant *value)
 220 {
 221   g_bit_lock (&value->state, 0);
 222 }
 223
 224 /* < private >
 225  * g_variant_unlock:
 226  * @value: a #GVariant
 227  *
 228  * Unlocks @value after performing sensitive operations.
 229  */
 230 static void
 231 g_variant_unlock (GVariant *value)
 232 {
 233   g_bit_unlock (&value->state, 0);
 234 }
 235
 236 /* < private >
 237  * g_variant_release_children:
 238  * @value: a #GVariant
 239  *
 240  * Releases the reference held on each child in the 'children' array of
 241  * @value and frees the array itself.  @value must be in tree form.
 242  *
 243  * This is done when freeing a tree-form instance or converting it to
 244  * serialised form.
 245  *
 246  * The current thread must hold the lock on @value.
 247  */
 248 static void
 249 g_variant_release_children (GVariant *value)
 250 {
 251   gsize i;
 252
 253   g_assert (value->state & STATE_LOCKED);
 254   g_assert (~value->state & STATE_SERIALISED);
 255
 256   for (i = 0; i < value->contents.tree.n_children; i++)
 257     g_variant_unref (value->contents.tree.children[i]);
 258
 259   g_free (value->contents.tree.children);
 260 }
 261
 262 /* This begins the main body of the recursive serialiser.
 263  *
 264  * There are 3 functions here that work as a team with the serialiser to
 265  * get things done.  g_variant_store() has a trivial role, but as a
 266  * public API function, it has its definition elsewhere.
 267  *
 268  * Note that "serialisation" of an instance does not mean that the
 269  * instance is converted to serialised form -- it means that the
 270  * serialised form of an instance is written to an external buffer.
 271  * g_variant_ensure_serialised() (which is not part of this set of
 272  * functions) is the function that is responsible for converting an
 273  * instance to serialised form.
 274  *
 275  * We are only concerned here with container types since non-container
 276  * instances are always in serialised form.  For these instances,
 277  * storing their serialised form merely involves a memcpy().
 278  *
 279  * Serialisation is a two-step process.  First, the size of the
 280  * serialised data must be calculated so that an appropriately-sized
 281  * buffer can be allocated.  Second, the data is written into the
 282  * buffer.
 283  *
 284  * Determining the size:
 285  *   The process of determining the size is triggered by a call to
 286  *   g_variant_ensure_size() on a container.  This invokes the
 287  *   serialiser code to determine the size.  The serialiser is passed
 288  *   g_variant_fill_gvs() as a callback.
 289  *
 290  *   g_variant_fill_gvs() is called by the serialiser on each child of
 291  *   the container which, in turn, calls g_variant_ensure_size() on
 292  *   itself and fills in the result of its own size calculation.
 293  *
 294  *   The serialiser uses the size information from the children to
 295  *   calculate the size needed for the entire container.
 296  *
 297  * Writing the data:
 298  *   After the buffer has been allocated, g_variant_serialise() is
 299  *   called on the container.  This invokes the serialiser code to write
 300  *   the bytes to the container.  The serialiser is, again, passed
 301  *   g_variant_fill_gvs() as a callback.
 302  *
 303  *   This time, when g_variant_fill_gvs() is called for each child, the
 304  *   child is given a pointer to a sub-region of the allocated buffer
 305  *   where it should write its data.  This is done by calling
 306  *   g_variant_store().  In the event that the instance is in serialised
 307  *   form this means a memcpy() of the serialised data into the
 308  *   allocated buffer.  In the event that the instance is in tree form
 309  *   this means a recursive call back into g_variant_serialise().
 310  *
 311  *
 312  * The forward declaration here allows corecursion via callback:
 313  */
 314 static void g_variant_fill_gvs (GVariantSerialised *, gpointer);
 315
 316 /* < private >
 317  * g_variant_ensure_size:
 318  * @value: a #GVariant
 319  *
 320  * Ensures that the ->size field of @value is filled in properly.  This
 321  * must be done as a precursor to any serialisation of the value in
 322  * order to know how large of a buffer is needed to store the data.
 323  *
 324  * The current thread must hold the lock on @value.
 325  */
 326 static void
 327 g_variant_ensure_size (GVariant *value)
 328 {
 329   g_assert (value->state & STATE_LOCKED);
 330
 331   if (value->size == (gssize) -1)
 332     {
 333       gpointer *children;
 334       gsize n_children;
 335
 336       children = (gpointer *) value->contents.tree.children;
 337       n_children = value->contents.tree.n_children;
 338       value->size = g_variant_serialiser_needed_size (value->type_info,
 339                                                       g_variant_fill_gvs,
 340                                                       children, n_children);
 341     }
 342 }
 343
 344 /* < private >
 345  * g_variant_serialise:
 346  * @value: a #GVariant
 347  * @data: an appropriately-sized buffer
 348  *
 349  * Serialises @value into @data.  @value must be in tree form.
 350  *
 351  * No change is made to @value.
 352  *
 353  * The current thread must hold the lock on @value.
 354  */
 355 static void
 356 g_variant_serialise (GVariant *value,
 357                      gpointer  data)
 358 {
 359   GVariantSerialised serialised = { 0, };
 360   gpointer *children;
 361   gsize n_children;
 362
 363   g_assert (~value->state & STATE_SERIALISED);
 364   g_assert (value->state & STATE_LOCKED);
 365
 366   serialised.type_info = value->type_info;
 367   serialised.size = value->size;
 368   serialised.data = data;
 369
 370   children = (gpointer *) value->contents.tree.children;
 371   n_children = value->contents.tree.n_children;
 372
 373   g_variant_serialiser_serialise (serialised, g_variant_fill_gvs,
 374                                   children, n_children);
 375 }
 376
 377 /* < private >
 378  * g_variant_fill_gvs:
 379  * @serialised: a pointer to a #GVariantSerialised
 380  * @data: a #GVariant instance
 381  *
 382  * This is the callback that is passed by a tree-form container instance
 383  * to the serialiser.  This callback gets called on each child of the
 384  * container.  Each child is responsible for performing the following
 385  * actions:
 386  *
 387  *  - reporting its type
 388  *
 389  *  - reporting its serialised size (requires knowing the size first)
 390  *
 391  *  - possibly storing its serialised form into the provided buffer
 392  */
 393 static void
 394 g_variant_fill_gvs (GVariantSerialised *serialised,
 395                     gpointer            data)
 396 {
 397   GVariant *value = data;
 398
 399   g_variant_lock (value);
 400   g_variant_ensure_size (value);
 401   g_variant_unlock (value);
 402
 403   if (serialised->type_info == NULL)
 404     serialised->type_info = value->type_info;
 405   g_assert (serialised->type_info == value->type_info);
 406
 407   if (serialised->size == 0)
 408     serialised->size = value->size;
 409   g_assert (serialised->size == value->size);
 410
 411   if (serialised->data)
 412     /* g_variant_store() is a public API, so it
 413      * it will reacquire the lock if it needs to.
 414      */
 415     g_variant_store (value, serialised->data);
 416 }
 417
 418 /* this ends the main body of the recursive serialiser */
 419
 420 /* < private >
 421  * g_variant_ensure_serialised:
 422  * @value: a #GVariant
 423  *
 424  * Ensures that @value is in serialised form.
 425  *
 426  * If @value is in tree form then this function ensures that the
 427  * serialised size is known and then allocates a buffer of that size and
 428  * serialises the instance into the buffer.  The 'children' array is
 429  * then released and the instance is set to serialised form based on the
 430  * contents of the buffer.
 431  *
 432  * The current thread must hold the lock on @value.
 433  */
 434 static void
 435 g_variant_ensure_serialised (GVariant *value)
 436 {
 437   g_assert (value->state & STATE_LOCKED);
 438
 439   if (~value->state & STATE_SERIALISED)
 440     {
 441       GBuffer *buffer;
 442       gpointer data;
 443
 444       g_variant_ensure_size (value);
 445       data = g_malloc (value->size);
 446       g_variant_serialise (value, data);
 447
 448       g_variant_release_children (value);
 449
 450       buffer = g_buffer_new_take_data (data, value->size);
 451       value->contents.serialised.data = buffer->data;
 452       value->contents.serialised.buffer = buffer;
 453       value->state |= STATE_SERIALISED;
 454     }
 455 }
 456
 457 /* < private >
 458  * g_variant_alloc:
 459  * @type: the type of the new instance
 460  * @serialised: if the instance will be in serialised form
 461  * @trusted: if the instance will be trusted
 462  * @returns: a new #GVariant with a floating reference
 463  *
 464  * Allocates a #GVariant instance and does some common work (such as
 465  * looking up and filling in the type info), setting the state field,
 466  * and setting the ref_count to 1.
 467  */
 468 static GVariant *
 469 g_variant_alloc (const GVariantType *type,
 470                  gboolean            serialised,
 471                  gboolean            trusted)
 472 {
 473   GVariant *value;
 474
 475   value = g_slice_new (GVariant);
 476   value->type_info = g_variant_type_info_get (type);
 477   value->state = (serialised ? STATE_SERIALISED : 0) |
 478                  (trusted ? STATE_TRUSTED : 0) |
 479                  STATE_FLOATING;
 480   value->size = (gssize) -1;
 481   value->ref_count = 1;
 482
 483   return value;
 484 }
 485
 486 /* -- internal -- */
 487 /* < internal >
 488  * g_variant_new_from_buffer:
 489  * @type: a #GVariantType
 490  * @buffer: a #GBuffer
 491  * @trusted: if the contents of @buffer are trusted
 492  * @returns: a new #GVariant with a floating reference
 493  *
 494  * Constructs a new serialised-mode #GVariant instance.  This is the
 495  * inner interface for creation of new serialised values that gets
 496  * called from various functions in gvariant.c.
 497  *
 498  * A reference is taken on @buffer.
 499  */
 500 GVariant *
 501 g_variant_new_from_buffer (const GVariantType *type,
 502                            GBuffer            *buffer,
 503                            gboolean            trusted)
 504 {
 505   GVariant *value;
 506
 507   value = g_variant_alloc (type, TRUE, trusted);
 508   value->contents.serialised.buffer = g_buffer_ref (buffer);
 509   value->contents.serialised.data = buffer->data;
 510   value->size = buffer->size;
 511
 512   return value;
 513 }
 514
 515 /* < internal >
 516  * g_variant_new_from_children:
 517  * @type: a #GVariantType
 518  * @children: an array of #GVariant pointers.  Consumed.
 519  * @n_children: the length of @children
 520  * @trusted: %TRUE if every child in @children in trusted
 521  * @returns: a new #GVariant with a floating reference
 522  *
 523  * Constructs a new tree-mode #GVariant instance.  This is the inner
 524  * interface for creation of new serialised values that gets called from
 525  * various functions in gvariant.c.
 526  *
 527  * @children is consumed by this function.  g_free() will be called on
 528  * it some time later.
 529  */
 530 GVariant *
 531 g_variant_new_from_children (const GVariantType  *type,
 532                              GVariant           **children,
 533                              gsize                n_children,
 534                              gboolean             trusted)
 535 {
 536   GVariant *value;
 537
 538   value = g_variant_alloc (type, FALSE, trusted);
 539   value->contents.tree.children = children;
 540   value->contents.tree.n_children = n_children;
 541
 542   return value;
 543 }
 544
 545 /* < internal >
 546  * g_variant_get_type_info:
 547  * @value: a #GVariant
 548  * @returns: the #GVariantTypeInfo for @value
 549  *
 550  * Returns the #GVariantTypeInfo corresponding to the type of @value.  A
 551  * reference is not added, so the return value is only good for the
 552  * duration of the life of @value.
 553  */
 554 GVariantTypeInfo *
 555 g_variant_get_type_info (GVariant *value)
 556 {
 557   return value->type_info;
 558 }
 559
 560 /* < internal >
 561  * g_variant_is_trusted:
 562  * @value: a #GVariant
 563  * @returns: if @value is trusted
 564  *
 565  * Determines if @value is trusted by #GVariant to contain only
 566  * fully-valid data.  All values constructed solely via #GVariant APIs
 567  * are trusted, but values containing data read in from other sources
 568  * are usually not trusted.
 569  *
 570  * The main advantage of trusted data is that certain checks can be
 571  * skipped.  For example, we don't need to check that a string is
 572  * properly nul-terminated or that an object path is actually a
 573  * properly-formatted object path.
 574  */
 575 gboolean
 576 g_variant_is_trusted (GVariant *value)
 577 {
 578   return (value->state & STATE_TRUSTED) != 0;
 579 }
 580
 581 /* -- public -- */
 582
 583 /**
 584  * g_variant_unref:
 585  * @value: a #GVariant
 586  *
 587  * Decreases the reference count of @value.  When its reference count
 588  * drops to 0, the memory used by the variant is freed.
 589  *
 590  * Since: 2.24
 591  **/
 592 void
 593 g_variant_unref (GVariant *value)
 594 {
 595   if (g_atomic_int_dec_and_test (&value->ref_count))
 596     {
 597       if G_UNLIKELY (value->state & STATE_LOCKED)
 598         g_critical ("attempting to free a locked GVariant instance.  "
 599                     "This should never happen.");
 600
 601       value->state |= STATE_LOCKED;
 602
 603       g_variant_type_info_unref (value->type_info);
 604
 605       if (value->state & STATE_SERIALISED)
 606         g_buffer_unref (value->contents.serialised.buffer);
 607       else
 608         g_variant_release_children (value);
 609
 610       g_slice_free (GVariant, value);
 611     }
 612 }
 613
 614 /**
 615  * g_variant_ref:
 616  * @value: a #GVariant
 617  * @returns: the same @value
 618  *
 619  * Increases the reference count of @value.
 620  *
 621  * Since: 2.24
 622  **/
 623 GVariant *
 624 g_variant_ref (GVariant *value)
 625 {
 626   g_atomic_int_inc (&value->ref_count);
 627
 628   return value;
 629 }
 630
 631 /**
 632  * g_variant_ref_sink:
 633  * @value: a #GVariant
 634  * @returns: the same @value
 635  *
 636  * #GVariant uses a floating reference count system.  All functions with
 637  * names starting with <literal>g_variant_new_</literal> return floating
 638  * references.
 639  *
 640  * Calling g_variant_ref_sink() on a #GVariant with a floating reference
 641  * will convert the floating reference into a full reference.  Calling
 642  * g_variant_ref_sink() on a non-floating #GVariant results in an
 643  * additional normal reference being added.
 644  *
 645  * In other words, if the @value is floating, then this call "assumes
 646  * ownership" of the floating reference, converting it to a normal
 647  * reference.  If the @value is not floating, then this call adds a
 648  * new normal reference increasing the reference count by one.
 649  *
 650  * All calls that result in a #GVariant instance being inserted into a
 651  * container will call g_variant_ref_sink() on the instance.  This means
 652  * that if the value was just created (and has only its floating
 653  * reference) then the container will assume sole ownership of the value
 654  * at that point and the caller will not need to unreference it.  This
 655  * makes certain common styles of programming much easier while still
 656  * maintaining normal refcounting semantics in situations where values
 657  * are not floating.
 658  *
 659  * Since: 2.24
 660  **/
 661 GVariant *
 662 g_variant_ref_sink (GVariant *value)
 663 {
 664   g_variant_lock (value);
 665
 666   if (~value->state & STATE_FLOATING)
 667     g_variant_ref (value);
 668   else
 669     value->state &= ~STATE_FLOATING;
 670
 671   g_variant_unlock (value);
 672
 673   return value;
 674 }
 675
 676 /**
 677  * g_variant_is_floating:
 678  * @value: a #GVariant
 679  * @returns: whether @value is floating
 680  *
 681  * Checks whether @value has a floating reference count.
 682  *
 683  * This function should only ever be used to assert that a given variant
 684  * is or is not floating, or for debug purposes. To acquire a reference
 685  * to a variant that might be floating, always use g_variant_ref_sink().
 686  *
 687  * See g_variant_ref_sink() for more information about floating reference
 688  * counts.
 689  *
 690  * Since: 2.26
 691  **/
 692 gboolean
 693 g_variant_is_floating (GVariant *value)
 694 {
 695   g_return_val_if_fail (value != NULL, FALSE);
 696
 697   return (value->state & STATE_FLOATING) != 0;
 698 }
 699
 700 /**
 701  * g_variant_get_size:
 702  * @value: a #GVariant instance
 703  * @returns: the serialised size of @value
 704  *
 705  * Determines the number of bytes that would be required to store @value
 706  * with g_variant_store().
 707  *
 708  * If @value has a fixed-sized type then this function always returned
 709  * that fixed size.
 710  *
 711  * In the case that @value is already in serialised form or the size has
 712  * already been calculated (ie: this function has been called before)
 713  * then this function is O(1).  Otherwise, the size is calculated, an
 714  * operation which is approximately O(n) in the number of values
 715  * involved.
 716  *
 717  * Since: 2.24
 718  **/
 719 gsize
 720 g_variant_get_size (GVariant *value)
 721 {
 722   g_variant_lock (value);
 723   g_variant_ensure_size (value);
 724   g_variant_unlock (value);
 725
 726   return value->size;
 727 }
 728
 729 /**
 730  * g_variant_get_data:
 731  * @value: a #GVariant instance
 732  * @returns: the serialised form of @value, or %NULL
 733  *
 734  * Returns a pointer to the serialised form of a #GVariant instance.
 735  * The returned data may not be in fully-normalised form if read from an
 736  * untrusted source.  The returned data must not be freed; it remains
 737  * valid for as long as @value exists.
 738  *
 739  * If @value is a fixed-sized value that was deserialised from a
 740  * corrupted serialised container then %NULL may be returned.  In this
 741  * case, the proper thing to do is typically to use the appropriate
 742  * number of nul bytes in place of @value.  If @value is not fixed-sized
 743  * then %NULL is never returned.
 744  *
 745  * In the case that @value is already in serialised form, this function
 746  * is O(1).  If the value is not already in serialised form,
 747  * serialisation occurs implicitly and is approximately O(n) in the size
 748  * of the result.
 749  *
 750  * Since: 2.24
 751  **/
 752 gconstpointer
 753 g_variant_get_data (GVariant *value)
 754 {
 755   g_variant_lock (value);
 756   g_variant_ensure_serialised (value);
 757   g_variant_unlock (value);
 758
 759   return value->contents.serialised.data;
 760 }
 761
 762 /**
 763  * g_variant_n_children:
 764  * @value: a container #GVariant
 765  * @returns: the number of children in the container
 766  *
 767  * Determines the number of children in a container #GVariant instance.
 768  * This includes variants, maybes, arrays, tuples and dictionary
 769  * entries.  It is an error to call this function on any other type of
 770  * #GVariant.
 771  *
 772  * For variants, the return value is always 1.  For values with maybe
 773  * types, it is always zero or one.  For arrays, it is the length of the
 774  * array.  For tuples it is the number of tuple items (which depends
 775  * only on the type).  For dictionary entries, it is always 2
 776  *
 777  * This function is O(1).
 778  *
 779  * Since: 2.24
 780  **/
 781 gsize
 782 g_variant_n_children (GVariant *value)
 783 {
 784   gsize n_children;
 785
 786   g_variant_lock (value);
 787
 788   if (value->state & STATE_SERIALISED)
 789     {
 790       GVariantSerialised serialised = {
 791         value->type_info,
 792         (gpointer) value->contents.serialised.data,
 793         value->size
 794       };
 795
 796       n_children = g_variant_serialised_n_children (serialised);
 797     }
 798   else
 799     n_children = value->contents.tree.n_children;
 800
 801   g_variant_unlock (value);
 802
 803   return n_children;
 804 }
 805
 806 /**
 807  * g_variant_get_child_value:
 808  * @value: a container #GVariant
 809  * @index_: the index of the child to fetch
 810  * @returns: the child at the specified index
 811  *
 812  * Reads a child item out of a container #GVariant instance.  This
 813  * includes variants, maybes, arrays, tuples and dictionary
 814  * entries.  It is an error to call this function on any other type of
 815  * #GVariant.
 816  *
 817  * It is an error if @index_ is greater than the number of child items
 818  * in the container.  See g_variant_n_children().
 819  *
 820  * This function is O(1).
 821  *
 822  * Since: 2.24
 823  **/
 824 GVariant *
 825 g_variant_get_child_value (GVariant *value,
 826                            gsize     index_)
 827 {
 828   GVariant *child = NULL;
 829
 830   g_variant_lock (value);
 831
 832   if (value->state & STATE_SERIALISED)
 833     {
 834       GVariantSerialised serialised = {
 835         value->type_info,
 836         (gpointer) value->contents.serialised.data,
 837         value->size
 838       };
 839       GVariantSerialised s_child;
 840
 841       /* get the serialiser to extract the serialised data for the child
 842        * from the serialised data for the container
 843        */
 844       s_child = g_variant_serialised_get_child (serialised, index_);
 845
 846       /* create a new serialised instance out of it */
 847       child = g_slice_new (GVariant);
 848       child->type_info = s_child.type_info;
 849       child->state = (value->state & STATE_TRUSTED) |
 850                      STATE_SERIALISED;
 851       child->size = s_child.size;
 852       child->ref_count = 1;
 853       child->contents.serialised.buffer =
 854         g_buffer_ref (value->contents.serialised.buffer);
 855       child->contents.serialised.data = s_child.data;
 856      }
 857   else
 858     child = g_variant_ref (value->contents.tree.children[index_]);
 859
 860   g_variant_unlock (value);
 861
 862   return child;
 863 }
 864
 865 /**
 866  * g_variant_store:
 867  * @value: the #GVariant to store
 868  * @data: the location to store the serialised data at
 869  *
 870  * Stores the serialised form of @value at @data.  @data should be
 871  * large enough.  See g_variant_get_size().
 872  *
 873  * The stored data is in machine native byte order but may not be in
 874  * fully-normalised form if read from an untrusted source.  See
 875  * g_variant_normalise() for a solution.
 876  *
 877  * This function is approximately O(n) in the size of @data.
 878  *
 879  * Since: 2.24
 880  **/
 881 void
 882 g_variant_store (GVariant *value,
 883                  gpointer  data)
 884 {
 885   g_variant_lock (value);
 886
 887   if (value->state & STATE_SERIALISED)
 888     {
 889       if (value->contents.serialised.data != NULL)
 890         memcpy (data, value->contents.serialised.data, value->size);
 891       else
 892         memset (data, 0, value->size);
 893     }
 894   else
 895     g_variant_serialise (value, data);
 896
 897   g_variant_unlock (value);
 898 }
 899
 900 /**
 901  * g_variant_is_normal_form:
 902  * @value: a #GVariant instance
 903  * @returns: %TRUE if @value is in normal form
 904  *
 905  * Checks if @value is in normal form.
 906  *
 907  * The main reason to do this is to detect if a given chunk of
 908  * serialised data is in normal form: load the data into a #GVariant
 909  * using g_variant_create_from_data() and then use this function to
 910  * check.
 911  *
 912  * If @value is found to be in normal form then it will be marked as
 913  * being trusted.  If the value was already marked as being trusted then
 914  * this function will immediately return %TRUE.
 915  *
 916  * Since: 2.24
 917  **/
 918 gboolean
 919 g_variant_is_normal_form (GVariant *value)
 920 {
 921   if (value->state & STATE_TRUSTED)
 922     return TRUE;
 923
 924   g_variant_lock (value);
 925
 926   if (value->state & STATE_SERIALISED)
 927     {
 928       GVariantSerialised serialised = {
 929         value->type_info,
 930         (gpointer) value->contents.serialised.data,
 931         value->size
 932       };
 933
 934       if (g_variant_serialised_is_normal (serialised))
 935         value->state |= STATE_TRUSTED;
 936     }
 937   else
 938     {
 939       gboolean normal = TRUE;
 940       gsize i;
 941
 942       for (i = 0; i < value->contents.tree.n_children; i++)
 943         normal &= g_variant_is_normal_form (value->contents.tree.children[i]);
 944
 945       if (normal)
 946         value->state |= STATE_TRUSTED;
 947     }
 948
 949   g_variant_unlock (value);
 950
 951   return (value->state & STATE_TRUSTED) != 0;
 952 }