X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=glib%2Fgvariant.c;h=aca95798553ae40d464dd76b39dab514799be5a2;hb=9f5afe3966d31ef6f1e880d950206a0325e6c777;hp=fd4dea1affab00916c01ff6bafa4dc396aa69117;hpb=c57c61c930896f278de61de170e57affc243e427;p=platform%2Fupstream%2Fglib.git diff --git a/glib/gvariant.c b/glib/gvariant.c index fd4dea1..aca9579 100644 --- a/glib/gvariant.c +++ b/glib/gvariant.c @@ -13,9 +13,7 @@ * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public - * License along with this library; if not, write to the - * Free Software Foundation, Inc., 59 Temple Place - Suite 330, - * Boston, MA 02111-1307, USA. + * License along with this library; if not, see . * * Author: Ryan Lortie */ @@ -29,15 +27,15 @@ #include #include #include +#include #include #include #include -#include "galias.h" /** - * SECTION: gvariant + * SECTION:gvariant * @title: GVariant * @short_description: strongly typed value datatype * @see_also: GVariantType @@ -50,7 +48,7 @@ * #GVariant instances always have a type and a value (which are given * at construction time). The type and value of a #GVariant instance * can never change other than by the #GVariant itself being - * destroyed. A #GVariant can not contain a pointer. + * destroyed. A #GVariant cannot contain a pointer. * * #GVariant is reference counted using g_variant_ref() and * g_variant_unref(). #GVariant also has floating reference counts -- @@ -66,9 +64,24 @@ * small constant time, usually touching only a single memory page. * Serialised #GVariant data can also be sent over the network. * - * #GVariant is largely compatible with DBus. Almost all types of - * #GVariant instances can be sent over DBus. See #GVariantType for - * exceptions. + * #GVariant is largely compatible with D-Bus. Almost all types of + * #GVariant instances can be sent over D-Bus. See #GVariantType for + * exceptions. (However, #GVariant's serialisation format is not the same + * as the serialisation format of a D-Bus message body: use #GDBusMessage, + * in the gio library, for those.) + * + * For space-efficiency, the #GVariant serialisation format does not + * automatically include the variant's type or endianness, which must + * either be implied from context (such as knowledge that a particular + * file format always contains a little-endian %G_VARIANT_TYPE_VARIANT) + * or supplied out-of-band (for instance, a type and/or endianness + * indicator could be placed at the beginning of a file, network message + * or network stream). + * + * A #GVariant's size is limited mainly by any lower level operating + * system constraints, such as the number of bits in #gsize. For + * example, it is reasonable to have a 2GB file mapped into memory + * with #GMappedFile, and call g_variant_new_from_data() on it. * * For convenience to C programmers, #GVariant features powerful * varargs-based value construction and destruction. This feature is @@ -78,201 +91,169 @@ * values. #GVariant includes a printer for this language and a parser * with type inferencing. * - * - * Memory Use - * - * #GVariant tries to be quite efficient with respect to memory use. - * This section gives a rough idea of how much memory is used by the - * current implementation. The information here is subject to change - * in the future. - * - * - * The memory allocated by #GVariant can be grouped into 4 broad - * purposes: memory for serialised data, memory for the type - * information cache, buffer management memory and memory for the - * #GVariant structure itself. - * - * - * Serialised Data Memory - * - * This is the memory that is used for storing GVariant data in - * serialised form. This is what would be sent over the network or - * what would end up on disk. - * - * - * The amount of memory required to store a boolean is 1 byte. 16, - * 32 and 64 bit integers and double precision floating point numbers - * use their "natural" size. Strings (including object path and - * signature strings) are stored with a nul terminator, and as such - * use the length of the string plus 1 byte. - * - * - * Maybe types use no space at all to represent the null value and - * use the same amount of space (sometimes plus one byte) as the - * equivalent non-maybe-typed value to represent the non-null case. - * - * - * Arrays use the amount of space required to store each of their - * members, concatenated. Additionally, if the items stored in an - * array are not of a fixed-size (ie: strings, other arrays, etc) - * then an additional framing offset is stored for each item. The - * size of this offset is either 1, 2 or 4 bytes depending on the - * overall size of the container. Additionally, extra padding bytes - * are added as required for alignment of child values. - * - * - * Tuples (including dictionary entries) use the amount of space - * required to store each of their members, concatenated, plus one - * framing offset (as per arrays) for each non-fixed-sized item in - * the tuple, except for the last one. Additionally, extra padding - * bytes are added as required for alignment of child values. - * - * - * Variants use the same amount of space as the item inside of the - * variant, plus 1 byte, plus the length of the type string for the - * item inside the variant. - * - * - * As an example, consider a dictionary mapping strings to variants. - * In the case that the dictionary is empty, 0 bytes are required for - * the serialisation. - * - * - * If we add an item "width" that maps to the int32 value of 500 then - * we will use 4 byte to store the int32 (so 6 for the variant - * containing it) and 6 bytes for the string. The variant must be - * aligned to 8 after the 6 bytes of the string, so that's 2 extra - * bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used - * for the dictionary entry. An additional 1 byte is added to the - * array as a framing offset making a total of 15 bytes. - * - * - * If we add another entry, "title" that maps to a nullable string - * that happens to have a value of null, then we use 0 bytes for the - * null value (and 3 bytes for the variant to contain it along with - * its type string) plus 6 bytes for the string. Again, we need 2 - * padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes. - * - * - * We now require extra padding between the two items in the array. - * After the 14 bytes of the first item, that's 2 bytes required. We - * now require 2 framing offsets for an extra two bytes. 14 + 2 + 11 - * + 2 = 29 bytes to encode the entire two-item dictionary. - * - * - * - * Type Information Cache - * - * For each GVariant type that currently exists in the program a type - * information structure is kept in the type information cache. The - * type information structure is required for rapid deserialisation. - * - * - * Continuing with the above example, if a #GVariant exists with the - * type "a{sv}" then a type information struct will exist for - * "a{sv}", "{sv}", "s", and "v". Multiple uses of the same type - * will share the same type information. Additionally, all - * single-digit types are stored in read-only static memory and do - * not contribute to the writable memory footprint of a program using - * #GVariant. - * - * - * Aside from the type information structures stored in read-only - * memory, there are two forms of type information. One is used for - * container types where there is a single element type: arrays and - * maybe types. The other is used for container types where there - * are multiple element types: tuples and dictionary entries. - * - * - * Array type info structures are 6 * sizeof (void *), plus the - * memory required to store the type string itself. This means that - * on 32bit systems, the cache entry for "a{sv}" would require 30 - * bytes of memory (plus malloc overhead). - * - * - * Tuple type info structures are 6 * sizeof (void *), plus 4 * - * sizeof (void *) for each item in the tuple, plus the memory - * required to store the type string itself. A 2-item tuple, for - * example, would have a type information structure that consumed - * writable memory in the size of 14 * sizeof (void *) (plus type - * string) This means that on 32bit systems, the cache entry for - * "{sv}" would require 61 bytes of memory (plus malloc overhead). - * - * - * This means that in total, for our "a{sv}" example, 91 bytes of - * type information would be allocated. - * - * - * The type information cache, additionally, uses a #GHashTable to - * store and lookup the cached items and stores a pointer to this - * hash table in static storage. The hash table is freed when there - * are zero items in the type cache. - * - * - * Although these sizes may seem large it is important to remember - * that a program will probably only have a very small number of - * different types of values in it and that only one type information - * structure is required for many different values of the same type. - * - * - * - * Buffer Management Memory - * - * #GVariant uses an internal buffer management structure to deal - * with the various different possible sources of serialised data - * that it uses. The buffer is responsible for ensuring that the - * correct call is made when the data is no longer in use by - * #GVariant. This may involve a g_free() or a g_slice_free() or - * even g_mapped_file_unref(). - * - * - * One buffer management structure is used for each chunk of - * serialised data. The size of the buffer management structure is 4 - * * (void *). On 32bit systems, that's 16 bytes. - * - * - * - * GVariant structure - * - * The size of a #GVariant structure is 6 * (void *). On 32 bit - * systems, that's 24 bytes. - * - * - * #GVariant structures only exist if they are explicitly created - * with API calls. For example, if a #GVariant is constructed out of - * serialised data for the example given above (with the dictionary) - * then although there are 9 individual values that comprise the - * entire dictionary (two keys, two values, two variants containing - * the values, two dictionary entries, plus the dictionary itself), - * only 1 #GVariant instance exists -- the one refering to the - * dictionary. - * - * - * If calls are made to start accessing the other values then - * #GVariant instances will exist for those values only for as long - * as they are in use (ie: until you call g_variant_unref()). The - * type information is shared. The serialised data and the buffer - * management structure for that serialised data is shared by the - * child. - * - * - * - * Summary - * - * To put the entire example together, for our dictionary mapping - * strings to variants (with two entries, as given above), we are - * using 91 bytes of memory for type information, 29 byes of memory - * for the serialised data, 16 bytes for buffer management and 24 - * bytes for the #GVariant instance, or a total of 160 bytes, plus - * malloc overhead. If we were to use g_variant_get_child_value() to - * access the two dictionary entries, we would use an additional 48 - * bytes. If we were to have other dictionaries of the same type, we - * would use more memory for the serialised data and buffer - * management for those dictionaries, but the type information would - * be shared. - * - * - * + * ## Memory Use + * + * #GVariant tries to be quite efficient with respect to memory use. + * This section gives a rough idea of how much memory is used by the + * current implementation. The information here is subject to change + * in the future. + * + * The memory allocated by #GVariant can be grouped into 4 broad + * purposes: memory for serialised data, memory for the type + * information cache, buffer management memory and memory for the + * #GVariant structure itself. + * + * ## Serialised Data Memory + * + * This is the memory that is used for storing GVariant data in + * serialised form. This is what would be sent over the network or + * what would end up on disk. + * + * The amount of memory required to store a boolean is 1 byte. 16, + * 32 and 64 bit integers and double precision floating point numbers + * use their "natural" size. Strings (including object path and + * signature strings) are stored with a nul terminator, and as such + * use the length of the string plus 1 byte. + * + * Maybe types use no space at all to represent the null value and + * use the same amount of space (sometimes plus one byte) as the + * equivalent non-maybe-typed value to represent the non-null case. + * + * Arrays use the amount of space required to store each of their + * members, concatenated. Additionally, if the items stored in an + * array are not of a fixed-size (ie: strings, other arrays, etc) + * then an additional framing offset is stored for each item. The + * size of this offset is either 1, 2 or 4 bytes depending on the + * overall size of the container. Additionally, extra padding bytes + * are added as required for alignment of child values. + * + * Tuples (including dictionary entries) use the amount of space + * required to store each of their members, concatenated, plus one + * framing offset (as per arrays) for each non-fixed-sized item in + * the tuple, except for the last one. Additionally, extra padding + * bytes are added as required for alignment of child values. + * + * Variants use the same amount of space as the item inside of the + * variant, plus 1 byte, plus the length of the type string for the + * item inside the variant. + * + * As an example, consider a dictionary mapping strings to variants. + * In the case that the dictionary is empty, 0 bytes are required for + * the serialisation. + * + * If we add an item "width" that maps to the int32 value of 500 then + * we will use 4 byte to store the int32 (so 6 for the variant + * containing it) and 6 bytes for the string. The variant must be + * aligned to 8 after the 6 bytes of the string, so that's 2 extra + * bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used + * for the dictionary entry. An additional 1 byte is added to the + * array as a framing offset making a total of 15 bytes. + * + * If we add another entry, "title" that maps to a nullable string + * that happens to have a value of null, then we use 0 bytes for the + * null value (and 3 bytes for the variant to contain it along with + * its type string) plus 6 bytes for the string. Again, we need 2 + * padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes. + * + * We now require extra padding between the two items in the array. + * After the 14 bytes of the first item, that's 2 bytes required. + * We now require 2 framing offsets for an extra two + * bytes. 14 + 2 + 11 + 2 = 29 bytes to encode the entire two-item + * dictionary. + * + * ## Type Information Cache + * + * For each GVariant type that currently exists in the program a type + * information structure is kept in the type information cache. The + * type information structure is required for rapid deserialisation. + * + * Continuing with the above example, if a #GVariant exists with the + * type "a{sv}" then a type information struct will exist for + * "a{sv}", "{sv}", "s", and "v". Multiple uses of the same type + * will share the same type information. Additionally, all + * single-digit types are stored in read-only static memory and do + * not contribute to the writable memory footprint of a program using + * #GVariant. + * + * Aside from the type information structures stored in read-only + * memory, there are two forms of type information. One is used for + * container types where there is a single element type: arrays and + * maybe types. The other is used for container types where there + * are multiple element types: tuples and dictionary entries. + * + * Array type info structures are 6 * sizeof (void *), plus the + * memory required to store the type string itself. This means that + * on 32-bit systems, the cache entry for "a{sv}" would require 30 + * bytes of memory (plus malloc overhead). + * + * Tuple type info structures are 6 * sizeof (void *), plus 4 * + * sizeof (void *) for each item in the tuple, plus the memory + * required to store the type string itself. A 2-item tuple, for + * example, would have a type information structure that consumed + * writable memory in the size of 14 * sizeof (void *) (plus type + * string) This means that on 32-bit systems, the cache entry for + * "{sv}" would require 61 bytes of memory (plus malloc overhead). + * + * This means that in total, for our "a{sv}" example, 91 bytes of + * type information would be allocated. + * + * The type information cache, additionally, uses a #GHashTable to + * store and lookup the cached items and stores a pointer to this + * hash table in static storage. The hash table is freed when there + * are zero items in the type cache. + * + * Although these sizes may seem large it is important to remember + * that a program will probably only have a very small number of + * different types of values in it and that only one type information + * structure is required for many different values of the same type. + * + * ## Buffer Management Memory + * + * #GVariant uses an internal buffer management structure to deal + * with the various different possible sources of serialised data + * that it uses. The buffer is responsible for ensuring that the + * correct call is made when the data is no longer in use by + * #GVariant. This may involve a g_free() or a g_slice_free() or + * even g_mapped_file_unref(). + * + * One buffer management structure is used for each chunk of + * serialised data. The size of the buffer management structure + * is 4 * (void *). On 32-bit systems, that's 16 bytes. + * + * ## GVariant structure + * + * The size of a #GVariant structure is 6 * (void *). On 32-bit + * systems, that's 24 bytes. + * + * #GVariant structures only exist if they are explicitly created + * with API calls. For example, if a #GVariant is constructed out of + * serialised data for the example given above (with the dictionary) + * then although there are 9 individual values that comprise the + * entire dictionary (two keys, two values, two variants containing + * the values, two dictionary entries, plus the dictionary itself), + * only 1 #GVariant instance exists -- the one referring to the + * dictionary. + * + * If calls are made to start accessing the other values then + * #GVariant instances will exist for those values only for as long + * as they are in use (ie: until you call g_variant_unref()). The + * type information is shared. The serialised data and the buffer + * management structure for that serialised data is shared by the + * child. + * + * ## Summary + * + * To put the entire example together, for our dictionary mapping + * strings to variants (with two entries, as given above), we are + * using 91 bytes of memory for type information, 29 byes of memory + * for the serialised data, 16 bytes for buffer management and 24 + * bytes for the #GVariant instance, or a total of 160 bytes, plus + * malloc overhead. If we were to use g_variant_get_child_value() to + * access the two dictionary entries, we would use an additional 48 + * bytes. If we were to have other dictionaries of the same type, we + * would use more memory for the serialised data and buffer + * management for those dictionaries, but the type information would + * be shared. */ /* definition of GVariant structure is in gvariant-core.c */ @@ -294,10 +275,11 @@ * @type: the #GVariantType * @data: the data to use * @size: the size of @data - * @returns: a new floating #GVariant * * Constructs a new trusted #GVariant instance from the provided data. * This is used to implement g_variant_new_* for all the basic types. + * + * Returns: a new floating #GVariant */ static GVariant * g_variant_new_from_trusted (const GVariantType *type, @@ -305,22 +287,23 @@ g_variant_new_from_trusted (const GVariantType *type, gsize size) { GVariant *value; - GBuffer *buffer; + GBytes *bytes; - buffer = g_buffer_new_from_data (data, size); - value = g_variant_new_from_buffer (type, buffer, TRUE); - g_buffer_unref (buffer); + bytes = g_bytes_new (data, size); + value = g_variant_new_from_bytes (type, bytes, TRUE); + g_bytes_unref (bytes); return value; } /** * g_variant_new_boolean: - * @boolean: a #gboolean value - * @returns: a new boolean #GVariant instance + * @value: a #gboolean value * * Creates a new boolean #GVariant instance -- either %TRUE or %FALSE. * + * Returns: (transfer none): a floating reference to a new boolean #GVariant instance + * * Since: 2.24 **/ GVariant * @@ -334,13 +317,14 @@ g_variant_new_boolean (gboolean value) /** * g_variant_get_boolean: * @value: a boolean #GVariant instance - * @returns: %TRUE or %FALSE * * Returns the boolean value of @value. * * It is an error to call this function with a @value of any type * other than %G_VARIANT_TYPE_BOOLEAN. * + * Returns: %TRUE or %FALSE + * * Since: 2.24 **/ gboolean @@ -374,182 +358,196 @@ g_variant_get_boolean (GVariant *value) /** * g_variant_new_byte: - * @byte: a #guint8 value - * @returns: a new byte #GVariant instance + * @value: a #guint8 value * * Creates a new byte #GVariant instance. * + * Returns: (transfer none): a floating reference to a new byte #GVariant instance + * * Since: 2.24 **/ /** * g_variant_get_byte: * @value: a byte #GVariant instance - * @returns: a #guchar * * Returns the byte value of @value. * * It is an error to call this function with a @value of any type * other than %G_VARIANT_TYPE_BYTE. * + * Returns: a #guchar + * * Since: 2.24 **/ NUMERIC_TYPE (BYTE, byte, guchar) /** * g_variant_new_int16: - * @int16: a #gint16 value - * @returns: a new int16 #GVariant instance + * @value: a #gint16 value * * Creates a new int16 #GVariant instance. * + * Returns: (transfer none): a floating reference to a new int16 #GVariant instance + * * Since: 2.24 **/ /** * g_variant_get_int16: * @value: a int16 #GVariant instance - * @returns: a #gint16 * * Returns the 16-bit signed integer value of @value. * * It is an error to call this function with a @value of any type * other than %G_VARIANT_TYPE_INT16. * + * Returns: a #gint16 + * * Since: 2.24 **/ NUMERIC_TYPE (INT16, int16, gint16) /** * g_variant_new_uint16: - * @uint16: a #guint16 value - * @returns: a new uint16 #GVariant instance + * @value: a #guint16 value * * Creates a new uint16 #GVariant instance. * + * Returns: (transfer none): a floating reference to a new uint16 #GVariant instance + * * Since: 2.24 **/ /** * g_variant_get_uint16: * @value: a uint16 #GVariant instance - * @returns: a #guint16 * * Returns the 16-bit unsigned integer value of @value. * * It is an error to call this function with a @value of any type * other than %G_VARIANT_TYPE_UINT16. * + * Returns: a #guint16 + * * Since: 2.24 **/ NUMERIC_TYPE (UINT16, uint16, guint16) /** * g_variant_new_int32: - * @int32: a #gint32 value - * @returns: a new int32 #GVariant instance + * @value: a #gint32 value * * Creates a new int32 #GVariant instance. * + * Returns: (transfer none): a floating reference to a new int32 #GVariant instance + * * Since: 2.24 **/ /** * g_variant_get_int32: * @value: a int32 #GVariant instance - * @returns: a #gint32 * * Returns the 32-bit signed integer value of @value. * * It is an error to call this function with a @value of any type * other than %G_VARIANT_TYPE_INT32. * + * Returns: a #gint32 + * * Since: 2.24 **/ NUMERIC_TYPE (INT32, int32, gint32) /** * g_variant_new_uint32: - * @uint32: a #guint32 value - * @returns: a new uint32 #GVariant instance + * @value: a #guint32 value * * Creates a new uint32 #GVariant instance. * + * Returns: (transfer none): a floating reference to a new uint32 #GVariant instance + * * Since: 2.24 **/ /** * g_variant_get_uint32: * @value: a uint32 #GVariant instance - * @returns: a #guint32 * * Returns the 32-bit unsigned integer value of @value. * * It is an error to call this function with a @value of any type * other than %G_VARIANT_TYPE_UINT32. * + * Returns: a #guint32 + * * Since: 2.24 **/ NUMERIC_TYPE (UINT32, uint32, guint32) /** * g_variant_new_int64: - * @int64: a #gint64 value - * @returns: a new int64 #GVariant instance + * @value: a #gint64 value * * Creates a new int64 #GVariant instance. * + * Returns: (transfer none): a floating reference to a new int64 #GVariant instance + * * Since: 2.24 **/ /** * g_variant_get_int64: * @value: a int64 #GVariant instance - * @returns: a #gint64 * * Returns the 64-bit signed integer value of @value. * * It is an error to call this function with a @value of any type * other than %G_VARIANT_TYPE_INT64. * + * Returns: a #gint64 + * * Since: 2.24 **/ NUMERIC_TYPE (INT64, int64, gint64) /** * g_variant_new_uint64: - * @uint64: a #guint64 value - * @returns: a new uint64 #GVariant instance + * @value: a #guint64 value * * Creates a new uint64 #GVariant instance. * + * Returns: (transfer none): a floating reference to a new uint64 #GVariant instance + * * Since: 2.24 **/ /** * g_variant_get_uint64: * @value: a uint64 #GVariant instance - * @returns: a #guint64 * * Returns the 64-bit unsigned integer value of @value. * * It is an error to call this function with a @value of any type * other than %G_VARIANT_TYPE_UINT64. * + * Returns: a #guint64 + * * Since: 2.24 **/ NUMERIC_TYPE (UINT64, uint64, guint64) /** * g_variant_new_handle: - * @handle: a #gint32 value - * @returns: a new handle #GVariant instance + * @value: a #gint32 value * * Creates a new handle #GVariant instance. * * By convention, handles are indexes into an array of file descriptors - * that are sent alongside a DBus message. If you're not interacting - * with DBus, you probably don't need them. + * that are sent alongside a D-Bus message. If you're not interacting + * with D-Bus, you probably don't need them. + * + * Returns: (transfer none): a floating reference to a new handle #GVariant instance * * Since: 2.24 **/ /** * g_variant_get_handle: * @value: a handle #GVariant instance - * @returns: a #gint32 * * Returns the 32-bit signed integer value of @value. * @@ -557,8 +555,10 @@ NUMERIC_TYPE (UINT64, uint64, guint64) * than %G_VARIANT_TYPE_HANDLE. * * By convention, handles are indexes into an array of file descriptors - * that are sent alongside a DBus message. If you're not interacting - * with DBus, you probably don't need them. + * that are sent alongside a D-Bus message. If you're not interacting + * with D-Bus, you probably don't need them. + * + * Returns: a #gint32 * * Since: 2.24 **/ @@ -566,23 +566,25 @@ NUMERIC_TYPE (HANDLE, handle, gint32) /** * g_variant_new_double: - * @floating: a #gdouble floating point value - * @returns: a new double #GVariant instance + * @value: a #gdouble floating point value * * Creates a new double #GVariant instance. * + * Returns: (transfer none): a floating reference to a new double #GVariant instance + * * Since: 2.24 **/ /** * g_variant_get_double: * @value: a double #GVariant instance - * @returns: a #gdouble * * Returns the double precision floating point value of @value. * * It is an error to call this function with a @value of any type * other than %G_VARIANT_TYPE_DOUBLE. * + * Returns: a #gdouble + * * Since: 2.24 **/ NUMERIC_TYPE (DOUBLE, double, gdouble) @@ -590,16 +592,21 @@ NUMERIC_TYPE (DOUBLE, double, gdouble) /* Container type Constructor / Deconstructors {{{1 */ /** * g_variant_new_maybe: - * @child_type: the #GVariantType of the child - * @child: the child value, or %NULL - * @returns: a new #GVariant maybe instance + * @child_type: (allow-none): the #GVariantType of the child, or %NULL + * @child: (allow-none): the child value, or %NULL * - * Depending on if @value is %NULL, either wraps @value inside of a + * Depending on if @child is %NULL, either wraps @child inside of a * maybe container or creates a Nothing instance for the given @type. * - * At least one of @type and @value must be non-%NULL. If @type is - * non-%NULL then it must be a definite type. If they are both - * non-%NULL then @type must be the type of @value. + * At least one of @child_type and @child must be non-%NULL. + * If @child_type is non-%NULL then it must be a definite type. + * If they are both non-%NULL then @child_type must be the type + * of @child. + * + * If @child is a floating reference (see g_variant_ref_sink()), the new + * instance takes ownership of @child. + * + * Returns: (transfer none): a floating reference to a new #GVariant maybe instance * * Since: 2.24 **/ @@ -644,11 +651,12 @@ g_variant_new_maybe (const GVariantType *child_type, /** * g_variant_get_maybe: * @value: a maybe-typed value - * @returns: the contents of @value, or %NULL * * Given a maybe-typed #GVariant instance, extract its value. If the * value is Nothing, then this function returns %NULL. * + * Returns: (allow-none) (transfer full): the contents of @value, or %NULL + * * Since: 2.24 **/ GVariant * @@ -663,13 +671,17 @@ g_variant_get_maybe (GVariant *value) } /** - * g_variant_new_variant: - * @value: a #GVariance instance - * @returns: a new variant #GVariant instance + * g_variant_new_variant: (constructor) + * @value: a #GVariant instance * * Boxes @value. The result is a #GVariant instance representing a * variant containing the original value. * + * If @child is a floating reference (see g_variant_ref_sink()), the new + * instance takes ownership of @child. + * + * Returns: (transfer none): a floating reference to a new variant #GVariant instance + * * Since: 2.24 **/ GVariant * @@ -686,12 +698,13 @@ g_variant_new_variant (GVariant *value) /** * g_variant_get_variant: - * @value: a variant #GVariance instance - * @returns: the item contained in the variant + * @value: a variant #GVariant instance * * Unboxes @value. The result is the #GVariant instance that was * contained in @value. * + * Returns: (transfer full): the item contained in the variant + * * Since: 2.24 **/ GVariant * @@ -704,10 +717,10 @@ g_variant_get_variant (GVariant *value) /** * g_variant_new_array: - * @child_type: the element type of the new array - * @children: an array of #GVariant pointers, the children + * @child_type: (allow-none): the element type of the new array + * @children: (allow-none) (array length=n_children): an array of + * #GVariant pointers, the children * @n_children: the length of @children - * @returns: a new #GVariant array * * Creates a new #GVariant array from @children. * @@ -722,6 +735,11 @@ g_variant_get_variant (GVariant *value) * All items in the array must have the same type, which must be the * same as @child_type, if given. * + * If the @children are floating references (see g_variant_ref_sink()), the + * new instance takes ownership of them as if via g_variant_ref_sink(). + * + * Returns: (transfer none): a floating reference to a new #GVariant array + * * Since: 2.24 **/ GVariant * @@ -763,7 +781,7 @@ g_variant_new_array (const GVariantType *child_type, /*< private > * g_variant_make_tuple_type: - * @children: an array of GVariant * + * @children: (array length=n_children): an array of GVariant * * @n_children: the length of @children * * Return the type of a tuple containing @children as its items. @@ -789,9 +807,8 @@ g_variant_make_tuple_type (GVariant * const *children, /** * g_variant_new_tuple: - * @children: the items to make the tuple out of + * @children: (array length=n_children): the items to make the tuple out of * @n_children: the length of @children - * @returns: a new #GVariant tuple * * Creates a new tuple #GVariant out of the items in @children. The * type is determined from the types of @children. No entry in the @@ -799,6 +816,11 @@ g_variant_make_tuple_type (GVariant * const *children, * * If @n_children is 0 then the unit tuple is constructed. * + * If the @children are floating references (see g_variant_ref_sink()), the + * new instance takes ownership of them as if via g_variant_ref_sink(). + * + * Returns: (transfer none): a floating reference to a new #GVariant tuple + * * Since: 2.24 **/ GVariant * @@ -847,15 +869,17 @@ g_variant_make_dict_entry_type (GVariant *key, } /** - * g_variant_new_dict_entry: + * g_variant_new_dict_entry: (constructor) * @key: a basic #GVariant, the key * @value: a #GVariant, the value - * @returns: a new dictionary entry #GVariant * - * Creates a new dictionary entry #GVariant. @key and @value must be - * non-%NULL. + * Creates a new dictionary entry #GVariant. @key and @value must be + * non-%NULL. @key must be a value of a basic type (ie: not a container). * - * @key must be a value of a basic type (ie: not a container). + * If the @key or @value are floating references (see g_variant_ref_sink()), + * the new instance takes ownership of them as if via g_variant_ref_sink(). + * + * Returns: (transfer none): a floating reference to a new dictionary entry #GVariant * * Since: 2.24 **/ @@ -883,27 +907,191 @@ g_variant_new_dict_entry (GVariant *key, } /** + * g_variant_lookup: (skip) + * @dictionary: a dictionary #GVariant + * @key: the key to lookup in the dictionary + * @format_string: a GVariant format string + * @...: the arguments to unpack the value into + * + * Looks up a value in a dictionary #GVariant. + * + * This function is a wrapper around g_variant_lookup_value() and + * g_variant_get(). In the case that %NULL would have been returned, + * this function returns %FALSE. Otherwise, it unpacks the returned + * value and returns %TRUE. + * + * @format_string determines the C types that are used for unpacking + * the values and also determines if the values are copied or borrowed, + * see the section on + * [GVariant format strings][gvariant-format-strings-pointers]. + * + * This function is currently implemented with a linear scan. If you + * plan to do many lookups then #GVariantDict may be more efficient. + * + * Returns: %TRUE if a value was unpacked + * + * Since: 2.28 + */ +gboolean +g_variant_lookup (GVariant *dictionary, + const gchar *key, + const gchar *format_string, + ...) +{ + GVariantType *type; + GVariant *value; + + /* flatten */ + g_variant_get_data (dictionary); + + type = g_variant_format_string_scan_type (format_string, NULL, NULL); + value = g_variant_lookup_value (dictionary, key, type); + g_variant_type_free (type); + + if (value) + { + va_list ap; + + va_start (ap, format_string); + g_variant_get_va (value, format_string, NULL, &ap); + g_variant_unref (value); + va_end (ap); + + return TRUE; + } + + else + return FALSE; +} + +/** + * g_variant_lookup_value: + * @dictionary: a dictionary #GVariant + * @key: the key to lookup in the dictionary + * @expected_type: (allow-none): a #GVariantType, or %NULL + * + * Looks up a value in a dictionary #GVariant. + * + * This function works with dictionaries of the type a{s*} (and equally + * well with type a{o*}, but we only further discuss the string case + * for sake of clarity). + * + * In the event that @dictionary has the type a{sv}, the @expected_type + * string specifies what type of value is expected to be inside of the + * variant. If the value inside the variant has a different type then + * %NULL is returned. In the event that @dictionary has a value type other + * than v then @expected_type must directly match the key type and it is + * used to unpack the value directly or an error occurs. + * + * In either case, if @key is not found in @dictionary, %NULL is returned. + * + * If the key is found and the value has the correct type, it is + * returned. If @expected_type was specified then any non-%NULL return + * value will have this type. + * + * This function is currently implemented with a linear scan. If you + * plan to do many lookups then #GVariantDict may be more efficient. + * + * Returns: (transfer full): the value of the dictionary key, or %NULL + * + * Since: 2.28 + */ +GVariant * +g_variant_lookup_value (GVariant *dictionary, + const gchar *key, + const GVariantType *expected_type) +{ + GVariantIter iter; + GVariant *entry; + GVariant *value; + + g_return_val_if_fail (g_variant_is_of_type (dictionary, + G_VARIANT_TYPE ("a{s*}")) || + g_variant_is_of_type (dictionary, + G_VARIANT_TYPE ("a{o*}")), + NULL); + + g_variant_iter_init (&iter, dictionary); + + while ((entry = g_variant_iter_next_value (&iter))) + { + GVariant *entry_key; + gboolean matches; + + entry_key = g_variant_get_child_value (entry, 0); + matches = strcmp (g_variant_get_string (entry_key, NULL), key) == 0; + g_variant_unref (entry_key); + + if (matches) + break; + + g_variant_unref (entry); + } + + if (entry == NULL) + return NULL; + + value = g_variant_get_child_value (entry, 1); + g_variant_unref (entry); + + if (g_variant_is_of_type (value, G_VARIANT_TYPE_VARIANT)) + { + GVariant *tmp; + + tmp = g_variant_get_variant (value); + g_variant_unref (value); + + if (expected_type && !g_variant_is_of_type (tmp, expected_type)) + { + g_variant_unref (tmp); + tmp = NULL; + } + + value = tmp; + } + + g_return_val_if_fail (expected_type == NULL || value == NULL || + g_variant_is_of_type (value, expected_type), NULL); + + return value; +} + +/** * g_variant_get_fixed_array: * @value: a #GVariant array with fixed-sized elements - * @n_elements: a pointer to the location to store the number of items + * @n_elements: (out): a pointer to the location to store the number of items * @element_size: the size of each element - * @returns: a pointer to the fixed array * * Provides access to the serialised data for an array of fixed-sized * items. * * @value must be an array with fixed-sized elements. Numeric types are - * fixed-size as are tuples containing only other fixed-sized types. - * - * @element_size must be the size of a single element in the array. For - * example, if calling this function for an array of 32 bit integers, - * you might say sizeof (gint32). This value isn't used - * except for the purpose of a double-check that the form of the - * seralised data matches the caller's expectation. + * fixed-size, as are tuples containing only other fixed-sized types. + * + * @element_size must be the size of a single element in the array, + * as given by the section on + * [serialized data memory][gvariant-serialised-data-memory]. + * + * In particular, arrays of these fixed-sized types can be interpreted + * as an array of the given C type, with @element_size set to the size + * the appropriate type: + * - %G_VARIANT_TYPE_INT16 (etc.): #gint16 (etc.) + * - %G_VARIANT_TYPE_BOOLEAN: #guchar (not #gboolean!) + * - %G_VARIANT_TYPE_BYTE: #guchar + * - %G_VARIANT_TYPE_HANDLE: #guint32 + * - %G_VARIANT_TYPE_DOUBLE: #gdouble + * + * For example, if calling this function for an array of 32-bit integers, + * you might say sizeof(gint32). This value isn't used except for the purpose + * of a double-check that the form of the serialised data matches the caller's + * expectation. * * @n_elements, which must be non-%NULL is set equal to the number of * items in the array. * + * Returns: (array length=n_elements) (transfer none): a pointer to + * the fixed array + * * Since: 2.24 **/ gconstpointer @@ -930,13 +1118,13 @@ g_variant_get_fixed_array (GVariant *value, { if (array_element_size) g_critical ("g_variant_get_fixed_array: assertion " - "`g_variant_array_has_fixed_size (value, element_size)' " + "'g_variant_array_has_fixed_size (value, element_size)' " "failed: array size %"G_GSIZE_FORMAT" does not match " "given element_size %"G_GSIZE_FORMAT".", array_element_size, element_size); else g_critical ("g_variant_get_fixed_array: assertion " - "`g_variant_array_has_fixed_size (value, element_size)' " + "'g_variant_array_has_fixed_size (value, element_size)' " "failed: array does not have fixed size."); } @@ -954,36 +1142,179 @@ g_variant_get_fixed_array (GVariant *value, return NULL; } +/** + * g_variant_new_fixed_array: + * @element_type: the #GVariantType of each element + * @elements: a pointer to the fixed array of contiguous elements + * @n_elements: the number of elements + * @element_size: the size of each element + * + * Provides access to the serialised data for an array of fixed-sized + * items. + * + * @value must be an array with fixed-sized elements. Numeric types are + * fixed-size as are tuples containing only other fixed-sized types. + * + * @element_size must be the size of a single element in the array. + * For example, if calling this function for an array of 32-bit integers, + * you might say sizeof(gint32). This value isn't used except for the purpose + * of a double-check that the form of the serialised data matches the caller's + * expectation. + * + * @n_elements, which must be non-%NULL is set equal to the number of + * items in the array. + * + * Returns: (transfer none): a floating reference to a new array #GVariant instance + * + * Since: 2.32 + **/ +GVariant * +g_variant_new_fixed_array (const GVariantType *element_type, + gconstpointer elements, + gsize n_elements, + gsize element_size) +{ + GVariantType *array_type; + gsize array_element_size; + GVariantTypeInfo *array_info; + GVariant *value; + gpointer data; + + g_return_val_if_fail (g_variant_type_is_definite (element_type), NULL); + g_return_val_if_fail (element_size > 0, NULL); + + array_type = g_variant_type_new_array (element_type); + array_info = g_variant_type_info_get (array_type); + g_variant_type_info_query_element (array_info, NULL, &array_element_size); + if G_UNLIKELY (array_element_size != element_size) + { + if (array_element_size) + g_critical ("g_variant_new_fixed_array: array size %" G_GSIZE_FORMAT + " does not match given element_size %" G_GSIZE_FORMAT ".", + array_element_size, element_size); + else + g_critical ("g_variant_get_fixed_array: array does not have fixed size."); + return NULL; + } + + data = g_memdup (elements, n_elements * element_size); + value = g_variant_new_from_data (array_type, data, + n_elements * element_size, + FALSE, g_free, data); + + g_variant_type_free (array_type); + g_variant_type_info_unref (array_info); + + return value; +} + /* String type constructor/getters/validation {{{1 */ /** * g_variant_new_string: * @string: a normal utf8 nul-terminated string - * @returns: a new string #GVariant instance * * Creates a string #GVariant with the contents of @string. * * @string must be valid utf8. * + * Returns: (transfer none): a floating reference to a new string #GVariant instance + * * Since: 2.24 **/ GVariant * g_variant_new_string (const gchar *string) { g_return_val_if_fail (string != NULL, NULL); + g_return_val_if_fail (g_utf8_validate (string, -1, NULL), NULL); return g_variant_new_from_trusted (G_VARIANT_TYPE_STRING, string, strlen (string) + 1); } /** + * g_variant_new_take_string: (skip) + * @string: a normal utf8 nul-terminated string + * + * Creates a string #GVariant with the contents of @string. + * + * @string must be valid utf8. + * + * This function consumes @string. g_free() will be called on @string + * when it is no longer required. + * + * You must not modify or access @string in any other way after passing + * it to this function. It is even possible that @string is immediately + * freed. + * + * Returns: (transfer none): a floating reference to a new string + * #GVariant instance + * + * Since: 2.38 + **/ +GVariant * +g_variant_new_take_string (gchar *string) +{ + GVariant *value; + GBytes *bytes; + + g_return_val_if_fail (string != NULL, NULL); + g_return_val_if_fail (g_utf8_validate (string, -1, NULL), NULL); + + bytes = g_bytes_new_take (string, strlen (string) + 1); + value = g_variant_new_from_bytes (G_VARIANT_TYPE_STRING, bytes, TRUE); + g_bytes_unref (bytes); + + return value; +} + +/** + * g_variant_new_printf: (skip) + * @format_string: a printf-style format string + * @...: arguments for @format_string + * + * Creates a string-type GVariant using printf formatting. + * + * This is similar to calling g_strdup_printf() and then + * g_variant_new_string() but it saves a temporary variable and an + * unnecessary copy. + * + * Returns: (transfer none): a floating reference to a new string + * #GVariant instance + * + * Since: 2.38 + **/ +GVariant * +g_variant_new_printf (const gchar *format_string, + ...) +{ + GVariant *value; + GBytes *bytes; + gchar *string; + va_list ap; + + g_return_val_if_fail (format_string != NULL, NULL); + + va_start (ap, format_string); + string = g_strdup_vprintf (format_string, ap); + va_end (ap); + + bytes = g_bytes_new_take (string, strlen (string) + 1); + value = g_variant_new_from_bytes (G_VARIANT_TYPE_STRING, bytes, TRUE); + g_bytes_unref (bytes); + + return value; +} + +/** * g_variant_new_object_path: * @object_path: a normal C nul-terminated string - * @returns: a new object path #GVariant instance * - * Creates a DBus object path #GVariant with the contents of @string. - * @string must be a valid DBus object path. Use + * Creates a D-Bus object path #GVariant with the contents of @string. + * @string must be a valid D-Bus object path. Use * g_variant_is_object_path() if you're not sure. * + * Returns: (transfer none): a floating reference to a new object path #GVariant instance + * * Since: 2.24 **/ GVariant * @@ -998,10 +1329,9 @@ g_variant_new_object_path (const gchar *object_path) /** * g_variant_is_object_path: * @string: a normal C nul-terminated string - * @returns: %TRUE if @string is a DBus object path * - * Determines if a given string is a valid DBus object path. You - * should ensure that a string is a valid DBus object path before + * Determines if a given string is a valid D-Bus object path. You + * should ensure that a string is a valid D-Bus object path before * passing it to g_variant_new_object_path(). * * A valid object path starts with '/' followed by zero or more @@ -1009,6 +1339,8 @@ g_variant_new_object_path (const gchar *object_path) * must contain only the characters "[A-Z][a-z][0-9]_". No sequence * (including the one following the final '/' character) may be empty. * + * Returns: %TRUE if @string is a D-Bus object path + * * Since: 2.24 **/ gboolean @@ -1022,12 +1354,13 @@ g_variant_is_object_path (const gchar *string) /** * g_variant_new_signature: * @signature: a normal C nul-terminated string - * @returns: a new signature #GVariant instance * - * Creates a DBus type signature #GVariant with the contents of - * @string. @string must be a valid DBus type signature. Use + * Creates a D-Bus type signature #GVariant with the contents of + * @string. @string must be a valid D-Bus type signature. Use * g_variant_is_signature() if you're not sure. * + * Returns: (transfer none): a floating reference to a new signature #GVariant instance + * * Since: 2.24 **/ GVariant * @@ -1042,15 +1375,16 @@ g_variant_new_signature (const gchar *signature) /** * g_variant_is_signature: * @string: a normal C nul-terminated string - * @returns: %TRUE if @string is a DBus type signature * - * Determines if a given string is a valid DBus type signature. You - * should ensure that a string is a valid DBus object path before + * Determines if a given string is a valid D-Bus type signature. You + * should ensure that a string is a valid D-Bus type signature before * passing it to g_variant_new_signature(). * - * DBus type signatures consist of zero or more definite #GVariantType + * D-Bus type signatures consist of zero or more definite #GVariantType * strings in sequence. * + * Returns: %TRUE if @string is a D-Bus type signature + * * Since: 2.24 **/ gboolean @@ -1064,8 +1398,8 @@ g_variant_is_signature (const gchar *string) /** * g_variant_get_string: * @value: a string #GVariant instance - * @length: a pointer to a #gsize, to store the length - * @returns: the constant string, utf8 encoded + * @length: (allow-none) (default 0) (out): a pointer to a #gsize, + * to store the length * * Returns the string value of a #GVariant instance with a string * type. This includes the types %G_VARIANT_TYPE_STRING, @@ -1082,6 +1416,8 @@ g_variant_is_signature (const gchar *string) * * The return value remains valid as long as @value exists. * + * Returns: (transfer none): the constant string, utf8 encoded + * * Since: 2.24 **/ const gchar * @@ -1142,8 +1478,7 @@ g_variant_get_string (GVariant *value, /** * g_variant_dup_string: * @value: a string #GVariant instance - * @length: a pointer to a #gsize, to store the length - * @returns: a newly allocated string, utf8 encoded + * @length: (out): a pointer to a #gsize, to store the length * * Similar to g_variant_get_string() except that instead of returning * a constant string, the string is duplicated. @@ -1152,6 +1487,8 @@ g_variant_get_string (GVariant *value, * * The return value must be freed using g_free(). * + * Returns: (transfer full): a newly allocated string, utf8 encoded + * * Since: 2.24 **/ gchar * @@ -1162,95 +1499,16 @@ g_variant_dup_string (GVariant *value, } /** - * g_variant_new_byte_array: - * @array: a pointer to an array of bytes - * @length: the length of @array, or -1 - * @returns: a new floating #GVariant instance - * - * Constructs an array of bytes #GVariant from the given array of bytes. - * - * If @length is -1 then @array is taken to be a normal C string (in the - * sense that it is terminated by a nul character). The nul character - * is included in the array. If length is not -1 then it gives the - * length of @array which may then contain nul chracters with no special - * meaning. - * - * Since: 2.26 - **/ -GVariant * -g_variant_new_byte_array (gconstpointer array, - gssize length) -{ - if (length == -1) - { - const gchar *bytes = array; - - length = 0; - while (bytes[length++]); - } - - return g_variant_new_from_trusted (G_VARIANT_TYPE ("ay"), - array, length); -} - -/** - * g_variant_get_byte_array: - * @value: an array of bytes #GVariant - * @length: the length of the result, or %NULL - * @returns: a pointer to the byte data, or %NULL - * - * Gets the contents of an array of bytes #GVariant. - * - * If @length is non-%NULL then it points to a location at which to - * store the length of the array and nul bytes contained within the - * array have no special meaning. - * - * If @length is %NULL then the caller has no way to determine what the - * length of the returned data might be. In this case, the function - * ensures that the last byte of the array is a nul byte and, if it is - * not, returns %NULL instead. In this way, the caller is assured that - * any non-%NULL pointer that is returned will be nul-terminated. - * - * The return value remains valid as long as @value exists. - * - * Since: 2.26 - **/ -gconstpointer -g_variant_get_byte_array (GVariant *value, - gsize *length) -{ - gconstpointer data; - gsize size; - - TYPE_CHECK (value, G_VARIANT_TYPE ("ay"), NULL); - - data = g_variant_get_data (value); - size = g_variant_get_size (value); - - if (length == NULL) - { - const gchar *bytes = data; - - if (bytes[size - 1] != '\0') - return NULL; - } - else - *length = size; - - return data; -} - -/** * g_variant_new_strv: - * @strv: an array of strings + * @strv: (array length=length) (element-type utf8): an array of strings * @length: the length of @strv, or -1 - * @returns: a new floating #GVariant instance * * Constructs an array of strings #GVariant from the given array of * strings. * - * If @length is not -1 then it gives the maximum length of @strv. In - * any case, a %NULL pointer in @strv is taken as a terminator. + * If @length is -1 then @strv is %NULL-terminated. + * + * Returns: (transfer none): a new floating #GVariant instance * * Since: 2.24 **/ @@ -1270,15 +1528,14 @@ g_variant_new_strv (const gchar * const *strv, for (i = 0; i < length; i++) strings[i] = g_variant_ref_sink (g_variant_new_string (strv[i])); - return g_variant_new_from_children (G_VARIANT_TYPE ("as"), + return g_variant_new_from_children (G_VARIANT_TYPE_STRING_ARRAY, strings, length, TRUE); } /** * g_variant_get_strv: * @value: an array of strings #GVariant - * @length: the length of the result, or %NULL - * @returns: an array of constant strings + * @length: (out) (allow-none): the length of the result, or %NULL * * Gets the contents of an array of strings #GVariant. This call * makes a shallow copy; the return result should be released with @@ -1291,6 +1548,8 @@ g_variant_new_strv (const gchar * const *strv, * For an empty array, @length will be set to 0 and a pointer to a * %NULL pointer will be returned. * + * Returns: (array length=length zero-terminated=1) (transfer container): an array of constant strings + * * Since: 2.24 **/ const gchar ** @@ -1301,10 +1560,7 @@ g_variant_get_strv (GVariant *value, gsize n; gsize i; - g_return_val_if_fail (g_variant_is_of_type (value, G_VARIANT_TYPE ("as")) || - g_variant_is_of_type (value, G_VARIANT_TYPE ("ao")) || - g_variant_is_of_type (value, G_VARIANT_TYPE ("ag")), - NULL); + TYPE_CHECK (value, G_VARIANT_TYPE_STRING_ARRAY, NULL); g_variant_get_data (value); n = g_variant_n_children (value); @@ -1329,8 +1585,7 @@ g_variant_get_strv (GVariant *value, /** * g_variant_dup_strv: * @value: an array of strings #GVariant - * @length: the length of the result, or %NULL - * @returns: an array of constant strings + * @length: (out) (allow-none): the length of the result, or %NULL * * Gets the contents of an array of strings #GVariant. This call * makes a deep copy; the return result should be released with @@ -1343,6 +1598,8 @@ g_variant_get_strv (GVariant *value, * For an empty array, @length will be set to 0 and a pointer to a * %NULL pointer will be returned. * + * Returns: (array length=length zero-terminated=1) (transfer full): an array of strings + * * Since: 2.24 **/ gchar ** @@ -1353,10 +1610,7 @@ g_variant_dup_strv (GVariant *value, gsize n; gsize i; - g_return_val_if_fail (g_variant_is_of_type (value, G_VARIANT_TYPE ("as")) || - g_variant_is_of_type (value, G_VARIANT_TYPE ("ao")) || - g_variant_is_of_type (value, G_VARIANT_TYPE ("ag")), - NULL); + TYPE_CHECK (value, G_VARIANT_TYPE_STRING_ARRAY, NULL); n = g_variant_n_children (value); strv = g_new (gchar *, n + 1); @@ -1377,21 +1631,396 @@ g_variant_dup_strv (GVariant *value, return strv; } -/* Type checking and querying {{{1 */ /** - * g_variant_get_type: - * @value: a #GVariant - * @returns: a #GVariantType + * g_variant_new_objv: + * @strv: (array length=length) (element-type utf8): an array of strings + * @length: the length of @strv, or -1 * - * Determines the type of @value. + * Constructs an array of object paths #GVariant from the given array of + * strings. * - * The return value is valid for the lifetime of @value and must not - * be freed. + * Each string must be a valid #GVariant object path; see + * g_variant_is_object_path(). * - * Since: 2.24 + * If @length is -1 then @strv is %NULL-terminated. + * + * Returns: (transfer none): a new floating #GVariant instance + * + * Since: 2.30 **/ -const GVariantType * -g_variant_get_type (GVariant *value) +GVariant * +g_variant_new_objv (const gchar * const *strv, + gssize length) +{ + GVariant **strings; + gsize i; + + g_return_val_if_fail (length == 0 || strv != NULL, NULL); + + if (length < 0) + length = g_strv_length ((gchar **) strv); + + strings = g_new (GVariant *, length); + for (i = 0; i < length; i++) + strings[i] = g_variant_ref_sink (g_variant_new_object_path (strv[i])); + + return g_variant_new_from_children (G_VARIANT_TYPE_OBJECT_PATH_ARRAY, + strings, length, TRUE); +} + +/** + * g_variant_get_objv: + * @value: an array of object paths #GVariant + * @length: (out) (allow-none): the length of the result, or %NULL + * + * Gets the contents of an array of object paths #GVariant. This call + * makes a shallow copy; the return result should be released with + * g_free(), but the individual strings must not be modified. + * + * If @length is non-%NULL then the number of elements in the result + * is stored there. In any case, the resulting array will be + * %NULL-terminated. + * + * For an empty array, @length will be set to 0 and a pointer to a + * %NULL pointer will be returned. + * + * Returns: (array length=length zero-terminated=1) (transfer container): an array of constant strings + * + * Since: 2.30 + **/ +const gchar ** +g_variant_get_objv (GVariant *value, + gsize *length) +{ + const gchar **strv; + gsize n; + gsize i; + + TYPE_CHECK (value, G_VARIANT_TYPE_OBJECT_PATH_ARRAY, NULL); + + g_variant_get_data (value); + n = g_variant_n_children (value); + strv = g_new (const gchar *, n + 1); + + for (i = 0; i < n; i++) + { + GVariant *string; + + string = g_variant_get_child_value (value, i); + strv[i] = g_variant_get_string (string, NULL); + g_variant_unref (string); + } + strv[i] = NULL; + + if (length) + *length = n; + + return strv; +} + +/** + * g_variant_dup_objv: + * @value: an array of object paths #GVariant + * @length: (out) (allow-none): the length of the result, or %NULL + * + * Gets the contents of an array of object paths #GVariant. This call + * makes a deep copy; the return result should be released with + * g_strfreev(). + * + * If @length is non-%NULL then the number of elements in the result + * is stored there. In any case, the resulting array will be + * %NULL-terminated. + * + * For an empty array, @length will be set to 0 and a pointer to a + * %NULL pointer will be returned. + * + * Returns: (array length=length zero-terminated=1) (transfer full): an array of strings + * + * Since: 2.30 + **/ +gchar ** +g_variant_dup_objv (GVariant *value, + gsize *length) +{ + gchar **strv; + gsize n; + gsize i; + + TYPE_CHECK (value, G_VARIANT_TYPE_OBJECT_PATH_ARRAY, NULL); + + n = g_variant_n_children (value); + strv = g_new (gchar *, n + 1); + + for (i = 0; i < n; i++) + { + GVariant *string; + + string = g_variant_get_child_value (value, i); + strv[i] = g_variant_dup_string (string, NULL); + g_variant_unref (string); + } + strv[i] = NULL; + + if (length) + *length = n; + + return strv; +} + + +/** + * g_variant_new_bytestring: + * @string: (array zero-terminated=1) (element-type guint8): a normal + * nul-terminated string in no particular encoding + * + * Creates an array-of-bytes #GVariant with the contents of @string. + * This function is just like g_variant_new_string() except that the + * string need not be valid utf8. + * + * The nul terminator character at the end of the string is stored in + * the array. + * + * Returns: (transfer none): a floating reference to a new bytestring #GVariant instance + * + * Since: 2.26 + **/ +GVariant * +g_variant_new_bytestring (const gchar *string) +{ + g_return_val_if_fail (string != NULL, NULL); + + return g_variant_new_from_trusted (G_VARIANT_TYPE_BYTESTRING, + string, strlen (string) + 1); +} + +/** + * g_variant_get_bytestring: + * @value: an array-of-bytes #GVariant instance + * + * Returns the string value of a #GVariant instance with an + * array-of-bytes type. The string has no particular encoding. + * + * If the array does not end with a nul terminator character, the empty + * string is returned. For this reason, you can always trust that a + * non-%NULL nul-terminated string will be returned by this function. + * + * If the array contains a nul terminator character somewhere other than + * the last byte then the returned string is the string, up to the first + * such nul character. + * + * It is an error to call this function with a @value that is not an + * array of bytes. + * + * The return value remains valid as long as @value exists. + * + * Returns: (transfer none) (array zero-terminated=1) (element-type guint8): + * the constant string + * + * Since: 2.26 + **/ +const gchar * +g_variant_get_bytestring (GVariant *value) +{ + const gchar *string; + gsize size; + + TYPE_CHECK (value, G_VARIANT_TYPE_BYTESTRING, NULL); + + /* Won't be NULL since this is an array type */ + string = g_variant_get_data (value); + size = g_variant_get_size (value); + + if (size && string[size - 1] == '\0') + return string; + else + return ""; +} + +/** + * g_variant_dup_bytestring: + * @value: an array-of-bytes #GVariant instance + * @length: (out) (allow-none) (default NULL): a pointer to a #gsize, to store + * the length (not including the nul terminator) + * + * Similar to g_variant_get_bytestring() except that instead of + * returning a constant string, the string is duplicated. + * + * The return value must be freed using g_free(). + * + * Returns: (transfer full) (array zero-terminated=1 length=length) (element-type guint8): + * a newly allocated string + * + * Since: 2.26 + **/ +gchar * +g_variant_dup_bytestring (GVariant *value, + gsize *length) +{ + const gchar *original = g_variant_get_bytestring (value); + gsize size; + + /* don't crash in case get_bytestring() had an assert failure */ + if (original == NULL) + return NULL; + + size = strlen (original); + + if (length) + *length = size; + + return g_memdup (original, size + 1); +} + +/** + * g_variant_new_bytestring_array: + * @strv: (array length=length): an array of strings + * @length: the length of @strv, or -1 + * + * Constructs an array of bytestring #GVariant from the given array of + * strings. + * + * If @length is -1 then @strv is %NULL-terminated. + * + * Returns: (transfer none): a new floating #GVariant instance + * + * Since: 2.26 + **/ +GVariant * +g_variant_new_bytestring_array (const gchar * const *strv, + gssize length) +{ + GVariant **strings; + gsize i; + + g_return_val_if_fail (length == 0 || strv != NULL, NULL); + + if (length < 0) + length = g_strv_length ((gchar **) strv); + + strings = g_new (GVariant *, length); + for (i = 0; i < length; i++) + strings[i] = g_variant_ref_sink (g_variant_new_bytestring (strv[i])); + + return g_variant_new_from_children (G_VARIANT_TYPE_BYTESTRING_ARRAY, + strings, length, TRUE); +} + +/** + * g_variant_get_bytestring_array: + * @value: an array of array of bytes #GVariant ('aay') + * @length: (out) (allow-none): the length of the result, or %NULL + * + * Gets the contents of an array of array of bytes #GVariant. This call + * makes a shallow copy; the return result should be released with + * g_free(), but the individual strings must not be modified. + * + * If @length is non-%NULL then the number of elements in the result is + * stored there. In any case, the resulting array will be + * %NULL-terminated. + * + * For an empty array, @length will be set to 0 and a pointer to a + * %NULL pointer will be returned. + * + * Returns: (array length=length) (transfer container): an array of constant strings + * + * Since: 2.26 + **/ +const gchar ** +g_variant_get_bytestring_array (GVariant *value, + gsize *length) +{ + const gchar **strv; + gsize n; + gsize i; + + TYPE_CHECK (value, G_VARIANT_TYPE_BYTESTRING_ARRAY, NULL); + + g_variant_get_data (value); + n = g_variant_n_children (value); + strv = g_new (const gchar *, n + 1); + + for (i = 0; i < n; i++) + { + GVariant *string; + + string = g_variant_get_child_value (value, i); + strv[i] = g_variant_get_bytestring (string); + g_variant_unref (string); + } + strv[i] = NULL; + + if (length) + *length = n; + + return strv; +} + +/** + * g_variant_dup_bytestring_array: + * @value: an array of array of bytes #GVariant ('aay') + * @length: (out) (allow-none): the length of the result, or %NULL + * + * Gets the contents of an array of array of bytes #GVariant. This call + * makes a deep copy; the return result should be released with + * g_strfreev(). + * + * If @length is non-%NULL then the number of elements in the result is + * stored there. In any case, the resulting array will be + * %NULL-terminated. + * + * For an empty array, @length will be set to 0 and a pointer to a + * %NULL pointer will be returned. + * + * Returns: (array length=length) (transfer full): an array of strings + * + * Since: 2.26 + **/ +gchar ** +g_variant_dup_bytestring_array (GVariant *value, + gsize *length) +{ + gchar **strv; + gsize n; + gsize i; + + TYPE_CHECK (value, G_VARIANT_TYPE_BYTESTRING_ARRAY, NULL); + + g_variant_get_data (value); + n = g_variant_n_children (value); + strv = g_new (gchar *, n + 1); + + for (i = 0; i < n; i++) + { + GVariant *string; + + string = g_variant_get_child_value (value, i); + strv[i] = g_variant_dup_bytestring (string, NULL); + g_variant_unref (string); + } + strv[i] = NULL; + + if (length) + *length = n; + + return strv; +} + +/* Type checking and querying {{{1 */ +/** + * g_variant_get_type: + * @value: a #GVariant + * + * Determines the type of @value. + * + * The return value is valid for the lifetime of @value and must not + * be freed. + * + * Returns: a #GVariantType + * + * Since: 2.24 + **/ +const GVariantType * +g_variant_get_type (GVariant *value) { GVariantTypeInfo *type_info; @@ -1405,12 +2034,13 @@ g_variant_get_type (GVariant *value) /** * g_variant_get_type_string: * @value: a #GVariant - * @returns: the type string for the type of @value * * Returns the type string of @value. Unlike the result of calling * g_variant_type_peek_string(), this string is nul-terminated. This * string belongs to #GVariant and must not be freed. * + * Returns: the type string for the type of @value + * * Since: 2.24 **/ const gchar * @@ -1429,10 +2059,11 @@ g_variant_get_type_string (GVariant *value) * g_variant_is_of_type: * @value: a #GVariant instance * @type: a #GVariantType - * @returns: %TRUE if the type of @value matches @type * * Checks if a value has a type matching the provided type. * + * Returns: %TRUE if the type of @value matches @type + * * Since: 2.24 **/ gboolean @@ -1445,9 +2076,12 @@ g_variant_is_of_type (GVariant *value, /** * g_variant_is_container: * @value: a #GVariant instance - * @returns: %TRUE if @value is a container * * Checks if @value is a container. + * + * Returns: %TRUE if @value is a container + * + * Since: 2.24 */ gboolean g_variant_is_container (GVariant *value) @@ -1459,10 +2093,11 @@ g_variant_is_container (GVariant *value) /** * g_variant_classify: * @value: a #GVariant - * @returns: the #GVariantClass of @value * * Classifies @value according to its top-level type. * + * Returns: the #GVariantClass of @value + * * Since: 2.24 **/ /** @@ -1479,9 +2114,9 @@ g_variant_is_container (GVariant *value) * @G_VARIANT_CLASS_DOUBLE: The #GVariant is a double precision floating * point value. * @G_VARIANT_CLASS_STRING: The #GVariant is a normal string. - * @G_VARIANT_CLASS_OBJECT_PATH: The #GVariant is a DBus object path + * @G_VARIANT_CLASS_OBJECT_PATH: The #GVariant is a D-Bus object path * string. - * @G_VARIANT_CLASS_SIGNATURE: The #GVariant is a DBus signature string. + * @G_VARIANT_CLASS_SIGNATURE: The #GVariant is a D-Bus signature string. * @G_VARIANT_CLASS_VARIANT: The #GVariant is a variant. * @G_VARIANT_CLASS_MAYBE: The #GVariant is a maybe-typed value. * @G_VARIANT_CLASS_ARRAY: The #GVariant is an array. @@ -1501,19 +2136,23 @@ g_variant_classify (GVariant *value) } /* Pretty printer {{{1 */ +/* This function is not introspectable because if @string is NULL, + @returns is (transfer full), otherwise it is (transfer none), which + is not supported by GObjectIntrospection */ /** - * g_variant_print_string: + * g_variant_print_string: (skip) * @value: a #GVariant - * @string: a #GString, or %NULL + * @string: (allow-none) (default NULL): a #GString, or %NULL * @type_annotate: %TRUE if type information should be included in * the output - * @returns: a #GString containing the string * * Behaves as g_variant_print(), but operates on a #GString. * * If @string is non-%NULL then it is appended to and returned. Else, * a new empty #GString is allocated and it is returned. * + * Returns: a #GString containing the string + * * Since: 2.24 **/ GString * @@ -1570,6 +2209,45 @@ g_variant_print_string (GVariant *value, case G_VARIANT_CLASS_ARRAY: /* it's an array so the first character of the type string is 'a' * + * if the first two characters are 'ay' then it's a bytestring. + * under certain conditions we print those as strings. + */ + if (g_variant_get_type_string (value)[1] == 'y') + { + const gchar *str; + gsize size; + gsize i; + + /* first determine if it is a byte string. + * that's when there's a single nul character: at the end. + */ + str = g_variant_get_data (value); + size = g_variant_get_size (value); + + for (i = 0; i < size; i++) + if (str[i] == '\0') + break; + + /* first nul byte is the last byte -> it's a byte string. */ + if (i == size - 1) + { + gchar *escaped = g_strescape (str, NULL); + + /* use double quotes only if a ' is in the string */ + if (strchr (str, '\'')) + g_string_append_printf (string, "b\"%s\"", escaped); + else + g_string_append_printf (string, "b'%s'", escaped); + + g_free (escaped); + break; + } + + else + /* fall through and handle normally... */; + } + + /* * if the first two characters are 'a{' then it's an array of * dictionary entries (ie: a dictionary) so we print that * differently. @@ -1716,15 +2394,66 @@ g_variant_print_string (GVariant *value, case G_VARIANT_CLASS_STRING: { const gchar *str = g_variant_get_string (value, NULL); - gchar *escaped = g_strescape (str, NULL); + gunichar quote = strchr (str, '\'') ? '"' : '\''; - /* use double quotes only if a ' is in the string */ - if (strchr (str, '\'')) - g_string_append_printf (string, "\"%s\"", escaped); - else - g_string_append_printf (string, "'%s'", escaped); + g_string_append_c (string, quote); - g_free (escaped); + while (*str) + { + gunichar c = g_utf8_get_char (str); + + if (c == quote || c == '\\') + g_string_append_c (string, '\\'); + + if (g_unichar_isprint (c)) + g_string_append_unichar (string, c); + + else + { + g_string_append_c (string, '\\'); + if (c < 0x10000) + switch (c) + { + case '\a': + g_string_append_c (string, 'a'); + break; + + case '\b': + g_string_append_c (string, 'b'); + break; + + case '\f': + g_string_append_c (string, 'f'); + break; + + case '\n': + g_string_append_c (string, 'n'); + break; + + case '\r': + g_string_append_c (string, 'r'); + break; + + case '\t': + g_string_append_c (string, 't'); + break; + + case '\v': + g_string_append_c (string, 'v'); + break; + + default: + g_string_append_printf (string, "u%04x", c); + break; + } + else + g_string_append_printf (string, "U%08x", c); + } + + str = g_utf8_next_char (str); + } + + g_string_append_c (string, quote); } break; @@ -1835,12 +2564,17 @@ g_variant_print_string (GVariant *value, * @value: a #GVariant * @type_annotate: %TRUE if type information should be included in * the output - * @returns: a newly-allocated string holding the result. * * Pretty-prints @value in the format understood by g_variant_parse(). * + * The format is described [here][gvariant-text]. + * * If @type_annotate is %TRUE, then type information is included in * the output. + * + * Returns: (transfer full): a newly-allocated string holding the result. + * + * Since: 2.24 */ gchar * g_variant_print (GVariant *value, @@ -1853,8 +2587,7 @@ g_variant_print (GVariant *value, /* Hash, Equal, Compare {{{1 */ /** * g_variant_hash: - * @value: a basic #GVariant value as a #gconstpointer - * @returns: a hash value corresponding to @value + * @value: (type GVariant): a basic #GVariant value as a #gconstpointer * * Generates a hash value for a #GVariant instance. * @@ -1866,6 +2599,8 @@ g_variant_print (GVariant *value, * The type of @value is #gconstpointer only to allow use of this * function with #GHashTable. @value must be a #GVariant. * + * Returns: a hash value corresponding to @value + * * Since: 2.24 **/ guint @@ -1939,15 +2674,16 @@ g_variant_hash (gconstpointer value_) /** * g_variant_equal: - * @one: a #GVariant instance - * @two: a #GVariant instance - * @returns: %TRUE if @one and @two are equal + * @one: (type GVariant): a #GVariant instance + * @two: (type GVariant): a #GVariant instance * * Checks if @one and @two have the same type and value. * * The types of @one and @two are #gconstpointer only to allow use of * this function with #GHashTable. They must each be a #GVariant. * + * Returns: %TRUE if @one and @two are equal + * * Since: 2.24 **/ gboolean @@ -2004,11 +2740,8 @@ g_variant_equal (gconstpointer one, /** * g_variant_compare: - * @one: a basic-typed #GVariant instance - * @two: a #GVariant instance of the same type - * @returns: negative value if a < b; - * zero if a = b; - * positive value if a > b. + * @one: (type GVariant): a basic-typed #GVariant instance + * @two: (type GVariant): a #GVariant instance of the same type * * Compares @one and @two. * @@ -2022,7 +2755,7 @@ g_variant_equal (gconstpointer one, * * It is a programmer error to attempt to compare container values or * two values that have types that are not exactly equal. For example, - * you can not compare a 32-bit signed integer with a 32-bit unsigned + * you cannot compare a 32-bit signed integer with a 32-bit unsigned * integer. Also note that this function is not particularly * well-behaved when it comes to comparison of doubles; in particular, * the handling of incomparable values (ie: NaN) is undefined. @@ -2030,6 +2763,10 @@ g_variant_equal (gconstpointer one, * If you only require an equality comparison, g_variant_equal() is more * general. * + * Returns: negative value if a < b; + * zero if a = b; + * positive value if a > b. + * * Since: 2.26 **/ gint @@ -2043,6 +2780,10 @@ g_variant_compare (gconstpointer one, switch (g_variant_classify (a)) { + case G_VARIANT_CLASS_BOOLEAN: + return g_variant_get_boolean (a) - + g_variant_get_boolean (b); + case G_VARIANT_CLASS_BYTE: return ((gint) g_variant_get_byte (a)) - ((gint) g_variant_get_byte (b)); @@ -2081,8 +2822,8 @@ g_variant_compare (gconstpointer one, case G_VARIANT_CLASS_UINT64: { - guint64 a_val = g_variant_get_int32 (a); - guint64 b_val = g_variant_get_int32 (b); + guint64 a_val = g_variant_get_uint64 (a); + guint64 b_val = g_variant_get_uint64 (b); return (a_val == b_val) ? 0 : (a_val > b_val) ? 1 : -1; } @@ -2109,7 +2850,7 @@ g_variant_compare (gconstpointer one, /* GVariantIter {{{1 */ /** - * GVariantIter: + * GVariantIter: (skip) * * #GVariantIter is an opaque data structure and can only be accessed * using the following functions. @@ -2147,7 +2888,6 @@ struct heap_iter /** * g_variant_iter_new: * @value: a container #GVariant - * @returns: a new heap-allocated #GVariantIter * * Creates a heap-allocated #GVariantIter for iterating over the items * in @value. @@ -2158,6 +2898,8 @@ struct heap_iter * A reference is taken to @value and will be released only when * g_variant_iter_free() is called. * + * Returns: (transfer full): a new heap-allocated #GVariantIter + * * Since: 2.24 **/ GVariantIter * @@ -2175,10 +2917,9 @@ g_variant_iter_new (GVariant *value) } /** - * g_variant_iter_init: + * g_variant_iter_init: (skip) * @iter: a pointer to a #GVariantIter * @value: a container #GVariant - * @returns: the number of items in @value * * Initialises (without allocating) a #GVariantIter. @iter may be * completely uninitialised prior to this call; its old value is @@ -2187,6 +2928,8 @@ g_variant_iter_new (GVariant *value) * The iterator remains valid for as long as @value exists, and need not * be freed in any way. * + * Returns: the number of items in @value + * * Since: 2.24 **/ gsize @@ -2205,7 +2948,6 @@ g_variant_iter_init (GVariantIter *iter, /** * g_variant_iter_copy: * @iter: a #GVariantIter - * @returns: a new heap-allocated #GVariantIter * * Creates a new heap-allocated #GVariantIter to iterate over the * container that was being iterated over by @iter. Iteration begins on @@ -2218,6 +2960,8 @@ g_variant_iter_init (GVariantIter *iter, * A reference is taken to the container that @iter is iterating over * and will be releated only when g_variant_iter_free() is called. * + * Returns: (transfer full): a new heap-allocated #GVariantIter + * * Since: 2.24 **/ GVariantIter * @@ -2236,7 +2980,6 @@ g_variant_iter_copy (GVariantIter *iter) /** * g_variant_iter_n_children: * @iter: a #GVariantIter - * @returns: the number of children in the container * * Queries the number of child items in the container that we are * iterating over. This is the total number of items -- not the number @@ -2244,6 +2987,8 @@ g_variant_iter_copy (GVariantIter *iter) * * This function might be useful for preallocation of arrays. * + * Returns: the number of children in the container + * * Since: 2.24 **/ gsize @@ -2256,7 +3001,7 @@ g_variant_iter_n_children (GVariantIter *iter) /** * g_variant_iter_free: - * @iter: a heap-allocated #GVariantIter + * @iter: (transfer full): a heap-allocated #GVariantIter * * Frees a heap-allocated #GVariantIter. Only call this function on * iterators that were returned by g_variant_iter_new() or @@ -2278,7 +3023,6 @@ g_variant_iter_free (GVariantIter *iter) /** * g_variant_iter_next_value: * @iter: a #GVariantIter - * @returns: a #GVariant, or %NULL * * Gets the next item in the container. If no more items remain then * %NULL is returned. @@ -2286,17 +3030,16 @@ g_variant_iter_free (GVariantIter *iter) * Use g_variant_unref() to drop your reference on the return value when * you no longer need it. * - * - * Iterating with g_variant_iter_next_value() - * - * /* recursively iterate a container */ + * Here is an example for iterating with g_variant_iter_next_value(): + * |[ + * // recursively iterate a container * void * iterate_container_recursive (GVariant *container) * { * GVariantIter iter; * GVariant *child; * - * g_variant_iter_init (&iter, dictionary); + * g_variant_iter_init (&iter, container); * while ((child = g_variant_iter_next_value (&iter))) * { * g_print ("type '%s'\n", g_variant_get_type_string (child)); @@ -2307,8 +3050,9 @@ g_variant_iter_free (GVariantIter *iter) * g_variant_unref (child); * } * } - * - * + * ]| + * + * Returns: (allow-none) (transfer full): a #GVariant, or %NULL * * Since: 2.24 **/ @@ -2402,7 +3146,6 @@ struct heap_builder /** * g_variant_builder_new: * @type: a container type - * @returns: a #GVariantBuilder * * Allocates and initialises a new #GVariantBuilder. * @@ -2414,6 +3157,8 @@ struct heap_builder * the stack of the calling function and initialise it with * g_variant_builder_init(). * + * Returns: (transfer full): a #GVariantBuilder + * * Since: 2.24 **/ GVariantBuilder * @@ -2431,7 +3176,7 @@ g_variant_builder_new (const GVariantType *type) /** * g_variant_builder_unref: - * @builder: a #GVariantBuilder allocated by g_variant_builder_new() + * @builder: (transfer full): a #GVariantBuilder allocated by g_variant_builder_new() * * Decreases the reference count on @builder. * @@ -2460,13 +3205,14 @@ g_variant_builder_unref (GVariantBuilder *builder) /** * g_variant_builder_ref: * @builder: a #GVariantBuilder allocated by g_variant_builder_new() - * @returns: a new reference to @builder * * Increases the reference count on @builder. * * Don't call this on stack-allocated #GVariantBuilder instances or bad * things will happen. * + * Returns: (transfer full): a new reference to @builder + * * Since: 2.24 **/ GVariantBuilder * @@ -2480,7 +3226,7 @@ g_variant_builder_ref (GVariantBuilder *builder) } /** - * g_variant_builder_clear: + * g_variant_builder_clear: (skip) * @builder: a #GVariantBuilder * * Releases all memory associated with a #GVariantBuilder without @@ -2491,7 +3237,7 @@ g_variant_builder_ref (GVariantBuilder *builder) * through. This function need not be called if you call * g_variant_builder_end() and it also doesn't need to be called on * builders allocated with g_variant_builder_new (see - * g_variant_builder_free() for that). + * g_variant_builder_unref() for that). * * This function leaves the #GVariantBuilder structure set to all-zeros. * It is valid to call this function on either an initialised @@ -2528,7 +3274,7 @@ g_variant_builder_clear (GVariantBuilder *builder) } /** - * g_variant_builder_init: + * g_variant_builder_init: (skip) * @builder: a #GVariantBuilder * @type: a container type * @@ -2663,6 +3409,9 @@ g_variant_builder_make_room (struct stack_builder *builder) * types or number of items in a tuple, putting more than one value into * a variant, etc. * + * If @value is a floating reference (see g_variant_ref_sink()), + * the @builder instance takes ownership of @value. + * * Since: 2.24 **/ void @@ -2775,110 +3524,614 @@ g_variant_builder_close (GVariantBuilder *builder) g_variant_builder_add_value (parent, g_variant_builder_end (builder)); *builder = *parent; - g_slice_free (GVariantBuilder, parent); + g_slice_free (GVariantBuilder, parent); +} + +/*< private > + * g_variant_make_maybe_type: + * @element: a #GVariant + * + * Return the type of a maybe containing @element. + */ +static GVariantType * +g_variant_make_maybe_type (GVariant *element) +{ + return g_variant_type_new_maybe (g_variant_get_type (element)); +} + +/*< private > + * g_variant_make_array_type: + * @element: a #GVariant + * + * Return the type of an array containing @element. + */ +static GVariantType * +g_variant_make_array_type (GVariant *element) +{ + return g_variant_type_new_array (g_variant_get_type (element)); +} + +/** + * g_variant_builder_end: + * @builder: a #GVariantBuilder + * + * Ends the builder process and returns the constructed value. + * + * It is not permissible to use @builder in any way after this call + * except for reference counting operations (in the case of a + * heap-allocated #GVariantBuilder) or by reinitialising it with + * g_variant_builder_init() (in the case of stack-allocated). + * + * It is an error to call this function in any way that would create an + * inconsistent value to be constructed (ie: insufficient number of + * items added to a container with a specific number of children + * required). It is also an error to call this function if the builder + * was created with an indefinite array or maybe type and no children + * have been added; in this case it is impossible to infer the type of + * the empty array. + * + * Returns: (transfer none): a new, floating, #GVariant + * + * Since: 2.24 + **/ +GVariant * +g_variant_builder_end (GVariantBuilder *builder) +{ + GVariantType *my_type; + GVariant *value; + + g_return_val_if_fail (is_valid_builder (builder), NULL); + g_return_val_if_fail (GVSB(builder)->offset >= GVSB(builder)->min_items, + NULL); + g_return_val_if_fail (!GVSB(builder)->uniform_item_types || + GVSB(builder)->prev_item_type != NULL || + g_variant_type_is_definite (GVSB(builder)->type), + NULL); + + if (g_variant_type_is_definite (GVSB(builder)->type)) + my_type = g_variant_type_copy (GVSB(builder)->type); + + else if (g_variant_type_is_maybe (GVSB(builder)->type)) + my_type = g_variant_make_maybe_type (GVSB(builder)->children[0]); + + else if (g_variant_type_is_array (GVSB(builder)->type)) + my_type = g_variant_make_array_type (GVSB(builder)->children[0]); + + else if (g_variant_type_is_tuple (GVSB(builder)->type)) + my_type = g_variant_make_tuple_type (GVSB(builder)->children, + GVSB(builder)->offset); + + else if (g_variant_type_is_dict_entry (GVSB(builder)->type)) + my_type = g_variant_make_dict_entry_type (GVSB(builder)->children[0], + GVSB(builder)->children[1]); + else + g_assert_not_reached (); + + value = g_variant_new_from_children (my_type, + g_renew (GVariant *, + GVSB(builder)->children, + GVSB(builder)->offset), + GVSB(builder)->offset, + GVSB(builder)->trusted); + GVSB(builder)->children = NULL; + GVSB(builder)->offset = 0; + + g_variant_builder_clear (builder); + g_variant_type_free (my_type); + + return value; +} + +/* GVariantDict {{{1 */ + +/** + * GVariantDict: + * + * #GVariantDict is a mutable interface to #GVariant dictionaries. + * + * It can be used for doing a sequence of dictionary lookups in an + * efficient way on an existing #GVariant dictionary or it can be used + * to construct new dictionaries with a hashtable-like interface. It + * can also be used for taking existing dictionaries and modifying them + * in order to create new ones. + * + * #GVariantDict can only be used with %G_VARIANT_TYPE_VARDICT + * dictionaries. + * + * It is possible to use #GVariantDict allocated on the stack or on the + * heap. When using a stack-allocated #GVariantDict, you begin with a + * call to g_variant_dict_init() and free the resources with a call to + * g_variant_dict_clear(). + * + * Heap-allocated #GVariantDict follows normal refcounting rules: you + * allocate it with g_variant_dict_new() and use g_variant_dict_ref() + * and g_variant_dict_unref(). + * + * g_variant_dict_end() is used to convert the #GVariantDict back into a + * dictionary-type #GVariant. When used with stack-allocated instances, + * this also implicitly frees all associated memory, but for + * heap-allocated instances, you must still call g_variant_dict_unref() + * afterwards. + * + * You will typically want to use a heap-allocated #GVariantDict when + * you expose it as part of an API. For most other uses, the + * stack-allocated form will be more convenient. + * + * Consider the following two examples that do the same thing in each + * style: take an existing dictionary and look up the "count" uint32 + * key, adding 1 to it if it is found, or returning an error if the + * key is not found. Each returns the new dictionary as a floating + * #GVariant. + * + * ## Using a stack-allocated GVariantDict + * + * |[ + * GVariant * + * add_to_count (GVariant *orig, + * GError **error) + * { + * GVariantDict dict; + * guint32 count; + * + * g_variant_dict_init (&dict, orig); + * if (!g_variant_dict_lookup (&dict, "count", "u", &count)) + * { + * g_set_error (...); + * g_variant_dict_clear (&dict); + * return NULL; + * } + * + * g_variant_dict_insert (&dict, "count", "u", count + 1); + * + * return g_variant_dict_end (&dict); + * } + * ]| + * + * ## Using heap-allocated GVariantDict + * + * |[ + * GVariant * + * add_to_count (GVariant *orig, + * GError **error) + * { + * GVariantDict *dict; + * GVariant *result; + * guint32 count; + * + * dict = g_variant_dict_new (orig); + * + * if (g_variant_dict_lookup (dict, "count", "u", &count)) + * { + * g_variant_dict_insert (dict, "count", "u", count + 1); + * result = g_variant_dict_end (dict); + * } + * else + * { + * g_set_error (...); + * result = NULL; + * } + * + * g_variant_dict_unref (dict); + * + * return result; + * } + * ]| + * + * Since: 2.40 + **/ +struct stack_dict +{ + GHashTable *values; + gsize magic; +}; + +G_STATIC_ASSERT (sizeof (struct stack_dict) <= sizeof (GVariantDict)); + +struct heap_dict +{ + struct stack_dict dict; + gint ref_count; + gsize magic; +}; + +#define GVSD(d) ((struct stack_dict *) (d)) +#define GVHD(d) ((struct heap_dict *) (d)) +#define GVSD_MAGIC ((gsize) 2579507750u) +#define GVHD_MAGIC ((gsize) 2450270775u) +#define is_valid_dict(d) (d != NULL && \ + GVSD(d)->magic == GVSD_MAGIC) +#define is_valid_heap_dict(d) (GVHD(d)->magic == GVHD_MAGIC) + +/** + * g_variant_dict_new: + * @from_asv: (allow-none): the #GVariant with which to initialise the + * dictionary + * + * Allocates and initialises a new #GVariantDict. + * + * You should call g_variant_dict_unref() on the return value when it + * is no longer needed. The memory will not be automatically freed by + * any other call. + * + * In some cases it may be easier to place a #GVariantDict directly on + * the stack of the calling function and initialise it with + * g_variant_dict_init(). This is particularly useful when you are + * using #GVariantDict to construct a #GVariant. + * + * Returns: (transfer full): a #GVariantDict + * + * Since: 2.40 + **/ +GVariantDict * +g_variant_dict_new (GVariant *from_asv) +{ + GVariantDict *dict; + + dict = g_slice_alloc (sizeof (struct heap_dict)); + g_variant_dict_init (dict, from_asv); + GVHD(dict)->magic = GVHD_MAGIC; + GVHD(dict)->ref_count = 1; + + return dict; +} + +/** + * g_variant_dict_init: (skip) + * @dict: a #GVariantDict + * @from_asv: (allow-none): the initial value for @dict + * + * Initialises a #GVariantDict structure. + * + * If @from_asv is given, it is used to initialise the dictionary. + * + * This function completely ignores the previous contents of @dict. On + * one hand this means that it is valid to pass in completely + * uninitialised memory. On the other hand, this means that if you are + * initialising over top of an existing #GVariantDict you need to first + * call g_variant_dict_clear() in order to avoid leaking memory. + * + * You must not call g_variant_dict_ref() or g_variant_dict_unref() on a + * #GVariantDict that was initialised with this function. If you ever + * pass a reference to a #GVariantDict outside of the control of your + * own code then you should assume that the person receiving that + * reference may try to use reference counting; you should use + * g_variant_dict_new() instead of this function. + * + * Since: 2.40 + **/ +void +g_variant_dict_init (GVariantDict *dict, + GVariant *from_asv) +{ + GVariantIter iter; + gchar *key; + GVariant *value; + + GVSD(dict)->values = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, (GDestroyNotify) g_variant_unref); + GVSD(dict)->magic = GVSD_MAGIC; + + if (from_asv) + { + g_variant_iter_init (&iter, from_asv); + while (g_variant_iter_next (&iter, "{sv}", &key, &value)) + g_hash_table_insert (GVSD(dict)->values, key, value); + } +} + +/** + * g_variant_dict_lookup: + * @dict: a #GVariantDict + * @key: the key to lookup in the dictionary + * @format_string: a GVariant format string + * @...: the arguments to unpack the value into + * + * Looks up a value in a #GVariantDict. + * + * This function is a wrapper around g_variant_dict_lookup_value() and + * g_variant_get(). In the case that %NULL would have been returned, + * this function returns %FALSE. Otherwise, it unpacks the returned + * value and returns %TRUE. + * + * @format_string determines the C types that are used for unpacking the + * values and also determines if the values are copied or borrowed, see the + * section on [GVariant format strings][gvariant-format-strings-pointers]. + * + * Returns: %TRUE if a value was unpacked + * + * Since: 2.40 + **/ +gboolean +g_variant_dict_lookup (GVariantDict *dict, + const gchar *key, + const gchar *format_string, + ...) +{ + GVariant *value; + va_list ap; + + g_return_val_if_fail (is_valid_dict (dict), FALSE); + g_return_val_if_fail (key != NULL, FALSE); + g_return_val_if_fail (format_string != NULL, FALSE); + + value = g_hash_table_lookup (GVSD(dict)->values, key); + + if (value == NULL || !g_variant_check_format_string (value, format_string, FALSE)) + return FALSE; + + va_start (ap, format_string); + g_variant_get_va (value, format_string, NULL, &ap); + va_end (ap); + + return TRUE; +} + +/** + * g_variant_dict_lookup_value: + * @dict: a #GVariantDict + * @key: the key to lookup in the dictionary + * @expected_type: (allow-none): a #GVariantType, or %NULL + * + * Looks up a value in a #GVariantDict. + * + * If @key is not found in @dictionary, %NULL is returned. + * + * The @expected_type string specifies what type of value is expected. + * If the value associated with @key has a different type then %NULL is + * returned. + * + * If the key is found and the value has the correct type, it is + * returned. If @expected_type was specified then any non-%NULL return + * value will have this type. + * + * Returns: (transfer full): the value of the dictionary key, or %NULL + * + * Since: 2.40 + **/ +GVariant * +g_variant_dict_lookup_value (GVariantDict *dict, + const gchar *key, + const GVariantType *expected_type) +{ + GVariant *result; + + g_return_val_if_fail (is_valid_dict (dict), NULL); + g_return_val_if_fail (key != NULL, NULL); + + result = g_hash_table_lookup (GVSD(dict)->values, key); + + if (result && (!expected_type || g_variant_is_of_type (result, expected_type))) + return g_variant_ref (result); + + return NULL; +} + +/** + * g_variant_dict_contains: + * @dict: a #GVariantDict + * @key: the key to lookup in the dictionary + * + * Checks if @key exists in @dict. + * + * Returns: %TRUE if @key is in @dict + * + * Since: 2.40 + **/ +gboolean +g_variant_dict_contains (GVariantDict *dict, + const gchar *key) +{ + g_return_val_if_fail (is_valid_dict (dict), FALSE); + g_return_val_if_fail (key != NULL, FALSE); + + return g_hash_table_contains (GVSD(dict)->values, key); +} + +/** + * g_variant_dict_insert: + * @dict: a #GVariantDict + * @key: the key to insert a value for + * @format_string: a #GVariant varargs format string + * @...: arguments, as per @format_string + * + * Inserts a value into a #GVariantDict. + * + * This call is a convenience wrapper that is exactly equivalent to + * calling g_variant_new() followed by g_variant_dict_insert_value(). + * + * Since: 2.40 + **/ +void +g_variant_dict_insert (GVariantDict *dict, + const gchar *key, + const gchar *format_string, + ...) +{ + va_list ap; + + g_return_if_fail (is_valid_dict (dict)); + g_return_if_fail (key != NULL); + g_return_if_fail (format_string != NULL); + + va_start (ap, format_string); + g_variant_dict_insert_value (dict, key, g_variant_new_va (format_string, NULL, &ap)); + va_end (ap); +} + +/** + * g_variant_dict_insert_value: + * @dict: a #GVariantDict + * @key: the key to insert a value for + * @value: the value to insert + * + * Inserts (or replaces) a key in a #GVariantDict. + * + * @value is consumed if it is floating. + * + * Since: 2.40 + **/ +void +g_variant_dict_insert_value (GVariantDict *dict, + const gchar *key, + GVariant *value) +{ + g_return_if_fail (is_valid_dict (dict)); + g_return_if_fail (key != NULL); + g_return_if_fail (value != NULL); + + g_hash_table_insert (GVSD(dict)->values, g_strdup (key), g_variant_ref_sink (value)); } -/*< private > - * g_variant_make_maybe_type: - * @element: a #GVariant +/** + * g_variant_dict_remove: + * @dict: a #GVariantDict + * @key: the key to remove * - * Return the type of a maybe containing @element. - */ -static GVariantType * -g_variant_make_maybe_type (GVariant *element) + * Removes a key and its associated value from a #GVariantDict. + * + * Returns: %TRUE if the key was found and removed + * + * Since: 2.40 + **/ +gboolean +g_variant_dict_remove (GVariantDict *dict, + const gchar *key) { - return g_variant_type_new_maybe (g_variant_get_type (element)); + g_return_val_if_fail (is_valid_dict (dict), FALSE); + g_return_val_if_fail (key != NULL, FALSE); + + return g_hash_table_remove (GVSD(dict)->values, key); } -/*< private > - * g_variant_make_array_type: - * @element: a #GVariant +/** + * g_variant_dict_clear: + * @dict: a #GVariantDict * - * Return the type of an array containing @element. - */ -static GVariantType * -g_variant_make_array_type (GVariant *element) + * Releases all memory associated with a #GVariantDict without freeing + * the #GVariantDict structure itself. + * + * It typically only makes sense to do this on a stack-allocated + * #GVariantDict if you want to abort building the value part-way + * through. This function need not be called if you call + * g_variant_dict_end() and it also doesn't need to be called on dicts + * allocated with g_variant_dict_new (see g_variant_dict_unref() for + * that). + * + * It is valid to call this function on either an initialised + * #GVariantDict or one that was previously cleared by an earlier call + * to g_variant_dict_clear() but it is not valid to call this function + * on uninitialised memory. + * + * Since: 2.40 + **/ +void +g_variant_dict_clear (GVariantDict *dict) { - return g_variant_type_new_array (g_variant_get_type (element)); + if (GVSD(dict)->magic == 0) + /* all-zeros case */ + return; + + g_return_if_fail (is_valid_dict (dict)); + + g_hash_table_unref (GVSD(dict)->values); + GVSD(dict)->values = NULL; + + GVSD(dict)->magic = 0; } /** - * g_variant_builder_end: - * @builder: a #GVariantBuilder - * @returns: a new, floating, #GVariant + * g_variant_dict_end: + * @dict: a #GVariantDict * - * Ends the builder process and returns the constructed value. + * Returns the current value of @dict as a #GVariant of type + * %G_VARIANT_TYPE_VARDICT, clearing it in the process. * - * It is not permissible to use @builder in any way after this call - * except for reference counting operations (in the case of a - * heap-allocated #GVariantBuilder) or by reinitialising it with - * g_variant_builder_init() (in the case of stack-allocated). + * It is not permissible to use @dict in any way after this call except + * for reference counting operations (in the case of a heap-allocated + * #GVariantDict) or by reinitialising it with g_variant_dict_init() (in + * the case of stack-allocated). * - * It is an error to call this function in any way that would create an - * inconsistent value to be constructed (ie: insufficient number of - * items added to a container with a specific number of children - * required). It is also an error to call this function if the builder - * was created with an indefinite array or maybe type and no children - * have been added; in this case it is impossible to infer the type of - * the empty array. + * Returns: (transfer none): a new, floating, #GVariant * - * Since: 2.24 + * Since: 2.40 **/ GVariant * -g_variant_builder_end (GVariantBuilder *builder) +g_variant_dict_end (GVariantDict *dict) { - GVariantType *my_type; - GVariant *value; + GVariantBuilder builder; + GHashTableIter iter; + gpointer key, value; - g_return_val_if_fail (is_valid_builder (builder), NULL); - g_return_val_if_fail (GVSB(builder)->offset >= GVSB(builder)->min_items, - NULL); - g_return_val_if_fail (!GVSB(builder)->uniform_item_types || - GVSB(builder)->prev_item_type != NULL || - g_variant_type_is_definite (GVSB(builder)->type), - NULL); + g_return_val_if_fail (is_valid_dict (dict), NULL); - if (g_variant_type_is_definite (GVSB(builder)->type)) - my_type = g_variant_type_copy (GVSB(builder)->type); + g_variant_builder_init (&builder, G_VARIANT_TYPE_VARDICT); - else if (g_variant_type_is_maybe (GVSB(builder)->type)) - my_type = g_variant_make_maybe_type (GVSB(builder)->children[0]); + g_hash_table_iter_init (&iter, GVSD(dict)->values); + while (g_hash_table_iter_next (&iter, &key, &value)) + g_variant_builder_add (&builder, "{sv}", (const gchar *) key, (GVariant *) value); - else if (g_variant_type_is_array (GVSB(builder)->type)) - my_type = g_variant_make_array_type (GVSB(builder)->children[0]); + g_variant_dict_clear (dict); - else if (g_variant_type_is_tuple (GVSB(builder)->type)) - my_type = g_variant_make_tuple_type (GVSB(builder)->children, - GVSB(builder)->offset); + return g_variant_builder_end (&builder); +} - else if (g_variant_type_is_dict_entry (GVSB(builder)->type)) - my_type = g_variant_make_dict_entry_type (GVSB(builder)->children[0], - GVSB(builder)->children[1]); - else - g_assert_not_reached (); +/** + * g_variant_dict_ref: + * @dict: a heap-allocated #GVariantDict + * + * Increases the reference count on @dict. + * + * Don't call this on stack-allocated #GVariantDict instances or bad + * things will happen. + * + * Returns: (transfer full): a new reference to @dict + * + * Since: 2.40 + **/ +GVariantDict * +g_variant_dict_ref (GVariantDict *dict) +{ + g_return_val_if_fail (is_valid_heap_dict (dict), NULL); - value = g_variant_new_from_children (my_type, - g_renew (GVariant *, - GVSB(builder)->children, - GVSB(builder)->offset), - GVSB(builder)->offset, - GVSB(builder)->trusted); - GVSB(builder)->children = NULL; - GVSB(builder)->offset = 0; + GVHD(dict)->ref_count++; - g_variant_builder_clear (builder); - g_variant_type_free (my_type); + return dict; +} - return value; +/** + * g_variant_dict_unref: + * @dict: (transfer full): a heap-allocated #GVariantDict + * + * Decreases the reference count on @dict. + * + * In the event that there are no more references, releases all memory + * associated with the #GVariantDict. + * + * Don't call this on stack-allocated #GVariantDict instances or bad + * things will happen. + * + * Since: 2.40 + **/ +void +g_variant_dict_unref (GVariantDict *dict) +{ + g_return_if_fail (is_valid_heap_dict (dict)); + + if (--GVHD(dict)->ref_count == 0) + { + g_variant_dict_clear (dict); + g_slice_free (struct heap_dict, (struct heap_dict *) dict); + } } + /* Format strings {{{1 */ /*< private > * g_variant_format_string_scan: * @string: a string that may be prefixed with a format string - * @limit: a pointer to the end of @string, or %NULL - * @endptr: location to store the end pointer, or %NULL - * @returns: %TRUE if there was a valid format string + * @limit: (allow-none) (default NULL): a pointer to the end of @string, + * or %NULL + * @endptr: (allow-none) (default NULL): location to store the end pointer, + * or %NULL * * Checks the string pointed to by @string for starting with a properly * formed #GVariant varargs format string. If no valid format string is @@ -2892,8 +4145,9 @@ g_variant_builder_end (GVariantBuilder *builder) * not be accessed and the effect is otherwise equivalent to if the * character at @limit were nul. * - * See the section on GVariant - * Format Strings. + * See the section on [GVariant format strings][gvariant-format-strings]. + * + * Returns: %TRUE if there was a valid format string * * Since: 2.24 */ @@ -2959,19 +4213,43 @@ g_variant_format_string_scan (const gchar *string, break; - case '^': /* '^as' or '^a&s' only */ - if (next_char() != 'a') - return FALSE; + case '^': + if ((c = next_char()) == 'a') + { + if ((c = next_char()) == '&') + { + if ((c = next_char()) == 'a') + { + if ((c = next_char()) == 'y') + break; /* '^a&ay' */ + } + + else if (c == 's' || c == 'o') + break; /* '^a&s', '^a&o' */ + } - if (peek_char() == '&') - next_char (); + else if (c == 'a') + { + if ((c = next_char()) == 'y') + break; /* '^aay' */ + } - c = next_char (); + else if (c == 's' || c == 'o') + break; /* '^as', '^ao' */ - if (c != 's' && c != 'o' && c != 'g') - return FALSE; + else if (c == 'y') + break; /* '^ay' */ + } + else if (c == '&') + { + if ((c = next_char()) == 'a') + { + if ((c = next_char()) == 'y') + break; /* '^&ay' */ + } + } - break; + return FALSE; case '&': c = next_char(); @@ -2994,12 +4272,117 @@ g_variant_format_string_scan (const gchar *string, return TRUE; } +/** + * g_variant_check_format_string: + * @value: a #GVariant + * @format_string: a valid #GVariant format string + * @copy_only: %TRUE to ensure the format string makes deep copies + * + * Checks if calling g_variant_get() with @format_string on @value would + * be valid from a type-compatibility standpoint. @format_string is + * assumed to be a valid format string (from a syntactic standpoint). + * + * If @copy_only is %TRUE then this function additionally checks that it + * would be safe to call g_variant_unref() on @value immediately after + * the call to g_variant_get() without invalidating the result. This is + * only possible if deep copies are made (ie: there are no pointers to + * the data inside of the soon-to-be-freed #GVariant instance). If this + * check fails then a g_critical() is printed and %FALSE is returned. + * + * This function is meant to be used by functions that wish to provide + * varargs accessors to #GVariant values of uncertain values (eg: + * g_variant_lookup() or g_menu_model_get_item_attribute()). + * + * Returns: %TRUE if @format_string is safe to use + * + * Since: 2.34 + */ +gboolean +g_variant_check_format_string (GVariant *value, + const gchar *format_string, + gboolean copy_only) +{ + const gchar *original_format = format_string; + const gchar *type_string; + + /* Interesting factoid: assuming a format string is valid, it can be + * converted to a type string by removing all '@' '&' and '^' + * characters. + * + * Instead of doing that, we can just skip those characters when + * comparing it to the type string of @value. + * + * For the copy-only case we can just drop the '&' from the list of + * characters to skip over. A '&' will never appear in a type string + * so we know that it won't be possible to return %TRUE if it is in a + * format string. + */ + type_string = g_variant_get_type_string (value); + + while (*type_string || *format_string) + { + gchar format = *format_string++; + + switch (format) + { + case '&': + if G_UNLIKELY (copy_only) + { + /* for the love of all that is good, please don't mark this string for translation... */ + g_critical ("g_variant_check_format_string() is being called by a function with a GVariant varargs " + "interface to validate the passed format string for type safety. The passed format " + "(%s) contains a '&' character which would result in a pointer being returned to the " + "data inside of a GVariant instance that may no longer exist by the time the function " + "returns. Modify your code to use a format string without '&'.", original_format); + return FALSE; + } + + /* fall through */ + case '^': + case '@': + /* ignore these 2 (or 3) */ + continue; + + case '?': + /* attempt to consume one of 'bynqiuxthdsog' */ + { + char s = *type_string++; + + if (s == '\0' || strchr ("bynqiuxthdsog", s) == NULL) + return FALSE; + } + continue; + + case 'r': + /* ensure it's a tuple */ + if (*type_string != '(') + return FALSE; + + /* fall through */ + case '*': + /* consume a full type string for the '*' or 'r' */ + if (!g_variant_type_string_scan (type_string, NULL, &type_string)) + return FALSE; + + continue; + + default: + /* attempt to consume exactly one character equal to the format */ + if (format != *type_string++) + return FALSE; + } + } + + return TRUE; +} + /*< private > * g_variant_format_string_scan_type: * @string: a string that may be prefixed with a format string - * @limit: a pointer to the end of @string - * @endptr: location to store the end pointer, or %NULL - * @returns: a #GVariantType if there was a valid format string + * @limit: (allow-none) (default NULL): a pointer to the end of @string, + * or %NULL + * @endptr: (allow-none) (default NULL): location to store the end pointer, + * or %NULL * * If @string starts with a valid format string then this function will * return the type that the format string corresponds to. Otherwise @@ -3011,6 +4394,8 @@ g_variant_format_string_scan (const gchar *string, * This function is otherwise exactly like * g_variant_format_string_scan(). * + * Returns: (allow-none): a #GVariantType if there was a valid format string + * * Since: 2.24 */ GVariantType * @@ -3053,10 +4438,10 @@ valid_format_string (const gchar *format_string, if G_UNLIKELY (type == NULL || (single && *endptr != '\0')) { if (single) - g_critical ("`%s' is not a valid GVariant format string", + g_critical ("'%s' is not a valid GVariant format string", format_string); else - g_critical ("`%s' does not have a valid GVariant format " + g_critical ("'%s' does not have a valid GVariant format " "string as a prefix", format_string); if (type != NULL) @@ -3073,11 +4458,13 @@ valid_format_string (const gchar *format_string, fragment = g_strndup (format_string, endptr - format_string); typestr = g_variant_type_dup_string (type); - g_critical ("the GVariant format string `%s' has a type of " - "`%s' but the given value has a type of `%s'", + g_critical ("the GVariant format string '%s' has a type of " + "'%s' but the given value has a type of '%s'", fragment, typestr, g_variant_get_type_string (value)); g_variant_type_free (type); + g_free (fragment); + g_free (typestr); return FALSE; } @@ -3157,9 +4544,9 @@ g_variant_valist_free_nnp (const gchar *str, break; case '^': - if (str[2] != '&') /* '^as' */ + if (str[2] != '&') /* '^as', '^ao' */ g_strfreev (ptr); - else /* '^a&s' */ + else /* '^a&s', '^a&o' */ g_free (ptr); break; @@ -3184,6 +4571,29 @@ g_variant_valist_free_nnp (const gchar *str, } } +static gchar +g_variant_scan_convenience (const gchar **str, + gboolean *constant, + guint *arrays) +{ + *constant = FALSE; + *arrays = 0; + + for (;;) + { + char c = *(*str)++; + + if (c == '&') + *constant = TRUE; + + else if (c == 'a') + (*arrays)++; + + else + return c; + } +} + static GVariant * g_variant_valist_new_nnp (const gchar **str, gpointer ptr) @@ -3194,33 +4604,58 @@ g_variant_valist_new_nnp (const gchar **str, switch (*(*str)++) { case 'a': - { - const GVariantType *type; - GVariant *value; + if (ptr != NULL) + { + const GVariantType *type; + GVariant *value; - value = g_variant_builder_end (ptr); - type = g_variant_get_type (value); + value = g_variant_builder_end (ptr); + type = g_variant_get_type (value); - if G_UNLIKELY (!g_variant_type_is_array (type)) - g_error ("g_variant_new: expected array GVariantBuilder but " - "the built value has type `%s'", - g_variant_get_type_string (value)); + if G_UNLIKELY (!g_variant_type_is_array (type)) + g_error ("g_variant_new: expected array GVariantBuilder but " + "the built value has type '%s'", + g_variant_get_type_string (value)); - type = g_variant_type_element (type); + type = g_variant_type_element (type); - if G_UNLIKELY (!g_variant_type_is_subtype_of (type, (GVariantType *) *str)) - g_error ("g_variant_new: expected GVariantBuilder array element " - "type `%s' but the built value has element type `%s'", - g_variant_type_dup_string ((GVariantType *) *str), - g_variant_get_type_string (value) + 1); + if G_UNLIKELY (!g_variant_type_is_subtype_of (type, (GVariantType *) *str)) + g_error ("g_variant_new: expected GVariantBuilder array element " + "type '%s' but the built value has element type '%s'", + g_variant_type_dup_string ((GVariantType *) *str), + g_variant_get_type_string (value) + 1); - g_variant_type_string_scan (*str, NULL, str); + g_variant_type_string_scan (*str, NULL, str); - return value; - } + return value; + } + else + + /* special case: NULL pointer for empty array */ + { + const GVariantType *type = (GVariantType *) *str; + + g_variant_type_string_scan (*str, NULL, str); + + if G_UNLIKELY (!g_variant_type_is_definite (type)) + g_error ("g_variant_new: NULL pointer given with indefinite " + "array type; unable to determine which type of empty " + "array to construct."); + + return g_variant_new_array (type, NULL, 0); + } case 's': - return g_variant_new_string (ptr); + { + GVariant *value; + + value = g_variant_new_string (ptr); + + if (value == NULL) + value = g_variant_new_string ("[Invalid UTF-8]"); + + return value; + } case 'o': return g_variant_new_object_path (ptr); @@ -3230,37 +4665,28 @@ g_variant_valist_new_nnp (const gchar **str, case '^': { - const GVariantType *type; - GVariantType *array_type; - GVariant **children; - gchar **strv = ptr; - GVariant *value; - guint length, i; + gboolean constant; + guint arrays; + gchar type; - if ((*str)[1] == '&') /* '^a&s' */ - (*str) += 2; - else /* '^as' */ - (*str)++; + type = g_variant_scan_convenience (str, &constant, &arrays); - type = (GVariantType *) (*str)++; - array_type = g_variant_type_new_array (type); - length = g_strv_length (strv); - children = g_new (GVariant *, length); - for (i = 0; i < length; i++) - children[i] = g_variant_ref_sink ( - g_variant_new_from_trusted (type, strv[i], strlen (strv[i]) + 1)); + if (type == 's') + return g_variant_new_strv (ptr, -1); - value = g_variant_new_from_children (array_type, children, - length, TRUE); - g_variant_type_free (array_type); + if (type == 'o') + return g_variant_new_objv (ptr, -1); - return value; + if (arrays > 1) + return g_variant_new_bytestring_array (ptr, -1); + + return g_variant_new_bytestring (ptr); } case '@': if G_UNLIKELY (!g_variant_is_of_type (ptr, (GVariantType *) *str)) - g_error ("g_variant_new: expected GVariant of type `%s' but " - "received value has type `%s'", + g_error ("g_variant_new: expected GVariant of type '%s' but " + "received value has type '%s'", g_variant_type_dup_string ((GVariantType *) *str), g_variant_get_type_string (ptr)); @@ -3273,16 +4699,16 @@ g_variant_valist_new_nnp (const gchar **str, case '?': if G_UNLIKELY (!g_variant_type_is_basic (g_variant_get_type (ptr))) - g_error ("g_variant_new: format string `?' expects basic-typed " - "GVariant, but received value has type `%s'", + g_error ("g_variant_new: format string '?' expects basic-typed " + "GVariant, but received value has type '%s'", g_variant_get_type_string (ptr)); return ptr; case 'r': if G_UNLIKELY (!g_variant_type_is_tuple (g_variant_get_type (ptr))) - g_error ("g_variant_new: format string `r` expects tuple-typed " - "GVariant, but received value has type `%s'", + g_error ("g_variant_new: format string 'r' expects tuple-typed " + "GVariant, but received value has type '%s'", g_variant_get_type_string (ptr)); return ptr; @@ -3315,16 +4741,45 @@ g_variant_valist_get_nnp (const gchar **str, return g_variant_dup_string (value, NULL); case '^': - if ((*str)[1] == '&') /* '^a&s' */ - { - (*str) += 3; - return g_variant_get_strv (value, NULL); - } - else /* '^as' */ - { - (*str) += 2; - return g_variant_dup_strv (value, NULL); - } + { + gboolean constant; + guint arrays; + gchar type; + + type = g_variant_scan_convenience (str, &constant, &arrays); + + if (type == 's') + { + if (constant) + return g_variant_get_strv (value, NULL); + else + return g_variant_dup_strv (value, NULL); + } + + else if (type == 'o') + { + if (constant) + return g_variant_get_objv (value, NULL); + else + return g_variant_dup_objv (value, NULL); + } + + else if (arrays > 1) + { + if (constant) + return g_variant_get_bytestring_array (value, NULL); + else + return g_variant_dup_bytestring_array (value, NULL); + } + + else + { + if (constant) + return (gchar *) g_variant_get_bytestring (value); + else + return g_variant_dup_bytestring (value, NULL); + } + } case '@': g_variant_type_string_scan (*str, NULL, str); @@ -3681,25 +5136,41 @@ g_variant_valist_get (const gchar **str, /* User-facing API {{{2 */ /** - * g_variant_new: + * g_variant_new: (skip) * @format_string: a #GVariant format string * @...: arguments, as per @format_string - * @returns: a new floating #GVariant instance * * Creates a new #GVariant instance. * * Think of this function as an analogue to g_strdup_printf(). * - * The type of the created instance and the arguments that are - * expected by this function are determined by @format_string. See the - * section on GVariant Format - * Strings. Please note that the syntax of the format string is - * very likely to be extended in the future. + * The type of the created instance and the arguments that are expected + * by this function are determined by @format_string. See the section on + * [GVariant format strings][gvariant-format-strings]. Please note that + * the syntax of the format string is very likely to be extended in the + * future. * * The first character of the format string must not be '*' '?' '@' or * 'r'; in essence, a new #GVariant must always be constructed by this * function (and not merely passed through it unmodified). * + * Note that the arguments must be of the correct width for their types + * specified in @format_string. This can be achieved by casting them. See + * the [GVariant varargs documentation][gvariant-varargs]. + * + * |[ + * MyFlags some_flags = FLAG_ONE | FLAG_TWO; + * const gchar *some_strings[] = { "a", "b", "c", NULL }; + * GVariant *new_variant; + * + * new_variant = g_variant_new ("(t^as)", + * /* This cast is required. */ + * (guint64) some_flags, + * some_strings); + * ]| + * + * Returns: a new floating #GVariant instance + * * Since: 2.24 **/ GVariant * @@ -3722,11 +5193,11 @@ g_variant_new (const gchar *format_string, } /** - * g_variant_new_va: + * g_variant_new_va: (skip) * @format_string: a string that is prefixed with a format string - * @endptr: location to store the end pointer, or %NULL + * @endptr: (allow-none) (default NULL): location to store the end pointer, + * or %NULL * @app: a pointer to a #va_list - * @returns: a new, usually floating, #GVariant * * This function is intended to be used by libraries based on * #GVariant that want to provide g_variant_new()-like functionality @@ -3744,6 +5215,10 @@ g_variant_new (const gchar *format_string, * @format_string, are collected from this #va_list and the list is left * pointing to the argument following the last. * + * Note that the arguments in @app must be of the correct width for their + * types specified in @format_string when collected into the #va_list. + * See the [GVariant varargs documentation][gvariant-varargs. + * * These two generalisations allow mixing of multiple calls to * g_variant_new_va() and g_variant_get_va() within a single actual * varargs call by the user. @@ -3761,6 +5236,8 @@ g_variant_new (const gchar *format_string, * result. This can also be done by adding the result to a container, * or by passing it to another g_variant_new() call. * + * Returns: a new, usually floating, #GVariant + * * Since: 2.24 **/ GVariant * @@ -3783,7 +5260,7 @@ g_variant_new_va (const gchar *format_string, } /** - * g_variant_get: + * g_variant_get: (skip) * @value: a #GVariant instance * @format_string: a #GVariant format string * @...: arguments, as per @format_string @@ -3795,11 +5272,16 @@ g_variant_new_va (const gchar *format_string, * The arguments that are expected by this function are entirely * determined by @format_string. @format_string also restricts the * permissible types of @value. It is an error to give a value with - * an incompatible type. See the section on GVariant Format Strings. + * an incompatible type. See the section on + * [GVariant format strings][gvariant-format-strings]. * Please note that the syntax of the format string is very likely to be * extended in the future. * + * @format_string determines the C types that are used for unpacking + * the values and also determines if the values are copied or borrowed, + * see the section on + * [GVariant format strings][gvariant-format-strings-pointers]. + * * Since: 2.24 **/ void @@ -3821,10 +5303,11 @@ g_variant_get (GVariant *value, } /** - * g_variant_get_va: + * g_variant_get_va: (skip) * @value: a #GVariant * @format_string: a string that is prefixed with a format string - * @endptr: location to store the end pointer, or %NULL + * @endptr: (allow-none) (default NULL): location to store the end pointer, + * or %NULL * @app: a pointer to a #va_list * * This function is intended to be used by libraries based on #GVariant @@ -3847,6 +5330,11 @@ g_variant_get (GVariant *value, * g_variant_new_va() and g_variant_get_va() within a single actual * varargs call by the user. * + * @format_string determines the C types that are used for unpacking + * the values and also determines if the values are copied or borrowed, + * see the section on + * [GVariant format strings][gvariant-format-strings-pointers]. + * * Since: 2.24 **/ void @@ -3872,7 +5360,7 @@ g_variant_get_va (GVariant *value, /* Varargs-enabled Utility Functions {{{1 */ /** - * g_variant_builder_add: + * g_variant_builder_add: (skip) * @builder: a #GVariantBuilder * @format_string: a #GVariant varargs format string * @...: arguments, as per @format_string @@ -3882,31 +5370,34 @@ g_variant_get_va (GVariant *value, * This call is a convenience wrapper that is exactly equivalent to * calling g_variant_new() followed by g_variant_builder_add_value(). * + * Note that the arguments must be of the correct width for their types + * specified in @format_string. This can be achieved by casting them. See + * the [GVariant varargs documentation][gvariant-varargs]. + * * This function might be used as follows: * - * + * |[ * GVariant * * make_pointless_dictionary (void) * { - * GVariantBuilder *builder; + * GVariantBuilder builder; * int i; * - * builder = g_variant_builder_new (G_VARIANT_TYPE_CLASS_ARRAY, - * NULL); + * g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY); * for (i = 0; i < 16; i++) * { * gchar buf[3]; * * sprintf (buf, "%d", i); - * g_variant_builder_add (builder, "{is}", i, buf); + * g_variant_builder_add (&builder, "{is}", i, buf); * } * - * return g_variant_builder_end (builder); + * return g_variant_builder_end (&builder); * } - * + * ]| * * Since: 2.24 - **/ + */ void g_variant_builder_add (GVariantBuilder *builder, const gchar *format_string, @@ -3923,7 +5414,7 @@ g_variant_builder_add (GVariantBuilder *builder, } /** - * g_variant_get_child: + * g_variant_get_child: (skip) * @value: a container #GVariant * @index_: the index of the child to deconstruct * @format_string: a #GVariant format string @@ -3934,6 +5425,11 @@ g_variant_builder_add (GVariantBuilder *builder, * essentially a combination of g_variant_get_child_value() and * g_variant_get(). * + * @format_string determines the C types that are used for unpacking + * the values and also determines if the values are copied or borrowed, + * see the section on + * [GVariant format strings][gvariant-format-strings-pointers]. + * * Since: 2.24 **/ void @@ -3956,12 +5452,10 @@ g_variant_get_child (GVariant *value, } /** - * g_variant_iter_next: + * g_variant_iter_next: (skip) * @iter: a #GVariantIter * @format_string: a GVariant format string * @...: the arguments to unpack the value into - * @returns: %TRUE if a value was unpacked, or %FALSE if there as no - * value * * Gets the next item in the container and unpacks it into the variable * argument list according to @format_string, returning %TRUE. @@ -3973,10 +5467,9 @@ g_variant_get_child (GVariant *value, * responsibility of the caller to free all of the values returned by * the unpacking process. * - * - * Memory management with g_variant_iter_next() - * - * /* Iterates a dictionary of type 'a{sv}' */ + * Here is an example for memory management with g_variant_iter_next(): + * |[ + * // Iterates a dictionary of type 'a{sv}' * void * iterate_dictionary (GVariant *dictionary) * { @@ -3990,17 +5483,24 @@ g_variant_get_child (GVariant *value, * g_print ("Item '%s' has type '%s'\n", key, * g_variant_get_type_string (value)); * - * /* must free data for ourselves */ + * // must free data for ourselves * g_variant_unref (value); * g_free (key); * } * } - * - * + * ]| * * For a solution that is likely to be more convenient to C programmers * when dealing with loops, see g_variant_iter_loop(). * + * @format_string determines the C types that are used for unpacking + * the values and also determines if the values are copied or borrowed. + * + * See the section on + * [GVariant format strings][gvariant-format-strings-pointers]. + * + * Returns: %TRUE if a value was unpacked, or %FALSE if there as no value + * * Since: 2.24 **/ gboolean @@ -4030,12 +5530,10 @@ g_variant_iter_next (GVariantIter *iter, } /** - * g_variant_iter_loop: + * g_variant_iter_loop: (skip) * @iter: a #GVariantIter * @format_string: a GVariant format string * @...: the arguments to unpack the value into - * @returns: %TRUE if a value was unpacked, or %FALSE if there as no - * value * * Gets the next item in the container and unpacks it into the variable * argument list according to @format_string, returning %TRUE. @@ -4055,12 +5553,15 @@ g_variant_iter_next (GVariantIter *iter, * function with a string constant for the format string and the same * string constant must be used each time. Mixing calls to this * function and g_variant_iter_next() or g_variant_iter_next_value() on - * the same iterator is not recommended. + * the same iterator causes undefined behavior. + * + * If you break out of a such a while loop using g_variant_iter_loop() then + * you must free or unreference all the unpacked values as you would with + * g_variant_get(). Failure to do so will cause a memory leak. * - * - * Memory management with g_variant_iter_loop() - * - * /* Iterates a dictionary of type 'a{sv}' */ + * Here is an example for memory management with g_variant_iter_loop(): + * |[ + * // Iterates a dictionary of type 'a{sv}' * void * iterate_dictionary (GVariant *dictionary) * { @@ -4074,14 +5575,31 @@ g_variant_iter_next (GVariantIter *iter, * g_print ("Item '%s' has type '%s'\n", key, * g_variant_get_type_string (value)); * - * /* no need to free 'key' and 'value' here */ + * // no need to free 'key' and 'value' here + * // unless breaking out of this loop * } * } - * - * + * ]| * - * If you want a slightly less magical alternative that requires more - * typing, see g_variant_iter_next(). + * For most cases you should use g_variant_iter_next(). + * + * This function is really only useful when unpacking into #GVariant or + * #GVariantIter in order to allow you to skip the call to + * g_variant_unref() or g_variant_iter_free(). + * + * For example, if you are only looping over simple integer and string + * types, g_variant_iter_next() is definitely preferred. For string + * types, use the '&' prefix to avoid allocating any memory at all (and + * thereby avoiding the need to free anything as well). + * + * @format_string determines the C types that are used for unpacking + * the values and also determines if the values are copied or borrowed. + * + * See the section on + * [GVariant format strings][gvariant-format-strings-pointers]. + * + * Returns: %TRUE if a value was unpacked, or %FALSE if there was no + * value * * Since: 2.24 **/ @@ -4197,7 +5715,6 @@ g_variant_deep_copy (GVariant *value) /** * g_variant_get_normal_form: * @value: a #GVariant - * @returns: a trusted #GVariant * * Gets a #GVariant instance that has the same value as @value and is * trusted to be in normal form. @@ -4216,6 +5733,8 @@ g_variant_deep_copy (GVariant *value) * data from untrusted sources and you want to ensure your serialised * output is definitely in normal form. * + * Returns: (transfer full): a trusted #GVariant + * * Since: 2.24 **/ GVariant * @@ -4235,7 +5754,6 @@ g_variant_get_normal_form (GVariant *value) /** * g_variant_byteswap: * @value: a #GVariant - * @returns: the byteswapped form of @value * * Performs a byteswapping operation on the contents of @value. The * result is that all multi-byte numeric data contained in @value is @@ -4249,28 +5767,44 @@ g_variant_get_normal_form (GVariant *value) * * The returned value is always in normal form and is marked as trusted. * + * Returns: (transfer full): the byteswapped form of @value + * * Since: 2.24 **/ GVariant * g_variant_byteswap (GVariant *value) { - GVariantSerialised serialised; - GVariant *trusted; - GBuffer *buffer; + GVariantTypeInfo *type_info; + guint alignment; GVariant *new; - trusted = g_variant_get_normal_form (value); - serialised.type_info = g_variant_get_type_info (trusted); - serialised.size = g_variant_get_size (trusted); - serialised.data = g_malloc (serialised.size); - g_variant_store (trusted, serialised.data); - g_variant_unref (trusted); + type_info = g_variant_get_type_info (value); - g_variant_serialised_byteswap (serialised); + g_variant_type_info_query (type_info, &alignment, NULL); - buffer = g_buffer_new_take_data (serialised.data, serialised.size); - new = g_variant_new_from_buffer (g_variant_get_type (value), buffer, TRUE); - g_buffer_unref (buffer); + if (alignment) + /* (potentially) contains multi-byte numeric data */ + { + GVariantSerialised serialised; + GVariant *trusted; + GBytes *bytes; + + trusted = g_variant_get_normal_form (value); + serialised.type_info = g_variant_get_type_info (trusted); + serialised.size = g_variant_get_size (trusted); + serialised.data = g_malloc (serialised.size); + g_variant_store (trusted, serialised.data); + g_variant_unref (trusted); + + g_variant_serialised_byteswap (serialised); + + bytes = g_bytes_new_take (serialised.data, serialised.size); + new = g_variant_new_from_bytes (g_variant_get_type (value), bytes, TRUE); + g_bytes_unref (bytes); + } + else + /* contains no multi-byte data */ + new = value; return g_variant_ref_sink (new); } @@ -4278,12 +5812,11 @@ g_variant_byteswap (GVariant *value) /** * g_variant_new_from_data: * @type: a definite #GVariantType - * @data: the serialised data + * @data: (array length=size) (element-type guint8): the serialised data * @size: the size of @data * @trusted: %TRUE if @data is definitely in normal form - * @notify: function to call when @data is no longer needed + * @notify: (scope async): function to call when @data is no longer needed * @user_data: data for @notify - * @returns: a new floating #GVariant of type @type * * Creates a new #GVariant instance from serialised data. * @@ -4302,10 +5835,16 @@ g_variant_byteswap (GVariant *value) * should set trusted to %FALSE if @data is read from the network, a * file in the user's home directory, etc. * + * If @data was not stored in this machine's native endianness, any multi-byte + * numeric values in the returned variant will also be in non-native + * endianness. g_variant_byteswap() can be used to recover the original values. + * * @notify will be called with @user_data when @data is no longer * needed. The exact time of this call is unspecified and might even be * before this function returns. * + * Returns: (transfer none): a new floating #GVariant of type @type + * * Since: 2.24 **/ GVariant * @@ -4317,24 +5856,21 @@ g_variant_new_from_data (const GVariantType *type, gpointer user_data) { GVariant *value; - GBuffer *buffer; + GBytes *bytes; g_return_val_if_fail (g_variant_type_is_definite (type), NULL); g_return_val_if_fail (data != NULL || size == 0, NULL); if (notify) - buffer = g_buffer_new_from_pointer (data, size, notify, user_data); + bytes = g_bytes_new_with_free_func (data, size, notify, user_data); else - buffer = g_buffer_new_from_static_data (data, size); + bytes = g_bytes_new_static (data, size); - value = g_variant_new_from_buffer (type, buffer, trusted); - g_buffer_unref (buffer); + value = g_variant_new_from_bytes (type, bytes, trusted); + g_bytes_unref (bytes); return value; } /* Epilogue {{{1 */ -#define __G_VARIANT_C__ -#include "galiasdef.c" - /* vim:set foldmethod=marker: */