Català-Valencià – Catalan中文 – Chinese (Simplified)中文 – Chinese (Traditional)Česky – CzechDansk – DanishNederlands – DutchEnglish – EnglishSuomi – FinnishFrançais – FrenchDeutsch – Germanעברית – Hebrewहिंदी – HindiMagyar – HungarianBahasa Indonesia – IndonesianItaliano – Italian日本語 – Japanese한국어 – KoreanМакедонски – Macedonianमराठी – MarathiNorsk – NorwegianPolski – PolishPortuguês – PortuguesePortuguês – Portuguese (Brazil)Русский – RussianSlovenčina – SlovakSlovenščina – SlovenianEspañol – SpanishSvenska – SwedishTürkçe – TurkishУкраїнська – UkrainianOëzbekcha – Uzbek

nexmon – Blame information for rev 1

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