nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 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, see <http://www.gnu.org/licenses/>.
17 */
18  
19 #include "config.h"
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/gbytes.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 GBytes *bytes;
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 * .bytes: the #GBytes 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 bytes will be shared by both of them. When
140 * the instance is freed, this reference must be released
141 * with g_bytes_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 * #GBytes 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 GBytes *bytes;
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 bytes = g_bytes_new_take (data, value->size);
451 value->contents.serialised.data = g_bytes_get_data (bytes, NULL);
452 value->contents.serialised.bytes = bytes;
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 *
463 * Allocates a #GVariant instance and does some common work (such as
464 * looking up and filling in the type info), setting the state field,
465 * and setting the ref_count to 1.
466 *
467 * Returns: a new #GVariant with a floating reference
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 /**
488 * g_variant_new_from_bytes:
489 * @type: a #GVariantType
490 * @bytes: a #GBytes
491 * @trusted: if the contents of @bytes are trusted
492 *
493 * Constructs a new serialised-mode #GVariant instance. This is the
494 * inner interface for creation of new serialised values that gets
495 * called from various functions in gvariant.c.
496 *
497 * A reference is taken on @bytes.
498 *
499 * Returns: (transfer none): a new #GVariant with a floating reference
500 *
501 * Since: 2.36
502 */
503 GVariant *
504 g_variant_new_from_bytes (const GVariantType *type,
505 GBytes *bytes,
506 gboolean trusted)
507 {
508 GVariant *value;
509 guint alignment;
510 gsize size;
511  
512 value = g_variant_alloc (type, TRUE, trusted);
513  
514 value->contents.serialised.bytes = g_bytes_ref (bytes);
515  
516 g_variant_type_info_query (value->type_info,
517 &alignment, &size);
518  
519 if (size && g_bytes_get_size (bytes) != size)
520 {
521 /* Creating a fixed-sized GVariant with a bytes of the wrong
522 * size.
523 *
524 * We should do the equivalent of pulling a fixed-sized child out
525 * of a brozen container (ie: data is NULL size is equal to the correct
526 * fixed size).
527 */
528 value->contents.serialised.data = NULL;
529 value->size = size;
530 }
531 else
532 {
533 value->contents.serialised.data = g_bytes_get_data (bytes, &value->size);
534 }
535  
536 return value;
537 }
538  
539 /* -- internal -- */
540  
541 /* < internal >
542 * g_variant_new_from_children:
543 * @type: a #GVariantType
544 * @children: an array of #GVariant pointers. Consumed.
545 * @n_children: the length of @children
546 * @trusted: %TRUE if every child in @children in trusted
547 *
548 * Constructs a new tree-mode #GVariant instance. This is the inner
549 * interface for creation of new serialised values that gets called from
550 * various functions in gvariant.c.
551 *
552 * @children is consumed by this function. g_free() will be called on
553 * it some time later.
554 *
555 * Returns: a new #GVariant with a floating reference
556 */
557 GVariant *
558 g_variant_new_from_children (const GVariantType *type,
559 GVariant **children,
560 gsize n_children,
561 gboolean trusted)
562 {
563 GVariant *value;
564  
565 value = g_variant_alloc (type, FALSE, trusted);
566 value->contents.tree.children = children;
567 value->contents.tree.n_children = n_children;
568  
569 return value;
570 }
571  
572 /* < internal >
573 * g_variant_get_type_info:
574 * @value: a #GVariant
575 *
576 * Returns the #GVariantTypeInfo corresponding to the type of @value. A
577 * reference is not added, so the return value is only good for the
578 * duration of the life of @value.
579 *
580 * Returns: the #GVariantTypeInfo for @value
581 */
582 GVariantTypeInfo *
583 g_variant_get_type_info (GVariant *value)
584 {
585 return value->type_info;
586 }
587  
588 /* < internal >
589 * g_variant_is_trusted:
590 * @value: a #GVariant
591 *
592 * Determines if @value is trusted by #GVariant to contain only
593 * fully-valid data. All values constructed solely via #GVariant APIs
594 * are trusted, but values containing data read in from other sources
595 * are usually not trusted.
596 *
597 * The main advantage of trusted data is that certain checks can be
598 * skipped. For example, we don't need to check that a string is
599 * properly nul-terminated or that an object path is actually a
600 * properly-formatted object path.
601 *
602 * Returns: if @value is trusted
603 */
604 gboolean
605 g_variant_is_trusted (GVariant *value)
606 {
607 return (value->state & STATE_TRUSTED) != 0;
608 }
609  
610 /* -- public -- */
611  
612 /**
613 * g_variant_unref:
614 * @value: a #GVariant
615 *
616 * Decreases the reference count of @value. When its reference count
617 * drops to 0, the memory used by the variant is freed.
618 *
619 * Since: 2.24
620 **/
621 void
622 g_variant_unref (GVariant *value)
623 {
624 g_return_if_fail (value != NULL);
625 g_return_if_fail (value->ref_count > 0);
626  
627 if (g_atomic_int_dec_and_test (&value->ref_count))
628 {
629 if G_UNLIKELY (value->state & STATE_LOCKED)
630 g_critical ("attempting to free a locked GVariant instance. "
631 "This should never happen.");
632  
633 value->state |= STATE_LOCKED;
634  
635 g_variant_type_info_unref (value->type_info);
636  
637 if (value->state & STATE_SERIALISED)
638 g_bytes_unref (value->contents.serialised.bytes);
639 else
640 g_variant_release_children (value);
641  
642 memset (value, 0, sizeof (GVariant));
643 g_slice_free (GVariant, value);
644 }
645 }
646  
647 /**
648 * g_variant_ref:
649 * @value: a #GVariant
650 *
651 * Increases the reference count of @value.
652 *
653 * Returns: the same @value
654 *
655 * Since: 2.24
656 **/
657 GVariant *
658 g_variant_ref (GVariant *value)
659 {
660 g_return_val_if_fail (value != NULL, NULL);
661 g_return_val_if_fail (value->ref_count > 0, NULL);
662  
663 g_atomic_int_inc (&value->ref_count);
664  
665 return value;
666 }
667  
668 /**
669 * g_variant_ref_sink:
670 * @value: a #GVariant
671 *
672 * #GVariant uses a floating reference count system. All functions with
673 * names starting with `g_variant_new_` return floating
674 * references.
675 *
676 * Calling g_variant_ref_sink() on a #GVariant with a floating reference
677 * will convert the floating reference into a full reference. Calling
678 * g_variant_ref_sink() on a non-floating #GVariant results in an
679 * additional normal reference being added.
680 *
681 * In other words, if the @value is floating, then this call "assumes
682 * ownership" of the floating reference, converting it to a normal
683 * reference. If the @value is not floating, then this call adds a
684 * new normal reference increasing the reference count by one.
685 *
686 * All calls that result in a #GVariant instance being inserted into a
687 * container will call g_variant_ref_sink() on the instance. This means
688 * that if the value was just created (and has only its floating
689 * reference) then the container will assume sole ownership of the value
690 * at that point and the caller will not need to unreference it. This
691 * makes certain common styles of programming much easier while still
692 * maintaining normal refcounting semantics in situations where values
693 * are not floating.
694 *
695 * Returns: the same @value
696 *
697 * Since: 2.24
698 **/
699 GVariant *
700 g_variant_ref_sink (GVariant *value)
701 {
702 g_return_val_if_fail (value != NULL, NULL);
703 g_return_val_if_fail (value->ref_count > 0, NULL);
704  
705 g_variant_lock (value);
706  
707 if (~value->state & STATE_FLOATING)
708 g_variant_ref (value);
709 else
710 value->state &= ~STATE_FLOATING;
711  
712 g_variant_unlock (value);
713  
714 return value;
715 }
716  
717 /**
718 * g_variant_take_ref:
719 * @value: a #GVariant
720 *
721 * If @value is floating, sink it. Otherwise, do nothing.
722 *
723 * Typically you want to use g_variant_ref_sink() in order to
724 * automatically do the correct thing with respect to floating or
725 * non-floating references, but there is one specific scenario where
726 * this function is helpful.
727 *
728 * The situation where this function is helpful is when creating an API
729 * that allows the user to provide a callback function that returns a
730 * #GVariant. We certainly want to allow the user the flexibility to
731 * return a non-floating reference from this callback (for the case
732 * where the value that is being returned already exists).
733 *
734 * At the same time, the style of the #GVariant API makes it likely that
735 * for newly-created #GVariant instances, the user can be saved some
736 * typing if they are allowed to return a #GVariant with a floating
737 * reference.
738 *
739 * Using this function on the return value of the user's callback allows
740 * the user to do whichever is more convenient for them. The caller
741 * will alway receives exactly one full reference to the value: either
742 * the one that was returned in the first place, or a floating reference
743 * that has been converted to a full reference.
744 *
745 * This function has an odd interaction when combined with
746 * g_variant_ref_sink() running at the same time in another thread on
747 * the same #GVariant instance. If g_variant_ref_sink() runs first then
748 * the result will be that the floating reference is converted to a hard
749 * reference. If g_variant_take_ref() runs first then the result will
750 * be that the floating reference is converted to a hard reference and
751 * an additional reference on top of that one is added. It is best to
752 * avoid this situation.
753 *
754 * Returns: the same @value
755 **/
756 GVariant *
757 g_variant_take_ref (GVariant *value)
758 {
759 g_return_val_if_fail (value != NULL, NULL);
760 g_return_val_if_fail (value->ref_count > 0, NULL);
761  
762 g_atomic_int_and (&value->state, ~STATE_FLOATING);
763  
764 return value;
765 }
766  
767 /**
768 * g_variant_is_floating:
769 * @value: a #GVariant
770 *
771 * Checks whether @value has a floating reference count.
772 *
773 * This function should only ever be used to assert that a given variant
774 * is or is not floating, or for debug purposes. To acquire a reference
775 * to a variant that might be floating, always use g_variant_ref_sink()
776 * or g_variant_take_ref().
777 *
778 * See g_variant_ref_sink() for more information about floating reference
779 * counts.
780 *
781 * Returns: whether @value is floating
782 *
783 * Since: 2.26
784 **/
785 gboolean
786 g_variant_is_floating (GVariant *value)
787 {
788 g_return_val_if_fail (value != NULL, FALSE);
789  
790 return (value->state & STATE_FLOATING) != 0;
791 }
792  
793 /**
794 * g_variant_get_size:
795 * @value: a #GVariant instance
796 *
797 * Determines the number of bytes that would be required to store @value
798 * with g_variant_store().
799 *
800 * If @value has a fixed-sized type then this function always returned
801 * that fixed size.
802 *
803 * In the case that @value is already in serialised form or the size has
804 * already been calculated (ie: this function has been called before)
805 * then this function is O(1). Otherwise, the size is calculated, an
806 * operation which is approximately O(n) in the number of values
807 * involved.
808 *
809 * Returns: the serialised size of @value
810 *
811 * Since: 2.24
812 **/
813 gsize
814 g_variant_get_size (GVariant *value)
815 {
816 g_variant_lock (value);
817 g_variant_ensure_size (value);
818 g_variant_unlock (value);
819  
820 return value->size;
821 }
822  
823 /**
824 * g_variant_get_data:
825 * @value: a #GVariant instance
826 *
827 * Returns a pointer to the serialised form of a #GVariant instance.
828 * The returned data may not be in fully-normalised form if read from an
829 * untrusted source. The returned data must not be freed; it remains
830 * valid for as long as @value exists.
831 *
832 * If @value is a fixed-sized value that was deserialised from a
833 * corrupted serialised container then %NULL may be returned. In this
834 * case, the proper thing to do is typically to use the appropriate
835 * number of nul bytes in place of @value. If @value is not fixed-sized
836 * then %NULL is never returned.
837 *
838 * In the case that @value is already in serialised form, this function
839 * is O(1). If the value is not already in serialised form,
840 * serialisation occurs implicitly and is approximately O(n) in the size
841 * of the result.
842 *
843 * To deserialise the data returned by this function, in addition to the
844 * serialised data, you must know the type of the #GVariant, and (if the
845 * machine might be different) the endianness of the machine that stored
846 * it. As a result, file formats or network messages that incorporate
847 * serialised #GVariants must include this information either
848 * implicitly (for instance "the file always contains a
849 * %G_VARIANT_TYPE_VARIANT and it is always in little-endian order") or
850 * explicitly (by storing the type and/or endianness in addition to the
851 * serialised data).
852 *
853 * Returns: (transfer none): the serialised form of @value, or %NULL
854 *
855 * Since: 2.24
856 **/
857 gconstpointer
858 g_variant_get_data (GVariant *value)
859 {
860 g_variant_lock (value);
861 g_variant_ensure_serialised (value);
862 g_variant_unlock (value);
863  
864 return value->contents.serialised.data;
865 }
866  
867 /**
868 * g_variant_get_data_as_bytes:
869 * @value: a #GVariant
870 *
871 * Returns a pointer to the serialised form of a #GVariant instance.
872 * The semantics of this function are exactly the same as
873 * g_variant_get_data(), except that the returned #GBytes holds
874 * a reference to the variant data.
875 *
876 * Returns: (transfer full): A new #GBytes representing the variant data
877 *
878 * Since: 2.36
879 */
880 GBytes *
881 g_variant_get_data_as_bytes (GVariant *value)
882 {
883 const gchar *bytes_data;
884 const gchar *data;
885 gsize bytes_size;
886 gsize size;
887  
888 g_variant_lock (value);
889 g_variant_ensure_serialised (value);
890 g_variant_unlock (value);
891  
892 bytes_data = g_bytes_get_data (value->contents.serialised.bytes, &bytes_size);
893 data = value->contents.serialised.data;
894 size = value->size;
895  
896 if (data == bytes_data && size == bytes_size)
897 return g_bytes_ref (value->contents.serialised.bytes);
898 else
899 return g_bytes_new_from_bytes (value->contents.serialised.bytes,
900 data - bytes_data, size);
901 }
902  
903  
904 /**
905 * g_variant_n_children:
906 * @value: a container #GVariant
907 *
908 * Determines the number of children in a container #GVariant instance.
909 * This includes variants, maybes, arrays, tuples and dictionary
910 * entries. It is an error to call this function on any other type of
911 * #GVariant.
912 *
913 * For variants, the return value is always 1. For values with maybe
914 * types, it is always zero or one. For arrays, it is the length of the
915 * array. For tuples it is the number of tuple items (which depends
916 * only on the type). For dictionary entries, it is always 2
917 *
918 * This function is O(1).
919 *
920 * Returns: the number of children in the container
921 *
922 * Since: 2.24
923 **/
924 gsize
925 g_variant_n_children (GVariant *value)
926 {
927 gsize n_children;
928  
929 g_variant_lock (value);
930  
931 if (value->state & STATE_SERIALISED)
932 {
933 GVariantSerialised serialised = {
934 value->type_info,
935 (gpointer) value->contents.serialised.data,
936 value->size
937 };
938  
939 n_children = g_variant_serialised_n_children (serialised);
940 }
941 else
942 n_children = value->contents.tree.n_children;
943  
944 g_variant_unlock (value);
945  
946 return n_children;
947 }
948  
949 /**
950 * g_variant_get_child_value:
951 * @value: a container #GVariant
952 * @index_: the index of the child to fetch
953 *
954 * Reads a child item out of a container #GVariant instance. This
955 * includes variants, maybes, arrays, tuples and dictionary
956 * entries. It is an error to call this function on any other type of
957 * #GVariant.
958 *
959 * It is an error if @index_ is greater than the number of child items
960 * in the container. See g_variant_n_children().
961 *
962 * The returned value is never floating. You should free it with
963 * g_variant_unref() when you're done with it.
964 *
965 * This function is O(1).
966 *
967 * Returns: (transfer full): the child at the specified index
968 *
969 * Since: 2.24
970 **/
971 GVariant *
972 g_variant_get_child_value (GVariant *value,
973 gsize index_)
974 {
975 g_return_val_if_fail (index_ < g_variant_n_children (value), NULL);
976  
977 if (~g_atomic_int_get (&value->state) & STATE_SERIALISED)
978 {
979 g_variant_lock (value);
980  
981 if (~value->state & STATE_SERIALISED)
982 {
983 GVariant *child;
984  
985 child = g_variant_ref (value->contents.tree.children[index_]);
986 g_variant_unlock (value);
987  
988 return child;
989 }
990  
991 g_variant_unlock (value);
992 }
993  
994 {
995 GVariantSerialised serialised = {
996 value->type_info,
997 (gpointer) value->contents.serialised.data,
998 value->size
999 };
1000 GVariantSerialised s_child;
1001 GVariant *child;
1002  
1003 /* get the serialiser to extract the serialised data for the child
1004 * from the serialised data for the container
1005 */
1006 s_child = g_variant_serialised_get_child (serialised, index_);
1007  
1008 /* create a new serialised instance out of it */
1009 child = g_slice_new (GVariant);
1010 child->type_info = s_child.type_info;
1011 child->state = (value->state & STATE_TRUSTED) |
1012 STATE_SERIALISED;
1013 child->size = s_child.size;
1014 child->ref_count = 1;
1015 child->contents.serialised.bytes =
1016 g_bytes_ref (value->contents.serialised.bytes);
1017 child->contents.serialised.data = s_child.data;
1018  
1019 return child;
1020 }
1021 }
1022  
1023 /**
1024 * g_variant_store:
1025 * @value: the #GVariant to store
1026 * @data: (not nullable): the location to store the serialised data at
1027 *
1028 * Stores the serialised form of @value at @data. @data should be
1029 * large enough. See g_variant_get_size().
1030 *
1031 * The stored data is in machine native byte order but may not be in
1032 * fully-normalised form if read from an untrusted source. See
1033 * g_variant_get_normal_form() for a solution.
1034 *
1035 * As with g_variant_get_data(), to be able to deserialise the
1036 * serialised variant successfully, its type and (if the destination
1037 * machine might be different) its endianness must also be available.
1038 *
1039 * This function is approximately O(n) in the size of @data.
1040 *
1041 * Since: 2.24
1042 **/
1043 void
1044 g_variant_store (GVariant *value,
1045 gpointer data)
1046 {
1047 g_variant_lock (value);
1048  
1049 if (value->state & STATE_SERIALISED)
1050 {
1051 if (value->contents.serialised.data != NULL)
1052 memcpy (data, value->contents.serialised.data, value->size);
1053 else
1054 memset (data, 0, value->size);
1055 }
1056 else
1057 g_variant_serialise (value, data);
1058  
1059 g_variant_unlock (value);
1060 }
1061  
1062 /**
1063 * g_variant_is_normal_form:
1064 * @value: a #GVariant instance
1065 *
1066 * Checks if @value is in normal form.
1067 *
1068 * The main reason to do this is to detect if a given chunk of
1069 * serialised data is in normal form: load the data into a #GVariant
1070 * using g_variant_new_from_data() and then use this function to
1071 * check.
1072 *
1073 * If @value is found to be in normal form then it will be marked as
1074 * being trusted. If the value was already marked as being trusted then
1075 * this function will immediately return %TRUE.
1076 *
1077 * Returns: %TRUE if @value is in normal form
1078 *
1079 * Since: 2.24
1080 **/
1081 gboolean
1082 g_variant_is_normal_form (GVariant *value)
1083 {
1084 if (value->state & STATE_TRUSTED)
1085 return TRUE;
1086  
1087 g_variant_lock (value);
1088  
1089 if (value->state & STATE_SERIALISED)
1090 {
1091 GVariantSerialised serialised = {
1092 value->type_info,
1093 (gpointer) value->contents.serialised.data,
1094 value->size
1095 };
1096  
1097 if (g_variant_serialised_is_normal (serialised))
1098 value->state |= STATE_TRUSTED;
1099 }
1100 else
1101 {
1102 gboolean normal = TRUE;
1103 gsize i;
1104  
1105 for (i = 0; i < value->contents.tree.n_children; i++)
1106 normal &= g_variant_is_normal_form (value->contents.tree.children[i]);
1107  
1108 if (normal)
1109 value->state |= STATE_TRUSTED;
1110 }
1111  
1112 g_variant_unlock (value);
1113  
1114 return (value->state & STATE_TRUSTED) != 0;
1115 }