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.1 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	* Author: Ryan Lortie <desrt@desrt.ca>
19	*/
20
21	/* Prologue {{{1 */
22
23	#include "config.h"
24
25	#include <glib/gvariant-serialiser.h>
26	#include "gvariant-internal.h"
27	#include <glib/gvariant-core.h>
28	#include <glib/gtestutils.h>
29	#include <glib/gstrfuncs.h>
30	#include <glib/gslice.h>
31	#include <glib/ghash.h>
32	#include <glib/gmem.h>
33
34	#include <string.h>
35
36
37	/**
38	* SECTION:gvariant
39	* @title: GVariant
40	* @short_description: strongly typed value datatype
41	* @see_also: GVariantType
42	*
43	* #GVariant is a variant datatype; it can contain one or more values
44	* along with information about the type of the values.
45	*
46	* A #GVariant may contain simple types, like an integer, or a boolean value;
47	* or complex types, like an array of two strings, or a dictionary of key
48	* value pairs. A #GVariant is also immutable: once it's been created neither
49	* its type nor its content can be modified further.
50	*
51	* GVariant is useful whenever data needs to be serialized, for example when
52	* sending method parameters in D-Bus, or when saving settings using GSettings.
53	*
54	* When creating a new #GVariant, you pass the data you want to store in it
55	* along with a string representing the type of data you wish to pass to it.
56	*
57	* For instance, if you want to create a #GVariant holding an integer value you
58	* can use:
59	*
60	* |[<!-- language="C" -->
61	* GVariant *v = g_variant_new ("u", 40);
62	* ]|
63	*
64	* The string "u" in the first argument tells #GVariant that the data passed to
65	* the constructor (40) is going to be an unsigned integer.
66	*
67	* More advanced examples of #GVariant in use can be found in documentation for
68	* [GVariant format strings][gvariant-format-strings-pointers].
69	*
70	* The range of possible values is determined by the type.
71	*
72	* The type system used by #GVariant is #GVariantType.
73	*
74	* #GVariant instances always have a type and a value (which are given
75	* at construction time). The type and value of a #GVariant instance
76	* can never change other than by the #GVariant itself being
77	* destroyed. A #GVariant cannot contain a pointer.
78	*
79	* #GVariant is reference counted using g_variant_ref() and
80	* g_variant_unref(). #GVariant also has floating reference counts --
81	* see g_variant_ref_sink().
82	*
83	* #GVariant is completely threadsafe. A #GVariant instance can be
84	* concurrently accessed in any way from any number of threads without
85	* problems.
86	*
87	* #GVariant is heavily optimised for dealing with data in serialised
88	* form. It works particularly well with data located in memory-mapped
89	* files. It can perform nearly all deserialisation operations in a
90	* small constant time, usually touching only a single memory page.
91	* Serialised #GVariant data can also be sent over the network.
92	*
93	* #GVariant is largely compatible with D-Bus. Almost all types of
94	* #GVariant instances can be sent over D-Bus. See #GVariantType for
95	* exceptions. (However, #GVariant's serialisation format is not the same
96	* as the serialisation format of a D-Bus message body: use #GDBusMessage,
97	* in the gio library, for those.)
98	*
99	* For space-efficiency, the #GVariant serialisation format does not
100	* automatically include the variant's length, type or endianness,
101	* which must either be implied from context (such as knowledge that a
102	* particular file format always contains a little-endian
103	* %G_VARIANT_TYPE_VARIANT which occupies the whole length of the file)
104	* or supplied out-of-band (for instance, a length, type and/or endianness
105	* indicator could be placed at the beginning of a file, network message
106	* or network stream).
107	*
108	* A #GVariant's size is limited mainly by any lower level operating
109	* system constraints, such as the number of bits in #gsize. For
110	* example, it is reasonable to have a 2GB file mapped into memory
111	* with #GMappedFile, and call g_variant_new_from_data() on it.
112	*
113	* For convenience to C programmers, #GVariant features powerful
114	* varargs-based value construction and destruction. This feature is
115	* designed to be embedded in other libraries.
116	*
117	* There is a Python-inspired text language for describing #GVariant
118	* values. #GVariant includes a printer for this language and a parser
119	* with type inferencing.
120	*
121	* ## Memory Use
122	*
123	* #GVariant tries to be quite efficient with respect to memory use.
124	* This section gives a rough idea of how much memory is used by the
125	* current implementation. The information here is subject to change
126	* in the future.
127	*
128	* The memory allocated by #GVariant can be grouped into 4 broad
129	* purposes: memory for serialised data, memory for the type
130	* information cache, buffer management memory and memory for the
131	* #GVariant structure itself.
132	*
133	* ## Serialised Data Memory
134	*
135	* This is the memory that is used for storing GVariant data in
136	* serialised form. This is what would be sent over the network or
137	* what would end up on disk, not counting any indicator of the
138	* endianness, or of the length or type of the top-level variant.
139	*
140	* The amount of memory required to store a boolean is 1 byte. 16,
141	* 32 and 64 bit integers and double precision floating point numbers
142	* use their "natural" size. Strings (including object path and
143	* signature strings) are stored with a nul terminator, and as such
144	* use the length of the string plus 1 byte.
145	*
146	* Maybe types use no space at all to represent the null value and
147	* use the same amount of space (sometimes plus one byte) as the
148	* equivalent non-maybe-typed value to represent the non-null case.
149	*
150	* Arrays use the amount of space required to store each of their
151	* members, concatenated. Additionally, if the items stored in an
152	* array are not of a fixed-size (ie: strings, other arrays, etc)
153	* then an additional framing offset is stored for each item. The
154	* size of this offset is either 1, 2 or 4 bytes depending on the
155	* overall size of the container. Additionally, extra padding bytes
156	* are added as required for alignment of child values.
157	*
158	* Tuples (including dictionary entries) use the amount of space
159	* required to store each of their members, concatenated, plus one
160	* framing offset (as per arrays) for each non-fixed-sized item in
161	* the tuple, except for the last one. Additionally, extra padding
162	* bytes are added as required for alignment of child values.
163	*
164	* Variants use the same amount of space as the item inside of the
165	* variant, plus 1 byte, plus the length of the type string for the
166	* item inside the variant.
167	*
168	* As an example, consider a dictionary mapping strings to variants.
169	* In the case that the dictionary is empty, 0 bytes are required for
170	* the serialisation.
171	*
172	* If we add an item "width" that maps to the int32 value of 500 then
173	* we will use 4 byte to store the int32 (so 6 for the variant
174	* containing it) and 6 bytes for the string. The variant must be
175	* aligned to 8 after the 6 bytes of the string, so that's 2 extra
176	* bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used
177	* for the dictionary entry. An additional 1 byte is added to the
178	* array as a framing offset making a total of 15 bytes.
179	*
180	* If we add another entry, "title" that maps to a nullable string
181	* that happens to have a value of null, then we use 0 bytes for the
182	* null value (and 3 bytes for the variant to contain it along with
183	* its type string) plus 6 bytes for the string. Again, we need 2
184	* padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes.
185	*
186	* We now require extra padding between the two items in the array.
187	* After the 14 bytes of the first item, that's 2 bytes required.
188	* We now require 2 framing offsets for an extra two
189	* bytes. 14 + 2 + 11 + 2 = 29 bytes to encode the entire two-item
190	* dictionary.
191	*
192	* ## Type Information Cache
193	*
194	* For each GVariant type that currently exists in the program a type
195	* information structure is kept in the type information cache. The
196	* type information structure is required for rapid deserialisation.
197	*
198	* Continuing with the above example, if a #GVariant exists with the
199	* type "a{sv}" then a type information struct will exist for
200	* "a{sv}", "{sv}", "s", and "v". Multiple uses of the same type
201	* will share the same type information. Additionally, all
202	* single-digit types are stored in read-only static memory and do
203	* not contribute to the writable memory footprint of a program using
204	* #GVariant.
205	*
206	* Aside from the type information structures stored in read-only
207	* memory, there are two forms of type information. One is used for
208	* container types where there is a single element type: arrays and
209	* maybe types. The other is used for container types where there
210	* are multiple element types: tuples and dictionary entries.
211	*
212	* Array type info structures are 6 * sizeof (void *), plus the
213	* memory required to store the type string itself. This means that
214	* on 32-bit systems, the cache entry for "a{sv}" would require 30
215	* bytes of memory (plus malloc overhead).
216	*
217	* Tuple type info structures are 6 * sizeof (void *), plus 4 *
218	* sizeof (void *) for each item in the tuple, plus the memory
219	* required to store the type string itself. A 2-item tuple, for
220	* example, would have a type information structure that consumed
221	* writable memory in the size of 14 * sizeof (void *) (plus type
222	* string) This means that on 32-bit systems, the cache entry for
223	* "{sv}" would require 61 bytes of memory (plus malloc overhead).
224	*
225	* This means that in total, for our "a{sv}" example, 91 bytes of
226	* type information would be allocated.
227	*
228	* The type information cache, additionally, uses a #GHashTable to
229	* store and look up the cached items and stores a pointer to this
230	* hash table in static storage. The hash table is freed when there
231	* are zero items in the type cache.
232	*
233	* Although these sizes may seem large it is important to remember
234	* that a program will probably only have a very small number of
235	* different types of values in it and that only one type information
236	* structure is required for many different values of the same type.
237	*
238	* ## Buffer Management Memory
239	*
240	* #GVariant uses an internal buffer management structure to deal
241	* with the various different possible sources of serialised data
242	* that it uses. The buffer is responsible for ensuring that the
243	* correct call is made when the data is no longer in use by
244	* #GVariant. This may involve a g_free() or a g_slice_free() or
245	* even g_mapped_file_unref().
246	*
247	* One buffer management structure is used for each chunk of
248	* serialised data. The size of the buffer management structure
249	* is 4 * (void *). On 32-bit systems, that's 16 bytes.
250	*
251	* ## GVariant structure
252	*
253	* The size of a #GVariant structure is 6 * (void *). On 32-bit
254	* systems, that's 24 bytes.
255	*
256	* #GVariant structures only exist if they are explicitly created
257	* with API calls. For example, if a #GVariant is constructed out of
258	* serialised data for the example given above (with the dictionary)
259	* then although there are 9 individual values that comprise the
260	* entire dictionary (two keys, two values, two variants containing
261	* the values, two dictionary entries, plus the dictionary itself),
262	* only 1 #GVariant instance exists -- the one referring to the
263	* dictionary.
264	*
265	* If calls are made to start accessing the other values then
266	* #GVariant instances will exist for those values only for as long
267	* as they are in use (ie: until you call g_variant_unref()). The
268	* type information is shared. The serialised data and the buffer
269	* management structure for that serialised data is shared by the
270	* child.
271	*
272	* ## Summary
273	*
274	* To put the entire example together, for our dictionary mapping
275	* strings to variants (with two entries, as given above), we are
276	* using 91 bytes of memory for type information, 29 bytes of memory
277	* for the serialised data, 16 bytes for buffer management and 24
278	* bytes for the #GVariant instance, or a total of 160 bytes, plus
279	* malloc overhead. If we were to use g_variant_get_child_value() to
280	* access the two dictionary entries, we would use an additional 48
281	* bytes. If we were to have other dictionaries of the same type, we
282	* would use more memory for the serialised data and buffer
283	* management for those dictionaries, but the type information would
284	* be shared.
285	*/
286
287	/* definition of GVariant structure is in gvariant-core.c */
288
289	/* this is a g_return_val_if_fail() for making
290	* sure a (GVariant *) has the required type.
291	*/
292	#define TYPE_CHECK(value, TYPE, val) \
293	if G_UNLIKELY (!g_variant_is_of_type (value, TYPE)) { \
294	g_return_if_fail_warning (G_LOG_DOMAIN, G_STRFUNC, \
295	"g_variant_is_of_type (" #value \
296	", " #TYPE ")"); \
297	return val; \
298	}
299
300	/* Numeric Type Constructor/Getters {{{1 */
301	/* < private >
302	* g_variant_new_from_trusted:
303	* @type: the #GVariantType
304	* @data: the data to use
305	* @size: the size of @data
306	*
307	* Constructs a new trusted #GVariant instance from the provided data.
308	* This is used to implement g_variant_new_* for all the basic types.
309	*
310	* Note: @data must be backed by memory that is aligned appropriately for the
311	* @type being loaded. Otherwise this function will internally create a copy of
312	* the memory (since GLib 2.60) or (in older versions) fail and exit the
313	* process.
314	*
315	* Returns: a new floating #GVariant
316	*/
317	static GVariant *
318	g_variant_new_from_trusted (const GVariantType *type,
319	gconstpointer data,
320	gsize size)
321	{
322	GVariant *value;
323	GBytes *bytes;
324
325	bytes = g_bytes_new (data, size);
326	value = g_variant_new_from_bytes (type, bytes, TRUE);
327	g_bytes_unref (bytes);
328
329	return value;
330	}
331
332	/**
333	* g_variant_new_boolean:
334	* @value: a #gboolean value
335	*
336	* Creates a new boolean #GVariant instance -- either %TRUE or %FALSE.
337	*
338	* Returns: (transfer none): a floating reference to a new boolean #GVariant instance
339	*
340	* Since: 2.24
341	**/
342	GVariant *
343	g_variant_new_boolean (gboolean value)
344	{
345	guchar v = value;
346
347	return g_variant_new_from_trusted (G_VARIANT_TYPE_BOOLEAN, data: &v, size: 1);
348	}
349
350	/**
351	* g_variant_get_boolean:
352	* @value: a boolean #GVariant instance
353	*
354	* Returns the boolean value of @value.
355	*
356	* It is an error to call this function with a @value of any type
357	* other than %G_VARIANT_TYPE_BOOLEAN.
358	*
359	* Returns: %TRUE or %FALSE
360	*
361	* Since: 2.24
362	**/
363	gboolean
364	g_variant_get_boolean (GVariant *value)
365	{
366	const guchar *data;
367
368	TYPE_CHECK (value, G_VARIANT_TYPE_BOOLEAN, FALSE);
369
370	data = g_variant_get_data (value);
371
372	return data != NULL ? *data != 0 : FALSE;
373	}
374
375	/* the constructors and accessors for byte, int{16,32,64}, handles and
376	* doubles all look pretty much exactly the same, so we reduce
377	* copy/pasting here.
378	*/
379	#define NUMERIC_TYPE(TYPE, type, ctype) \
380	GVariant *g_variant_new_##type (ctype value) { \
381	return g_variant_new_from_trusted (G_VARIANT_TYPE_##TYPE, \
382	&value, sizeof value); \
383	} \
384	ctype g_variant_get_##type (GVariant *value) { \
385	const ctype *data; \
386	TYPE_CHECK (value, G_VARIANT_TYPE_ ## TYPE, 0); \
387	data = g_variant_get_data (value); \
388	return data != NULL ? *data : 0; \
389	}
390
391
392	/**
393	* g_variant_new_byte:
394	* @value: a #guint8 value
395	*
396	* Creates a new byte #GVariant instance.
397	*
398	* Returns: (transfer none): a floating reference to a new byte #GVariant instance
399	*
400	* Since: 2.24
401	**/
402	/**
403	* g_variant_get_byte:
404	* @value: a byte #GVariant instance
405	*
406	* Returns the byte value of @value.
407	*
408	* It is an error to call this function with a @value of any type
409	* other than %G_VARIANT_TYPE_BYTE.
410	*
411	* Returns: a #guint8
412	*
413	* Since: 2.24
414	**/
415	NUMERIC_TYPE (BYTE, byte, guint8)
416
417	/**
418	* g_variant_new_int16:
419	* @value: a #gint16 value
420	*
421	* Creates a new int16 #GVariant instance.
422	*
423	* Returns: (transfer none): a floating reference to a new int16 #GVariant instance
424	*
425	* Since: 2.24
426	**/
427	/**
428	* g_variant_get_int16:
429	* @value: an int16 #GVariant instance
430	*
431	* Returns the 16-bit signed integer value of @value.
432	*
433	* It is an error to call this function with a @value of any type
434	* other than %G_VARIANT_TYPE_INT16.
435	*
436	* Returns: a #gint16
437	*
438	* Since: 2.24
439	**/
440	NUMERIC_TYPE (INT16, int16, gint16)
441
442	/**
443	* g_variant_new_uint16:
444	* @value: a #guint16 value
445	*
446	* Creates a new uint16 #GVariant instance.
447	*
448	* Returns: (transfer none): a floating reference to a new uint16 #GVariant instance
449	*
450	* Since: 2.24
451	**/
452	/**
453	* g_variant_get_uint16:
454	* @value: a uint16 #GVariant instance
455	*
456	* Returns the 16-bit unsigned integer value of @value.
457	*
458	* It is an error to call this function with a @value of any type
459	* other than %G_VARIANT_TYPE_UINT16.
460	*
461	* Returns: a #guint16
462	*
463	* Since: 2.24
464	**/
465	NUMERIC_TYPE (UINT16, uint16, guint16)
466
467	/**
468	* g_variant_new_int32:
469	* @value: a #gint32 value
470	*
471	* Creates a new int32 #GVariant instance.
472	*
473	* Returns: (transfer none): a floating reference to a new int32 #GVariant instance
474	*
475	* Since: 2.24
476	**/
477	/**
478	* g_variant_get_int32:
479	* @value: an int32 #GVariant instance
480	*
481	* Returns the 32-bit signed integer value of @value.
482	*
483	* It is an error to call this function with a @value of any type
484	* other than %G_VARIANT_TYPE_INT32.
485	*
486	* Returns: a #gint32
487	*
488	* Since: 2.24
489	**/
490	NUMERIC_TYPE (INT32, int32, gint32)
491
492	/**
493	* g_variant_new_uint32:
494	* @value: a #guint32 value
495	*
496	* Creates a new uint32 #GVariant instance.
497	*
498	* Returns: (transfer none): a floating reference to a new uint32 #GVariant instance
499	*
500	* Since: 2.24
501	**/
502	/**
503	* g_variant_get_uint32:
504	* @value: a uint32 #GVariant instance
505	*
506	* Returns the 32-bit unsigned integer value of @value.
507	*
508	* It is an error to call this function with a @value of any type
509	* other than %G_VARIANT_TYPE_UINT32.
510	*
511	* Returns: a #guint32
512	*
513	* Since: 2.24
514	**/
515	NUMERIC_TYPE (UINT32, uint32, guint32)
516
517	/**
518	* g_variant_new_int64:
519	* @value: a #gint64 value
520	*
521	* Creates a new int64 #GVariant instance.
522	*
523	* Returns: (transfer none): a floating reference to a new int64 #GVariant instance
524	*
525	* Since: 2.24
526	**/
527	/**
528	* g_variant_get_int64:
529	* @value: an int64 #GVariant instance
530	*
531	* Returns the 64-bit signed integer value of @value.
532	*
533	* It is an error to call this function with a @value of any type
534	* other than %G_VARIANT_TYPE_INT64.
535	*
536	* Returns: a #gint64
537	*
538	* Since: 2.24
539	**/
540	NUMERIC_TYPE (INT64, int64, gint64)
541
542	/**
543	* g_variant_new_uint64:
544	* @value: a #guint64 value
545	*
546	* Creates a new uint64 #GVariant instance.
547	*
548	* Returns: (transfer none): a floating reference to a new uint64 #GVariant instance
549	*
550	* Since: 2.24
551	**/
552	/**
553	* g_variant_get_uint64:
554	* @value: a uint64 #GVariant instance
555	*
556	* Returns the 64-bit unsigned integer value of @value.
557	*
558	* It is an error to call this function with a @value of any type
559	* other than %G_VARIANT_TYPE_UINT64.
560	*
561	* Returns: a #guint64
562	*
563	* Since: 2.24
564	**/
565	NUMERIC_TYPE (UINT64, uint64, guint64)
566
567	/**
568	* g_variant_new_handle:
569	* @value: a #gint32 value
570	*
571	* Creates a new handle #GVariant instance.
572	*
573	* By convention, handles are indexes into an array of file descriptors
574	* that are sent alongside a D-Bus message. If you're not interacting
575	* with D-Bus, you probably don't need them.
576	*
577	* Returns: (transfer none): a floating reference to a new handle #GVariant instance
578	*
579	* Since: 2.24
580	**/
581	/**
582	* g_variant_get_handle:
583	* @value: a handle #GVariant instance
584	*
585	* Returns the 32-bit signed integer value of @value.
586	*
587	* It is an error to call this function with a @value of any type other
588	* than %G_VARIANT_TYPE_HANDLE.
589	*
590	* By convention, handles are indexes into an array of file descriptors
591	* that are sent alongside a D-Bus message. If you're not interacting
592	* with D-Bus, you probably don't need them.
593	*
594	* Returns: a #gint32
595	*
596	* Since: 2.24
597	**/
598	NUMERIC_TYPE (HANDLE, handle, gint32)
599
600	/**
601	* g_variant_new_double:
602	* @value: a #gdouble floating point value
603	*
604	* Creates a new double #GVariant instance.
605	*
606	* Returns: (transfer none): a floating reference to a new double #GVariant instance
607	*
608	* Since: 2.24
609	**/
610	/**
611	* g_variant_get_double:
612	* @value: a double #GVariant instance
613	*
614	* Returns the double precision floating point value of @value.
615	*
616	* It is an error to call this function with a @value of any type
617	* other than %G_VARIANT_TYPE_DOUBLE.
618	*
619	* Returns: a #gdouble
620	*
621	* Since: 2.24
622	**/
623	NUMERIC_TYPE (DOUBLE, double, gdouble)
624
625	/* Container type Constructor / Deconstructors {{{1 */
626	/**
627	* g_variant_new_maybe:
628	* @child_type: (nullable): the #GVariantType of the child, or %NULL
629	* @child: (nullable): the child value, or %NULL
630	*
631	* Depending on if @child is %NULL, either wraps @child inside of a
632	* maybe container or creates a Nothing instance for the given @type.
633	*
634	* At least one of @child_type and @child must be non-%NULL.
635	* If @child_type is non-%NULL then it must be a definite type.
636	* If they are both non-%NULL then @child_type must be the type
637	* of @child.
638	*
639	* If @child is a floating reference (see g_variant_ref_sink()), the new
640	* instance takes ownership of @child.
641	*
642	* Returns: (transfer none): a floating reference to a new #GVariant maybe instance
643	*
644	* Since: 2.24
645	**/
646	GVariant *
647	g_variant_new_maybe (const GVariantType *child_type,
648	GVariant *child)
649	{
650	GVariantType *maybe_type;
651	GVariant *value;
652
653	g_return_val_if_fail (child_type == NULL || g_variant_type_is_definite
654	(child_type), 0);
655	g_return_val_if_fail (child_type != NULL || child != NULL, NULL);
656	g_return_val_if_fail (child_type == NULL || child == NULL ||
657	g_variant_is_of_type (child, child_type),
658	NULL);
659
660	if (child_type == NULL)
661	child_type = g_variant_get_type (value: child);
662
663	maybe_type = g_variant_type_new_maybe (element: child_type);
664
665	if (child != NULL)
666	{
667	GVariant **children;
668	gboolean trusted;
669
670	children = g_new (GVariant *, 1);
671	children[0] = g_variant_ref_sink (value: child);
672	trusted = g_variant_is_trusted (value: children[0]);
673
674	value = g_variant_new_from_children (type: maybe_type, children, n_children: 1, trusted);
675	}
676	else
677	value = g_variant_new_from_children (type: maybe_type, NULL, n_children: 0, TRUE);
678
679	g_variant_type_free (type: maybe_type);
680
681	return value;
682	}
683
684	/**
685	* g_variant_get_maybe:
686	* @value: a maybe-typed value
687	*
688	* Given a maybe-typed #GVariant instance, extract its value. If the
689	* value is Nothing, then this function returns %NULL.
690	*
691	* Returns: (nullable) (transfer full): the contents of @value, or %NULL
692	*
693	* Since: 2.24
694	**/
695	GVariant *
696	g_variant_get_maybe (GVariant *value)
697	{
698	TYPE_CHECK (value, G_VARIANT_TYPE_MAYBE, NULL);
699
700	if (g_variant_n_children (value))
701	return g_variant_get_child_value (value, index_: 0);
702
703	return NULL;
704	}
705
706	/**
707	* g_variant_new_variant: (constructor)
708	* @value: a #GVariant instance
709	*
710	* Boxes @value. The result is a #GVariant instance representing a
711	* variant containing the original value.
712	*
713	* If @child is a floating reference (see g_variant_ref_sink()), the new
714	* instance takes ownership of @child.
715	*
716	* Returns: (transfer none): a floating reference to a new variant #GVariant instance
717	*
718	* Since: 2.24
719	**/
720	GVariant *
721	g_variant_new_variant (GVariant *value)
722	{
723	g_return_val_if_fail (value != NULL, NULL);
724
725	g_variant_ref_sink (value);
726
727	return g_variant_new_from_children (G_VARIANT_TYPE_VARIANT,
728	children: g_memdup2 (mem: &value, byte_size: sizeof value),
729	n_children: 1, trusted: g_variant_is_trusted (value));
730	}
731
732	/**
733	* g_variant_get_variant:
734	* @value: a variant #GVariant instance
735	*
736	* Unboxes @value. The result is the #GVariant instance that was
737	* contained in @value.
738	*
739	* Returns: (transfer full): the item contained in the variant
740	*
741	* Since: 2.24
742	**/
743	GVariant *
744	g_variant_get_variant (GVariant *value)
745	{
746	TYPE_CHECK (value, G_VARIANT_TYPE_VARIANT, NULL);
747
748	return g_variant_get_child_value (value, index_: 0);
749	}
750
751	/**
752	* g_variant_new_array:
753	* @child_type: (nullable): the element type of the new array
754	* @children: (nullable) (array length=n_children): an array of
755	* #GVariant pointers, the children
756	* @n_children: the length of @children
757	*
758	* Creates a new #GVariant array from @children.
759	*
760	* @child_type must be non-%NULL if @n_children is zero. Otherwise, the
761	* child type is determined by inspecting the first element of the
762	* @children array. If @child_type is non-%NULL then it must be a
763	* definite type.
764	*
765	* The items of the array are taken from the @children array. No entry
766	* in the @children array may be %NULL.
767	*
768	* All items in the array must have the same type, which must be the
769	* same as @child_type, if given.
770	*
771	* If the @children are floating references (see g_variant_ref_sink()), the
772	* new instance takes ownership of them as if via g_variant_ref_sink().
773	*
774	* Returns: (transfer none): a floating reference to a new #GVariant array
775	*
776	* Since: 2.24
777	**/
778	GVariant *
779	g_variant_new_array (const GVariantType *child_type,
780	GVariant * const *children,
781	gsize n_children)
782	{
783	GVariantType *array_type;
784	GVariant **my_children;
785	gboolean trusted;
786	GVariant *value;
787	gsize i;
788
789	g_return_val_if_fail (n_children > 0 || child_type != NULL, NULL);
790	g_return_val_if_fail (n_children == 0 || children != NULL, NULL);
791	g_return_val_if_fail (child_type == NULL ||
792	g_variant_type_is_definite (child_type), NULL);
793
794	my_children = g_new (GVariant *, n_children);
795	trusted = TRUE;
796
797	if (child_type == NULL)
798	child_type = g_variant_get_type (value: children[0]);
799	array_type = g_variant_type_new_array (element: child_type);
800
801	for (i = 0; i < n_children; i++)
802	{
803	TYPE_CHECK (children[i], child_type, NULL);
804	my_children[i] = g_variant_ref_sink (value: children[i]);
805	trusted &= g_variant_is_trusted (value: children[i]);
806	}
807
808	value = g_variant_new_from_children (type: array_type, children: my_children,
809	n_children, trusted);
810	g_variant_type_free (type: array_type);
811
812	return value;
813	}
814
815	/*< private >
816	* g_variant_make_tuple_type:
817	* @children: (array length=n_children): an array of GVariant *
818	* @n_children: the length of @children
819	*
820	* Return the type of a tuple containing @children as its items.
821	**/
822	static GVariantType *
823	g_variant_make_tuple_type (GVariant * const *children,
824	gsize n_children)
825	{
826	const GVariantType **types;
827	GVariantType *type;
828	gsize i;
829
830	types = g_new (const GVariantType *, n_children);
831
832	for (i = 0; i < n_children; i++)
833	types[i] = g_variant_get_type (value: children[i]);
834
835	type = g_variant_type_new_tuple (items: types, length: n_children);
836	g_free (mem: types);
837
838	return type;
839	}
840
841	/**
842	* g_variant_new_tuple:
843	* @children: (array length=n_children): the items to make the tuple out of
844	* @n_children: the length of @children
845	*
846	* Creates a new tuple #GVariant out of the items in @children. The
847	* type is determined from the types of @children. No entry in the
848	* @children array may be %NULL.
849	*
850	* If @n_children is 0 then the unit tuple is constructed.
851	*
852	* If the @children are floating references (see g_variant_ref_sink()), the
853	* new instance takes ownership of them as if via g_variant_ref_sink().
854	*
855	* Returns: (transfer none): a floating reference to a new #GVariant tuple
856	*
857	* Since: 2.24
858	**/
859	GVariant *
860	g_variant_new_tuple (GVariant * const *children,
861	gsize n_children)
862	{
863	GVariantType *tuple_type;
864	GVariant **my_children;
865	gboolean trusted;
866	GVariant *value;
867	gsize i;
868
869	g_return_val_if_fail (n_children == 0 || children != NULL, NULL);
870
871	my_children = g_new (GVariant *, n_children);
872	trusted = TRUE;
873
874	for (i = 0; i < n_children; i++)
875	{
876	my_children[i] = g_variant_ref_sink (value: children[i]);
877	trusted &= g_variant_is_trusted (value: children[i]);
878	}
879
880	tuple_type = g_variant_make_tuple_type (children, n_children);
881	value = g_variant_new_from_children (type: tuple_type, children: my_children,
882	n_children, trusted);
883	g_variant_type_free (type: tuple_type);
884
885	return value;
886	}
887
888	/*< private >
889	* g_variant_make_dict_entry_type:
890	* @key: a #GVariant, the key
891	* @val: a #GVariant, the value
892	*
893	* Return the type of a dictionary entry containing @key and @val as its
894	* children.
895	**/
896	static GVariantType *
897	g_variant_make_dict_entry_type (GVariant *key,
898	GVariant *val)
899	{
900	return g_variant_type_new_dict_entry (key: g_variant_get_type (value: key),
901	value: g_variant_get_type (value: val));
902	}
903
904	/**
905	* g_variant_new_dict_entry: (constructor)
906	* @key: a basic #GVariant, the key
907	* @value: a #GVariant, the value
908	*
909	* Creates a new dictionary entry #GVariant. @key and @value must be
910	* non-%NULL. @key must be a value of a basic type (ie: not a container).
911	*
912	* If the @key or @value are floating references (see g_variant_ref_sink()),
913	* the new instance takes ownership of them as if via g_variant_ref_sink().
914	*
915	* Returns: (transfer none): a floating reference to a new dictionary entry #GVariant
916	*
917	* Since: 2.24
918	**/
919	GVariant *
920	g_variant_new_dict_entry (GVariant *key,
921	GVariant *value)
922	{
923	GVariantType *dict_type;
924	GVariant **children;
925	gboolean trusted;
926
927	g_return_val_if_fail (key != NULL && value != NULL, NULL);
928	g_return_val_if_fail (!g_variant_is_container (key), NULL);
929
930	children = g_new (GVariant *, 2);
931	children[0] = g_variant_ref_sink (value: key);
932	children[1] = g_variant_ref_sink (value);
933	trusted = g_variant_is_trusted (value: key) && g_variant_is_trusted (value);
934
935	dict_type = g_variant_make_dict_entry_type (key, val: value);
936	value = g_variant_new_from_children (type: dict_type, children, n_children: 2, trusted);
937	g_variant_type_free (type: dict_type);
938
939	return value;
940	}
941
942	/**
943	* g_variant_lookup: (skip)
944	* @dictionary: a dictionary #GVariant
945	* @key: the key to look up in the dictionary
946	* @format_string: a GVariant format string
947	* @...: the arguments to unpack the value into
948	*
949	* Looks up a value in a dictionary #GVariant.
950	*
951	* This function is a wrapper around g_variant_lookup_value() and
952	* g_variant_get(). In the case that %NULL would have been returned,
953	* this function returns %FALSE. Otherwise, it unpacks the returned
954	* value and returns %TRUE.
955	*
956	* @format_string determines the C types that are used for unpacking
957	* the values and also determines if the values are copied or borrowed,
958	* see the section on
959	* [GVariant format strings][gvariant-format-strings-pointers].
960	*
961	* This function is currently implemented with a linear scan. If you
962	* plan to do many lookups then #GVariantDict may be more efficient.
963	*
964	* Returns: %TRUE if a value was unpacked
965	*
966	* Since: 2.28
967	*/
968	gboolean
969	g_variant_lookup (GVariant *dictionary,
970	const gchar *key,
971	const gchar *format_string,
972	...)
973	{
974	GVariantType *type;
975	GVariant *value;
976
977	/* flatten */
978	g_variant_get_data (value: dictionary);
979
980	type = g_variant_format_string_scan_type (string: format_string, NULL, NULL);
981	value = g_variant_lookup_value (dictionary, key, expected_type: type);
982	g_variant_type_free (type);
983
984	if (value)
985	{
986	va_list ap;
987
988	va_start (ap, format_string);
989	g_variant_get_va (value, format_string, NULL, app: &ap);
990	g_variant_unref (value);
991	va_end (ap);
992
993	return TRUE;
994	}
995
996	else
997	return FALSE;
998	}
999
1000	/**
1001	* g_variant_lookup_value:
1002	* @dictionary: a dictionary #GVariant
1003	* @key: the key to look up in the dictionary
1004	* @expected_type: (nullable): a #GVariantType, or %NULL
1005	*
1006	* Looks up a value in a dictionary #GVariant.
1007	*
1008	* This function works with dictionaries of the type a{s*} (and equally
1009	* well with type a{o*}, but we only further discuss the string case
1010	* for sake of clarity).
1011	*
1012	* In the event that @dictionary has the type a{sv}, the @expected_type
1013	* string specifies what type of value is expected to be inside of the
1014	* variant. If the value inside the variant has a different type then
1015	* %NULL is returned. In the event that @dictionary has a value type other
1016	* than v then @expected_type must directly match the value type and it is
1017	* used to unpack the value directly or an error occurs.
1018	*
1019	* In either case, if @key is not found in @dictionary, %NULL is returned.
1020	*
1021	* If the key is found and the value has the correct type, it is
1022	* returned. If @expected_type was specified then any non-%NULL return
1023	* value will have this type.
1024	*
1025	* This function is currently implemented with a linear scan. If you
1026	* plan to do many lookups then #GVariantDict may be more efficient.
1027	*
1028	* Returns: (transfer full): the value of the dictionary key, or %NULL
1029	*
1030	* Since: 2.28
1031	*/
1032	GVariant *
1033	g_variant_lookup_value (GVariant *dictionary,
1034	const gchar *key,
1035	const GVariantType *expected_type)
1036	{
1037	GVariantIter iter;
1038	GVariant *entry;
1039	GVariant *value;
1040
1041	g_return_val_if_fail (g_variant_is_of_type (dictionary,
1042	G_VARIANT_TYPE ("a{s*}")) ||
1043	g_variant_is_of_type (dictionary,
1044	G_VARIANT_TYPE ("a{o*}")),
1045	NULL);
1046
1047	g_variant_iter_init (iter: &iter, value: dictionary);
1048
1049	while ((entry = g_variant_iter_next_value (iter: &iter)))
1050	{
1051	GVariant *entry_key;
1052	gboolean matches;
1053
1054	entry_key = g_variant_get_child_value (value: entry, index_: 0);
1055	matches = strcmp (s1: g_variant_get_string (value: entry_key, NULL), s2: key) == 0;
1056	g_variant_unref (value: entry_key);
1057
1058	if (matches)
1059	break;
1060
1061	g_variant_unref (value: entry);
1062	}
1063
1064	if (entry == NULL)
1065	return NULL;
1066
1067	value = g_variant_get_child_value (value: entry, index_: 1);
1068	g_variant_unref (value: entry);
1069
1070	if (g_variant_is_of_type (value, G_VARIANT_TYPE_VARIANT))
1071	{
1072	GVariant *tmp;
1073
1074	tmp = g_variant_get_variant (value);
1075	g_variant_unref (value);
1076
1077	if (expected_type && !g_variant_is_of_type (value: tmp, type: expected_type))
1078	{
1079	g_variant_unref (value: tmp);
1080	tmp = NULL;
1081	}
1082
1083	value = tmp;
1084	}
1085
1086	g_return_val_if_fail (expected_type == NULL || value == NULL ||
1087	g_variant_is_of_type (value, expected_type), NULL);
1088
1089	return value;
1090	}
1091
1092	/**
1093	* g_variant_get_fixed_array:
1094	* @value: a #GVariant array with fixed-sized elements
1095	* @n_elements: (out): a pointer to the location to store the number of items
1096	* @element_size: the size of each element
1097	*
1098	* Provides access to the serialised data for an array of fixed-sized
1099	* items.
1100	*
1101	* @value must be an array with fixed-sized elements. Numeric types are
1102	* fixed-size, as are tuples containing only other fixed-sized types.
1103	*
1104	* @element_size must be the size of a single element in the array,
1105	* as given by the section on
1106	* [serialized data memory][gvariant-serialised-data-memory].
1107	*
1108	* In particular, arrays of these fixed-sized types can be interpreted
1109	* as an array of the given C type, with @element_size set to the size
1110	* the appropriate type:
1111	* - %G_VARIANT_TYPE_INT16 (etc.): #gint16 (etc.)
1112	* - %G_VARIANT_TYPE_BOOLEAN: #guchar (not #gboolean!)
1113	* - %G_VARIANT_TYPE_BYTE: #guint8
1114	* - %G_VARIANT_TYPE_HANDLE: #guint32
1115	* - %G_VARIANT_TYPE_DOUBLE: #gdouble
1116	*
1117	* For example, if calling this function for an array of 32-bit integers,
1118	* you might say `sizeof(gint32)`. This value isn't used except for the purpose
1119	* of a double-check that the form of the serialised data matches the caller's
1120	* expectation.
1121	*
1122	* @n_elements, which must be non-%NULL, is set equal to the number of
1123	* items in the array.
1124	*
1125	* Returns: (array length=n_elements) (transfer none): a pointer to
1126	* the fixed array
1127	*
1128	* Since: 2.24
1129	**/
1130	gconstpointer
1131	g_variant_get_fixed_array (GVariant *value,
1132	gsize *n_elements,
1133	gsize element_size)
1134	{
1135	GVariantTypeInfo *array_info;
1136	gsize array_element_size;
1137	gconstpointer data;
1138	gsize size;
1139
1140	TYPE_CHECK (value, G_VARIANT_TYPE_ARRAY, NULL);
1141
1142	g_return_val_if_fail (n_elements != NULL, NULL);
1143	g_return_val_if_fail (element_size > 0, NULL);
1144
1145	array_info = g_variant_get_type_info (value);
1146	g_variant_type_info_query_element (typeinfo: array_info, NULL, size: &array_element_size);
1147
1148	g_return_val_if_fail (array_element_size, NULL);
1149
1150	if G_UNLIKELY (array_element_size != element_size)
1151	{
1152	if (array_element_size)
1153	g_critical ("g_variant_get_fixed_array: assertion "
1154	"'g_variant_array_has_fixed_size (value, element_size)' "
1155	"failed: array size %"G_GSIZE_FORMAT" does not match "
1156	"given element_size %"G_GSIZE_FORMAT".",
1157	array_element_size, element_size);
1158	else
1159	g_critical ("g_variant_get_fixed_array: assertion "
1160	"'g_variant_array_has_fixed_size (value, element_size)' "
1161	"failed: array does not have fixed size.");
1162	}
1163
1164	data = g_variant_get_data (value);
1165	size = g_variant_get_size (value);
1166
1167	if (size % element_size)
1168	*n_elements = 0;
1169	else
1170	*n_elements = size / element_size;
1171
1172	if (*n_elements)
1173	return data;
1174
1175	return NULL;
1176	}
1177
1178	/**
1179	* g_variant_new_fixed_array:
1180	* @element_type: the #GVariantType of each element
1181	* @elements: a pointer to the fixed array of contiguous elements
1182	* @n_elements: the number of elements
1183	* @element_size: the size of each element
1184	*
1185	* Constructs a new array #GVariant instance, where the elements are
1186	* of @element_type type.
1187	*
1188	* @elements must be an array with fixed-sized elements. Numeric types are
1189	* fixed-size as are tuples containing only other fixed-sized types.
1190	*
1191	* @element_size must be the size of a single element in the array.
1192	* For example, if calling this function for an array of 32-bit integers,
1193	* you might say sizeof(gint32). This value isn't used except for the purpose
1194	* of a double-check that the form of the serialised data matches the caller's
1195	* expectation.
1196	*
1197	* @n_elements must be the length of the @elements array.
1198	*
1199	* Returns: (transfer none): a floating reference to a new array #GVariant instance
1200	*
1201	* Since: 2.32
1202	**/
1203	GVariant *
1204	g_variant_new_fixed_array (const GVariantType *element_type,
1205	gconstpointer elements,
1206	gsize n_elements,
1207	gsize element_size)
1208	{
1209	GVariantType *array_type;
1210	gsize array_element_size;
1211	GVariantTypeInfo *array_info;
1212	GVariant *value;
1213	gpointer data;
1214
1215	g_return_val_if_fail (g_variant_type_is_definite (element_type), NULL);
1216	g_return_val_if_fail (element_size > 0, NULL);
1217
1218	array_type = g_variant_type_new_array (element: element_type);
1219	array_info = g_variant_type_info_get (type: array_type);
1220	g_variant_type_info_query_element (typeinfo: array_info, NULL, size: &array_element_size);
1221	if G_UNLIKELY (array_element_size != element_size)
1222	{
1223	if (array_element_size)
1224	g_critical ("g_variant_new_fixed_array: array size %" G_GSIZE_FORMAT
1225	" does not match given element_size %" G_GSIZE_FORMAT ".",
1226	array_element_size, element_size);
1227	else
1228	g_critical ("g_variant_get_fixed_array: array does not have fixed size.");
1229	return NULL;
1230	}
1231
1232	data = g_memdup2 (mem: elements, byte_size: n_elements * element_size);
1233	value = g_variant_new_from_data (type: array_type, data,
1234	size: n_elements * element_size,
1235	FALSE, notify: g_free, user_data: data);
1236
1237	g_variant_type_free (type: array_type);
1238	g_variant_type_info_unref (typeinfo: array_info);
1239
1240	return value;
1241	}
1242
1243	/* String type constructor/getters/validation {{{1 */
1244	/**
1245	* g_variant_new_string:
1246	* @string: a normal UTF-8 nul-terminated string
1247	*
1248	* Creates a string #GVariant with the contents of @string.
1249	*
1250	* @string must be valid UTF-8, and must not be %NULL. To encode
1251	* potentially-%NULL strings, use g_variant_new() with `ms` as the
1252	* [format string][gvariant-format-strings-maybe-types].
1253	*
1254	* Returns: (transfer none): a floating reference to a new string #GVariant instance
1255	*
1256	* Since: 2.24
1257	**/
1258	GVariant *
1259	g_variant_new_string (const gchar *string)
1260	{
1261	g_return_val_if_fail (string != NULL, NULL);
1262	g_return_val_if_fail (g_utf8_validate (string, -1, NULL), NULL);
1263
1264	return g_variant_new_from_trusted (G_VARIANT_TYPE_STRING,
1265	data: string, size: strlen (s: string) + 1);
1266	}
1267
1268	/**
1269	* g_variant_new_take_string: (skip)
1270	* @string: a normal UTF-8 nul-terminated string
1271	*
1272	* Creates a string #GVariant with the contents of @string.
1273	*
1274	* @string must be valid UTF-8, and must not be %NULL. To encode
1275	* potentially-%NULL strings, use this with g_variant_new_maybe().
1276	*
1277	* This function consumes @string. g_free() will be called on @string
1278	* when it is no longer required.
1279	*
1280	* You must not modify or access @string in any other way after passing
1281	* it to this function. It is even possible that @string is immediately
1282	* freed.
1283	*
1284	* Returns: (transfer none): a floating reference to a new string
1285	* #GVariant instance
1286	*
1287	* Since: 2.38
1288	**/
1289	GVariant *
1290	g_variant_new_take_string (gchar *string)
1291	{
1292	GVariant *value;
1293	GBytes *bytes;
1294
1295	g_return_val_if_fail (string != NULL, NULL);
1296	g_return_val_if_fail (g_utf8_validate (string, -1, NULL), NULL);
1297
1298	bytes = g_bytes_new_take (data: string, size: strlen (s: string) + 1);
1299	value = g_variant_new_from_bytes (G_VARIANT_TYPE_STRING, bytes, TRUE);
1300	g_bytes_unref (bytes);
1301
1302	return value;
1303	}
1304
1305	/**
1306	* g_variant_new_printf: (skip)
1307	* @format_string: a printf-style format string
1308	* @...: arguments for @format_string
1309	*
1310	* Creates a string-type GVariant using printf formatting.
1311	*
1312	* This is similar to calling g_strdup_printf() and then
1313	* g_variant_new_string() but it saves a temporary variable and an
1314	* unnecessary copy.
1315	*
1316	* Returns: (transfer none): a floating reference to a new string
1317	* #GVariant instance
1318	*
1319	* Since: 2.38
1320	**/
1321	GVariant *
1322	g_variant_new_printf (const gchar *format_string,
1323	...)
1324	{
1325	GVariant *value;
1326	GBytes *bytes;
1327	gchar *string;
1328	va_list ap;
1329
1330	g_return_val_if_fail (format_string != NULL, NULL);
1331
1332	va_start (ap, format_string);
1333	string = g_strdup_vprintf (format: format_string, args: ap);
1334	va_end (ap);
1335
1336	bytes = g_bytes_new_take (data: string, size: strlen (s: string) + 1);
1337	value = g_variant_new_from_bytes (G_VARIANT_TYPE_STRING, bytes, TRUE);
1338	g_bytes_unref (bytes);
1339
1340	return value;
1341	}
1342
1343	/**
1344	* g_variant_new_object_path:
1345	* @object_path: a normal C nul-terminated string
1346	*
1347	* Creates a D-Bus object path #GVariant with the contents of @string.
1348	* @string must be a valid D-Bus object path. Use
1349	* g_variant_is_object_path() if you're not sure.
1350	*
1351	* Returns: (transfer none): a floating reference to a new object path #GVariant instance
1352	*
1353	* Since: 2.24
1354	**/
1355	GVariant *
1356	g_variant_new_object_path (const gchar *object_path)
1357	{
1358	g_return_val_if_fail (g_variant_is_object_path (object_path), NULL);
1359
1360	return g_variant_new_from_trusted (G_VARIANT_TYPE_OBJECT_PATH,
1361	data: object_path, size: strlen (s: object_path) + 1);
1362	}
1363
1364	/**
1365	* g_variant_is_object_path:
1366	* @string: a normal C nul-terminated string
1367	*
1368	* Determines if a given string is a valid D-Bus object path. You
1369	* should ensure that a string is a valid D-Bus object path before
1370	* passing it to g_variant_new_object_path().
1371	*
1372	* A valid object path starts with `/` followed by zero or more
1373	* sequences of characters separated by `/` characters. Each sequence
1374	* must contain only the characters `[A-Z][a-z][0-9]_`. No sequence
1375	* (including the one following the final `/` character) may be empty.
1376	*
1377	* Returns: %TRUE if @string is a D-Bus object path
1378	*
1379	* Since: 2.24
1380	**/
1381	gboolean
1382	g_variant_is_object_path (const gchar *string)
1383	{
1384	g_return_val_if_fail (string != NULL, FALSE);
1385
1386	return g_variant_serialiser_is_object_path (data: string, size: strlen (s: string) + 1);
1387	}
1388
1389	/**
1390	* g_variant_new_signature:
1391	* @signature: a normal C nul-terminated string
1392	*
1393	* Creates a D-Bus type signature #GVariant with the contents of
1394	* @string. @string must be a valid D-Bus type signature. Use
1395	* g_variant_is_signature() if you're not sure.
1396	*
1397	* Returns: (transfer none): a floating reference to a new signature #GVariant instance
1398	*
1399	* Since: 2.24
1400	**/
1401	GVariant *
1402	g_variant_new_signature (const gchar *signature)
1403	{
1404	g_return_val_if_fail (g_variant_is_signature (signature), NULL);
1405
1406	return g_variant_new_from_trusted (G_VARIANT_TYPE_SIGNATURE,
1407	data: signature, size: strlen (s: signature) + 1);
1408	}
1409
1410	/**
1411	* g_variant_is_signature:
1412	* @string: a normal C nul-terminated string
1413	*
1414	* Determines if a given string is a valid D-Bus type signature. You
1415	* should ensure that a string is a valid D-Bus type signature before
1416	* passing it to g_variant_new_signature().
1417	*
1418	* D-Bus type signatures consist of zero or more definite #GVariantType
1419	* strings in sequence.
1420	*
1421	* Returns: %TRUE if @string is a D-Bus type signature
1422	*
1423	* Since: 2.24
1424	**/
1425	gboolean
1426	g_variant_is_signature (const gchar *string)
1427	{
1428	g_return_val_if_fail (string != NULL, FALSE);
1429
1430	return g_variant_serialiser_is_signature (data: string, size: strlen (s: string) + 1);
1431	}
1432
1433	/**
1434	* g_variant_get_string:
1435	* @value: a string #GVariant instance
1436	* @length: (optional) (default 0) (out): a pointer to a #gsize,
1437	* to store the length
1438	*
1439	* Returns the string value of a #GVariant instance with a string
1440	* type. This includes the types %G_VARIANT_TYPE_STRING,
1441	* %G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE.
1442	*
1443	* The string will always be UTF-8 encoded, will never be %NULL, and will never
1444	* contain nul bytes.
1445	*
1446	* If @length is non-%NULL then the length of the string (in bytes) is
1447	* returned there. For trusted values, this information is already
1448	* known. Untrusted values will be validated and, if valid, a strlen() will be
1449	* performed. If invalid, a default value will be returned — for
1450	* %G_VARIANT_TYPE_OBJECT_PATH, this is `"/"`, and for other types it is the
1451	* empty string.
1452	*
1453	* It is an error to call this function with a @value of any type
1454	* other than those three.
1455	*
1456	* The return value remains valid as long as @value exists.
1457	*
1458	* Returns: (transfer none): the constant string, UTF-8 encoded
1459	*
1460	* Since: 2.24
1461	**/
1462	const gchar *
1463	g_variant_get_string (GVariant *value,
1464	gsize *length)
1465	{
1466	gconstpointer data;
1467	gsize size;
1468
1469	g_return_val_if_fail (value != NULL, NULL);
1470	g_return_val_if_fail (
1471	g_variant_is_of_type (value, G_VARIANT_TYPE_STRING) ||
1472	g_variant_is_of_type (value, G_VARIANT_TYPE_OBJECT_PATH) ||
1473	g_variant_is_of_type (value, G_VARIANT_TYPE_SIGNATURE), NULL);
1474
1475	data = g_variant_get_data (value);
1476	size = g_variant_get_size (value);
1477
1478	if (!g_variant_is_trusted (value))
1479	{
1480	switch (g_variant_classify (value))
1481	{
1482	case G_VARIANT_CLASS_STRING:
1483	if (g_variant_serialiser_is_string (data, size))
1484	break;
1485
1486	data = "";
1487	size = 1;
1488	break;
1489
1490	case G_VARIANT_CLASS_OBJECT_PATH:
1491	if (g_variant_serialiser_is_object_path (data, size))
1492	break;
1493
1494	data = "/";
1495	size = 2;
1496	break;
1497
1498	case G_VARIANT_CLASS_SIGNATURE:
1499	if (g_variant_serialiser_is_signature (data, size))
1500	break;
1501
1502	data = "";
1503	size = 1;
1504	break;
1505
1506	default:
1507	g_assert_not_reached ();
1508	}
1509	}
1510
1511	if (length)
1512	*length = size - 1;
1513
1514	return data;
1515	}
1516
1517	/**
1518	* g_variant_dup_string:
1519	* @value: a string #GVariant instance
1520	* @length: (out): a pointer to a #gsize, to store the length
1521	*
1522	* Similar to g_variant_get_string() except that instead of returning
1523	* a constant string, the string is duplicated.
1524	*
1525	* The string will always be UTF-8 encoded.
1526	*
1527	* The return value must be freed using g_free().
1528	*
1529	* Returns: (transfer full): a newly allocated string, UTF-8 encoded
1530	*
1531	* Since: 2.24
1532	**/
1533	gchar *
1534	g_variant_dup_string (GVariant *value,
1535	gsize *length)
1536	{
1537	return g_strdup (str: g_variant_get_string (value, length));
1538	}
1539
1540	/**
1541	* g_variant_new_strv:
1542	* @strv: (array length=length) (element-type utf8): an array of strings
1543	* @length: the length of @strv, or -1
1544	*
1545	* Constructs an array of strings #GVariant from the given array of
1546	* strings.
1547	*
1548	* If @length is -1 then @strv is %NULL-terminated.
1549	*
1550	* Returns: (transfer none): a new floating #GVariant instance
1551	*
1552	* Since: 2.24
1553	**/
1554	GVariant *
1555	g_variant_new_strv (const gchar * const *strv,
1556	gssize length)
1557	{
1558	GVariant **strings;
1559	gsize i, length_unsigned;
1560
1561	g_return_val_if_fail (length == 0 || strv != NULL, NULL);
1562
1563	if (length < 0)
1564	length = g_strv_length (str_array: (gchar **) strv);
1565	length_unsigned = length;
1566
1567	strings = g_new (GVariant *, length_unsigned);
1568	for (i = 0; i < length_unsigned; i++)
1569	strings[i] = g_variant_ref_sink (value: g_variant_new_string (string: strv[i]));
1570
1571	return g_variant_new_from_children (G_VARIANT_TYPE_STRING_ARRAY,
1572	children: strings, n_children: length_unsigned, TRUE);
1573	}
1574
1575	/**
1576	* g_variant_get_strv:
1577	* @value: an array of strings #GVariant
1578	* @length: (out) (optional): the length of the result, or %NULL
1579	*
1580	* Gets the contents of an array of strings #GVariant. This call
1581	* makes a shallow copy; the return result should be released with
1582	* g_free(), but the individual strings must not be modified.
1583	*
1584	* If @length is non-%NULL then the number of elements in the result
1585	* is stored there. In any case, the resulting array will be
1586	* %NULL-terminated.
1587	*
1588	* For an empty array, @length will be set to 0 and a pointer to a
1589	* %NULL pointer will be returned.
1590	*
1591	* Returns: (array length=length zero-terminated=1) (transfer container): an array of constant strings
1592	*
1593	* Since: 2.24
1594	**/
1595	const gchar **
1596	g_variant_get_strv (GVariant *value,
1597	gsize *length)
1598	{
1599	const gchar **strv;
1600	gsize n;
1601	gsize i;
1602
1603	TYPE_CHECK (value, G_VARIANT_TYPE_STRING_ARRAY, NULL);
1604
1605	g_variant_get_data (value);
1606	n = g_variant_n_children (value);
1607	strv = g_new (const gchar *, n + 1);
1608
1609	for (i = 0; i < n; i++)
1610	{
1611	GVariant *string;
1612
1613	string = g_variant_get_child_value (value, index_: i);
1614	strv[i] = g_variant_get_string (value: string, NULL);
1615	g_variant_unref (value: string);
1616	}
1617	strv[i] = NULL;
1618
1619	if (length)
1620	*length = n;
1621
1622	return strv;
1623	}
1624
1625	/**
1626	* g_variant_dup_strv:
1627	* @value: an array of strings #GVariant
1628	* @length: (out) (optional): the length of the result, or %NULL
1629	*
1630	* Gets the contents of an array of strings #GVariant. This call
1631	* makes a deep copy; the return result should be released with
1632	* g_strfreev().
1633	*
1634	* If @length is non-%NULL then the number of elements in the result
1635	* is stored there. In any case, the resulting array will be
1636	* %NULL-terminated.
1637	*
1638	* For an empty array, @length will be set to 0 and a pointer to a
1639	* %NULL pointer will be returned.
1640	*
1641	* Returns: (array length=length zero-terminated=1) (transfer full): an array of strings
1642	*
1643	* Since: 2.24
1644	**/
1645	gchar **
1646	g_variant_dup_strv (GVariant *value,
1647	gsize *length)
1648	{
1649	gchar **strv;
1650	gsize n;
1651	gsize i;
1652
1653	TYPE_CHECK (value, G_VARIANT_TYPE_STRING_ARRAY, NULL);
1654
1655	n = g_variant_n_children (value);
1656	strv = g_new (gchar *, n + 1);
1657
1658	for (i = 0; i < n; i++)
1659	{
1660	GVariant *string;
1661
1662	string = g_variant_get_child_value (value, index_: i);
1663	strv[i] = g_variant_dup_string (value: string, NULL);
1664	g_variant_unref (value: string);
1665	}
1666	strv[i] = NULL;
1667
1668	if (length)
1669	*length = n;
1670
1671	return strv;
1672	}
1673
1674	/**
1675	* g_variant_new_objv:
1676	* @strv: (array length=length) (element-type utf8): an array of strings
1677	* @length: the length of @strv, or -1
1678	*
1679	* Constructs an array of object paths #GVariant from the given array of
1680	* strings.
1681	*
1682	* Each string must be a valid #GVariant object path; see
1683	* g_variant_is_object_path().
1684	*
1685	* If @length is -1 then @strv is %NULL-terminated.
1686	*
1687	* Returns: (transfer none): a new floating #GVariant instance
1688	*
1689	* Since: 2.30
1690	**/
1691	GVariant *
1692	g_variant_new_objv (const gchar * const *strv,
1693	gssize length)
1694	{
1695	GVariant **strings;
1696	gsize i, length_unsigned;
1697
1698	g_return_val_if_fail (length == 0 || strv != NULL, NULL);
1699
1700	if (length < 0)
1701	length = g_strv_length (str_array: (gchar **) strv);
1702	length_unsigned = length;
1703
1704	strings = g_new (GVariant *, length_unsigned);
1705	for (i = 0; i < length_unsigned; i++)
1706	strings[i] = g_variant_ref_sink (value: g_variant_new_object_path (object_path: strv[i]));
1707
1708	return g_variant_new_from_children (G_VARIANT_TYPE_OBJECT_PATH_ARRAY,
1709	children: strings, n_children: length_unsigned, TRUE);
1710	}
1711
1712	/**
1713	* g_variant_get_objv:
1714	* @value: an array of object paths #GVariant
1715	* @length: (out) (optional): the length of the result, or %NULL
1716	*
1717	* Gets the contents of an array of object paths #GVariant. This call
1718	* makes a shallow copy; the return result should be released with
1719	* g_free(), but the individual strings must not be modified.
1720	*
1721	* If @length is non-%NULL then the number of elements in the result
1722	* is stored there. In any case, the resulting array will be
1723	* %NULL-terminated.
1724	*
1725	* For an empty array, @length will be set to 0 and a pointer to a
1726	* %NULL pointer will be returned.
1727	*
1728	* Returns: (array length=length zero-terminated=1) (transfer container): an array of constant strings
1729	*
1730	* Since: 2.30
1731	**/
1732	const gchar **
1733	g_variant_get_objv (GVariant *value,
1734	gsize *length)
1735	{
1736	const gchar **strv;
1737	gsize n;
1738	gsize i;
1739
1740	TYPE_CHECK (value, G_VARIANT_TYPE_OBJECT_PATH_ARRAY, NULL);
1741
1742	g_variant_get_data (value);
1743	n = g_variant_n_children (value);
1744	strv = g_new (const gchar *, n + 1);
1745
1746	for (i = 0; i < n; i++)
1747	{
1748	GVariant *string;
1749
1750	string = g_variant_get_child_value (value, index_: i);
1751	strv[i] = g_variant_get_string (value: string, NULL);
1752	g_variant_unref (value: string);
1753	}
1754	strv[i] = NULL;
1755
1756	if (length)
1757	*length = n;
1758
1759	return strv;
1760	}
1761
1762	/**
1763	* g_variant_dup_objv:
1764	* @value: an array of object paths #GVariant
1765	* @length: (out) (optional): the length of the result, or %NULL
1766	*
1767	* Gets the contents of an array of object paths #GVariant. This call
1768	* makes a deep copy; the return result should be released with
1769	* g_strfreev().
1770	*
1771	* If @length is non-%NULL then the number of elements in the result
1772	* is stored there. In any case, the resulting array will be
1773	* %NULL-terminated.
1774	*
1775	* For an empty array, @length will be set to 0 and a pointer to a
1776	* %NULL pointer will be returned.
1777	*
1778	* Returns: (array length=length zero-terminated=1) (transfer full): an array of strings
1779	*
1780	* Since: 2.30
1781	**/
1782	gchar **
1783	g_variant_dup_objv (GVariant *value,
1784	gsize *length)
1785	{
1786	gchar **strv;
1787	gsize n;
1788	gsize i;
1789
1790	TYPE_CHECK (value, G_VARIANT_TYPE_OBJECT_PATH_ARRAY, NULL);
1791
1792	n = g_variant_n_children (value);
1793	strv = g_new (gchar *, n + 1);
1794
1795	for (i = 0; i < n; i++)
1796	{
1797	GVariant *string;
1798
1799	string = g_variant_get_child_value (value, index_: i);
1800	strv[i] = g_variant_dup_string (value: string, NULL);
1801	g_variant_unref (value: string);
1802	}
1803	strv[i] = NULL;
1804
1805	if (length)
1806	*length = n;
1807
1808	return strv;
1809	}
1810
1811
1812	/**
1813	* g_variant_new_bytestring:
1814	* @string: (array zero-terminated=1) (element-type guint8): a normal
1815	* nul-terminated string in no particular encoding
1816	*
1817	* Creates an array-of-bytes #GVariant with the contents of @string.
1818	* This function is just like g_variant_new_string() except that the
1819	* string need not be valid UTF-8.
1820	*
1821	* The nul terminator character at the end of the string is stored in
1822	* the array.
1823	*
1824	* Returns: (transfer none): a floating reference to a new bytestring #GVariant instance
1825	*
1826	* Since: 2.26
1827	**/
1828	GVariant *
1829	g_variant_new_bytestring (const gchar *string)
1830	{
1831	g_return_val_if_fail (string != NULL, NULL);
1832
1833	return g_variant_new_from_trusted (G_VARIANT_TYPE_BYTESTRING,
1834	data: string, size: strlen (s: string) + 1);
1835	}
1836
1837	/**
1838	* g_variant_get_bytestring:
1839	* @value: an array-of-bytes #GVariant instance
1840	*
1841	* Returns the string value of a #GVariant instance with an
1842	* array-of-bytes type. The string has no particular encoding.
1843	*
1844	* If the array does not end with a nul terminator character, the empty
1845	* string is returned. For this reason, you can always trust that a
1846	* non-%NULL nul-terminated string will be returned by this function.
1847	*
1848	* If the array contains a nul terminator character somewhere other than
1849	* the last byte then the returned string is the string, up to the first
1850	* such nul character.
1851	*
1852	* g_variant_get_fixed_array() should be used instead if the array contains
1853	* arbitrary data that could not be nul-terminated or could contain nul bytes.
1854	*
1855	* It is an error to call this function with a @value that is not an
1856	* array of bytes.
1857	*
1858	* The return value remains valid as long as @value exists.
1859	*
1860	* Returns: (transfer none) (array zero-terminated=1) (element-type guint8):
1861	* the constant string
1862	*
1863	* Since: 2.26
1864	**/
1865	const gchar *
1866	g_variant_get_bytestring (GVariant *value)
1867	{
1868	const gchar *string;
1869	gsize size;
1870
1871	TYPE_CHECK (value, G_VARIANT_TYPE_BYTESTRING, NULL);
1872
1873	/* Won't be NULL since this is an array type */
1874	string = g_variant_get_data (value);
1875	size = g_variant_get_size (value);
1876
1877	if (size && string[size - 1] == '\0')
1878	return string;
1879	else
1880	return "";
1881	}
1882
1883	/**
1884	* g_variant_dup_bytestring:
1885	* @value: an array-of-bytes #GVariant instance
1886	* @length: (out) (optional) (default NULL): a pointer to a #gsize, to store
1887	* the length (not including the nul terminator)
1888	*
1889	* Similar to g_variant_get_bytestring() except that instead of
1890	* returning a constant string, the string is duplicated.
1891	*
1892	* The return value must be freed using g_free().
1893	*
1894	* Returns: (transfer full) (array zero-terminated=1 length=length) (element-type guint8):
1895	* a newly allocated string
1896	*
1897	* Since: 2.26
1898	**/
1899	gchar *
1900	g_variant_dup_bytestring (GVariant *value,
1901	gsize *length)
1902	{
1903	const gchar *original = g_variant_get_bytestring (value);
1904	gsize size;
1905
1906	/* don't crash in case get_bytestring() had an assert failure */
1907	if (original == NULL)
1908	return NULL;
1909
1910	size = strlen (s: original);
1911
1912	if (length)
1913	*length = size;
1914
1915	return g_memdup2 (mem: original, byte_size: size + 1);
1916	}
1917
1918	/**
1919	* g_variant_new_bytestring_array:
1920	* @strv: (array length=length): an array of strings
1921	* @length: the length of @strv, or -1
1922	*
1923	* Constructs an array of bytestring #GVariant from the given array of
1924	* strings.
1925	*
1926	* If @length is -1 then @strv is %NULL-terminated.
1927	*
1928	* Returns: (transfer none): a new floating #GVariant instance
1929	*
1930	* Since: 2.26
1931	**/
1932	GVariant *
1933	g_variant_new_bytestring_array (const gchar * const *strv,
1934	gssize length)
1935	{
1936	GVariant **strings;
1937	gsize i, length_unsigned;
1938
1939	g_return_val_if_fail (length == 0 || strv != NULL, NULL);
1940
1941	if (length < 0)
1942	length = g_strv_length (str_array: (gchar **) strv);
1943	length_unsigned = length;
1944
1945	strings = g_new (GVariant *, length_unsigned);
1946	for (i = 0; i < length_unsigned; i++)
1947	strings[i] = g_variant_ref_sink (value: g_variant_new_bytestring (string: strv[i]));
1948
1949	return g_variant_new_from_children (G_VARIANT_TYPE_BYTESTRING_ARRAY,
1950	children: strings, n_children: length_unsigned, TRUE);
1951	}
1952
1953	/**
1954	* g_variant_get_bytestring_array:
1955	* @value: an array of array of bytes #GVariant ('aay')
1956	* @length: (out) (optional): the length of the result, or %NULL
1957	*
1958	* Gets the contents of an array of array of bytes #GVariant. This call
1959	* makes a shallow copy; the return result should be released with
1960	* g_free(), but the individual strings must not be modified.
1961	*
1962	* If @length is non-%NULL then the number of elements in the result is
1963	* stored there. In any case, the resulting array will be
1964	* %NULL-terminated.
1965	*
1966	* For an empty array, @length will be set to 0 and a pointer to a
1967	* %NULL pointer will be returned.
1968	*
1969	* Returns: (array length=length) (transfer container): an array of constant strings
1970	*
1971	* Since: 2.26
1972	**/
1973	const gchar **
1974	g_variant_get_bytestring_array (GVariant *value,
1975	gsize *length)
1976	{
1977	const gchar **strv;
1978	gsize n;
1979	gsize i;
1980
1981	TYPE_CHECK (value, G_VARIANT_TYPE_BYTESTRING_ARRAY, NULL);
1982
1983	g_variant_get_data (value);
1984	n = g_variant_n_children (value);
1985	strv = g_new (const gchar *, n + 1);
1986
1987	for (i = 0; i < n; i++)
1988	{
1989	GVariant *string;
1990
1991	string = g_variant_get_child_value (value, index_: i);
1992	strv[i] = g_variant_get_bytestring (value: string);
1993	g_variant_unref (value: string);
1994	}
1995	strv[i] = NULL;
1996
1997	if (length)
1998	*length = n;
1999
2000	return strv;
2001	}
2002
2003	/**
2004	* g_variant_dup_bytestring_array:
2005	* @value: an array of array of bytes #GVariant ('aay')
2006	* @length: (out) (optional): the length of the result, or %NULL
2007	*
2008	* Gets the contents of an array of array of bytes #GVariant. This call
2009	* makes a deep copy; the return result should be released with
2010	* g_strfreev().
2011	*
2012	* If @length is non-%NULL then the number of elements in the result is
2013	* stored there. In any case, the resulting array will be
2014	* %NULL-terminated.
2015	*
2016	* For an empty array, @length will be set to 0 and a pointer to a
2017	* %NULL pointer will be returned.
2018	*
2019	* Returns: (array length=length) (transfer full): an array of strings
2020	*
2021	* Since: 2.26
2022	**/
2023	gchar **
2024	g_variant_dup_bytestring_array (GVariant *value,
2025	gsize *length)
2026	{
2027	gchar **strv;
2028	gsize n;
2029	gsize i;
2030
2031	TYPE_CHECK (value, G_VARIANT_TYPE_BYTESTRING_ARRAY, NULL);
2032
2033	g_variant_get_data (value);
2034	n = g_variant_n_children (value);
2035	strv = g_new (gchar *, n + 1);
2036
2037	for (i = 0; i < n; i++)
2038	{
2039	GVariant *string;
2040
2041	string = g_variant_get_child_value (value, index_: i);
2042	strv[i] = g_variant_dup_bytestring (value: string, NULL);
2043	g_variant_unref (value: string);
2044	}
2045	strv[i] = NULL;
2046
2047	if (length)
2048	*length = n;
2049
2050	return strv;
2051	}
2052
2053	/* Type checking and querying {{{1 */
2054	/**
2055	* g_variant_get_type:
2056	* @value: a #GVariant
2057	*
2058	* Determines the type of @value.
2059	*
2060	* The return value is valid for the lifetime of @value and must not
2061	* be freed.
2062	*
2063	* Returns: a #GVariantType
2064	*
2065	* Since: 2.24
2066	**/
2067	const GVariantType *
2068	g_variant_get_type (GVariant *value)
2069	{
2070	GVariantTypeInfo *type_info;
2071
2072	g_return_val_if_fail (value != NULL, NULL);
2073
2074	type_info = g_variant_get_type_info (value);
2075
2076	return (GVariantType *) g_variant_type_info_get_type_string (typeinfo: type_info);
2077	}
2078
2079	/**
2080	* g_variant_get_type_string:
2081	* @value: a #GVariant
2082	*
2083	* Returns the type string of @value. Unlike the result of calling
2084	* g_variant_type_peek_string(), this string is nul-terminated. This
2085	* string belongs to #GVariant and must not be freed.
2086	*
2087	* Returns: the type string for the type of @value
2088	*
2089	* Since: 2.24
2090	**/
2091	const gchar *
2092	g_variant_get_type_string (GVariant *value)
2093	{
2094	GVariantTypeInfo *type_info;
2095
2096	g_return_val_if_fail (value != NULL, NULL);
2097
2098	type_info = g_variant_get_type_info (value);
2099
2100	return g_variant_type_info_get_type_string (typeinfo: type_info);
2101	}
2102
2103	/**
2104	* g_variant_is_of_type:
2105	* @value: a #GVariant instance
2106	* @type: a #GVariantType
2107	*
2108	* Checks if a value has a type matching the provided type.
2109	*
2110	* Returns: %TRUE if the type of @value matches @type
2111	*
2112	* Since: 2.24
2113	**/
2114	gboolean
2115	g_variant_is_of_type (GVariant *value,
2116	const GVariantType *type)
2117	{
2118	return g_variant_type_is_subtype_of (type: g_variant_get_type (value), supertype: type);
2119	}
2120
2121	/**
2122	* g_variant_is_container:
2123	* @value: a #GVariant instance
2124	*
2125	* Checks if @value is a container.
2126	*
2127	* Returns: %TRUE if @value is a container
2128	*
2129	* Since: 2.24
2130	*/
2131	gboolean
2132	g_variant_is_container (GVariant *value)
2133	{
2134	return g_variant_type_is_container (type: g_variant_get_type (value));
2135	}
2136
2137
2138	/**
2139	* g_variant_classify:
2140	* @value: a #GVariant
2141	*
2142	* Classifies @value according to its top-level type.
2143	*
2144	* Returns: the #GVariantClass of @value
2145	*
2146	* Since: 2.24
2147	**/
2148	/**
2149	* GVariantClass:
2150	* @G_VARIANT_CLASS_BOOLEAN: The #GVariant is a boolean.
2151	* @G_VARIANT_CLASS_BYTE: The #GVariant is a byte.
2152	* @G_VARIANT_CLASS_INT16: The #GVariant is a signed 16 bit integer.
2153	* @G_VARIANT_CLASS_UINT16: The #GVariant is an unsigned 16 bit integer.
2154	* @G_VARIANT_CLASS_INT32: The #GVariant is a signed 32 bit integer.
2155	* @G_VARIANT_CLASS_UINT32: The #GVariant is an unsigned 32 bit integer.
2156	* @G_VARIANT_CLASS_INT64: The #GVariant is a signed 64 bit integer.
2157	* @G_VARIANT_CLASS_UINT64: The #GVariant is an unsigned 64 bit integer.
2158	* @G_VARIANT_CLASS_HANDLE: The #GVariant is a file handle index.
2159	* @G_VARIANT_CLASS_DOUBLE: The #GVariant is a double precision floating
2160	* point value.
2161	* @G_VARIANT_CLASS_STRING: The #GVariant is a normal string.
2162	* @G_VARIANT_CLASS_OBJECT_PATH: The #GVariant is a D-Bus object path
2163	* string.
2164	* @G_VARIANT_CLASS_SIGNATURE: The #GVariant is a D-Bus signature string.
2165	* @G_VARIANT_CLASS_VARIANT: The #GVariant is a variant.
2166	* @G_VARIANT_CLASS_MAYBE: The #GVariant is a maybe-typed value.
2167	* @G_VARIANT_CLASS_ARRAY: The #GVariant is an array.
2168	* @G_VARIANT_CLASS_TUPLE: The #GVariant is a tuple.
2169	* @G_VARIANT_CLASS_DICT_ENTRY: The #GVariant is a dictionary entry.
2170	*
2171	* The range of possible top-level types of #GVariant instances.
2172	*
2173	* Since: 2.24
2174	**/
2175	GVariantClass
2176	g_variant_classify (GVariant *value)
2177	{
2178	g_return_val_if_fail (value != NULL, 0);
2179
2180	return *g_variant_get_type_string (value);
2181	}
2182
2183	/* Pretty printer {{{1 */
2184	/* This function is not introspectable because if @string is NULL,
2185	@returns is (transfer full), otherwise it is (transfer none), which
2186	is not supported by GObjectIntrospection */
2187	/**
2188	* g_variant_print_string: (skip)
2189	* @value: a #GVariant
2190	* @string: (nullable) (default NULL): a #GString, or %NULL
2191	* @type_annotate: %TRUE if type information should be included in
2192	* the output
2193	*
2194	* Behaves as g_variant_print(), but operates on a #GString.
2195	*
2196	* If @string is non-%NULL then it is appended to and returned. Else,
2197	* a new empty #GString is allocated and it is returned.
2198	*
2199	* Returns: a #GString containing the string
2200	*
2201	* Since: 2.24
2202	**/
2203	GString *
2204	g_variant_print_string (GVariant *value,
2205	GString *string,
2206	gboolean type_annotate)
2207	{
2208	if G_UNLIKELY (string == NULL)
2209	string = g_string_new (NULL);
2210
2211	switch (g_variant_classify (value))
2212	{
2213	case G_VARIANT_CLASS_MAYBE:
2214	if (type_annotate)
2215	g_string_append_printf (string, format: "@%s ",
2216	g_variant_get_type_string (value));
2217
2218	if (g_variant_n_children (value))
2219	{
2220	gchar *printed_child;
2221	GVariant *element;
2222
2223	/* Nested maybes:
2224	*
2225	* Consider the case of the type "mmi". In this case we could
2226	* write "just just 4", but "4" alone is totally unambiguous,
2227	* so we try to drop "just" where possible.
2228	*
2229	* We have to be careful not to always drop "just", though,
2230	* since "nothing" needs to be distinguishable from "just
2231	* nothing". The case where we need to ensure we keep the
2232	* "just" is actually exactly the case where we have a nested
2233	* Nothing.
2234	*
2235	* Instead of searching for that nested Nothing, we just print
2236	* the contained value into a separate string and see if we
2237	* end up with "nothing" at the end of it. If so, we need to
2238	* add "just" at our level.
2239	*/
2240	element = g_variant_get_child_value (value, index_: 0);
2241	printed_child = g_variant_print (value: element, FALSE);
2242	g_variant_unref (value: element);
2243
2244	if (g_str_has_suffix (str: printed_child, suffix: "nothing"))
2245	g_string_append (string, val: "just ");
2246	g_string_append (string, val: printed_child);
2247	g_free (mem: printed_child);
2248	}
2249	else
2250	g_string_append (string, val: "nothing");
2251
2252	break;
2253
2254	case G_VARIANT_CLASS_ARRAY:
2255	/* it's an array so the first character of the type string is 'a'
2256	*
2257	* if the first two characters are 'ay' then it's a bytestring.
2258	* under certain conditions we print those as strings.
2259	*/
2260	if (g_variant_get_type_string (value)[1] == 'y')
2261	{
2262	const gchar *str;
2263	gsize size;
2264	gsize i;
2265
2266	/* first determine if it is a byte string.
2267	* that's when there's a single nul character: at the end.
2268	*/
2269	str = g_variant_get_data (value);
2270	size = g_variant_get_size (value);
2271
2272	for (i = 0; i < size; i++)
2273	if (str[i] == '\0')
2274	break;
2275
2276	/* first nul byte is the last byte -> it's a byte string. */
2277	if (i == size - 1)
2278	{
2279	gchar *escaped = g_strescape (source: str, NULL);
2280
2281	/* use double quotes only if a ' is in the string */
2282	if (strchr (s: str, c: '\''))
2283	g_string_append_printf (string, format: "b\"%s\"", escaped);
2284	else
2285	g_string_append_printf (string, format: "b'%s'", escaped);
2286
2287	g_free (mem: escaped);
2288	break;
2289	}
2290
2291	else
2292	{
2293	/* fall through and handle normally... */
2294	}
2295	}
2296
2297	/*
2298	* if the first two characters are 'a{' then it's an array of
2299	* dictionary entries (ie: a dictionary) so we print that
2300	* differently.
2301	*/
2302	if (g_variant_get_type_string (value)[1] == '{')
2303	/* dictionary */
2304	{
2305	const gchar *comma = "";
2306	gsize n, i;
2307
2308	if ((n = g_variant_n_children (value)) == 0)
2309	{
2310	if (type_annotate)
2311	g_string_append_printf (string, format: "@%s ",
2312	g_variant_get_type_string (value));
2313	g_string_append (string, val: "{}");
2314	break;
2315	}
2316
2317	g_string_append_c (string, '{');
2318	for (i = 0; i < n; i++)
2319	{
2320	GVariant *entry, *key, *val;
2321
2322	g_string_append (string, val: comma);
2323	comma = ", ";
2324
2325	entry = g_variant_get_child_value (value, index_: i);
2326	key = g_variant_get_child_value (value: entry, index_: 0);
2327	val = g_variant_get_child_value (value: entry, index_: 1);
2328	g_variant_unref (value: entry);
2329
2330	g_variant_print_string (value: key, string, type_annotate);
2331	g_variant_unref (value: key);
2332	g_string_append (string, val: ": ");
2333	g_variant_print_string (value: val, string, type_annotate);
2334	g_variant_unref (value: val);
2335	type_annotate = FALSE;
2336	}
2337	g_string_append_c (string, '}');
2338	}
2339	else
2340	/* normal (non-dictionary) array */
2341	{
2342	const gchar *comma = "";
2343	gsize n, i;
2344
2345	if ((n = g_variant_n_children (value)) == 0)
2346	{
2347	if (type_annotate)
2348	g_string_append_printf (string, format: "@%s ",
2349	g_variant_get_type_string (value));
2350	g_string_append (string, val: "[]");
2351	break;
2352	}
2353
2354	g_string_append_c (string, '[');
2355	for (i = 0; i < n; i++)
2356	{
2357	GVariant *element;
2358
2359	g_string_append (string, val: comma);
2360	comma = ", ";
2361
2362	element = g_variant_get_child_value (value, index_: i);
2363
2364	g_variant_print_string (value: element, string, type_annotate);
2365	g_variant_unref (value: element);
2366	type_annotate = FALSE;
2367	}
2368	g_string_append_c (string, ']');
2369	}
2370
2371	break;
2372
2373	case G_VARIANT_CLASS_TUPLE:
2374	{
2375	gsize n, i;
2376
2377	n = g_variant_n_children (value);
2378
2379	g_string_append_c (string, '(');
2380	for (i = 0; i < n; i++)
2381	{
2382	GVariant *element;
2383
2384	element = g_variant_get_child_value (value, index_: i);
2385	g_variant_print_string (value: element, string, type_annotate);
2386	g_string_append (string, val: ", ");
2387	g_variant_unref (value: element);
2388	}
2389
2390	/* for >1 item: remove final ", "
2391	* for 1 item: remove final " ", but leave the ","
2392	* for 0 items: there is only "(", so remove nothing
2393	*/
2394	g_string_truncate (string, len: string->len - (n > 0) - (n > 1));
2395	g_string_append_c (string, ')');
2396	}
2397	break;
2398
2399	case G_VARIANT_CLASS_DICT_ENTRY:
2400	{
2401	GVariant *element;
2402
2403	g_string_append_c (string, '{');
2404
2405	element = g_variant_get_child_value (value, index_: 0);
2406	g_variant_print_string (value: element, string, type_annotate);
2407	g_variant_unref (value: element);
2408
2409	g_string_append (string, val: ", ");
2410
2411	element = g_variant_get_child_value (value, index_: 1);
2412	g_variant_print_string (value: element, string, type_annotate);
2413	g_variant_unref (value: element);
2414
2415	g_string_append_c (string, '}');
2416	}
2417	break;
2418
2419	case G_VARIANT_CLASS_VARIANT:
2420	{
2421	GVariant *child = g_variant_get_variant (value);
2422
2423	/* Always annotate types in nested variants, because they are
2424	* (by nature) of variable type.
2425	*/
2426	g_string_append_c (string, '<');
2427	g_variant_print_string (value: child, string, TRUE);
2428	g_string_append_c (string, '>');
2429
2430	g_variant_unref (value: child);
2431	}
2432	break;
2433
2434	case G_VARIANT_CLASS_BOOLEAN:
2435	if (g_variant_get_boolean (value))
2436	g_string_append (string, val: "true");
2437	else
2438	g_string_append (string, val: "false");
2439	break;
2440
2441	case G_VARIANT_CLASS_STRING:
2442	{
2443	const gchar *str = g_variant_get_string (value, NULL);
2444	gunichar quote = strchr (s: str, c: '\'') ? '"' : '\'';
2445
2446	g_string_append_c (string, quote);
2447
2448	while (*str)
2449	{
2450	gunichar c = g_utf8_get_char (p: str);
2451
2452	if (c == quote || c == '\\')
2453	g_string_append_c (string, '\\');
2454
2455	if (g_unichar_isprint (c))
2456	g_string_append_unichar (string, wc: c);
2457
2458	else
2459	{
2460	g_string_append_c (string, '\\');
2461	if (c < 0x10000)
2462	switch (c)
2463	{
2464	case '\a':
2465	g_string_append_c (string, 'a');
2466	break;
2467
2468	case '\b':
2469	g_string_append_c (string, 'b');
2470	break;
2471
2472	case '\f':
2473	g_string_append_c (string, 'f');
2474	break;
2475
2476	case '\n':
2477	g_string_append_c (string, 'n');
2478	break;
2479
2480	case '\r':
2481	g_string_append_c (string, 'r');
2482	break;
2483
2484	case '\t':
2485	g_string_append_c (string, 't');
2486	break;
2487
2488	case '\v':
2489	g_string_append_c (string, 'v');
2490	break;
2491
2492	default:
2493	g_string_append_printf (string, format: "u%04x", c);
2494	break;
2495	}
2496	else
2497	g_string_append_printf (string, format: "U%08x", c);
2498	}
2499
2500	str = g_utf8_next_char (str);
2501	}
2502
2503	g_string_append_c (string, quote);
2504	}
2505	break;
2506
2507	case G_VARIANT_CLASS_BYTE:
2508	if (type_annotate)
2509	g_string_append (string, val: "byte ");
2510	g_string_append_printf (string, format: "0x%02x",
2511	g_variant_get_byte (value));
2512	break;
2513
2514	case G_VARIANT_CLASS_INT16:
2515	if (type_annotate)
2516	g_string_append (string, val: "int16 ");
2517	g_string_append_printf (string, format: "%"G_GINT16_FORMAT,
2518	g_variant_get_int16 (value));
2519	break;
2520
2521	case G_VARIANT_CLASS_UINT16:
2522	if (type_annotate)
2523	g_string_append (string, val: "uint16 ");
2524	g_string_append_printf (string, format: "%"G_GUINT16_FORMAT,
2525	g_variant_get_uint16 (value));
2526	break;
2527
2528	case G_VARIANT_CLASS_INT32:
2529	/* Never annotate this type because it is the default for numbers
2530	* (and this is a *pretty* printer)
2531	*/
2532	g_string_append_printf (string, format: "%"G_GINT32_FORMAT,
2533	g_variant_get_int32 (value));
2534	break;
2535
2536	case G_VARIANT_CLASS_HANDLE:
2537	if (type_annotate)
2538	g_string_append (string, val: "handle ");
2539	g_string_append_printf (string, format: "%"G_GINT32_FORMAT,
2540	g_variant_get_handle (value));
2541	break;
2542
2543	case G_VARIANT_CLASS_UINT32:
2544	if (type_annotate)
2545	g_string_append (string, val: "uint32 ");
2546	g_string_append_printf (string, format: "%"G_GUINT32_FORMAT,
2547	g_variant_get_uint32 (value));
2548	break;
2549
2550	case G_VARIANT_CLASS_INT64:
2551	if (type_annotate)
2552	g_string_append (string, val: "int64 ");
2553	g_string_append_printf (string, format: "%"G_GINT64_FORMAT,
2554	g_variant_get_int64 (value));
2555	break;
2556
2557	case G_VARIANT_CLASS_UINT64:
2558	if (type_annotate)
2559	g_string_append (string, val: "uint64 ");
2560	g_string_append_printf (string, format: "%"G_GUINT64_FORMAT,
2561	g_variant_get_uint64 (value));
2562	break;
2563
2564	case G_VARIANT_CLASS_DOUBLE:
2565	{
2566	gchar buffer[100];
2567	gint i;
2568
2569	g_ascii_dtostr (buffer, buf_len: sizeof buffer, d: g_variant_get_double (value));
2570
2571	for (i = 0; buffer[i]; i++)
2572	if (buffer[i] == '.' || buffer[i] == 'e' ||
2573	buffer[i] == 'n' || buffer[i] == 'N')
2574	break;
2575
2576	/* if there is no '.' or 'e' in the float then add one */
2577	if (buffer[i] == '\0')
2578	{
2579	buffer[i++] = '.';
2580	buffer[i++] = '0';
2581	buffer[i++] = '\0';
2582	}
2583
2584	g_string_append (string, val: buffer);
2585	}
2586	break;
2587
2588	case G_VARIANT_CLASS_OBJECT_PATH:
2589	if (type_annotate)
2590	g_string_append (string, val: "objectpath ");
2591	g_string_append_printf (string, format: "\'%s\'",
2592	g_variant_get_string (value, NULL));
2593	break;
2594
2595	case G_VARIANT_CLASS_SIGNATURE:
2596	if (type_annotate)
2597	g_string_append (string, val: "signature ");
2598	g_string_append_printf (string, format: "\'%s\'",
2599	g_variant_get_string (value, NULL));
2600	break;
2601
2602	default:
2603	g_assert_not_reached ();
2604	}
2605
2606	return string;
2607	}
2608
2609	/**
2610	* g_variant_print:
2611	* @value: a #GVariant
2612	* @type_annotate: %TRUE if type information should be included in
2613	* the output
2614	*
2615	* Pretty-prints @value in the format understood by g_variant_parse().
2616	*
2617	* The format is described [here][gvariant-text].
2618	*
2619	* If @type_annotate is %TRUE, then type information is included in
2620	* the output.
2621	*
2622	* Returns: (transfer full): a newly-allocated string holding the result.
2623	*
2624	* Since: 2.24
2625	*/
2626	gchar *
2627	g_variant_print (GVariant *value,
2628	gboolean type_annotate)
2629	{
2630	return g_string_free (string: g_variant_print_string (value, NULL, type_annotate),
2631	FALSE);
2632	}
2633
2634	/* Hash, Equal, Compare {{{1 */
2635	/**
2636	* g_variant_hash:
2637	* @value: (type GVariant): a basic #GVariant value as a #gconstpointer
2638	*
2639	* Generates a hash value for a #GVariant instance.
2640	*
2641	* The output of this function is guaranteed to be the same for a given
2642	* value only per-process. It may change between different processor
2643	* architectures or even different versions of GLib. Do not use this
2644	* function as a basis for building protocols or file formats.
2645	*
2646	* The type of @value is #gconstpointer only to allow use of this
2647	* function with #GHashTable. @value must be a #GVariant.
2648	*
2649	* Returns: a hash value corresponding to @value
2650	*
2651	* Since: 2.24
2652	**/
2653	guint
2654	g_variant_hash (gconstpointer value_)
2655	{
2656	GVariant *value = (GVariant *) value_;
2657
2658	switch (g_variant_classify (value))
2659	{
2660	case G_VARIANT_CLASS_STRING:
2661	case G_VARIANT_CLASS_OBJECT_PATH:
2662	case G_VARIANT_CLASS_SIGNATURE:
2663	return g_str_hash (v: g_variant_get_string (value, NULL));
2664
2665	case G_VARIANT_CLASS_BOOLEAN:
2666	/* this is a very odd thing to hash... */
2667	return g_variant_get_boolean (value);
2668
2669	case G_VARIANT_CLASS_BYTE:
2670	return g_variant_get_byte (value);
2671
2672	case G_VARIANT_CLASS_INT16:
2673	case G_VARIANT_CLASS_UINT16:
2674	{
2675	const guint16 *ptr;
2676
2677	ptr = g_variant_get_data (value);
2678
2679	if (ptr)
2680	return *ptr;
2681	else
2682	return 0;
2683	}
2684
2685	case G_VARIANT_CLASS_INT32:
2686	case G_VARIANT_CLASS_UINT32:
2687	case G_VARIANT_CLASS_HANDLE:
2688	{
2689	const guint *ptr;
2690
2691	ptr = g_variant_get_data (value);
2692
2693	if (ptr)
2694	return *ptr;
2695	else
2696	return 0;
2697	}
2698
2699	case G_VARIANT_CLASS_INT64:
2700	case G_VARIANT_CLASS_UINT64:
2701	case G_VARIANT_CLASS_DOUBLE:
2702	/* need a separate case for these guys because otherwise
2703	* performance could be quite bad on big endian systems
2704	*/
2705	{
2706	const guint *ptr;
2707
2708	ptr = g_variant_get_data (value);
2709
2710	if (ptr)
2711	return ptr[0] + ptr[1];
2712	else
2713	return 0;
2714	}
2715
2716	default:
2717	g_return_val_if_fail (!g_variant_is_container (value), 0);
2718	g_assert_not_reached ();
2719	}
2720	}
2721
2722	/**
2723	* g_variant_equal:
2724	* @one: (type GVariant): a #GVariant instance
2725	* @two: (type GVariant): a #GVariant instance
2726	*
2727	* Checks if @one and @two have the same type and value.
2728	*
2729	* The types of @one and @two are #gconstpointer only to allow use of
2730	* this function with #GHashTable. They must each be a #GVariant.
2731	*
2732	* Returns: %TRUE if @one and @two are equal
2733	*
2734	* Since: 2.24
2735	**/
2736	gboolean
2737	g_variant_equal (gconstpointer one,
2738	gconstpointer two)
2739	{
2740	gboolean equal;
2741
2742	g_return_val_if_fail (one != NULL && two != NULL, FALSE);
2743
2744	if (g_variant_get_type_info (value: (GVariant *) one) !=
2745	g_variant_get_type_info (value: (GVariant *) two))
2746	return FALSE;
2747
2748	/* if both values are trusted to be in their canonical serialised form
2749	* then a simple memcmp() of their serialised data will answer the
2750	* question.
2751	*
2752	* if not, then this might generate a false negative (since it is
2753	* possible for two different byte sequences to represent the same
2754	* value). for now we solve this by pretty-printing both values and
2755	* comparing the result.
2756	*/
2757	if (g_variant_is_trusted (value: (GVariant *) one) &&
2758	g_variant_is_trusted (value: (GVariant *) two))
2759	{
2760	gconstpointer data_one, data_two;
2761	gsize size_one, size_two;
2762
2763	size_one = g_variant_get_size (value: (GVariant *) one);
2764	size_two = g_variant_get_size (value: (GVariant *) two);
2765
2766	if (size_one != size_two)
2767	return FALSE;
2768
2769	data_one = g_variant_get_data (value: (GVariant *) one);
2770	data_two = g_variant_get_data (value: (GVariant *) two);
2771
2772	if (size_one)
2773	equal = memcmp (s1: data_one, s2: data_two, n: size_one) == 0;
2774	else
2775	equal = TRUE;
2776	}
2777	else
2778	{
2779	gchar *strone, *strtwo;
2780
2781	strone = g_variant_print (value: (GVariant *) one, FALSE);
2782	strtwo = g_variant_print (value: (GVariant *) two, FALSE);
2783	equal = strcmp (s1: strone, s2: strtwo) == 0;
2784	g_free (mem: strone);
2785	g_free (mem: strtwo);
2786	}
2787
2788	return equal;
2789	}
2790
2791	/**
2792	* g_variant_compare:
2793	* @one: (type GVariant): a basic-typed #GVariant instance
2794	* @two: (type GVariant): a #GVariant instance of the same type
2795	*
2796	* Compares @one and @two.
2797	*
2798	* The types of @one and @two are #gconstpointer only to allow use of
2799	* this function with #GTree, #GPtrArray, etc. They must each be a
2800	* #GVariant.
2801	*
2802	* Comparison is only defined for basic types (ie: booleans, numbers,
2803	* strings). For booleans, %FALSE is less than %TRUE. Numbers are
2804	* ordered in the usual way. Strings are in ASCII lexographical order.
2805	*
2806	* It is a programmer error to attempt to compare container values or
2807	* two values that have types that are not exactly equal. For example,
2808	* you cannot compare a 32-bit signed integer with a 32-bit unsigned
2809	* integer. Also note that this function is not particularly
2810	* well-behaved when it comes to comparison of doubles; in particular,
2811	* the handling of incomparable values (ie: NaN) is undefined.
2812	*
2813	* If you only require an equality comparison, g_variant_equal() is more
2814	* general.
2815	*
2816	* Returns: negative value if a < b;
2817	* zero if a = b;
2818	* positive value if a > b.
2819	*
2820	* Since: 2.26
2821	**/
2822	gint
2823	g_variant_compare (gconstpointer one,
2824	gconstpointer two)
2825	{
2826	GVariant *a = (GVariant *) one;
2827	GVariant *b = (GVariant *) two;
2828
2829	g_return_val_if_fail (g_variant_classify (a) == g_variant_classify (b), 0);
2830
2831	switch (g_variant_classify (value: a))
2832	{
2833	case G_VARIANT_CLASS_BOOLEAN:
2834	return g_variant_get_boolean (value: a) -
2835	g_variant_get_boolean (value: b);
2836
2837	case G_VARIANT_CLASS_BYTE:
2838	return ((gint) g_variant_get_byte (value: a)) -
2839	((gint) g_variant_get_byte (value: b));
2840
2841	case G_VARIANT_CLASS_INT16:
2842	return ((gint) g_variant_get_int16 (value: a)) -
2843	((gint) g_variant_get_int16 (value: b));
2844
2845	case G_VARIANT_CLASS_UINT16:
2846	return ((gint) g_variant_get_uint16 (value: a)) -
2847	((gint) g_variant_get_uint16 (value: b));
2848
2849	case G_VARIANT_CLASS_INT32:
2850	{
2851	gint32 a_val = g_variant_get_int32 (value: a);
2852	gint32 b_val = g_variant_get_int32 (value: b);
2853
2854	return (a_val == b_val) ? 0 : (a_val > b_val) ? 1 : -1;
2855	}
2856
2857	case G_VARIANT_CLASS_UINT32:
2858	{
2859	guint32 a_val = g_variant_get_uint32 (value: a);
2860	guint32 b_val = g_variant_get_uint32 (value: b);
2861
2862	return (a_val == b_val) ? 0 : (a_val > b_val) ? 1 : -1;
2863	}
2864
2865	case G_VARIANT_CLASS_INT64:
2866	{
2867	gint64 a_val = g_variant_get_int64 (value: a);
2868	gint64 b_val = g_variant_get_int64 (value: b);
2869
2870	return (a_val == b_val) ? 0 : (a_val > b_val) ? 1 : -1;
2871	}
2872
2873	case G_VARIANT_CLASS_UINT64:
2874	{
2875	guint64 a_val = g_variant_get_uint64 (value: a);
2876	guint64 b_val = g_variant_get_uint64 (value: b);
2877
2878	return (a_val == b_val) ? 0 : (a_val > b_val) ? 1 : -1;
2879	}
2880
2881	case G_VARIANT_CLASS_DOUBLE:
2882	{
2883	gdouble a_val = g_variant_get_double (value: a);
2884	gdouble b_val = g_variant_get_double (value: b);
2885
2886	return (a_val == b_val) ? 0 : (a_val > b_val) ? 1 : -1;
2887	}
2888
2889	case G_VARIANT_CLASS_STRING:
2890	case G_VARIANT_CLASS_OBJECT_PATH:
2891	case G_VARIANT_CLASS_SIGNATURE:
2892	return strcmp (s1: g_variant_get_string (value: a, NULL),
2893	s2: g_variant_get_string (value: b, NULL));
2894
2895	default:
2896	g_return_val_if_fail (!g_variant_is_container (a), 0);
2897	g_assert_not_reached ();
2898	}
2899	}
2900
2901	/* GVariantIter {{{1 */
2902	/**
2903	* GVariantIter: (skip)
2904	*
2905	* #GVariantIter is an opaque data structure and can only be accessed
2906	* using the following functions.
2907	**/
2908	struct stack_iter
2909	{
2910	GVariant *value;
2911	gssize n, i;
2912
2913	const gchar *loop_format;
2914
2915	gsize padding[3];
2916	gsize magic;
2917	};
2918
2919	G_STATIC_ASSERT (sizeof (struct stack_iter) <= sizeof (GVariantIter));
2920
2921	struct heap_iter
2922	{
2923	struct stack_iter iter;
2924
2925	GVariant *value_ref;
2926	gsize magic;
2927	};
2928
2929	#define GVSI(i) ((struct stack_iter *) (i))
2930	#define GVHI(i) ((struct heap_iter *) (i))
2931	#define GVSI_MAGIC ((gsize) 3579507750u)
2932	#define GVHI_MAGIC ((gsize) 1450270775u)
2933	#define is_valid_iter(i) (i != NULL && \
2934	GVSI(i)->magic == GVSI_MAGIC)
2935	#define is_valid_heap_iter(i) (is_valid_iter(i) && \
2936	GVHI(i)->magic == GVHI_MAGIC)
2937
2938	/**
2939	* g_variant_iter_new:
2940	* @value: a container #GVariant
2941	*
2942	* Creates a heap-allocated #GVariantIter for iterating over the items
2943	* in @value.
2944	*
2945	* Use g_variant_iter_free() to free the return value when you no longer
2946	* need it.
2947	*
2948	* A reference is taken to @value and will be released only when
2949	* g_variant_iter_free() is called.
2950	*
2951	* Returns: (transfer full): a new heap-allocated #GVariantIter
2952	*
2953	* Since: 2.24
2954	**/
2955	GVariantIter *
2956	g_variant_iter_new (GVariant *value)
2957	{
2958	GVariantIter *iter;
2959
2960	iter = (GVariantIter *) g_slice_new (struct heap_iter);
2961	GVHI(iter)->value_ref = g_variant_ref (value);
2962	GVHI(iter)->magic = GVHI_MAGIC;
2963
2964	g_variant_iter_init (iter, value);
2965
2966	return iter;
2967	}
2968
2969	/**
2970	* g_variant_iter_init: (skip)
2971	* @iter: a pointer to a #GVariantIter
2972	* @value: a container #GVariant
2973	*
2974	* Initialises (without allocating) a #GVariantIter. @iter may be
2975	* completely uninitialised prior to this call; its old value is
2976	* ignored.
2977	*
2978	* The iterator remains valid for as long as @value exists, and need not
2979	* be freed in any way.
2980	*
2981	* Returns: the number of items in @value
2982	*
2983	* Since: 2.24
2984	**/
2985	gsize
2986	g_variant_iter_init (GVariantIter *iter,
2987	GVariant *value)
2988	{
2989	GVSI(iter)->magic = GVSI_MAGIC;
2990	GVSI(iter)->value = value;
2991	GVSI(iter)->n = g_variant_n_children (value);
2992	GVSI(iter)->i = -1;
2993	GVSI(iter)->loop_format = NULL;
2994
2995	return GVSI(iter)->n;
2996	}
2997
2998	/**
2999	* g_variant_iter_copy:
3000	* @iter: a #GVariantIter
3001	*
3002	* Creates a new heap-allocated #GVariantIter to iterate over the
3003	* container that was being iterated over by @iter. Iteration begins on
3004	* the new iterator from the current position of the old iterator but
3005	* the two copies are independent past that point.
3006	*
3007	* Use g_variant_iter_free() to free the return value when you no longer
3008	* need it.
3009	*
3010	* A reference is taken to the container that @iter is iterating over
3011	* and will be related only when g_variant_iter_free() is called.
3012	*
3013	* Returns: (transfer full): a new heap-allocated #GVariantIter
3014	*
3015	* Since: 2.24
3016	**/
3017	GVariantIter *
3018	g_variant_iter_copy (GVariantIter *iter)
3019	{
3020	GVariantIter *copy;
3021
3022	g_return_val_if_fail (is_valid_iter (iter), 0);
3023
3024	copy = g_variant_iter_new (GVSI(iter)->value);
3025	GVSI(copy)->i = GVSI(iter)->i;
3026
3027	return copy;
3028	}
3029
3030	/**
3031	* g_variant_iter_n_children:
3032	* @iter: a #GVariantIter
3033	*
3034	* Queries the number of child items in the container that we are
3035	* iterating over. This is the total number of items -- not the number
3036	* of items remaining.
3037	*
3038	* This function might be useful for preallocation of arrays.
3039	*
3040	* Returns: the number of children in the container
3041	*
3042	* Since: 2.24
3043	**/
3044	gsize
3045	g_variant_iter_n_children (GVariantIter *iter)
3046	{
3047	g_return_val_if_fail (is_valid_iter (iter), 0);
3048
3049	return GVSI(iter)->n;
3050	}
3051
3052	/**
3053	* g_variant_iter_free:
3054	* @iter: (transfer full): a heap-allocated #GVariantIter
3055	*
3056	* Frees a heap-allocated #GVariantIter. Only call this function on
3057	* iterators that were returned by g_variant_iter_new() or
3058	* g_variant_iter_copy().
3059	*
3060	* Since: 2.24
3061	**/
3062	void
3063	g_variant_iter_free (GVariantIter *iter)
3064	{
3065	g_return_if_fail (is_valid_heap_iter (iter));
3066
3067	g_variant_unref (GVHI(iter)->value_ref);
3068	GVHI(iter)->magic = 0;
3069
3070	g_slice_free (struct heap_iter, GVHI(iter));
3071	}
3072
3073	/**
3074	* g_variant_iter_next_value:
3075	* @iter: a #GVariantIter
3076	*
3077	* Gets the next item in the container. If no more items remain then
3078	* %NULL is returned.
3079	*
3080	* Use g_variant_unref() to drop your reference on the return value when
3081	* you no longer need it.
3082	*
3083	* Here is an example for iterating with g_variant_iter_next_value():
3084	* |[<!-- language="C" -->
3085	* // recursively iterate a container
3086	* void
3087	* iterate_container_recursive (GVariant *container)
3088	* {
3089	* GVariantIter iter;
3090	* GVariant *child;
3091	*
3092	* g_variant_iter_init (&iter, container);
3093	* while ((child = g_variant_iter_next_value (&iter)))
3094	* {
3095	* g_print ("type '%s'\n", g_variant_get_type_string (child));
3096	*
3097	* if (g_variant_is_container (child))
3098	* iterate_container_recursive (child);
3099	*
3100	* g_variant_unref (child);
3101	* }
3102	* }
3103	* ]|
3104	*
3105	* Returns: (nullable) (transfer full): a #GVariant, or %NULL
3106	*
3107	* Since: 2.24
3108	**/
3109	GVariant *
3110	g_variant_iter_next_value (GVariantIter *iter)
3111	{
3112	g_return_val_if_fail (is_valid_iter (iter), FALSE);
3113
3114	if G_UNLIKELY (GVSI(iter)->i >= GVSI(iter)->n)
3115	{
3116	g_critical ("g_variant_iter_next_value: must not be called again "
3117	"after NULL has already been returned.");
3118	return NULL;
3119	}
3120
3121	GVSI(iter)->i++;
3122
3123	if (GVSI(iter)->i < GVSI(iter)->n)
3124	return g_variant_get_child_value (GVSI(iter)->value, GVSI(iter)->i);
3125
3126	return NULL;
3127	}
3128
3129	/* GVariantBuilder {{{1 */
3130	/**
3131	* GVariantBuilder:
3132	*
3133	* A utility type for constructing container-type #GVariant instances.
3134	*
3135	* This is an opaque structure and may only be accessed using the
3136	* following functions.
3137	*
3138	* #GVariantBuilder is not threadsafe in any way. Do not attempt to
3139	* access it from more than one thread.
3140	**/
3141
3142	struct stack_builder
3143	{
3144	GVariantBuilder *parent;
3145	GVariantType *type;
3146
3147	/* type constraint explicitly specified by 'type'.
3148	* for tuple types, this moves along as we add more items.
3149	*/
3150	const GVariantType *expected_type;
3151
3152	/* type constraint implied by previous array item.
3153	*/
3154	const GVariantType *prev_item_type;
3155
3156	/* constraints on the number of children. max = -1 for unlimited. */
3157	gsize min_items;
3158	gsize max_items;
3159
3160	/* dynamically-growing pointer array */
3161	GVariant **children;
3162	gsize allocated_children;
3163	gsize offset;
3164
3165	/* set to '1' if all items in the container will have the same type
3166	* (ie: maybe, array, variant) '0' if not (ie: tuple, dict entry)
3167	*/
3168	guint uniform_item_types : 1;
3169
3170	/* set to '1' initially and changed to '0' if an untrusted value is
3171	* added
3172	*/
3173	guint trusted : 1;
3174
3175	gsize magic;
3176	};
3177
3178	G_STATIC_ASSERT (sizeof (struct stack_builder) <= sizeof (GVariantBuilder));
3179
3180	struct heap_builder
3181	{
3182	GVariantBuilder builder;
3183	gsize magic;
3184
3185	gint ref_count;
3186	};
3187
3188	#define GVSB(b) ((struct stack_builder *) (b))
3189	#define GVHB(b) ((struct heap_builder *) (b))
3190	#define GVSB_MAGIC ((gsize) 1033660112u)
3191	#define GVSB_MAGIC_PARTIAL ((gsize) 2942751021u)
3192	#define GVHB_MAGIC ((gsize) 3087242682u)
3193	#define is_valid_builder(b) (b != NULL && \
3194	GVSB(b)->magic == GVSB_MAGIC)
3195	#define is_valid_heap_builder(b) (GVHB(b)->magic == GVHB_MAGIC)
3196
3197	/* Just to make sure that by adding a union to GVariantBuilder, we
3198	* didn't accidentally change ABI. */
3199	G_STATIC_ASSERT (sizeof (GVariantBuilder) == sizeof (gsize[16]));
3200
3201	static gboolean
3202	ensure_valid_builder (GVariantBuilder *builder)
3203	{
3204	if (is_valid_builder (builder))
3205	return TRUE;
3206	if (builder->u.s.partial_magic == GVSB_MAGIC_PARTIAL)
3207	{
3208	static GVariantBuilder cleared_builder;
3209
3210	/* Make sure that only first two fields were set and the rest is
3211	* zeroed to avoid messing up the builder that had parent
3212	* address equal to GVSB_MAGIC_PARTIAL. */
3213	if (memcmp (s1: cleared_builder.u.s.y, s2: builder->u.s.y, n: sizeof cleared_builder.u.s.y))
3214	return FALSE;
3215
3216	g_variant_builder_init (builder, type: builder->u.s.type);
3217	}
3218	return is_valid_builder (builder);
3219	}
3220
3221	/**
3222	* g_variant_builder_new:
3223	* @type: a container type
3224	*
3225	* Allocates and initialises a new #GVariantBuilder.
3226	*
3227	* You should call g_variant_builder_unref() on the return value when it
3228	* is no longer needed. The memory will not be automatically freed by
3229	* any other call.
3230	*
3231	* In most cases it is easier to place a #GVariantBuilder directly on
3232	* the stack of the calling function and initialise it with
3233	* g_variant_builder_init().
3234	*
3235	* Returns: (transfer full): a #GVariantBuilder
3236	*
3237	* Since: 2.24
3238	**/
3239	GVariantBuilder *
3240	g_variant_builder_new (const GVariantType *type)
3241	{
3242	GVariantBuilder *builder;
3243
3244	builder = (GVariantBuilder *) g_slice_new (struct heap_builder);
3245	g_variant_builder_init (builder, type);
3246	GVHB(builder)->magic = GVHB_MAGIC;
3247	GVHB(builder)->ref_count = 1;
3248
3249	return builder;
3250	}
3251
3252	/**
3253	* g_variant_builder_unref:
3254	* @builder: (transfer full): a #GVariantBuilder allocated by g_variant_builder_new()
3255	*
3256	* Decreases the reference count on @builder.
3257	*
3258	* In the event that there are no more references, releases all memory
3259	* associated with the #GVariantBuilder.
3260	*
3261	* Don't call this on stack-allocated #GVariantBuilder instances or bad
3262	* things will happen.
3263	*
3264	* Since: 2.24
3265	**/
3266	void
3267	g_variant_builder_unref (GVariantBuilder *builder)
3268	{
3269	g_return_if_fail (is_valid_heap_builder (builder));
3270
3271	if (--GVHB(builder)->ref_count)
3272	return;
3273
3274	g_variant_builder_clear (builder);
3275	GVHB(builder)->magic = 0;
3276
3277	g_slice_free (struct heap_builder, GVHB(builder));
3278	}
3279
3280	/**
3281	* g_variant_builder_ref:
3282	* @builder: a #GVariantBuilder allocated by g_variant_builder_new()
3283	*
3284	* Increases the reference count on @builder.
3285	*
3286	* Don't call this on stack-allocated #GVariantBuilder instances or bad
3287	* things will happen.
3288	*
3289	* Returns: (transfer full): a new reference to @builder
3290	*
3291	* Since: 2.24
3292	**/
3293	GVariantBuilder *
3294	g_variant_builder_ref (GVariantBuilder *builder)
3295	{
3296	g_return_val_if_fail (is_valid_heap_builder (builder), NULL);
3297
3298	GVHB(builder)->ref_count++;
3299
3300	return builder;
3301	}
3302
3303	/**
3304	* g_variant_builder_clear: (skip)
3305	* @builder: a #GVariantBuilder
3306	*
3307	* Releases all memory associated with a #GVariantBuilder without
3308	* freeing the #GVariantBuilder structure itself.
3309	*
3310	* It typically only makes sense to do this on a stack-allocated
3311	* #GVariantBuilder if you want to abort building the value part-way
3312	* through. This function need not be called if you call
3313	* g_variant_builder_end() and it also doesn't need to be called on
3314	* builders allocated with g_variant_builder_new() (see
3315	* g_variant_builder_unref() for that).
3316	*
3317	* This function leaves the #GVariantBuilder structure set to all-zeros.
3318	* It is valid to call this function on either an initialised
3319	* #GVariantBuilder or one that is set to all-zeros but it is not valid
3320	* to call this function on uninitialised memory.
3321	*
3322	* Since: 2.24
3323	**/
3324	void
3325	g_variant_builder_clear (GVariantBuilder *builder)
3326	{
3327	gsize i;
3328
3329	if (GVSB(builder)->magic == 0)
3330	/* all-zeros or partial case */
3331	return;
3332
3333	g_return_if_fail (ensure_valid_builder (builder));
3334
3335	g_variant_type_free (GVSB(builder)->type);
3336
3337	for (i = 0; i < GVSB(builder)->offset; i++)
3338	g_variant_unref (GVSB(builder)->children[i]);
3339
3340	g_free (GVSB(builder)->children);
3341
3342	if (GVSB(builder)->parent)
3343	{
3344	g_variant_builder_clear (GVSB(builder)->parent);
3345	g_slice_free (GVariantBuilder, GVSB(builder)->parent);
3346	}
3347
3348	memset (s: builder, c: 0, n: sizeof (GVariantBuilder));
3349	}
3350
3351	/**
3352	* g_variant_builder_init: (skip)
3353	* @builder: a #GVariantBuilder
3354	* @type: a container type
3355	*
3356	* Initialises a #GVariantBuilder structure.
3357	*
3358	* @type must be non-%NULL. It specifies the type of container to
3359	* construct. It can be an indefinite type such as
3360	* %G_VARIANT_TYPE_ARRAY or a definite type such as "as" or "(ii)".
3361	* Maybe, array, tuple, dictionary entry and variant-typed values may be
3362	* constructed.
3363	*
3364	* After the builder is initialised, values are added using
3365	* g_variant_builder_add_value() or g_variant_builder_add().
3366	*
3367	* After all the child values are added, g_variant_builder_end() frees
3368	* the memory associated with the builder and returns the #GVariant that
3369	* was created.
3370	*
3371	* This function completely ignores the previous contents of @builder.
3372	* On one hand this means that it is valid to pass in completely
3373	* uninitialised memory. On the other hand, this means that if you are
3374	* initialising over top of an existing #GVariantBuilder you need to
3375	* first call g_variant_builder_clear() in order to avoid leaking
3376	* memory.
3377	*
3378	* You must not call g_variant_builder_ref() or
3379	* g_variant_builder_unref() on a #GVariantBuilder that was initialised
3380	* with this function. If you ever pass a reference to a
3381	* #GVariantBuilder outside of the control of your own code then you
3382	* should assume that the person receiving that reference may try to use
3383	* reference counting; you should use g_variant_builder_new() instead of
3384	* this function.
3385	*
3386	* Since: 2.24
3387	**/
3388	void
3389	g_variant_builder_init (GVariantBuilder *builder,
3390	const GVariantType *type)
3391	{
3392	g_return_if_fail (type != NULL);
3393	g_return_if_fail (g_variant_type_is_container (type));
3394
3395	memset (s: builder, c: 0, n: sizeof (GVariantBuilder));
3396
3397	GVSB(builder)->type = g_variant_type_copy (type);
3398	GVSB(builder)->magic = GVSB_MAGIC;
3399	GVSB(builder)->trusted = TRUE;
3400
3401	switch (*(const gchar *) type)
3402	{
3403	case G_VARIANT_CLASS_VARIANT:
3404	GVSB(builder)->uniform_item_types = TRUE;
3405	GVSB(builder)->allocated_children = 1;
3406	GVSB(builder)->expected_type = NULL;
3407	GVSB(builder)->min_items = 1;
3408	GVSB(builder)->max_items = 1;
3409	break;
3410
3411	case G_VARIANT_CLASS_ARRAY:
3412	GVSB(builder)->uniform_item_types = TRUE;
3413	GVSB(builder)->allocated_children = 8;
3414	GVSB(builder)->expected_type =
3415	g_variant_type_element (GVSB(builder)->type);
3416	GVSB(builder)->min_items = 0;
3417	GVSB(builder)->max_items = -1;
3418	break;
3419
3420	case G_VARIANT_CLASS_MAYBE:
3421	GVSB(builder)->uniform_item_types = TRUE;
3422	GVSB(builder)->allocated_children = 1;
3423	GVSB(builder)->expected_type =
3424	g_variant_type_element (GVSB(builder)->type);
3425	GVSB(builder)->min_items = 0;
3426	GVSB(builder)->max_items = 1;
3427	break;
3428
3429	case G_VARIANT_CLASS_DICT_ENTRY:
3430	GVSB(builder)->uniform_item_types = FALSE;
3431	GVSB(builder)->allocated_children = 2;
3432	GVSB(builder)->expected_type =
3433	g_variant_type_key (GVSB(builder)->type);
3434	GVSB(builder)->min_items = 2;
3435	GVSB(builder)->max_items = 2;
3436	break;
3437
3438	case 'r': /* G_VARIANT_TYPE_TUPLE was given */
3439	GVSB(builder)->uniform_item_types = FALSE;
3440	GVSB(builder)->allocated_children = 8;
3441	GVSB(builder)->expected_type = NULL;
3442	GVSB(builder)->min_items = 0;
3443	GVSB(builder)->max_items = -1;
3444	break;
3445
3446	case G_VARIANT_CLASS_TUPLE: /* a definite tuple type was given */
3447	GVSB(builder)->allocated_children = g_variant_type_n_items (type);
3448	GVSB(builder)->expected_type =
3449	g_variant_type_first (GVSB(builder)->type);
3450	GVSB(builder)->min_items = GVSB(builder)->allocated_children;
3451	GVSB(builder)->max_items = GVSB(builder)->allocated_children;
3452	GVSB(builder)->uniform_item_types = FALSE;
3453	break;
3454
3455	default:
3456	g_assert_not_reached ();
3457	}
3458
3459	GVSB(builder)->children = g_new (GVariant *,
3460	GVSB(builder)->allocated_children);
3461	}
3462
3463	static void
3464	g_variant_builder_make_room (struct stack_builder *builder)
3465	{
3466	if (builder->offset == builder->allocated_children)
3467	{
3468	builder->allocated_children *= 2;
3469	builder->children = g_renew (GVariant *, builder->children,
3470	builder->allocated_children);
3471	}
3472	}
3473
3474	/**
3475	* g_variant_builder_add_value:
3476	* @builder: a #GVariantBuilder
3477	* @value: a #GVariant
3478	*
3479	* Adds @value to @builder.
3480	*
3481	* It is an error to call this function in any way that would create an
3482	* inconsistent value to be constructed. Some examples of this are
3483	* putting different types of items into an array, putting the wrong
3484	* types or number of items in a tuple, putting more than one value into
3485	* a variant, etc.
3486	*
3487	* If @value is a floating reference (see g_variant_ref_sink()),
3488	* the @builder instance takes ownership of @value.
3489	*
3490	* Since: 2.24
3491	**/
3492	void
3493	g_variant_builder_add_value (GVariantBuilder *builder,
3494	GVariant *value)
3495	{
3496	g_return_if_fail (ensure_valid_builder (builder));
3497	g_return_if_fail (GVSB(builder)->offset < GVSB(builder)->max_items);
3498	g_return_if_fail (!GVSB(builder)->expected_type ||
3499	g_variant_is_of_type (value,
3500	GVSB(builder)->expected_type));
3501	g_return_if_fail (!GVSB(builder)->prev_item_type ||
3502	g_variant_is_of_type (value,
3503	GVSB(builder)->prev_item_type));
3504
3505	GVSB(builder)->trusted &= g_variant_is_trusted (value);
3506
3507	if (!GVSB(builder)->uniform_item_types)
3508	{
3509	/* advance our expected type pointers */
3510	if (GVSB(builder)->expected_type)
3511	GVSB(builder)->expected_type =
3512	g_variant_type_next (GVSB(builder)->expected_type);
3513
3514	if (GVSB(builder)->prev_item_type)
3515	GVSB(builder)->prev_item_type =
3516	g_variant_type_next (GVSB(builder)->prev_item_type);
3517	}
3518	else
3519	GVSB(builder)->prev_item_type = g_variant_get_type (value);
3520
3521	g_variant_builder_make_room (GVSB(builder));
3522
3523	GVSB(builder)->children[GVSB(builder)->offset++] =
3524	g_variant_ref_sink (value);
3525	}
3526
3527	/**
3528	* g_variant_builder_open:
3529	* @builder: a #GVariantBuilder
3530	* @type: the #GVariantType of the container
3531	*
3532	* Opens a subcontainer inside the given @builder. When done adding
3533	* items to the subcontainer, g_variant_builder_close() must be called. @type
3534	* is the type of the container: so to build a tuple of several values, @type
3535	* must include the tuple itself.
3536	*
3537	* It is an error to call this function in any way that would cause an
3538	* inconsistent value to be constructed (ie: adding too many values or
3539	* a value of an incorrect type).
3540	*
3541	* Example of building a nested variant:
3542	* |[<!-- language="C" -->
3543	* GVariantBuilder builder;
3544	* guint32 some_number = get_number ();
3545	* g_autoptr (GHashTable) some_dict = get_dict ();
3546	* GHashTableIter iter;
3547	* const gchar *key;
3548	* const GVariant *value;
3549	* g_autoptr (GVariant) output = NULL;
3550	*
3551	* g_variant_builder_init (&builder, G_VARIANT_TYPE ("(ua{sv})"));
3552	* g_variant_builder_add (&builder, "u", some_number);
3553	* g_variant_builder_open (&builder, G_VARIANT_TYPE ("a{sv}"));
3554	*
3555	* g_hash_table_iter_init (&iter, some_dict);
3556	* while (g_hash_table_iter_next (&iter, (gpointer *) &key, (gpointer *) &value))
3557	* {
3558	* g_variant_builder_open (&builder, G_VARIANT_TYPE ("{sv}"));
3559	* g_variant_builder_add (&builder, "s", key);
3560	* g_variant_builder_add (&builder, "v", value);
3561	* g_variant_builder_close (&builder);
3562	* }
3563	*
3564	* g_variant_builder_close (&builder);
3565	*
3566	* output = g_variant_builder_end (&builder);
3567	* ]|
3568	*
3569	* Since: 2.24
3570	**/
3571	void
3572	g_variant_builder_open (GVariantBuilder *builder,
3573	const GVariantType *type)
3574	{
3575	GVariantBuilder *parent;
3576
3577	g_return_if_fail (ensure_valid_builder (builder));
3578	g_return_if_fail (GVSB(builder)->offset < GVSB(builder)->max_items);
3579	g_return_if_fail (!GVSB(builder)->expected_type ||
3580	g_variant_type_is_subtype_of (type,
3581	GVSB(builder)->expected_type));
3582	g_return_if_fail (!GVSB(builder)->prev_item_type ||
3583	g_variant_type_is_subtype_of (GVSB(builder)->prev_item_type,
3584	type));
3585
3586	parent = g_slice_dup (GVariantBuilder, builder);
3587	g_variant_builder_init (builder, type);
3588	GVSB(builder)->parent = parent;
3589
3590	/* push the prev_item_type down into the subcontainer */
3591	if (GVSB(parent)->prev_item_type)
3592	{
3593	if (!GVSB(builder)->uniform_item_types)
3594	/* tuples and dict entries */
3595	GVSB(builder)->prev_item_type =
3596	g_variant_type_first (GVSB(parent)->prev_item_type);
3597
3598	else if (!g_variant_type_is_variant (GVSB(builder)->type))
3599	/* maybes and arrays */
3600	GVSB(builder)->prev_item_type =
3601	g_variant_type_element (GVSB(parent)->prev_item_type);
3602	}
3603	}
3604
3605	/**
3606	* g_variant_builder_close:
3607	* @builder: a #GVariantBuilder
3608	*
3609	* Closes the subcontainer inside the given @builder that was opened by
3610	* the most recent call to g_variant_builder_open().
3611	*
3612	* It is an error to call this function in any way that would create an
3613	* inconsistent value to be constructed (ie: too few values added to the
3614	* subcontainer).
3615	*
3616	* Since: 2.24
3617	**/
3618	void
3619	g_variant_builder_close (GVariantBuilder *builder)
3620	{
3621	GVariantBuilder *parent;
3622
3623	g_return_if_fail (ensure_valid_builder (builder));
3624	g_return_if_fail (GVSB(builder)->parent != NULL);
3625
3626	parent = GVSB(builder)->parent;
3627	GVSB(builder)->parent = NULL;
3628
3629	g_variant_builder_add_value (builder: parent, value: g_variant_builder_end (builder));
3630	*builder = *parent;
3631
3632	g_slice_free (GVariantBuilder, parent);
3633	}
3634
3635	/*< private >
3636	* g_variant_make_maybe_type:
3637	* @element: a #GVariant
3638	*
3639	* Return the type of a maybe containing @element.
3640	*/
3641	static GVariantType *
3642	g_variant_make_maybe_type (GVariant *element)
3643	{
3644	return g_variant_type_new_maybe (element: g_variant_get_type (value: element));
3645	}
3646
3647	/*< private >
3648	* g_variant_make_array_type:
3649	* @element: a #GVariant
3650	*
3651	* Return the type of an array containing @element.
3652	*/
3653	static GVariantType *
3654	g_variant_make_array_type (GVariant *element)
3655	{
3656	return g_variant_type_new_array (element: g_variant_get_type (value: element));
3657	}
3658
3659	/**
3660	* g_variant_builder_end:
3661	* @builder: a #GVariantBuilder
3662	*
3663	* Ends the builder process and returns the constructed value.
3664	*
3665	* It is not permissible to use @builder in any way after this call
3666	* except for reference counting operations (in the case of a
3667	* heap-allocated #GVariantBuilder) or by reinitialising it with
3668	* g_variant_builder_init() (in the case of stack-allocated). This
3669	* means that for the stack-allocated builders there is no need to
3670	* call g_variant_builder_clear() after the call to
3671	* g_variant_builder_end().
3672	*
3673	* It is an error to call this function in any way that would create an
3674	* inconsistent value to be constructed (ie: insufficient number of
3675	* items added to a container with a specific number of children
3676	* required). It is also an error to call this function if the builder
3677	* was created with an indefinite array or maybe type and no children
3678	* have been added; in this case it is impossible to infer the type of
3679	* the empty array.
3680	*
3681	* Returns: (transfer none): a new, floating, #GVariant
3682	*
3683	* Since: 2.24
3684	**/
3685	GVariant *
3686	g_variant_builder_end (GVariantBuilder *builder)
3687	{
3688	GVariantType *my_type;
3689	GVariant *value;
3690
3691	g_return_val_if_fail (ensure_valid_builder (builder), NULL);
3692	g_return_val_if_fail (GVSB(builder)->offset >= GVSB(builder)->min_items,
3693	NULL);
3694	g_return_val_if_fail (!GVSB(builder)->uniform_item_types ||
3695	GVSB(builder)->prev_item_type != NULL ||
3696	g_variant_type_is_definite (GVSB(builder)->type),
3697	NULL);
3698
3699	if (g_variant_type_is_definite (GVSB(builder)->type))
3700	my_type = g_variant_type_copy (GVSB(builder)->type);
3701
3702	else if (g_variant_type_is_maybe (GVSB(builder)->type))
3703	my_type = g_variant_make_maybe_type (GVSB(builder)->children[0]);
3704
3705	else if (g_variant_type_is_array (GVSB(builder)->type))
3706	my_type = g_variant_make_array_type (GVSB(builder)->children[0]);
3707
3708	else if (g_variant_type_is_tuple (GVSB(builder)->type))
3709	my_type = g_variant_make_tuple_type (GVSB(builder)->children,
3710	GVSB(builder)->offset);
3711
3712	else if (g_variant_type_is_dict_entry (GVSB(builder)->type))
3713	my_type = g_variant_make_dict_entry_type (GVSB(builder)->children[0],
3714	GVSB(builder)->children[1]);
3715	else
3716	g_assert_not_reached ();
3717
3718	value = g_variant_new_from_children (type: my_type,
3719	g_renew (GVariant *,
3720	GVSB(builder)->children,
3721	GVSB(builder)->offset),
3722	GVSB(builder)->offset,
3723	GVSB(builder)->trusted);
3724	GVSB(builder)->children = NULL;
3725	GVSB(builder)->offset = 0;
3726
3727	g_variant_builder_clear (builder);
3728	g_variant_type_free (type: my_type);
3729
3730	return value;
3731	}
3732
3733	/* GVariantDict {{{1 */
3734
3735	/**
3736	* GVariantDict:
3737	*
3738	* #GVariantDict is a mutable interface to #GVariant dictionaries.
3739	*
3740	* It can be used for doing a sequence of dictionary lookups in an
3741	* efficient way on an existing #GVariant dictionary or it can be used
3742	* to construct new dictionaries with a hashtable-like interface. It
3743	* can also be used for taking existing dictionaries and modifying them
3744	* in order to create new ones.
3745	*
3746	* #GVariantDict can only be used with %G_VARIANT_TYPE_VARDICT
3747	* dictionaries.
3748	*
3749	* It is possible to use #GVariantDict allocated on the stack or on the
3750	* heap. When using a stack-allocated #GVariantDict, you begin with a
3751	* call to g_variant_dict_init() and free the resources with a call to
3752	* g_variant_dict_clear().
3753	*
3754	* Heap-allocated #GVariantDict follows normal refcounting rules: you
3755	* allocate it with g_variant_dict_new() and use g_variant_dict_ref()
3756	* and g_variant_dict_unref().
3757	*
3758	* g_variant_dict_end() is used to convert the #GVariantDict back into a
3759	* dictionary-type #GVariant. When used with stack-allocated instances,
3760	* this also implicitly frees all associated memory, but for
3761	* heap-allocated instances, you must still call g_variant_dict_unref()
3762	* afterwards.
3763	*
3764	* You will typically want to use a heap-allocated #GVariantDict when
3765	* you expose it as part of an API. For most other uses, the
3766	* stack-allocated form will be more convenient.
3767	*
3768	* Consider the following two examples that do the same thing in each
3769	* style: take an existing dictionary and look up the "count" uint32
3770	* key, adding 1 to it if it is found, or returning an error if the
3771	* key is not found. Each returns the new dictionary as a floating
3772	* #GVariant.
3773	*
3774	* ## Using a stack-allocated GVariantDict
3775	*
3776	* |[<!-- language="C" -->
3777	* GVariant *
3778	* add_to_count (GVariant *orig,
3779	* GError **error)
3780	* {
3781	* GVariantDict dict;
3782	* guint32 count;
3783	*
3784	* g_variant_dict_init (&dict, orig);
3785	* if (!g_variant_dict_lookup (&dict, "count", "u", &count))
3786	* {
3787	* g_set_error (...);
3788	* g_variant_dict_clear (&dict);
3789	* return NULL;
3790	* }
3791	*
3792	* g_variant_dict_insert (&dict, "count", "u", count + 1);
3793	*
3794	* return g_variant_dict_end (&dict);
3795	* }
3796	* ]|
3797	*
3798	* ## Using heap-allocated GVariantDict
3799	*
3800	* |[<!-- language="C" -->
3801	* GVariant *
3802	* add_to_count (GVariant *orig,
3803	* GError **error)
3804	* {
3805	* GVariantDict *dict;
3806	* GVariant *result;
3807	* guint32 count;
3808	*
3809	* dict = g_variant_dict_new (orig);
3810	*
3811	* if (g_variant_dict_lookup (dict, "count", "u", &count))
3812	* {
3813	* g_variant_dict_insert (dict, "count", "u", count + 1);
3814	* result = g_variant_dict_end (dict);
3815	* }
3816	* else
3817	* {
3818	* g_set_error (...);
3819	* result = NULL;
3820	* }
3821	*
3822	* g_variant_dict_unref (dict);
3823	*
3824	* return result;
3825	* }
3826	* ]|
3827	*
3828	* Since: 2.40
3829	**/
3830	struct stack_dict
3831	{
3832	GHashTable *values;
3833	gsize magic;
3834	};
3835
3836	G_STATIC_ASSERT (sizeof (struct stack_dict) <= sizeof (GVariantDict));
3837
3838	struct heap_dict
3839	{
3840	struct stack_dict dict;
3841	gint ref_count;
3842	gsize magic;
3843	};
3844
3845	#define GVSD(d) ((struct stack_dict *) (d))
3846	#define GVHD(d) ((struct heap_dict *) (d))
3847	#define GVSD_MAGIC ((gsize) 2579507750u)
3848	#define GVSD_MAGIC_PARTIAL ((gsize) 3488698669u)
3849	#define GVHD_MAGIC ((gsize) 2450270775u)
3850	#define is_valid_dict(d) (d != NULL && \
3851	GVSD(d)->magic == GVSD_MAGIC)
3852	#define is_valid_heap_dict(d) (GVHD(d)->magic == GVHD_MAGIC)
3853
3854	/* Just to make sure that by adding a union to GVariantDict, we didn't
3855	* accidentally change ABI. */
3856	G_STATIC_ASSERT (sizeof (GVariantDict) == sizeof (gsize[16]));
3857
3858	static gboolean
3859	ensure_valid_dict (GVariantDict *dict)
3860	{
3861	if (is_valid_dict (dict))
3862	return TRUE;
3863	if (dict->u.s.partial_magic == GVSD_MAGIC_PARTIAL)
3864	{
3865	static GVariantDict cleared_dict;
3866
3867	/* Make sure that only first two fields were set and the rest is
3868	* zeroed to avoid messing up the builder that had parent
3869	* address equal to GVSB_MAGIC_PARTIAL. */
3870	if (memcmp (s1: cleared_dict.u.s.y, s2: dict->u.s.y, n: sizeof cleared_dict.u.s.y))
3871	return FALSE;
3872
3873	g_variant_dict_init (dict, from_asv: dict->u.s.asv);
3874	}
3875	return is_valid_dict (dict);
3876	}
3877
3878	/**
3879	* g_variant_dict_new:
3880	* @from_asv: (nullable): the #GVariant with which to initialise the
3881	* dictionary
3882	*
3883	* Allocates and initialises a new #GVariantDict.
3884	*
3885	* You should call g_variant_dict_unref() on the return value when it
3886	* is no longer needed. The memory will not be automatically freed by
3887	* any other call.
3888	*
3889	* In some cases it may be easier to place a #GVariantDict directly on
3890	* the stack of the calling function and initialise it with
3891	* g_variant_dict_init(). This is particularly useful when you are
3892	* using #GVariantDict to construct a #GVariant.
3893	*
3894	* Returns: (transfer full): a #GVariantDict
3895	*
3896	* Since: 2.40
3897	**/
3898	GVariantDict *
3899	g_variant_dict_new (GVariant *from_asv)
3900	{
3901	GVariantDict *dict;
3902
3903	dict = g_slice_alloc (block_size: sizeof (struct heap_dict));
3904	g_variant_dict_init (dict, from_asv);
3905	GVHD(dict)->magic = GVHD_MAGIC;
3906	GVHD(dict)->ref_count = 1;
3907
3908	return dict;
3909	}
3910
3911	/**
3912	* g_variant_dict_init: (skip)
3913	* @dict: a #GVariantDict
3914	* @from_asv: (nullable): the initial value for @dict
3915	*
3916	* Initialises a #GVariantDict structure.
3917	*
3918	* If @from_asv is given, it is used to initialise the dictionary.
3919	*
3920	* This function completely ignores the previous contents of @dict. On
3921	* one hand this means that it is valid to pass in completely
3922	* uninitialised memory. On the other hand, this means that if you are
3923	* initialising over top of an existing #GVariantDict you need to first
3924	* call g_variant_dict_clear() in order to avoid leaking memory.
3925	*
3926	* You must not call g_variant_dict_ref() or g_variant_dict_unref() on a
3927	* #GVariantDict that was initialised with this function. If you ever
3928	* pass a reference to a #GVariantDict outside of the control of your
3929	* own code then you should assume that the person receiving that
3930	* reference may try to use reference counting; you should use
3931	* g_variant_dict_new() instead of this function.
3932	*
3933	* Since: 2.40
3934	**/
3935	void
3936	g_variant_dict_init (GVariantDict *dict,
3937	GVariant *from_asv)
3938	{
3939	GVariantIter iter;
3940	gchar *key;
3941	GVariant *value;
3942
3943	GVSD(dict)->values = g_hash_table_new_full (hash_func: g_str_hash, key_equal_func: g_str_equal, key_destroy_func: g_free, value_destroy_func: (GDestroyNotify) g_variant_unref);
3944	GVSD(dict)->magic = GVSD_MAGIC;
3945
3946	if (from_asv)
3947	{
3948	g_variant_iter_init (iter: &iter, value: from_asv);
3949	while (g_variant_iter_next (iter: &iter, format_string: "{sv}", &key, &value))
3950	g_hash_table_insert (GVSD(dict)->values, key, value);
3951	}
3952	}
3953
3954	/**
3955	* g_variant_dict_lookup:
3956	* @dict: a #GVariantDict
3957	* @key: the key to look up in the dictionary
3958	* @format_string: a GVariant format string
3959	* @...: the arguments to unpack the value into
3960	*
3961	* Looks up a value in a #GVariantDict.
3962	*
3963	* This function is a wrapper around g_variant_dict_lookup_value() and
3964	* g_variant_get(). In the case that %NULL would have been returned,
3965	* this function returns %FALSE. Otherwise, it unpacks the returned
3966	* value and returns %TRUE.
3967	*
3968	* @format_string determines the C types that are used for unpacking the
3969	* values and also determines if the values are copied or borrowed, see the
3970	* section on [GVariant format strings][gvariant-format-strings-pointers].
3971	*
3972	* Returns: %TRUE if a value was unpacked
3973	*
3974	* Since: 2.40
3975	**/
3976	gboolean
3977	g_variant_dict_lookup (GVariantDict *dict,
3978	const gchar *key,
3979	const gchar *format_string,
3980	...)
3981	{
3982	GVariant *value;
3983	va_list ap;
3984
3985	g_return_val_if_fail (ensure_valid_dict (dict), FALSE);
3986	g_return_val_if_fail (key != NULL, FALSE);
3987	g_return_val_if_fail (format_string != NULL, FALSE);
3988
3989	value = g_hash_table_lookup (GVSD(dict)->values, key);
3990
3991	if (value == NULL || !g_variant_check_format_string (value, format_string, FALSE))
3992	return FALSE;
3993
3994	va_start (ap, format_string);
3995	g_variant_get_va (value, format_string, NULL, app: &ap);
3996	va_end (ap);
3997
3998	return TRUE;
3999	}
4000
4001	/**
4002	* g_variant_dict_lookup_value:
4003	* @dict: a #GVariantDict
4004	* @key: the key to look up in the dictionary
4005	* @expected_type: (nullable): a #GVariantType, or %NULL
4006	*
4007	* Looks up a value in a #GVariantDict.
4008	*
4009	* If @key is not found in @dictionary, %NULL is returned.
4010	*
4011	* The @expected_type string specifies what type of value is expected.
4012	* If the value associated with @key has a different type then %NULL is
4013	* returned.
4014	*
4015	* If the key is found and the value has the correct type, it is
4016	* returned. If @expected_type was specified then any non-%NULL return
4017	* value will have this type.
4018	*
4019	* Returns: (transfer full): the value of the dictionary key, or %NULL
4020	*
4021	* Since: 2.40
4022	**/
4023	GVariant *
4024	g_variant_dict_lookup_value (GVariantDict *dict,
4025	const gchar *key,
4026	const GVariantType *expected_type)
4027	{
4028	GVariant *result;
4029
4030	g_return_val_if_fail (ensure_valid_dict (dict), NULL);
4031	g_return_val_if_fail (key != NULL, NULL);
4032
4033	result = g_hash_table_lookup (GVSD(dict)->values, key);
4034
4035	if (result && (!expected_type || g_variant_is_of_type (value: result, type: expected_type)))
4036	return g_variant_ref (value: result);
4037
4038	return NULL;
4039	}
4040
4041	/**
4042	* g_variant_dict_contains:
4043	* @dict: a #GVariantDict
4044	* @key: the key to look up in the dictionary
4045	*
4046	* Checks if @key exists in @dict.
4047	*
4048	* Returns: %TRUE if @key is in @dict
4049	*
4050	* Since: 2.40
4051	**/
4052	gboolean
4053	g_variant_dict_contains (GVariantDict *dict,
4054	const gchar *key)
4055	{
4056	g_return_val_if_fail (ensure_valid_dict (dict), FALSE);
4057	g_return_val_if_fail (key != NULL, FALSE);
4058
4059	return g_hash_table_contains (GVSD(dict)->values, key);
4060	}
4061
4062	/**
4063	* g_variant_dict_insert:
4064	* @dict: a #GVariantDict
4065	* @key: the key to insert a value for
4066	* @format_string: a #GVariant varargs format string
4067	* @...: arguments, as per @format_string
4068	*
4069	* Inserts a value into a #GVariantDict.
4070	*
4071	* This call is a convenience wrapper that is exactly equivalent to
4072	* calling g_variant_new() followed by g_variant_dict_insert_value().
4073	*
4074	* Since: 2.40
4075	**/
4076	void
4077	g_variant_dict_insert (GVariantDict *dict,
4078	const gchar *key,
4079	const gchar *format_string,
4080	...)
4081	{
4082	va_list ap;
4083
4084	g_return_if_fail (ensure_valid_dict (dict));
4085	g_return_if_fail (key != NULL);
4086	g_return_if_fail (format_string != NULL);
4087
4088	va_start (ap, format_string);
4089	g_variant_dict_insert_value (dict, key, value: g_variant_new_va (format_string, NULL, app: &ap));
4090	va_end (ap);
4091	}
4092
4093	/**
4094	* g_variant_dict_insert_value:
4095	* @dict: a #GVariantDict
4096	* @key: the key to insert a value for
4097	* @value: the value to insert
4098	*
4099	* Inserts (or replaces) a key in a #GVariantDict.
4100	*
4101	* @value is consumed if it is floating.
4102	*
4103	* Since: 2.40
4104	**/
4105	void
4106	g_variant_dict_insert_value (GVariantDict *dict,
4107	const gchar *key,
4108	GVariant *value)
4109	{
4110	g_return_if_fail (ensure_valid_dict (dict));
4111	g_return_if_fail (key != NULL);
4112	g_return_if_fail (value != NULL);
4113
4114	g_hash_table_insert (GVSD(dict)->values, key: g_strdup (str: key), value: g_variant_ref_sink (value));
4115	}
4116
4117	/**
4118	* g_variant_dict_remove:
4119	* @dict: a #GVariantDict
4120	* @key: the key to remove
4121	*
4122	* Removes a key and its associated value from a #GVariantDict.
4123	*
4124	* Returns: %TRUE if the key was found and removed
4125	*
4126	* Since: 2.40
4127	**/
4128	gboolean
4129	g_variant_dict_remove (GVariantDict *dict,
4130	const gchar *key)
4131	{
4132	g_return_val_if_fail (ensure_valid_dict (dict), FALSE);
4133	g_return_val_if_fail (key != NULL, FALSE);
4134
4135	return g_hash_table_remove (GVSD(dict)->values, key);
4136	}
4137
4138	/**
4139	* g_variant_dict_clear:
4140	* @dict: a #GVariantDict
4141	*
4142	* Releases all memory associated with a #GVariantDict without freeing
4143	* the #GVariantDict structure itself.
4144	*
4145	* It typically only makes sense to do this on a stack-allocated
4146	* #GVariantDict if you want to abort building the value part-way
4147	* through. This function need not be called if you call
4148	* g_variant_dict_end() and it also doesn't need to be called on dicts
4149	* allocated with g_variant_dict_new (see g_variant_dict_unref() for
4150	* that).
4151	*
4152	* It is valid to call this function on either an initialised
4153	* #GVariantDict or one that was previously cleared by an earlier call
4154	* to g_variant_dict_clear() but it is not valid to call this function
4155	* on uninitialised memory.
4156	*
4157	* Since: 2.40
4158	**/
4159	void
4160	g_variant_dict_clear (GVariantDict *dict)
4161	{
4162	if (GVSD(dict)->magic == 0)
4163	/* all-zeros case */
4164	return;
4165
4166	g_return_if_fail (ensure_valid_dict (dict));
4167
4168	g_hash_table_unref (GVSD(dict)->values);
4169	GVSD(dict)->values = NULL;
4170
4171	GVSD(dict)->magic = 0;
4172	}
4173
4174	/**
4175	* g_variant_dict_end:
4176	* @dict: a #GVariantDict
4177	*
4178	* Returns the current value of @dict as a #GVariant of type
4179	* %G_VARIANT_TYPE_VARDICT, clearing it in the process.
4180	*
4181	* It is not permissible to use @dict in any way after this call except
4182	* for reference counting operations (in the case of a heap-allocated
4183	* #GVariantDict) or by reinitialising it with g_variant_dict_init() (in
4184	* the case of stack-allocated).
4185	*
4186	* Returns: (transfer none): a new, floating, #GVariant
4187	*
4188	* Since: 2.40
4189	**/
4190	GVariant *
4191	g_variant_dict_end (GVariantDict *dict)
4192	{
4193	GVariantBuilder builder;
4194	GHashTableIter iter;
4195	gpointer key, value;
4196
4197	g_return_val_if_fail (ensure_valid_dict (dict), NULL);
4198
4199	g_variant_builder_init (builder: &builder, G_VARIANT_TYPE_VARDICT);
4200
4201	g_hash_table_iter_init (iter: &iter, GVSD(dict)->values);
4202	while (g_hash_table_iter_next (iter: &iter, key: &key, value: &value))
4203	g_variant_builder_add (builder: &builder, format_string: "{sv}", (const gchar *) key, (GVariant *) value);
4204
4205	g_variant_dict_clear (dict);
4206
4207	return g_variant_builder_end (builder: &builder);
4208	}
4209
4210	/**
4211	* g_variant_dict_ref:
4212	* @dict: a heap-allocated #GVariantDict
4213	*
4214	* Increases the reference count on @dict.
4215	*
4216	* Don't call this on stack-allocated #GVariantDict instances or bad
4217	* things will happen.
4218	*
4219	* Returns: (transfer full): a new reference to @dict
4220	*
4221	* Since: 2.40
4222	**/
4223	GVariantDict *
4224	g_variant_dict_ref (GVariantDict *dict)
4225	{
4226	g_return_val_if_fail (is_valid_heap_dict (dict), NULL);
4227
4228	GVHD(dict)->ref_count++;
4229
4230	return dict;
4231	}
4232
4233	/**
4234	* g_variant_dict_unref:
4235	* @dict: (transfer full): a heap-allocated #GVariantDict
4236	*
4237	* Decreases the reference count on @dict.
4238	*
4239	* In the event that there are no more references, releases all memory
4240	* associated with the #GVariantDict.
4241	*
4242	* Don't call this on stack-allocated #GVariantDict instances or bad
4243	* things will happen.
4244	*
4245	* Since: 2.40
4246	**/
4247	void
4248	g_variant_dict_unref (GVariantDict *dict)
4249	{
4250	g_return_if_fail (is_valid_heap_dict (dict));
4251
4252	if (--GVHD(dict)->ref_count == 0)
4253	{
4254	g_variant_dict_clear (dict);
4255	g_slice_free (struct heap_dict, (struct heap_dict *) dict);
4256	}
4257	}
4258
4259
4260	/* Format strings {{{1 */
4261	/*< private >
4262	* g_variant_format_string_scan:
4263	* @string: a string that may be prefixed with a format string
4264	* @limit: (nullable) (default NULL): a pointer to the end of @string,
4265	* or %NULL
4266	* @endptr: (nullable) (default NULL): location to store the end pointer,
4267	* or %NULL
4268	*
4269	* Checks the string pointed to by @string for starting with a properly
4270	* formed #GVariant varargs format string. If no valid format string is
4271	* found then %FALSE is returned.
4272	*
4273	* If @string does start with a valid format string then %TRUE is
4274	* returned. If @endptr is non-%NULL then it is updated to point to the
4275	* first character after the format string.
4276	*
4277	* If @limit is non-%NULL then @limit (and any character after it) will
4278	* not be accessed and the effect is otherwise equivalent to if the
4279	* character at @limit were nul.
4280	*
4281	* See the section on [GVariant format strings][gvariant-format-strings].
4282	*
4283	* Returns: %TRUE if there was a valid format string
4284	*
4285	* Since: 2.24
4286	*/
4287	gboolean
4288	g_variant_format_string_scan (const gchar *string,
4289	const gchar *limit,
4290	const gchar **endptr)
4291	{
4292	#define next_char() (string == limit ? '\0' : *(string++))
4293	#define peek_char() (string == limit ? '\0' : *string)
4294	char c;
4295
4296	switch (next_char())
4297	{
4298	case 'b': case 'y': case 'n': case 'q': case 'i': case 'u':
4299	case 'x': case 't': case 'h': case 'd': case 's': case 'o':
4300	case 'g': case 'v': case '*': case '?': case 'r':
4301	break;
4302
4303	case 'm':
4304	return g_variant_format_string_scan (string, limit, endptr);
4305
4306	case 'a':
4307	case '@':
4308	return g_variant_type_string_scan (string, limit, endptr);
4309
4310	case '(':
4311	while (peek_char() != ')')
4312	if (!g_variant_format_string_scan (string, limit, endptr: &string))
4313	return FALSE;
4314
4315	next_char(); /* consume ')' */
4316	break;
4317
4318	case '{':
4319	c = next_char();
4320
4321	if (c == '&')
4322	{
4323	c = next_char ();
4324
4325	if (c != 's' && c != 'o' && c != 'g')
4326	return FALSE;
4327	}
4328	else
4329	{
4330	if (c == '@')
4331	c = next_char ();
4332
4333	/* ISO/IEC 9899:1999 (C99) §7.21.5.2:
4334	* The terminating null character is considered to be
4335	* part of the string.
4336	*/
4337	if (c != '\0' && strchr (s: "bynqiuxthdsog?", c: c) == NULL)
4338	return FALSE;
4339	}
4340
4341	if (!g_variant_format_string_scan (string, limit, endptr: &string))
4342	return FALSE;
4343
4344	if (next_char() != '}')
4345	return FALSE;
4346
4347	break;
4348
4349	case '^':
4350	if ((c = next_char()) == 'a')
4351	{
4352	if ((c = next_char()) == '&')
4353	{
4354	if ((c = next_char()) == 'a')
4355	{
4356	if ((c = next_char()) == 'y')
4357	break; /* '^a&ay' */
4358	}
4359
4360	else if (c == 's' || c == 'o')
4361	break; /* '^a&s', '^a&o' */
4362	}
4363
4364	else if (c == 'a')
4365	{
4366	if ((c = next_char()) == 'y')
4367	break; /* '^aay' */
4368	}
4369
4370	else if (c == 's' || c == 'o')
4371	break; /* '^as', '^ao' */
4372
4373	else if (c == 'y')
4374	break; /* '^ay' */
4375	}
4376	else if (c == '&')
4377	{
4378	if ((c = next_char()) == 'a')
4379	{
4380	if ((c = next_char()) == 'y')
4381	break; /* '^&ay' */
4382	}
4383	}
4384
4385	return FALSE;
4386
4387	case '&':
4388	c = next_char();
4389
4390	if (c != 's' && c != 'o' && c != 'g')
4391	return FALSE;
4392
4393	break;
4394
4395	default:
4396	return FALSE;
4397	}
4398
4399	if (endptr != NULL)
4400	*endptr = string;
4401
4402	#undef next_char
4403	#undef peek_char
4404
4405	return TRUE;
4406	}
4407
4408	/**
4409	* g_variant_check_format_string:
4410	* @value: a #GVariant
4411	* @format_string: a valid #GVariant format string
4412	* @copy_only: %TRUE to ensure the format string makes deep copies
4413	*
4414	* Checks if calling g_variant_get() with @format_string on @value would
4415	* be valid from a type-compatibility standpoint. @format_string is
4416	* assumed to be a valid format string (from a syntactic standpoint).
4417	*
4418	* If @copy_only is %TRUE then this function additionally checks that it
4419	* would be safe to call g_variant_unref() on @value immediately after
4420	* the call to g_variant_get() without invalidating the result. This is
4421	* only possible if deep copies are made (ie: there are no pointers to
4422	* the data inside of the soon-to-be-freed #GVariant instance). If this
4423	* check fails then a g_critical() is printed and %FALSE is returned.
4424	*
4425	* This function is meant to be used by functions that wish to provide
4426	* varargs accessors to #GVariant values of uncertain values (eg:
4427	* g_variant_lookup() or g_menu_model_get_item_attribute()).
4428	*
4429	* Returns: %TRUE if @format_string is safe to use
4430	*
4431	* Since: 2.34
4432	*/
4433	gboolean
4434	g_variant_check_format_string (GVariant *value,
4435	const gchar *format_string,
4436	gboolean copy_only)
4437	{
4438	const gchar *original_format = format_string;
4439	const gchar *type_string;
4440
4441	/* Interesting factoid: assuming a format string is valid, it can be
4442	* converted to a type string by removing all '@' '&' and '^'
4443	* characters.
4444	*
4445	* Instead of doing that, we can just skip those characters when
4446	* comparing it to the type string of @value.
4447	*
4448	* For the copy-only case we can just drop the '&' from the list of
4449	* characters to skip over. A '&' will never appear in a type string
4450	* so we know that it won't be possible to return %TRUE if it is in a
4451	* format string.
4452	*/
4453	type_string = g_variant_get_type_string (value);
4454
4455	while (*type_string || *format_string)
4456	{
4457	gchar format = *format_string++;
4458
4459	switch (format)
4460	{
4461	case '&':
4462	if G_UNLIKELY (copy_only)
4463	{
4464	/* for the love of all that is good, please don't mark this string for translation... */
4465	g_critical ("g_variant_check_format_string() is being called by a function with a GVariant varargs "
4466	"interface to validate the passed format string for type safety. The passed format "
4467	"(%s) contains a '&' character which would result in a pointer being returned to the "
4468	"data inside of a GVariant instance that may no longer exist by the time the function "
4469	"returns. Modify your code to use a format string without '&'.", original_format);
4470	return FALSE;
4471	}
4472
4473	G_GNUC_FALLTHROUGH;
4474	case '^':
4475	case '@':
4476	/* ignore these 2 (or 3) */
4477	continue;
4478
4479	case '?':
4480	/* attempt to consume one of 'bynqiuxthdsog' */
4481	{
4482	char s = *type_string++;
4483
4484	if (s == '\0' || strchr (s: "bynqiuxthdsog", c: s) == NULL)
4485	return FALSE;
4486	}
4487	continue;
4488
4489	case 'r':
4490	/* ensure it's a tuple */
4491	if (*type_string != '(')
4492	return FALSE;
4493
4494	G_GNUC_FALLTHROUGH;
4495	case '*':
4496	/* consume a full type string for the '*' or 'r' */
4497	if (!g_variant_type_string_scan (string: type_string, NULL, endptr: &type_string))
4498	return FALSE;
4499
4500	continue;
4501
4502	default:
4503	/* attempt to consume exactly one character equal to the format */
4504	if (format != *type_string++)
4505	return FALSE;
4506	}
4507	}
4508
4509	return TRUE;
4510	}
4511
4512	/*< private >
4513	* g_variant_format_string_scan_type:
4514	* @string: a string that may be prefixed with a format string
4515	* @limit: (nullable) (default NULL): a pointer to the end of @string,
4516	* or %NULL
4517	* @endptr: (nullable) (default NULL): location to store the end pointer,
4518	* or %NULL
4519	*
4520	* If @string starts with a valid format string then this function will
4521	* return the type that the format string corresponds to. Otherwise
4522	* this function returns %NULL.
4523	*
4524	* Use g_variant_type_free() to free the return value when you no longer
4525	* need it.
4526	*
4527	* This function is otherwise exactly like
4528	* g_variant_format_string_scan().
4529	*
4530	* Returns: (nullable): a #GVariantType if there was a valid format string
4531	*
4532	* Since: 2.24
4533	*/
4534	GVariantType *
4535	g_variant_format_string_scan_type (const gchar *string,
4536	const gchar *limit,
4537	const gchar **endptr)
4538	{
4539	const gchar *my_end;
4540	gchar *dest;
4541	gchar *new;
4542
4543	if (endptr == NULL)
4544	endptr = &my_end;
4545
4546	if (!g_variant_format_string_scan (string, limit, endptr))
4547	return NULL;
4548
4549	dest = new = g_malloc (n_bytes: *endptr - string + 1);
4550	while (string != *endptr)
4551	{
4552	if (*string != '@' && *string != '&' && *string != '^')
4553	*dest++ = *string;
4554	string++;
4555	}
4556	*dest = '\0';
4557
4558	return (GVariantType *) G_VARIANT_TYPE (new);
4559	}
4560
4561	static gboolean
4562	valid_format_string (const gchar *format_string,
4563	gboolean single,
4564	GVariant *value)
4565	{
4566	const gchar *endptr;
4567	GVariantType *type;
4568
4569	type = g_variant_format_string_scan_type (string: format_string, NULL, endptr: &endptr);
4570
4571	if G_UNLIKELY (type == NULL || (single && *endptr != '\0'))
4572	{
4573	if (single)
4574	g_critical ("'%s' is not a valid GVariant format string",
4575	format_string);
4576	else
4577	g_critical ("'%s' does not have a valid GVariant format "
4578	"string as a prefix", format_string);
4579
4580	if (type != NULL)
4581	g_variant_type_free (type);
4582
4583	return FALSE;
4584	}
4585
4586	if G_UNLIKELY (value && !g_variant_is_of_type (value, type))
4587	{
4588	gchar *fragment;
4589	gchar *typestr;
4590
4591	fragment = g_strndup (str: format_string, n: endptr - format_string);
4592	typestr = g_variant_type_dup_string (type);
4593
4594	g_critical ("the GVariant format string '%s' has a type of "
4595	"'%s' but the given value has a type of '%s'",
4596	fragment, typestr, g_variant_get_type_string (value));
4597
4598	g_variant_type_free (type);
4599	g_free (mem: fragment);
4600	g_free (mem: typestr);
4601
4602	return FALSE;
4603	}
4604
4605	g_variant_type_free (type);
4606
4607	return TRUE;
4608	}
4609
4610	/* Variable Arguments {{{1 */
4611	/* We consider 2 main classes of format strings:
4612	*
4613	* - recursive format strings
4614	* these are ones that result in recursion and the collection of
4615	* possibly more than one argument. Maybe types, tuples,
4616	* dictionary entries.
4617	*
4618	* - leaf format string
4619	* these result in the collection of a single argument.
4620	*
4621	* Leaf format strings are further subdivided into two categories:
4622	*
4623	* - single non-null pointer ("nnp")
4624	* these either collect or return a single non-null pointer.
4625	*
4626	* - other
4627	* these collect or return something else (bool, number, etc).
4628	*
4629	* Based on the above, the varargs handling code is split into 4 main parts:
4630	*
4631	* - nnp handling code
4632	* - leaf handling code (which may invoke nnp code)
4633	* - generic handling code (may be recursive, may invoke leaf code)
4634	* - user-facing API (which invokes the generic code)
4635	*
4636	* Each section implements some of the following functions:
4637	*
4638	* - skip:
4639	* collect the arguments for the format string as if
4640	* g_variant_new() had been called, but do nothing with them. used
4641	* for skipping over arguments when constructing a Nothing maybe
4642	* type.
4643	*
4644	* - new:
4645	* create a GVariant *
4646	*
4647	* - get:
4648	* unpack a GVariant *
4649	*
4650	* - free (nnp only):
4651	* free a previously allocated item
4652	*/
4653
4654	static gboolean
4655	g_variant_format_string_is_leaf (const gchar *str)
4656	{
4657	return str[0] != 'm' && str[0] != '(' && str[0] != '{';
4658	}
4659
4660	static gboolean
4661	g_variant_format_string_is_nnp (const gchar *str)
4662	{
4663	return str[0] == 'a' || str[0] == 's' || str[0] == 'o' || str[0] == 'g' ||
4664	str[0] == '^' || str[0] == '@' || str[0] == '*' || str[0] == '?' ||
4665	str[0] == 'r' || str[0] == 'v' || str[0] == '&';
4666	}
4667
4668	/* Single non-null pointer ("nnp") {{{2 */
4669	static void
4670	g_variant_valist_free_nnp (const gchar *str,
4671	gpointer ptr)
4672	{
4673	switch (*str)
4674	{
4675	case 'a':
4676	g_variant_iter_free (iter: ptr);
4677	break;
4678
4679	case '^':
4680	if (g_str_has_suffix (str, suffix: "y"))
4681	{
4682	if (str[2] != 'a') /* '^a&ay', '^ay' */
4683	g_free (mem: ptr);
4684	else if (str[1] == 'a') /* '^aay' */
4685	g_strfreev (str_array: ptr);
4686	break; /* '^&ay' */
4687	}
4688	else if (str[2] != '&') /* '^as', '^ao' */
4689	g_strfreev (str_array: ptr);
4690	else /* '^a&s', '^a&o' */
4691	g_free (mem: ptr);
4692	break;
4693
4694	case 's':
4695	case 'o':
4696	case 'g':
4697	g_free (mem: ptr);
4698	break;
4699
4700	case '@':
4701	case '*':
4702	case '?':
4703	case 'v':
4704	g_variant_unref (value: ptr);
4705	break;
4706
4707	case '&':
4708	break;
4709
4710	default:
4711	g_assert_not_reached ();
4712	}
4713	}
4714
4715	static gchar
4716	g_variant_scan_convenience (const gchar **str,
4717	gboolean *constant,
4718	guint *arrays)
4719	{
4720	*constant = FALSE;
4721	*arrays = 0;
4722
4723	for (;;)
4724	{
4725	char c = *(*str)++;
4726
4727	if (c == '&')
4728	*constant = TRUE;
4729
4730	else if (c == 'a')
4731	(*arrays)++;
4732
4733	else
4734	return c;
4735	}
4736	}
4737
4738	static GVariant *
4739	g_variant_valist_new_nnp (const gchar **str,
4740	gpointer ptr)
4741	{
4742	if (**str == '&')
4743	(*str)++;
4744
4745	switch (*(*str)++)
4746	{
4747	case 'a':
4748	if (ptr != NULL)
4749	{
4750	const GVariantType *type;
4751	GVariant *value;
4752
4753	value = g_variant_builder_end (builder: ptr);
4754	type = g_variant_get_type (value);
4755
4756	if G_UNLIKELY (!g_variant_type_is_array (type))
4757	g_error ("g_variant_new: expected array GVariantBuilder but "
4758	"the built value has type '%s'",
4759	g_variant_get_type_string (value));
4760
4761	type = g_variant_type_element (type);
4762
4763	if G_UNLIKELY (!g_variant_type_is_subtype_of (type, (GVariantType *) *str))
4764	{
4765	gchar *type_string = g_variant_type_dup_string (type: (GVariantType *) *str);
4766	g_error ("g_variant_new: expected GVariantBuilder array element "
4767	"type '%s' but the built value has element type '%s'",
4768	type_string, g_variant_get_type_string (value) + 1);
4769	g_free (mem: type_string);
4770	}
4771
4772	g_variant_type_string_scan (string: *str, NULL, endptr: str);
4773
4774	return value;
4775	}
4776	else
4777
4778	/* special case: NULL pointer for empty array */
4779	{
4780	const GVariantType *type = (GVariantType *) *str;
4781
4782	g_variant_type_string_scan (string: *str, NULL, endptr: str);
4783
4784	if G_UNLIKELY (!g_variant_type_is_definite (type))
4785	g_error ("g_variant_new: NULL pointer given with indefinite "
4786	"array type; unable to determine which type of empty "
4787	"array to construct.");
4788
4789	return g_variant_new_array (child_type: type, NULL, n_children: 0);
4790	}
4791
4792	case 's':
4793	{
4794	GVariant *value;
4795
4796	value = g_variant_new_string (string: ptr);
4797
4798	if (value == NULL)
4799	value = g_variant_new_string (string: "[Invalid UTF-8]");
4800
4801	return value;
4802	}
4803
4804	case 'o':
4805	return g_variant_new_object_path (object_path: ptr);
4806
4807	case 'g':
4808	return g_variant_new_signature (signature: ptr);
4809
4810	case '^':
4811	{
4812	gboolean constant;
4813	guint arrays;
4814	gchar type;
4815
4816	type = g_variant_scan_convenience (str, constant: &constant, arrays: &arrays);
4817
4818	if (type == 's')
4819	return g_variant_new_strv (strv: ptr, length: -1);
4820
4821	if (type == 'o')
4822	return g_variant_new_objv (strv: ptr, length: -1);
4823
4824	if (arrays > 1)
4825	return g_variant_new_bytestring_array (strv: ptr, length: -1);
4826
4827	return g_variant_new_bytestring (string: ptr);
4828	}
4829
4830	case '@':
4831	if G_UNLIKELY (!g_variant_is_of_type (ptr, (GVariantType *) *str))
4832	{
4833	gchar *type_string = g_variant_type_dup_string (type: (GVariantType *) *str);
4834	g_error ("g_variant_new: expected GVariant of type '%s' but "
4835	"received value has type '%s'",
4836	type_string, g_variant_get_type_string (ptr));
4837	g_free (mem: type_string);
4838	}
4839
4840	g_variant_type_string_scan (string: *str, NULL, endptr: str);
4841
4842	return ptr;
4843
4844	case '*':
4845	return ptr;
4846
4847	case '?':
4848	if G_UNLIKELY (!g_variant_type_is_basic (g_variant_get_type (ptr)))
4849	g_error ("g_variant_new: format string '?' expects basic-typed "
4850	"GVariant, but received value has type '%s'",
4851	g_variant_get_type_string (ptr));
4852
4853	return ptr;
4854
4855	case 'r':
4856	if G_UNLIKELY (!g_variant_type_is_tuple (g_variant_get_type (ptr)))
4857	g_error ("g_variant_new: format string 'r' expects tuple-typed "
4858	"GVariant, but received value has type '%s'",
4859	g_variant_get_type_string (ptr));
4860
4861	return ptr;
4862
4863	case 'v':
4864	return g_variant_new_variant (value: ptr);
4865
4866	default:
4867	g_assert_not_reached ();
4868	}
4869	}
4870
4871	static gpointer
4872	g_variant_valist_get_nnp (const gchar **str,
4873	GVariant *value)
4874	{
4875	switch (*(*str)++)
4876	{
4877	case 'a':
4878	g_variant_type_string_scan (string: *str, NULL, endptr: str);
4879	return g_variant_iter_new (value);
4880
4881	case '&':
4882	(*str)++;
4883	return (gchar *) g_variant_get_string (value, NULL);
4884
4885	case 's':
4886	case 'o':
4887	case 'g':
4888	return g_variant_dup_string (value, NULL);
4889
4890	case '^':
4891	{
4892	gboolean constant;
4893	guint arrays;
4894	gchar type;
4895
4896	type = g_variant_scan_convenience (str, constant: &constant, arrays: &arrays);
4897
4898	if (type == 's')
4899	{
4900	if (constant)
4901	return g_variant_get_strv (value, NULL);
4902	else
4903	return g_variant_dup_strv (value, NULL);
4904	}
4905
4906	else if (type == 'o')
4907	{
4908	if (constant)
4909	return g_variant_get_objv (value, NULL);
4910	else
4911	return g_variant_dup_objv (value, NULL);
4912	}
4913
4914	else if (arrays > 1)
4915	{
4916	if (constant)
4917	return g_variant_get_bytestring_array (value, NULL);
4918	else
4919	return g_variant_dup_bytestring_array (value, NULL);
4920	}
4921
4922	else
4923	{
4924	if (constant)
4925	return (gchar *) g_variant_get_bytestring (value);
4926	else
4927	return g_variant_dup_bytestring (value, NULL);
4928	}
4929	}
4930
4931	case '@':
4932	g_variant_type_string_scan (string: *str, NULL, endptr: str);
4933	G_GNUC_FALLTHROUGH;
4934
4935	case '*':
4936	case '?':
4937	case 'r':
4938	return g_variant_ref (value);
4939
4940	case 'v':
4941	return g_variant_get_variant (value);
4942
4943	default:
4944	g_assert_not_reached ();
4945	}
4946	}
4947
4948	/* Leaves {{{2 */
4949	static void
4950	g_variant_valist_skip_leaf (const gchar **str,
4951	va_list *app)
4952	{
4953	if (g_variant_format_string_is_nnp (str: *str))
4954	{
4955	g_variant_format_string_scan (string: *str, NULL, endptr: str);
4956	va_arg (*app, gpointer);
4957	return;
4958	}
4959
4960	switch (*(*str)++)
4961	{
4962	case 'b':
4963	case 'y':
4964	case 'n':
4965	case 'q':
4966	case 'i':
4967	case 'u':
4968	case 'h':
4969	va_arg (*app, int);
4970	return;
4971
4972	case 'x':
4973	case 't':
4974	va_arg (*app, guint64);
4975	return;
4976
4977	case 'd':
4978	va_arg (*app, gdouble);
4979	return;
4980
4981	default:
4982	g_assert_not_reached ();
4983	}
4984	}
4985
4986	static GVariant *
4987	g_variant_valist_new_leaf (const gchar **str,
4988	va_list *app)
4989	{
4990	if (g_variant_format_string_is_nnp (str: *str))
4991	return g_variant_valist_new_nnp (str, va_arg (*app, gpointer));
4992
4993	switch (*(*str)++)
4994	{
4995	case 'b':
4996	return g_variant_new_boolean (va_arg (*app, gboolean));
4997
4998	case 'y':
4999	return g_variant_new_byte (va_arg (*app, guint));
5000
5001	case 'n':
5002	return g_variant_new_int16 (va_arg (*app, gint));
5003
5004	case 'q':
5005	return g_variant_new_uint16 (va_arg (*app, guint));
5006
5007	case 'i':
5008	return g_variant_new_int32 (va_arg (*app, gint));
5009
5010	case 'u':
5011	return g_variant_new_uint32 (va_arg (*app, guint));
5012
5013	case 'x':
5014	return g_variant_new_int64 (va_arg (*app, gint64));
5015
5016	case 't':
5017	return g_variant_new_uint64 (va_arg (*app, guint64));
5018
5019	case 'h':
5020	return g_variant_new_handle (va_arg (*app, gint));
5021
5022	case 'd':
5023	return g_variant_new_double (va_arg (*app, gdouble));
5024
5025	default:
5026	g_assert_not_reached ();
5027	}
5028	}
5029
5030	/* The code below assumes this */
5031	G_STATIC_ASSERT (sizeof (gboolean) == sizeof (guint32));
5032	G_STATIC_ASSERT (sizeof (gdouble) == sizeof (guint64));
5033
5034	static void
5035	g_variant_valist_get_leaf (const gchar **str,
5036	GVariant *value,
5037	gboolean free,
5038	va_list *app)
5039	{
5040	gpointer ptr = va_arg (*app, gpointer);
5041
5042	if (ptr == NULL)
5043	{
5044	g_variant_format_string_scan (string: *str, NULL, endptr: str);
5045	return;
5046	}
5047
5048	if (g_variant_format_string_is_nnp (str: *str))
5049	{
5050	gpointer *nnp = (gpointer *) ptr;
5051
5052	if (free && *nnp != NULL)
5053	g_variant_valist_free_nnp (str: *str, ptr: *nnp);
5054
5055	*nnp = NULL;
5056
5057	if (value != NULL)
5058	*nnp = g_variant_valist_get_nnp (str, value);
5059	else
5060	g_variant_format_string_scan (string: *str, NULL, endptr: str);
5061
5062	return;
5063	}
5064
5065	if (value != NULL)
5066	{
5067	switch (*(*str)++)
5068	{
5069	case 'b':
5070	*(gboolean *) ptr = g_variant_get_boolean (value);
5071	return;
5072
5073	case 'y':
5074	*(guint8 *) ptr = g_variant_get_byte (value);
5075	return;
5076
5077	case 'n':
5078	*(gint16 *) ptr = g_variant_get_int16 (value);
5079	return;
5080
5081	case 'q':
5082	*(guint16 *) ptr = g_variant_get_uint16 (value);
5083	return;
5084
5085	case 'i':
5086	*(gint32 *) ptr = g_variant_get_int32 (value);
5087	return;
5088
5089	case 'u':
5090	*(guint32 *) ptr = g_variant_get_uint32 (value);
5091	return;
5092
5093	case 'x':
5094	*(gint64 *) ptr = g_variant_get_int64 (value);
5095	return;
5096
5097	case 't':
5098	*(guint64 *) ptr = g_variant_get_uint64 (value);
5099	return;
5100
5101	case 'h':
5102	*(gint32 *) ptr = g_variant_get_handle (value);
5103	return;
5104
5105	case 'd':
5106	*(gdouble *) ptr = g_variant_get_double (value);
5107	return;
5108	}
5109	}
5110	else
5111	{
5112	switch (*(*str)++)
5113	{
5114	case 'y':
5115	*(guint8 *) ptr = 0;
5116	return;
5117
5118	case 'n':
5119	case 'q':
5120	*(guint16 *) ptr = 0;
5121	return;
5122
5123	case 'i':
5124	case 'u':
5125	case 'h':
5126	case 'b':
5127	*(guint32 *) ptr = 0;
5128	return;
5129
5130	case 'x':
5131	case 't':
5132	case 'd':
5133	*(guint64 *) ptr = 0;
5134	return;
5135	}
5136	}
5137
5138	g_assert_not_reached ();
5139	}
5140
5141	/* Generic (recursive) {{{2 */
5142	static void
5143	g_variant_valist_skip (const gchar **str,
5144	va_list *app)
5145	{
5146	if (g_variant_format_string_is_leaf (str: *str))
5147	g_variant_valist_skip_leaf (str, app);
5148
5149	else if (**str == 'm') /* maybe */
5150	{
5151	(*str)++;
5152
5153	if (!g_variant_format_string_is_nnp (str: *str))
5154	va_arg (*app, gboolean);
5155
5156	g_variant_valist_skip (str, app);
5157	}
5158	else /* tuple, dictionary entry */
5159	{
5160	g_assert (**str == '(' || **str == '{');
5161	(*str)++;
5162	while (**str != ')' && **str != '}')
5163	g_variant_valist_skip (str, app);
5164	(*str)++;
5165	}
5166	}
5167
5168	static GVariant *
5169	g_variant_valist_new (const gchar **str,
5170	va_list *app)
5171	{
5172	if (g_variant_format_string_is_leaf (str: *str))
5173	return g_variant_valist_new_leaf (str, app);
5174
5175	if (**str == 'm') /* maybe */
5176	{
5177	GVariantType *type = NULL;
5178	GVariant *value = NULL;
5179
5180	(*str)++;
5181
5182	if (g_variant_format_string_is_nnp (str: *str))
5183	{
5184	gpointer nnp = va_arg (*app, gpointer);
5185
5186	if (nnp != NULL)
5187	value = g_variant_valist_new_nnp (str, ptr: nnp);
5188	else
5189	type = g_variant_format_string_scan_type (string: *str, NULL, endptr: str);
5190	}
5191	else
5192	{
5193	gboolean just = va_arg (*app, gboolean);
5194
5195	if (just)
5196	value = g_variant_valist_new (str, app);
5197	else
5198	{
5199	type = g_variant_format_string_scan_type (string: *str, NULL, NULL);
5200	g_variant_valist_skip (str, app);
5201	}
5202	}
5203
5204	value = g_variant_new_maybe (child_type: type, child: value);
5205
5206	if (type != NULL)
5207	g_variant_type_free (type);
5208
5209	return value;
5210	}
5211	else /* tuple, dictionary entry */
5212	{
5213	GVariantBuilder b;
5214
5215	if (**str == '(')
5216	g_variant_builder_init (builder: &b, G_VARIANT_TYPE_TUPLE);
5217	else
5218	{
5219	g_assert (**str == '{');
5220	g_variant_builder_init (builder: &b, G_VARIANT_TYPE_DICT_ENTRY);
5221	}
5222
5223	(*str)++; /* '(' */
5224	while (**str != ')' && **str != '}')
5225	g_variant_builder_add_value (builder: &b, value: g_variant_valist_new (str, app));
5226	(*str)++; /* ')' */
5227
5228	return g_variant_builder_end (builder: &b);
5229	}
5230	}
5231
5232	static void
5233	g_variant_valist_get (const gchar **str,
5234	GVariant *value,
5235	gboolean free,
5236	va_list *app)
5237	{
5238	if (g_variant_format_string_is_leaf (str: *str))
5239	g_variant_valist_get_leaf (str, value, free, app);
5240
5241	else if (**str == 'm')
5242	{
5243	(*str)++;
5244
5245	if (value != NULL)
5246	value = g_variant_get_maybe (value);
5247
5248	if (!g_variant_format_string_is_nnp (str: *str))
5249	{
5250	gboolean *ptr = va_arg (*app, gboolean *);
5251
5252	if (ptr != NULL)
5253	*ptr = value != NULL;
5254	}
5255
5256	g_variant_valist_get (str, value, free, app);
5257
5258	if (value != NULL)
5259	g_variant_unref (value);
5260	}
5261
5262	else /* tuple, dictionary entry */
5263	{
5264	gint index = 0;
5265
5266	g_assert (**str == '(' || **str == '{');
5267
5268	(*str)++;
5269	while (**str != ')' && **str != '}')
5270	{
5271	if (value != NULL)
5272	{
5273	GVariant *child = g_variant_get_child_value (value, index_: index++);
5274	g_variant_valist_get (str, value: child, free, app);
5275	g_variant_unref (value: child);
5276	}
5277	else
5278	g_variant_valist_get (str, NULL, free, app);
5279	}
5280	(*str)++;
5281	}
5282	}
5283
5284	/* User-facing API {{{2 */
5285	/**
5286	* g_variant_new: (skip)
5287	* @format_string: a #GVariant format string
5288	* @...: arguments, as per @format_string
5289	*
5290	* Creates a new #GVariant instance.
5291	*
5292	* Think of this function as an analogue to g_strdup_printf().
5293	*
5294	* The type of the created instance and the arguments that are expected
5295	* by this function are determined by @format_string. See the section on
5296	* [GVariant format strings][gvariant-format-strings]. Please note that
5297	* the syntax of the format string is very likely to be extended in the
5298	* future.
5299	*
5300	* The first character of the format string must not be '*' '?' '@' or
5301	* 'r'; in essence, a new #GVariant must always be constructed by this
5302	* function (and not merely passed through it unmodified).
5303	*
5304	* Note that the arguments must be of the correct width for their types
5305	* specified in @format_string. This can be achieved by casting them. See
5306	* the [GVariant varargs documentation][gvariant-varargs].
5307	*
5308	* |[<!-- language="C" -->
5309	* MyFlags some_flags = FLAG_ONE | FLAG_TWO;
5310	* const gchar *some_strings[] = { "a", "b", "c", NULL };
5311	* GVariant *new_variant;
5312	*
5313	* new_variant = g_variant_new ("(t^as)",
5314	* // This cast is required.
5315	* (guint64) some_flags,
5316	* some_strings);
5317	* ]|
5318	*
5319	* Returns: a new floating #GVariant instance
5320	*
5321	* Since: 2.24
5322	**/
5323	GVariant *
5324	g_variant_new (const gchar *format_string,
5325	...)
5326	{
5327	GVariant *value;
5328	va_list ap;
5329
5330	g_return_val_if_fail (valid_format_string (format_string, TRUE, NULL) &&
5331	format_string[0] != '?' && format_string[0] != '@' &&
5332	format_string[0] != '*' && format_string[0] != 'r',
5333	NULL);
5334
5335	va_start (ap, format_string);
5336	value = g_variant_new_va (format_string, NULL, app: &ap);
5337	va_end (ap);
5338
5339	return value;
5340	}
5341
5342	/**
5343	* g_variant_new_va: (skip)
5344	* @format_string: a string that is prefixed with a format string
5345	* @endptr: (nullable) (default NULL): location to store the end pointer,
5346	* or %NULL
5347	* @app: a pointer to a #va_list
5348	*
5349	* This function is intended to be used by libraries based on
5350	* #GVariant that want to provide g_variant_new()-like functionality
5351	* to their users.
5352	*
5353	* The API is more general than g_variant_new() to allow a wider range
5354	* of possible uses.
5355	*
5356	* @format_string must still point to a valid format string, but it only
5357	* needs to be nul-terminated if @endptr is %NULL. If @endptr is
5358	* non-%NULL then it is updated to point to the first character past the
5359	* end of the format string.
5360	*
5361	* @app is a pointer to a #va_list. The arguments, according to
5362	* @format_string, are collected from this #va_list and the list is left
5363	* pointing to the argument following the last.
5364	*
5365	* Note that the arguments in @app must be of the correct width for their
5366	* types specified in @format_string when collected into the #va_list.
5367	* See the [GVariant varargs documentation][gvariant-varargs].
5368	*
5369	* These two generalisations allow mixing of multiple calls to
5370	* g_variant_new_va() and g_variant_get_va() within a single actual
5371	* varargs call by the user.
5372	*
5373	* The return value will be floating if it was a newly created GVariant
5374	* instance (for example, if the format string was "(ii)"). In the case
5375	* that the format_string was '*', '?', 'r', or a format starting with
5376	* '@' then the collected #GVariant pointer will be returned unmodified,
5377	* without adding any additional references.
5378	*
5379	* In order to behave correctly in all cases it is necessary for the
5380	* calling function to g_variant_ref_sink() the return result before
5381	* returning control to the user that originally provided the pointer.
5382	* At this point, the caller will have their own full reference to the
5383	* result. This can also be done by adding the result to a container,
5384	* or by passing it to another g_variant_new() call.
5385	*
5386	* Returns: a new, usually floating, #GVariant
5387	*
5388	* Since: 2.24
5389	**/
5390	GVariant *
5391	g_variant_new_va (const gchar *format_string,
5392	const gchar **endptr,
5393	va_list *app)
5394	{
5395	GVariant *value;
5396
5397	g_return_val_if_fail (valid_format_string (format_string, !endptr, NULL),
5398	NULL);
5399	g_return_val_if_fail (app != NULL, NULL);
5400
5401	value = g_variant_valist_new (str: &format_string, app);
5402
5403	if (endptr != NULL)
5404	*endptr = format_string;
5405
5406	return value;
5407	}
5408
5409	/**
5410	* g_variant_get: (skip)
5411	* @value: a #GVariant instance
5412	* @format_string: a #GVariant format string
5413	* @...: arguments, as per @format_string
5414	*
5415	* Deconstructs a #GVariant instance.
5416	*
5417	* Think of this function as an analogue to scanf().
5418	*
5419	* The arguments that are expected by this function are entirely
5420	* determined by @format_string. @format_string also restricts the
5421	* permissible types of @value. It is an error to give a value with
5422	* an incompatible type. See the section on
5423	* [GVariant format strings][gvariant-format-strings].
5424	* Please note that the syntax of the format string is very likely to be
5425	* extended in the future.
5426	*
5427	* @format_string determines the C types that are used for unpacking
5428	* the values and also determines if the values are copied or borrowed,
5429	* see the section on
5430	* [GVariant format strings][gvariant-format-strings-pointers].
5431	*
5432	* Since: 2.24
5433	**/
5434	void
5435	g_variant_get (GVariant *value,
5436	const gchar *format_string,
5437	...)
5438	{
5439	va_list ap;
5440
5441	g_return_if_fail (value != NULL);
5442	g_return_if_fail (valid_format_string (format_string, TRUE, value));
5443
5444	/* if any direct-pointer-access formats are in use, flatten first */
5445	if (strchr (s: format_string, c: '&'))
5446	g_variant_get_data (value);
5447
5448	va_start (ap, format_string);
5449	g_variant_get_va (value, format_string, NULL, app: &ap);
5450	va_end (ap);
5451	}
5452
5453	/**
5454	* g_variant_get_va: (skip)
5455	* @value: a #GVariant
5456	* @format_string: a string that is prefixed with a format string
5457	* @endptr: (nullable) (default NULL): location to store the end pointer,
5458	* or %NULL
5459	* @app: a pointer to a #va_list
5460	*
5461	* This function is intended to be used by libraries based on #GVariant
5462	* that want to provide g_variant_get()-like functionality to their
5463	* users.
5464	*
5465	* The API is more general than g_variant_get() to allow a wider range
5466	* of possible uses.
5467	*
5468	* @format_string must still point to a valid format string, but it only
5469	* need to be nul-terminated if @endptr is %NULL. If @endptr is
5470	* non-%NULL then it is updated to point to the first character past the
5471	* end of the format string.
5472	*
5473	* @app is a pointer to a #va_list. The arguments, according to
5474	* @format_string, are collected from this #va_list and the list is left
5475	* pointing to the argument following the last.
5476	*
5477	* These two generalisations allow mixing of multiple calls to
5478	* g_variant_new_va() and g_variant_get_va() within a single actual
5479	* varargs call by the user.
5480	*
5481	* @format_string determines the C types that are used for unpacking
5482	* the values and also determines if the values are copied or borrowed,
5483	* see the section on
5484	* [GVariant format strings][gvariant-format-strings-pointers].
5485	*
5486	* Since: 2.24
5487	**/
5488	void
5489	g_variant_get_va (GVariant *value,
5490	const gchar *format_string,
5491	const gchar **endptr,
5492	va_list *app)
5493	{
5494	g_return_if_fail (valid_format_string (format_string, !endptr, value));
5495	g_return_if_fail (value != NULL);
5496	g_return_if_fail (app != NULL);
5497
5498	/* if any direct-pointer-access formats are in use, flatten first */
5499	if (strchr (s: format_string, c: '&'))
5500	g_variant_get_data (value);
5501
5502	g_variant_valist_get (str: &format_string, value, FALSE, app);
5503
5504	if (endptr != NULL)
5505	*endptr = format_string;
5506	}
5507
5508	/* Varargs-enabled Utility Functions {{{1 */
5509
5510	/**
5511	* g_variant_builder_add: (skip)
5512	* @builder: a #GVariantBuilder
5513	* @format_string: a #GVariant varargs format string
5514	* @...: arguments, as per @format_string
5515	*
5516	* Adds to a #GVariantBuilder.
5517	*
5518	* This call is a convenience wrapper that is exactly equivalent to
5519	* calling g_variant_new() followed by g_variant_builder_add_value().
5520	*
5521	* Note that the arguments must be of the correct width for their types
5522	* specified in @format_string. This can be achieved by casting them. See
5523	* the [GVariant varargs documentation][gvariant-varargs].
5524	*
5525	* This function might be used as follows:
5526	*
5527	* |[<!-- language="C" -->
5528	* GVariant *
5529	* make_pointless_dictionary (void)
5530	* {
5531	* GVariantBuilder builder;
5532	* int i;
5533	*
5534	* g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY);
5535	* for (i = 0; i < 16; i++)
5536	* {
5537	* gchar buf[3];
5538	*
5539	* sprintf (buf, "%d", i);
5540	* g_variant_builder_add (&builder, "{is}", i, buf);
5541	* }
5542	*
5543	* return g_variant_builder_end (&builder);
5544	* }
5545	* ]|
5546	*
5547	* Since: 2.24
5548	*/
5549	void
5550	g_variant_builder_add (GVariantBuilder *builder,
5551	const gchar *format_string,
5552	...)
5553	{
5554	GVariant *variant;
5555	va_list ap;
5556
5557	va_start (ap, format_string);
5558	variant = g_variant_new_va (format_string, NULL, app: &ap);
5559	va_end (ap);
5560
5561	g_variant_builder_add_value (builder, value: variant);
5562	}
5563
5564	/**
5565	* g_variant_get_child: (skip)
5566	* @value: a container #GVariant
5567	* @index_: the index of the child to deconstruct
5568	* @format_string: a #GVariant format string
5569	* @...: arguments, as per @format_string
5570	*
5571	* Reads a child item out of a container #GVariant instance and
5572	* deconstructs it according to @format_string. This call is
5573	* essentially a combination of g_variant_get_child_value() and
5574	* g_variant_get().
5575	*
5576	* @format_string determines the C types that are used for unpacking
5577	* the values and also determines if the values are copied or borrowed,
5578	* see the section on
5579	* [GVariant format strings][gvariant-format-strings-pointers].
5580	*
5581	* Since: 2.24
5582	**/
5583	void
5584	g_variant_get_child (GVariant *value,
5585	gsize index_,
5586	const gchar *format_string,
5587	...)
5588	{
5589	GVariant *child;
5590	va_list ap;
5591
5592	/* if any direct-pointer-access formats are in use, flatten first */
5593	if (strchr (s: format_string, c: '&'))
5594	g_variant_get_data (value);
5595
5596	child = g_variant_get_child_value (value, index_);
5597	g_return_if_fail (valid_format_string (format_string, TRUE, child));
5598
5599	va_start (ap, format_string);
5600	g_variant_get_va (value: child, format_string, NULL, app: &ap);
5601	va_end (ap);
5602
5603	g_variant_unref (value: child);
5604	}
5605
5606	/**
5607	* g_variant_iter_next: (skip)
5608	* @iter: a #GVariantIter
5609	* @format_string: a GVariant format string
5610	* @...: the arguments to unpack the value into
5611	*
5612	* Gets the next item in the container and unpacks it into the variable
5613	* argument list according to @format_string, returning %TRUE.
5614	*
5615	* If no more items remain then %FALSE is returned.
5616	*
5617	* All of the pointers given on the variable arguments list of this
5618	* function are assumed to point at uninitialised memory. It is the
5619	* responsibility of the caller to free all of the values returned by
5620	* the unpacking process.
5621	*
5622	* Here is an example for memory management with g_variant_iter_next():
5623	* |[<!-- language="C" -->
5624	* // Iterates a dictionary of type 'a{sv}'
5625	* void
5626	* iterate_dictionary (GVariant *dictionary)
5627	* {
5628	* GVariantIter iter;
5629	* GVariant *value;
5630	* gchar *key;
5631	*
5632	* g_variant_iter_init (&iter, dictionary);
5633	* while (g_variant_iter_next (&iter, "{sv}", &key, &value))
5634	* {
5635	* g_print ("Item '%s' has type '%s'\n", key,
5636	* g_variant_get_type_string (value));
5637	*
5638	* // must free data for ourselves
5639	* g_variant_unref (value);
5640	* g_free (key);
5641	* }
5642	* }
5643	* ]|
5644	*
5645	* For a solution that is likely to be more convenient to C programmers
5646	* when dealing with loops, see g_variant_iter_loop().
5647	*
5648	* @format_string determines the C types that are used for unpacking
5649	* the values and also determines if the values are copied or borrowed.
5650	*
5651	* See the section on
5652	* [GVariant format strings][gvariant-format-strings-pointers].
5653	*
5654	* Returns: %TRUE if a value was unpacked, or %FALSE if there as no value
5655	*
5656	* Since: 2.24
5657	**/
5658	gboolean
5659	g_variant_iter_next (GVariantIter *iter,
5660	const gchar *format_string,
5661	...)
5662	{
5663	GVariant *value;
5664
5665	value = g_variant_iter_next_value (iter);
5666
5667	g_return_val_if_fail (valid_format_string (format_string, TRUE, value),
5668	FALSE);
5669
5670	if (value != NULL)
5671	{
5672	va_list ap;
5673
5674	va_start (ap, format_string);
5675	g_variant_valist_get (str: &format_string, value, FALSE, app: &ap);
5676	va_end (ap);
5677
5678	g_variant_unref (value);
5679	}
5680
5681	return value != NULL;
5682	}
5683
5684	/**
5685	* g_variant_iter_loop: (skip)
5686	* @iter: a #GVariantIter
5687	* @format_string: a GVariant format string
5688	* @...: the arguments to unpack the value into
5689	*
5690	* Gets the next item in the container and unpacks it into the variable
5691	* argument list according to @format_string, returning %TRUE.
5692	*
5693	* If no more items remain then %FALSE is returned.
5694	*
5695	* On the first call to this function, the pointers appearing on the
5696	* variable argument list are assumed to point at uninitialised memory.
5697	* On the second and later calls, it is assumed that the same pointers
5698	* will be given and that they will point to the memory as set by the
5699	* previous call to this function. This allows the previous values to
5700	* be freed, as appropriate.
5701	*
5702	* This function is intended to be used with a while loop as
5703	* demonstrated in the following example. This function can only be
5704	* used when iterating over an array. It is only valid to call this
5705	* function with a string constant for the format string and the same
5706	* string constant must be used each time. Mixing calls to this
5707	* function and g_variant_iter_next() or g_variant_iter_next_value() on
5708	* the same iterator causes undefined behavior.
5709	*
5710	* If you break out of a such a while loop using g_variant_iter_loop() then
5711	* you must free or unreference all the unpacked values as you would with
5712	* g_variant_get(). Failure to do so will cause a memory leak.
5713	*
5714	* Here is an example for memory management with g_variant_iter_loop():
5715	* |[<!-- language="C" -->
5716	* // Iterates a dictionary of type 'a{sv}'
5717	* void
5718	* iterate_dictionary (GVariant *dictionary)
5719	* {
5720	* GVariantIter iter;
5721	* GVariant *value;
5722	* gchar *key;
5723	*
5724	* g_variant_iter_init (&iter, dictionary);
5725	* while (g_variant_iter_loop (&iter, "{sv}", &key, &value))
5726	* {
5727	* g_print ("Item '%s' has type '%s'\n", key,
5728	* g_variant_get_type_string (value));
5729	*
5730	* // no need to free 'key' and 'value' here
5731	* // unless breaking out of this loop
5732	* }
5733	* }
5734	* ]|
5735	*
5736	* For most cases you should use g_variant_iter_next().
5737	*
5738	* This function is really only useful when unpacking into #GVariant or
5739	* #GVariantIter in order to allow you to skip the call to
5740	* g_variant_unref() or g_variant_iter_free().
5741	*
5742	* For example, if you are only looping over simple integer and string
5743	* types, g_variant_iter_next() is definitely preferred. For string
5744	* types, use the '&' prefix to avoid allocating any memory at all (and
5745	* thereby avoiding the need to free anything as well).
5746	*
5747	* @format_string determines the C types that are used for unpacking
5748	* the values and also determines if the values are copied or borrowed.
5749	*
5750	* See the section on
5751	* [GVariant format strings][gvariant-format-strings-pointers].
5752	*
5753	* Returns: %TRUE if a value was unpacked, or %FALSE if there was no
5754	* value
5755	*
5756	* Since: 2.24
5757	**/
5758	gboolean
5759	g_variant_iter_loop (GVariantIter *iter,
5760	const gchar *format_string,
5761	...)
5762	{
5763	gboolean first_time = GVSI(iter)->loop_format == NULL;
5764	GVariant *value;
5765	va_list ap;
5766
5767	g_return_val_if_fail (first_time ||
5768	format_string == GVSI(iter)->loop_format,
5769	FALSE);
5770
5771	if (first_time)
5772	{
5773	TYPE_CHECK (GVSI(iter)->value, G_VARIANT_TYPE_ARRAY, FALSE);
5774	GVSI(iter)->loop_format = format_string;
5775
5776	if (strchr (s: format_string, c: '&'))
5777	g_variant_get_data (GVSI(iter)->value);
5778	}
5779
5780	value = g_variant_iter_next_value (iter);
5781
5782	g_return_val_if_fail (!first_time ||
5783	valid_format_string (format_string, TRUE, value),
5784	FALSE);
5785
5786	va_start (ap, format_string);
5787	g_variant_valist_get (str: &format_string, value, free: !first_time, app: &ap);
5788	va_end (ap);
5789
5790	if (value != NULL)
5791	g_variant_unref (value);
5792
5793	return value != NULL;
5794	}
5795
5796	/* Serialised data {{{1 */
5797	static GVariant *
5798	g_variant_deep_copy (GVariant *value)
5799	{
5800	switch (g_variant_classify (value))
5801	{
5802	case G_VARIANT_CLASS_MAYBE:
5803	case G_VARIANT_CLASS_ARRAY:
5804	case G_VARIANT_CLASS_TUPLE:
5805	case G_VARIANT_CLASS_DICT_ENTRY:
5806	case G_VARIANT_CLASS_VARIANT:
5807	{
5808	GVariantBuilder builder;
5809	GVariantIter iter;
5810	GVariant *child;
5811
5812	g_variant_builder_init (builder: &builder, type: g_variant_get_type (value));
5813	g_variant_iter_init (iter: &iter, value);
5814
5815	while ((child = g_variant_iter_next_value (iter: &iter)))
5816	{
5817	g_variant_builder_add_value (builder: &builder, value: g_variant_deep_copy (value: child));
5818	g_variant_unref (value: child);
5819	}
5820
5821	return g_variant_builder_end (builder: &builder);
5822	}
5823
5824	case G_VARIANT_CLASS_BOOLEAN:
5825	return g_variant_new_boolean (value: g_variant_get_boolean (value));
5826
5827	case G_VARIANT_CLASS_BYTE:
5828	return g_variant_new_byte (value: g_variant_get_byte (value));
5829
5830	case G_VARIANT_CLASS_INT16:
5831	return g_variant_new_int16 (value: g_variant_get_int16 (value));
5832
5833	case G_VARIANT_CLASS_UINT16:
5834	return g_variant_new_uint16 (value: g_variant_get_uint16 (value));
5835
5836	case G_VARIANT_CLASS_INT32:
5837	return g_variant_new_int32 (value: g_variant_get_int32 (value));
5838
5839	case G_VARIANT_CLASS_UINT32:
5840	return g_variant_new_uint32 (value: g_variant_get_uint32 (value));
5841
5842	case G_VARIANT_CLASS_INT64:
5843	return g_variant_new_int64 (value: g_variant_get_int64 (value));
5844
5845	case G_VARIANT_CLASS_UINT64:
5846	return g_variant_new_uint64 (value: g_variant_get_uint64 (value));
5847
5848	case G_VARIANT_CLASS_HANDLE:
5849	return g_variant_new_handle (value: g_variant_get_handle (value));
5850
5851	case G_VARIANT_CLASS_DOUBLE:
5852	return g_variant_new_double (value: g_variant_get_double (value));
5853
5854	case G_VARIANT_CLASS_STRING:
5855	return g_variant_new_string (string: g_variant_get_string (value, NULL));
5856
5857	case G_VARIANT_CLASS_OBJECT_PATH:
5858	return g_variant_new_object_path (object_path: g_variant_get_string (value, NULL));
5859
5860	case G_VARIANT_CLASS_SIGNATURE:
5861	return g_variant_new_signature (signature: g_variant_get_string (value, NULL));
5862	}
5863
5864	g_assert_not_reached ();
5865	}
5866
5867	/**
5868	* g_variant_get_normal_form:
5869	* @value: a #GVariant
5870	*
5871	* Gets a #GVariant instance that has the same value as @value and is
5872	* trusted to be in normal form.
5873	*
5874	* If @value is already trusted to be in normal form then a new
5875	* reference to @value is returned.
5876	*
5877	* If @value is not already trusted, then it is scanned to check if it
5878	* is in normal form. If it is found to be in normal form then it is
5879	* marked as trusted and a new reference to it is returned.
5880	*
5881	* If @value is found not to be in normal form then a new trusted
5882	* #GVariant is created with the same value as @value.
5883	*
5884	* It makes sense to call this function if you've received #GVariant
5885	* data from untrusted sources and you want to ensure your serialised
5886	* output is definitely in normal form.
5887	*
5888	* If @value is already in normal form, a new reference will be returned
5889	* (which will be floating if @value is floating). If it is not in normal form,
5890	* the newly created #GVariant will be returned with a single non-floating
5891	* reference. Typically, g_variant_take_ref() should be called on the return
5892	* value from this function to guarantee ownership of a single non-floating
5893	* reference to it.
5894	*
5895	* Returns: (transfer full): a trusted #GVariant
5896	*
5897	* Since: 2.24
5898	**/
5899	GVariant *
5900	g_variant_get_normal_form (GVariant *value)
5901	{
5902	GVariant *trusted;
5903
5904	if (g_variant_is_normal_form (value))
5905	return g_variant_ref (value);
5906
5907	trusted = g_variant_deep_copy (value);
5908	g_assert (g_variant_is_trusted (trusted));
5909
5910	return g_variant_ref_sink (value: trusted);
5911	}
5912
5913	/**
5914	* g_variant_byteswap:
5915	* @value: a #GVariant
5916	*
5917	* Performs a byteswapping operation on the contents of @value. The
5918	* result is that all multi-byte numeric data contained in @value is
5919	* byteswapped. That includes 16, 32, and 64bit signed and unsigned
5920	* integers as well as file handles and double precision floating point
5921	* values.
5922	*
5923	* This function is an identity mapping on any value that does not
5924	* contain multi-byte numeric data. That include strings, booleans,
5925	* bytes and containers containing only these things (recursively).
5926	*
5927	* The returned value is always in normal form and is marked as trusted.
5928	*
5929	* Returns: (transfer full): the byteswapped form of @value
5930	*
5931	* Since: 2.24
5932	**/
5933	GVariant *
5934	g_variant_byteswap (GVariant *value)
5935	{
5936	GVariantTypeInfo *type_info;
5937	guint alignment;
5938	GVariant *new;
5939
5940	type_info = g_variant_get_type_info (value);
5941
5942	g_variant_type_info_query (typeinfo: type_info, alignment: &alignment, NULL);
5943
5944	if (alignment)
5945	/* (potentially) contains multi-byte numeric data */
5946	{
5947	GVariantSerialised serialised;
5948	GVariant *trusted;
5949	GBytes *bytes;
5950
5951	trusted = g_variant_get_normal_form (value);
5952	serialised.type_info = g_variant_get_type_info (value: trusted);
5953	serialised.size = g_variant_get_size (value: trusted);
5954	serialised.data = g_malloc (n_bytes: serialised.size);
5955	serialised.depth = g_variant_get_depth (value: trusted);
5956	g_variant_store (value: trusted, data: serialised.data);
5957	g_variant_unref (value: trusted);
5958
5959	g_variant_serialised_byteswap (value: serialised);
5960
5961	bytes = g_bytes_new_take (data: serialised.data, size: serialised.size);
5962	new = g_variant_new_from_bytes (type: g_variant_get_type (value), bytes, TRUE);
5963	g_bytes_unref (bytes);
5964	}
5965	else
5966	/* contains no multi-byte data */
5967	new = value;
5968
5969	return g_variant_ref_sink (value: new);
5970	}
5971
5972	/**
5973	* g_variant_new_from_data:
5974	* @type: a definite #GVariantType
5975	* @data: (array length=size) (element-type guint8): the serialised data
5976	* @size: the size of @data
5977	* @trusted: %TRUE if @data is definitely in normal form
5978	* @notify: (scope async): function to call when @data is no longer needed
5979	* @user_data: data for @notify
5980	*
5981	* Creates a new #GVariant instance from serialised data.
5982	*
5983	* @type is the type of #GVariant instance that will be constructed.
5984	* The interpretation of @data depends on knowing the type.
5985	*
5986	* @data is not modified by this function and must remain valid with an
5987	* unchanging value until such a time as @notify is called with
5988	* @user_data. If the contents of @data change before that time then
5989	* the result is undefined.
5990	*
5991	* If @data is trusted to be serialised data in normal form then
5992	* @trusted should be %TRUE. This applies to serialised data created
5993	* within this process or read from a trusted location on the disk (such
5994	* as a file installed in /usr/lib alongside your application). You
5995	* should set trusted to %FALSE if @data is read from the network, a
5996	* file in the user's home directory, etc.
5997	*
5998	* If @data was not stored in this machine's native endianness, any multi-byte
5999	* numeric values in the returned variant will also be in non-native
6000	* endianness. g_variant_byteswap() can be used to recover the original values.
6001	*
6002	* @notify will be called with @user_data when @data is no longer
6003	* needed. The exact time of this call is unspecified and might even be
6004	* before this function returns.
6005	*
6006	* Note: @data must be backed by memory that is aligned appropriately for the
6007	* @type being loaded. Otherwise this function will internally create a copy of
6008	* the memory (since GLib 2.60) or (in older versions) fail and exit the
6009	* process.
6010	*
6011	* Returns: (transfer none): a new floating #GVariant of type @type
6012	*
6013	* Since: 2.24
6014	**/
6015	GVariant *
6016	g_variant_new_from_data (const GVariantType *type,
6017	gconstpointer data,
6018	gsize size,
6019	gboolean trusted,
6020	GDestroyNotify notify,
6021	gpointer user_data)
6022	{
6023	GVariant *value;
6024	GBytes *bytes;
6025
6026	g_return_val_if_fail (g_variant_type_is_definite (type), NULL);
6027	g_return_val_if_fail (data != NULL || size == 0, NULL);
6028
6029	if (notify)
6030	bytes = g_bytes_new_with_free_func (data, size, free_func: notify, user_data);
6031	else
6032	bytes = g_bytes_new_static (data, size);
6033
6034	value = g_variant_new_from_bytes (type, bytes, trusted);
6035	g_bytes_unref (bytes);
6036
6037	return value;
6038	}
6039
6040	/* Epilogue {{{1 */
6041	/* vim:set foldmethod=marker: */
6042