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   guint alignment;
 507   gsize size;
 508
 509   value = g_variant_alloc (type, TRUE, trusted);
 510
 511   value->contents.serialised.buffer = g_buffer_ref (buffer);
 512
 513   g_variant_type_info_query (value->type_info,
 514                              &alignment, &size);
 515
 516   if (size && buffer->size != size)
 517     {
 518       /* Creating a fixed-sized GVariant with a buffer of the wrong
 519        * size.
 520        *
 521        * We should do the equivalent of pulling a fixed-sized child out
 522        * of a brozen container (ie: data is NULL size is equal to the correct
 523        * fixed size).
 524        */
 525       value->contents.serialised.data = NULL;
 526       value->size = size;
 527     }
 528   else
 529     {
 530       value->contents.serialised.data = buffer->data;
 531       value->size = buffer->size;
 532     }
 533
 534   return value;
 535 }
 536
 537 /* < internal >
 538  * g_variant_new_from_children:
 539  * @type: a #GVariantType
 540  * @children: an array of #GVariant pointers.  Consumed.
 541  * @n_children: the length of @children
 542  * @trusted: %TRUE if every child in @children in trusted
 543  * @returns: a new #GVariant with a floating reference
 544  *
 545  * Constructs a new tree-mode #GVariant instance.  This is the inner
 546  * interface for creation of new serialised values that gets called from
 547  * various functions in gvariant.c.
 548  *
 549  * @children is consumed by this function.  g_free() will be called on
 550  * it some time later.
 551  */
 552 GVariant *
 553 g_variant_new_from_children (const GVariantType  *type,
 554                              GVariant           **children,
 555                              gsize                n_children,
 556                              gboolean             trusted)
 557 {
 558   GVariant *value;
 559
 560   value = g_variant_alloc (type, FALSE, trusted);
 561   value->contents.tree.children = children;
 562   value->contents.tree.n_children = n_children;
 563
 564   return value;
 565 }
 566
 567 /* < internal >
 568  * g_variant_get_type_info:
 569  * @value: a #GVariant
 570  * @returns: the #GVariantTypeInfo for @value
 571  *
 572  * Returns the #GVariantTypeInfo corresponding to the type of @value.  A
 573  * reference is not added, so the return value is only good for the
 574  * duration of the life of @value.
 575  */
 576 GVariantTypeInfo *
 577 g_variant_get_type_info (GVariant *value)
 578 {
 579   return value->type_info;
 580 }
 581
 582 /* < internal >
 583  * g_variant_is_trusted:
 584  * @value: a #GVariant
 585  * @returns: if @value is trusted
 586  *
 587  * Determines if @value is trusted by #GVariant to contain only
 588  * fully-valid data.  All values constructed solely via #GVariant APIs
 589  * are trusted, but values containing data read in from other sources
 590  * are usually not trusted.
 591  *
 592  * The main advantage of trusted data is that certain checks can be
 593  * skipped.  For example, we don't need to check that a string is
 594  * properly nul-terminated or that an object path is actually a
 595  * properly-formatted object path.
 596  */
 597 gboolean
 598 g_variant_is_trusted (GVariant *value)
 599 {
 600   return (value->state & STATE_TRUSTED) != 0;
 601 }
 602
 603 /* -- public -- */
 604
 605 /**
 606  * g_variant_unref:
 607  * @value: a #GVariant
 608  *
 609  * Decreases the reference count of @value.  When its reference count
 610  * drops to 0, the memory used by the variant is freed.
 611  *
 612  * Since: 2.24
 613  **/
 614 void
 615 g_variant_unref (GVariant *value)
 616 {
 617   if (g_atomic_int_dec_and_test (&value->ref_count))
 618     {
 619       if G_UNLIKELY (value->state & STATE_LOCKED)
 620         g_critical ("attempting to free a locked GVariant instance.  "
 621                     "This should never happen.");
 622
 623       value->state |= STATE_LOCKED;
 624
 625       g_variant_type_info_unref (value->type_info);
 626
 627       if (value->state & STATE_SERIALISED)
 628         g_buffer_unref (value->contents.serialised.buffer);
 629       else
 630         g_variant_release_children (value);
 631
 632       g_slice_free (GVariant, value);
 633     }
 634 }
 635
 636 /**
 637  * g_variant_ref:
 638  * @value: a #GVariant
 639  * @returns: the same @value
 640  *
 641  * Increases the reference count of @value.
 642  *
 643  * Since: 2.24
 644  **/
 645 GVariant *
 646 g_variant_ref (GVariant *value)
 647 {
 648   g_atomic_int_inc (&value->ref_count);
 649
 650   return value;
 651 }
 652
 653 /**
 654  * g_variant_ref_sink:
 655  * @value: a #GVariant
 656  * @returns: the same @value
 657  *
 658  * #GVariant uses a floating reference count system.  All functions with
 659  * names starting with <literal>g_variant_new_</literal> return floating
 660  * references.
 661  *
 662  * Calling g_variant_ref_sink() on a #GVariant with a floating reference
 663  * will convert the floating reference into a full reference.  Calling
 664  * g_variant_ref_sink() on a non-floating #GVariant results in an
 665  * additional normal reference being added.
 666  *
 667  * In other words, if the @value is floating, then this call "assumes
 668  * ownership" of the floating reference, converting it to a normal
 669  * reference.  If the @value is not floating, then this call adds a
 670  * new normal reference increasing the reference count by one.
 671  *
 672  * All calls that result in a #GVariant instance being inserted into a
 673  * container will call g_variant_ref_sink() on the instance.  This means
 674  * that if the value was just created (and has only its floating
 675  * reference) then the container will assume sole ownership of the value
 676  * at that point and the caller will not need to unreference it.  This
 677  * makes certain common styles of programming much easier while still
 678  * maintaining normal refcounting semantics in situations where values
 679  * are not floating.
 680  *
 681  * Since: 2.24
 682  **/
 683 GVariant *
 684 g_variant_ref_sink (GVariant *value)
 685 {
 686   g_variant_lock (value);
 687
 688   if (~value->state & STATE_FLOATING)
 689     g_variant_ref (value);
 690   else
 691     value->state &= ~STATE_FLOATING;
 692
 693   g_variant_unlock (value);
 694
 695   return value;
 696 }
 697
 698 /**
 699  * g_variant_is_floating:
 700  * @value: a #GVariant
 701  * @returns: whether @value is floating
 702  *
 703  * Checks whether @value has a floating reference count.
 704  *
 705  * This function should only ever be used to assert that a given variant
 706  * is or is not floating, or for debug purposes. To acquire a reference
 707  * to a variant that might be floating, always use g_variant_ref_sink().
 708  *
 709  * See g_variant_ref_sink() for more information about floating reference
 710  * counts.
 711  *
 712  * Since: 2.26
 713  **/
 714 gboolean
 715 g_variant_is_floating (GVariant *value)
 716 {
 717   g_return_val_if_fail (value != NULL, FALSE);
 718
 719   return (value->state & STATE_FLOATING) != 0;
 720 }
 721
 722 /**
 723  * g_variant_get_size:
 724  * @value: a #GVariant instance
 725  * @returns: the serialised size of @value
 726  *
 727  * Determines the number of bytes that would be required to store @value
 728  * with g_variant_store().
 729  *
 730  * If @value has a fixed-sized type then this function always returned
 731  * that fixed size.
 732  *
 733  * In the case that @value is already in serialised form or the size has
 734  * already been calculated (ie: this function has been called before)
 735  * then this function is O(1).  Otherwise, the size is calculated, an
 736  * operation which is approximately O(n) in the number of values
 737  * involved.
 738  *
 739  * Since: 2.24
 740  **/
 741 gsize
 742 g_variant_get_size (GVariant *value)
 743 {
 744   g_variant_lock (value);
 745   g_variant_ensure_size (value);
 746   g_variant_unlock (value);
 747
 748   return value->size;
 749 }
 750
 751 /**
 752  * g_variant_get_data:
 753  * @value: a #GVariant instance
 754  * @returns: the serialised form of @value, or %NULL
 755  *
 756  * Returns a pointer to the serialised form of a #GVariant instance.
 757  * The returned data may not be in fully-normalised form if read from an
 758  * untrusted source.  The returned data must not be freed; it remains
 759  * valid for as long as @value exists.
 760  *
 761  * If @value is a fixed-sized value that was deserialised from a
 762  * corrupted serialised container then %NULL may be returned.  In this
 763  * case, the proper thing to do is typically to use the appropriate
 764  * number of nul bytes in place of @value.  If @value is not fixed-sized
 765  * then %NULL is never returned.
 766  *
 767  * In the case that @value is already in serialised form, this function
 768  * is O(1).  If the value is not already in serialised form,
 769  * serialisation occurs implicitly and is approximately O(n) in the size
 770  * of the result.
 771  *
 772  * Since: 2.24
 773  **/
 774 gconstpointer
 775 g_variant_get_data (GVariant *value)
 776 {
 777   g_variant_lock (value);
 778   g_variant_ensure_serialised (value);
 779   g_variant_unlock (value);
 780
 781   return value->contents.serialised.data;
 782 }
 783
 784 /**
 785  * g_variant_n_children:
 786  * @value: a container #GVariant
 787  * @returns: the number of children in the container
 788  *
 789  * Determines the number of children in a container #GVariant instance.
 790  * This includes variants, maybes, arrays, tuples and dictionary
 791  * entries.  It is an error to call this function on any other type of
 792  * #GVariant.
 793  *
 794  * For variants, the return value is always 1.  For values with maybe
 795  * types, it is always zero or one.  For arrays, it is the length of the
 796  * array.  For tuples it is the number of tuple items (which depends
 797  * only on the type).  For dictionary entries, it is always 2
 798  *
 799  * This function is O(1).
 800  *
 801  * Since: 2.24
 802  **/
 803 gsize
 804 g_variant_n_children (GVariant *value)
 805 {
 806   gsize n_children;
 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
 818       n_children = g_variant_serialised_n_children (serialised);
 819     }
 820   else
 821     n_children = value->contents.tree.n_children;
 822
 823   g_variant_unlock (value);
 824
 825   return n_children;
 826 }
 827
 828 /**
 829  * g_variant_get_child_value:
 830  * @value: a container #GVariant
 831  * @index_: the index of the child to fetch
 832  * @returns: the child at the specified index
 833  *
 834  * Reads a child item out of a container #GVariant instance.  This
 835  * includes variants, maybes, arrays, tuples and dictionary
 836  * entries.  It is an error to call this function on any other type of
 837  * #GVariant.
 838  *
 839  * It is an error if @index_ is greater than the number of child items
 840  * in the container.  See g_variant_n_children().
 841  *
 842  * This function is O(1).
 843  *
 844  * Since: 2.24
 845  **/
 846 GVariant *
 847 g_variant_get_child_value (GVariant *value,
 848                            gsize     index_)
 849 {
 850   GVariant *child = NULL;
 851
 852   g_variant_lock (value);
 853
 854   if (value->state & STATE_SERIALISED)
 855     {
 856       GVariantSerialised serialised = {
 857         value->type_info,
 858         (gpointer) value->contents.serialised.data,
 859         value->size
 860       };
 861       GVariantSerialised s_child;
 862
 863       /* get the serialiser to extract the serialised data for the child
 864        * from the serialised data for the container
 865        */
 866       s_child = g_variant_serialised_get_child (serialised, index_);
 867
 868       /* create a new serialised instance out of it */
 869       child = g_slice_new (GVariant);
 870       child->type_info = s_child.type_info;
 871       child->state = (value->state & STATE_TRUSTED) |
 872                      STATE_SERIALISED;
 873       child->size = s_child.size;
 874       child->ref_count = 1;
 875       child->contents.serialised.buffer =
 876         g_buffer_ref (value->contents.serialised.buffer);
 877       child->contents.serialised.data = s_child.data;
 878      }
 879   else
 880     child = g_variant_ref (value->contents.tree.children[index_]);
 881
 882   g_variant_unlock (value);
 883
 884   return child;
 885 }
 886
 887 /**
 888  * g_variant_store:
 889  * @value: the #GVariant to store
 890  * @data: the location to store the serialised data at
 891  *
 892  * Stores the serialised form of @value at @data.  @data should be
 893  * large enough.  See g_variant_get_size().
 894  *
 895  * The stored data is in machine native byte order but may not be in
 896  * fully-normalised form if read from an untrusted source.  See
 897  * g_variant_normalise() for a solution.
 898  *
 899  * This function is approximately O(n) in the size of @data.
 900  *
 901  * Since: 2.24
 902  **/
 903 void
 904 g_variant_store (GVariant *value,
 905                  gpointer  data)
 906 {
 907   g_variant_lock (value);
 908
 909   if (value->state & STATE_SERIALISED)
 910     {
 911       if (value->contents.serialised.data != NULL)
 912         memcpy (data, value->contents.serialised.data, value->size);
 913       else
 914         memset (data, 0, value->size);
 915     }
 916   else
 917     g_variant_serialise (value, data);
 918
 919   g_variant_unlock (value);
 920 }
 921
 922 /**
 923  * g_variant_is_normal_form:
 924  * @value: a #GVariant instance
 925  * @returns: %TRUE if @value is in normal form
 926  *
 927  * Checks if @value is in normal form.
 928  *
 929  * The main reason to do this is to detect if a given chunk of
 930  * serialised data is in normal form: load the data into a #GVariant
 931  * using g_variant_create_from_data() and then use this function to
 932  * check.
 933  *
 934  * If @value is found to be in normal form then it will be marked as
 935  * being trusted.  If the value was already marked as being trusted then
 936  * this function will immediately return %TRUE.
 937  *
 938  * Since: 2.24
 939  **/
 940 gboolean
 941 g_variant_is_normal_form (GVariant *value)
 942 {
 943   if (value->state & STATE_TRUSTED)
 944     return TRUE;
 945
 946   g_variant_lock (value);
 947
 948   if (value->state & STATE_SERIALISED)
 949     {
 950       GVariantSerialised serialised = {
 951         value->type_info,
 952         (gpointer) value->contents.serialised.data,
 953         value->size
 954       };
 955
 956       if (g_variant_serialised_is_normal (serialised))
 957         value->state |= STATE_TRUSTED;
 958     }
 959   else
 960     {
 961       gboolean normal = TRUE;
 962       gsize i;
 963
 964       for (i = 0; i < value->contents.tree.n_children; i++)
 965         normal &= g_variant_is_normal_form (value->contents.tree.children[i]);
 966
 967       if (normal)
 968         value->state |= STATE_TRUSTED;
 969     }
 970
 971   g_variant_unlock (value);
 972
 973   return (value->state & STATE_TRUSTED) != 0;
 974 }