X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;ds=sidebyside;f=glib%2Fgvariant.c;h=aca95798553ae40d464dd76b39dab514799be5a2;hb=14f2376c8a06f0936d734ec6a7e0e836072acf65;hp=fe1cd9f0c7df27b712a1928a51bb91777e29bffd;hpb=33c977917c1dbcfec56168083dc05837da8ea57c;p=platform%2Fupstream%2Fglib.git diff --git a/glib/gvariant.c b/glib/gvariant.c index fe1cd9f..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,6 +27,7 @@ #include #include #include +#include #include #include @@ -67,7 +66,22 @@ * * #GVariant is largely compatible with D-Bus. Almost all types of * #GVariant instances can be sent over D-Bus. See #GVariantType for - * exceptions. + * 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 @@ -77,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 */ @@ -293,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, @@ -304,11 +287,11 @@ 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; } @@ -316,10 +299,11 @@ g_variant_new_from_trusted (const GVariantType *type, /** * g_variant_new_boolean: * @value: a #gboolean value - * @returns: (transfer none): a floating reference to a new boolean #GVariant instance * * 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 * @@ -333,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,22 +359,24 @@ g_variant_get_boolean (GVariant *value) /** * g_variant_new_byte: * @value: a #guint8 value - * @returns: (transfer none): a floating reference to a new byte #GVariant instance * * 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) @@ -397,22 +384,24 @@ NUMERIC_TYPE (BYTE, byte, guchar) /** * g_variant_new_int16: * @value: a #gint16 value - * @returns: (transfer none): a floating reference to a new int16 #GVariant instance * * 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) @@ -420,22 +409,24 @@ NUMERIC_TYPE (INT16, int16, gint16) /** * g_variant_new_uint16: * @value: a #guint16 value - * @returns: (transfer none): a floating reference to a new uint16 #GVariant instance * * 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) @@ -443,22 +434,24 @@ NUMERIC_TYPE (UINT16, uint16, guint16) /** * g_variant_new_int32: * @value: a #gint32 value - * @returns: (transfer none): a floating reference to a new int32 #GVariant instance * * 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) @@ -466,22 +459,24 @@ NUMERIC_TYPE (INT32, int32, gint32) /** * g_variant_new_uint32: * @value: a #guint32 value - * @returns: (transfer none): a floating reference to a new uint32 #GVariant instance * * 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) @@ -489,22 +484,24 @@ NUMERIC_TYPE (UINT32, uint32, guint32) /** * g_variant_new_int64: * @value: a #gint64 value - * @returns: (transfer none): a floating reference to a new int64 #GVariant instance * * 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) @@ -512,22 +509,24 @@ NUMERIC_TYPE (INT64, int64, gint64) /** * g_variant_new_uint64: * @value: a #guint64 value - * @returns: (transfer none): a floating reference to a new uint64 #GVariant instance * * 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) @@ -535,7 +534,6 @@ NUMERIC_TYPE (UINT64, uint64, guint64) /** * g_variant_new_handle: * @value: a #gint32 value - * @returns: (transfer none): a floating reference to a new handle #GVariant instance * * Creates a new handle #GVariant instance. * @@ -543,12 +541,13 @@ NUMERIC_TYPE (UINT64, uint64, guint64) * 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. * @@ -559,6 +558,8 @@ NUMERIC_TYPE (UINT64, uint64, guint64) * 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 **/ NUMERIC_TYPE (HANDLE, handle, gint32) @@ -566,22 +567,24 @@ NUMERIC_TYPE (HANDLE, handle, gint32) /** * g_variant_new_double: * @value: a #gdouble floating point value - * @returns: (transfer none): a floating reference to a new double #GVariant instance * * 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) @@ -591,7 +594,6 @@ NUMERIC_TYPE (DOUBLE, double, gdouble) * g_variant_new_maybe: * @child_type: (allow-none): the #GVariantType of the child, or %NULL * @child: (allow-none): the child value, or %NULL - * @returns: (transfer none): a floating reference to a new #GVariant maybe instance * * Depending on if @child is %NULL, either wraps @child inside of a * maybe container or creates a Nothing instance for the given @type. @@ -604,6 +606,8 @@ NUMERIC_TYPE (DOUBLE, double, gdouble) * 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 **/ GVariant * @@ -647,11 +651,12 @@ g_variant_new_maybe (const GVariantType *child_type, /** * g_variant_get_maybe: * @value: a maybe-typed value - * @returns: (allow-none) (transfer full): 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 * @@ -668,7 +673,6 @@ g_variant_get_maybe (GVariant *value) /** * g_variant_new_variant: (constructor) * @value: a #GVariant instance - * @returns: (transfer none): a floating reference to a new variant #GVariant instance * * Boxes @value. The result is a #GVariant instance representing a * variant containing the original value. @@ -676,6 +680,8 @@ g_variant_get_maybe (GVariant *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 * @@ -693,11 +699,12 @@ g_variant_new_variant (GVariant *value) /** * g_variant_get_variant: * @value: a variant #GVariant instance - * @returns: (transfer full): the item contained in the variant * * 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 * @@ -714,7 +721,6 @@ g_variant_get_variant (GVariant *value) * @children: (allow-none) (array length=n_children): an array of * #GVariant pointers, the children * @n_children: the length of @children - * @returns: (transfer none): a floating reference to a new #GVariant array * * Creates a new #GVariant array from @children. * @@ -732,6 +738,8 @@ g_variant_get_variant (GVariant *value) * 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 * @@ -801,7 +809,6 @@ g_variant_make_tuple_type (GVariant * const *children, * g_variant_new_tuple: * @children: (array length=n_children): the items to make the tuple out of * @n_children: the length of @children - * @returns: (transfer none): a floating reference to 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 @@ -812,6 +819,8 @@ g_variant_make_tuple_type (GVariant * const *children, * 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 * @@ -863,7 +872,6 @@ g_variant_make_dict_entry_type (GVariant *key, * g_variant_new_dict_entry: (constructor) * @key: a basic #GVariant, the key * @value: a #GVariant, the value - * @returns: (transfer none): a floating reference to a new dictionary entry #GVariant * * 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). @@ -871,6 +879,8 @@ g_variant_make_dict_entry_type (GVariant *key, * 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 **/ GVariant * @@ -910,7 +920,13 @@ g_variant_new_dict_entry (GVariant *key, * this function returns %FALSE. Otherwise, it unpacks the returned * value and returns %TRUE. * - * See g_variant_get() for information about @format_string. + * @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 * @@ -956,26 +972,26 @@ g_variant_lookup (GVariant *dictionary, * * 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 + * 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 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. + * 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 @@ -1045,23 +1061,37 @@ g_variant_lookup_value (GVariant *dictionary, * @value: a #GVariant array with fixed-sized elements * @n_elements: (out): a pointer to the location to store the number of items * @element_size: the size of each element - * @returns: (array length=n_elements): 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 @@ -1088,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."); } @@ -1112,16 +1142,83 @@ 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: (transfer none): a floating reference to 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 * @@ -1135,14 +1232,89 @@ g_variant_new_string (const gchar *string) } /** + * 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: (transfer none): a floating reference to a new object path #GVariant instance * * 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 * @@ -1157,7 +1329,6 @@ 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 D-Bus object path * * 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 @@ -1168,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 @@ -1181,12 +1354,13 @@ g_variant_is_object_path (const gchar *string) /** * g_variant_new_signature: * @signature: a normal C nul-terminated string - * @returns: (transfer none): a floating reference to a new signature #GVariant instance * * 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 * @@ -1201,7 +1375,6 @@ g_variant_new_signature (const gchar *signature) /** * g_variant_is_signature: * @string: a normal C nul-terminated string - * @returns: %TRUE if @string is a D-Bus type signature * * 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 @@ -1210,6 +1383,8 @@ g_variant_new_signature (const gchar *signature) * 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 @@ -1225,7 +1400,6 @@ g_variant_is_signature (const gchar *string) * @value: a string #GVariant instance * @length: (allow-none) (default 0) (out): a pointer to a #gsize, * to store the length - * @returns: (transfer none): the constant string, utf8 encoded * * Returns the string value of a #GVariant instance with a string * type. This includes the types %G_VARIANT_TYPE_STRING, @@ -1242,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 * @@ -1303,7 +1479,6 @@ g_variant_get_string (GVariant *value, * g_variant_dup_string: * @value: a string #GVariant instance * @length: (out): a pointer to a #gsize, to store the length - * @returns: (transfer full): a newly allocated string, utf8 encoded * * Similar to g_variant_get_string() except that instead of returning * a constant string, the string is duplicated. @@ -1312,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 * @@ -1325,13 +1502,14 @@ g_variant_dup_string (GVariant *value, * g_variant_new_strv: * @strv: (array length=length) (element-type utf8): an array of strings * @length: the length of @strv, or -1 - * @returns: (transfer none): a new floating #GVariant instance * * Constructs an array of strings #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.24 **/ GVariant * @@ -1358,8 +1536,6 @@ g_variant_new_strv (const gchar * const *strv, * g_variant_get_strv: * @value: an array of strings #GVariant * @length: (out) (allow-none): the length of the result, or %NULL - * @returns: (array length=length zero-terminated=1) (transfer container): an array of constant - * strings * * Gets the contents of an array of strings #GVariant. This call * makes a shallow copy; the return result should be released with @@ -1372,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 ** @@ -1408,7 +1586,6 @@ g_variant_get_strv (GVariant *value, * g_variant_dup_strv: * @value: an array of strings #GVariant * @length: (out) (allow-none): the length of the result, or %NULL - * @returns: (array length=length zero-terminated=1) (transfer full): an array of strings * * Gets the contents of an array of strings #GVariant. This call * makes a deep copy; the return result should be released with @@ -1421,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 ** @@ -1456,7 +1635,6 @@ g_variant_dup_strv (GVariant *value, * g_variant_new_objv: * @strv: (array length=length) (element-type utf8): an array of strings * @length: the length of @strv, or -1 - * @returns: (transfer none): a new floating #GVariant instance * * Constructs an array of object paths #GVariant from the given array of * strings. @@ -1466,6 +1644,8 @@ g_variant_dup_strv (GVariant *value, * * If @length is -1 then @strv is %NULL-terminated. * + * Returns: (transfer none): a new floating #GVariant instance + * * Since: 2.30 **/ GVariant * @@ -1492,8 +1672,6 @@ g_variant_new_objv (const gchar * const *strv, * g_variant_get_objv: * @value: an array of object paths #GVariant * @length: (out) (allow-none): the length of the result, or %NULL - * @returns: (array length=length zero-terminated=1) (transfer container): an array of constant - * strings * * Gets the contents of an array of object paths #GVariant. This call * makes a shallow copy; the return result should be released with @@ -1506,6 +1684,8 @@ g_variant_new_objv (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.30 **/ const gchar ** @@ -1542,7 +1722,6 @@ g_variant_get_objv (GVariant *value, * g_variant_dup_objv: * @value: an array of object paths #GVariant * @length: (out) (allow-none): the length of the result, or %NULL - * @returns: (array length=length zero-terminated=1) (transfer full): an array of strings * * Gets the contents of an array of object paths #GVariant. This call * makes a deep copy; the return result should be released with @@ -1555,6 +1734,8 @@ g_variant_get_objv (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.30 **/ gchar ** @@ -1589,8 +1770,8 @@ g_variant_dup_objv (GVariant *value, /** * g_variant_new_bytestring: - * @string: (array zero-terminated=1): a normal nul-terminated string in no particular encoding - * @returns: (transfer none): a floating reference to a new bytestring #GVariant instance + * @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 @@ -1599,6 +1780,8 @@ g_variant_dup_objv (GVariant *value, * 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 * @@ -1613,7 +1796,6 @@ g_variant_new_bytestring (const gchar *string) /** * g_variant_get_bytestring: * @value: an array-of-bytes #GVariant instance - * @returns: (transfer none) (array zero-terminated=1): the constant string * * Returns the string value of a #GVariant instance with an * array-of-bytes type. The string has no particular encoding. @@ -1631,6 +1813,9 @@ g_variant_new_bytestring (const gchar *string) * * 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 * @@ -1656,13 +1841,15 @@ g_variant_get_bytestring (GVariant *value) * @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) - * @returns: (transfer full) (array zero-terminated=1): a newly allocated string * * 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 * @@ -1688,13 +1875,14 @@ g_variant_dup_bytestring (GVariant *value, * g_variant_new_bytestring_array: * @strv: (array length=length): an array of strings * @length: the length of @strv, or -1 - * @returns: (transfer none): a new floating #GVariant instance * * 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 * @@ -1721,7 +1909,6 @@ g_variant_new_bytestring_array (const gchar * const *strv, * 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 - * @returns: (array length=length) (transfer container): an array of constant strings * * Gets the contents of an array of array of bytes #GVariant. This call * makes a shallow copy; the return result should be released with @@ -1734,6 +1921,8 @@ g_variant_new_bytestring_array (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) (transfer container): an array of constant strings + * * Since: 2.26 **/ const gchar ** @@ -1770,7 +1959,6 @@ g_variant_get_bytestring_array (GVariant *value, * 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 - * @returns: (array length=length) (transfer full): an array of strings * * Gets the contents of an array of array of bytes #GVariant. This call * makes a deep copy; the return result should be released with @@ -1783,6 +1971,8 @@ g_variant_get_bytestring_array (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) (transfer full): an array of strings + * * Since: 2.26 **/ gchar ** @@ -1819,13 +2009,14 @@ g_variant_dup_bytestring_array (GVariant *value, /** * g_variant_get_type: * @value: a #GVariant - * @returns: a #GVariantType * * 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 * @@ -1843,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 * @@ -1867,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 @@ -1883,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) @@ -1897,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 **/ /** @@ -1939,7 +2136,7 @@ g_variant_classify (GVariant *value) } /* Pretty printer {{{1 */ -/* This function is not introspectable because if @string is NULL, +/* 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 */ /** @@ -1948,13 +2145,14 @@ g_variant_classify (GVariant *value) * @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 * @@ -2366,14 +2564,17 @@ g_variant_print_string (GVariant *value, * @value: a #GVariant * @type_annotate: %TRUE if type information should be included in * the output - * @returns: (transfer full): a newly-allocated string holding the result. * * Pretty-prints @value in the format understood by g_variant_parse(). * - * The format is described here. + * 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, @@ -2387,7 +2588,6 @@ g_variant_print (GVariant *value, /** * g_variant_hash: * @value: (type GVariant): a basic #GVariant value as a #gconstpointer - * @returns: a hash value corresponding to @value * * Generates a hash value for a #GVariant instance. * @@ -2399,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 @@ -2474,13 +2676,14 @@ g_variant_hash (gconstpointer value_) * g_variant_equal: * @one: (type GVariant): a #GVariant instance * @two: (type GVariant): a #GVariant instance - * @returns: %TRUE if @one and @two are equal * * 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 @@ -2539,9 +2742,6 @@ g_variant_equal (gconstpointer one, * g_variant_compare: * @one: (type GVariant): a basic-typed #GVariant instance * @two: (type GVariant): a #GVariant instance of the same type - * @returns: negative value if a < b; - * zero if a = b; - * positive value if a > b. * * Compares @one and @two. * @@ -2563,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 @@ -2576,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)); @@ -2614,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; } @@ -2680,7 +2888,6 @@ struct heap_iter /** * g_variant_iter_new: * @value: a container #GVariant - * @returns: (transfer full): a new heap-allocated #GVariantIter * * Creates a heap-allocated #GVariantIter for iterating over the items * in @value. @@ -2691,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 * @@ -2711,7 +2920,6 @@ g_variant_iter_new (GVariant *value) * 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 @@ -2720,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 @@ -2738,7 +2948,6 @@ g_variant_iter_init (GVariantIter *iter, /** * g_variant_iter_copy: * @iter: a #GVariantIter - * @returns: (transfer full): 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 @@ -2751,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 * @@ -2769,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 @@ -2777,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 @@ -2811,7 +3023,6 @@ g_variant_iter_free (GVariantIter *iter) /** * g_variant_iter_next_value: * @iter: a #GVariantIter - * @returns: (allow-none) (transfer full): a #GVariant, or %NULL * * Gets the next item in the container. If no more items remain then * %NULL is returned. @@ -2819,10 +3030,9 @@ 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) * { @@ -2840,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 **/ @@ -2935,7 +3146,6 @@ struct heap_builder /** * g_variant_builder_new: * @type: a container type - * @returns: (transfer full): a #GVariantBuilder * * Allocates and initialises a new #GVariantBuilder. * @@ -2947,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 * @@ -2993,13 +3205,14 @@ g_variant_builder_unref (GVariantBuilder *builder) /** * g_variant_builder_ref: * @builder: a #GVariantBuilder allocated by g_variant_builder_new() - * @returns: (transfer full): 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 * @@ -3341,7 +3554,6 @@ g_variant_make_array_type (GVariant *element) /** * g_variant_builder_end: * @builder: a #GVariantBuilder - * @returns: (transfer none): a new, floating, #GVariant * * Ends the builder process and returns the constructed value. * @@ -3358,6 +3570,8 @@ g_variant_make_array_type (GVariant *element) * 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 * @@ -3408,6 +3622,508 @@ g_variant_builder_end (GVariantBuilder *builder) 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)); +} + +/** + * g_variant_dict_remove: + * @dict: a #GVariantDict + * @key: the key to remove + * + * 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) +{ + 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); +} + +/** + * g_variant_dict_clear: + * @dict: a #GVariantDict + * + * 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) +{ + 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_dict_end: + * @dict: a #GVariantDict + * + * 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 @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). + * + * Returns: (transfer none): a new, floating, #GVariant + * + * Since: 2.40 + **/ +GVariant * +g_variant_dict_end (GVariantDict *dict) +{ + GVariantBuilder builder; + GHashTableIter iter; + gpointer key, value; + + g_return_val_if_fail (is_valid_dict (dict), NULL); + + g_variant_builder_init (&builder, G_VARIANT_TYPE_VARDICT); + + 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); + + g_variant_dict_clear (dict); + + return g_variant_builder_end (&builder); +} + +/** + * 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); + + GVHD(dict)->ref_count++; + + return dict; +} + +/** + * 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: @@ -3416,7 +4132,6 @@ g_variant_builder_end (GVariantBuilder *builder) * or %NULL * @endptr: (allow-none) (default NULL): location to store the end pointer, * or %NULL - * @returns: %TRUE if there was a valid format string * * Checks the string pointed to by @string for starting with a properly * formed #GVariant varargs format string. If no valid format string is @@ -3430,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 */ @@ -3556,6 +4272,110 @@ 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 @@ -3563,7 +4383,6 @@ g_variant_format_string_scan (const gchar *string, * or %NULL * @endptr: (allow-none) (default NULL): location to store the end pointer, * or %NULL - * @returns: (allow-none): a #GVariantType if there was a valid format string * * If @string starts with a valid format string then this function will * return the type that the format string corresponds to. Otherwise @@ -3575,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 * @@ -3617,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) @@ -3637,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; } @@ -3791,14 +4614,14 @@ g_variant_valist_new_nnp (const gchar **str, if G_UNLIKELY (!g_variant_type_is_array (type)) g_error ("g_variant_new: expected array GVariantBuilder but " - "the built value has type `%s'", + "the built value has type '%s'", g_variant_get_type_string (value)); 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'", + "type '%s' but the built value has element type '%s'", g_variant_type_dup_string ((GVariantType *) *str), g_variant_get_type_string (value) + 1); @@ -3862,8 +4685,8 @@ g_variant_valist_new_nnp (const gchar **str, 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)); @@ -3876,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; @@ -4316,22 +5139,38 @@ g_variant_valist_get (const gchar **str, * 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 * @@ -4359,7 +5198,6 @@ g_variant_new (const gchar *format_string, * @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 @@ -4377,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. @@ -4394,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 * @@ -4428,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 @@ -4481,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 @@ -4506,7 +5360,7 @@ g_variant_get_va (GVariant *value, /* Varargs-enabled Utility Functions {{{1 */ /** - * g_variant_builder_add: (skp) + * g_variant_builder_add: (skip) * @builder: a #GVariantBuilder * @format_string: a #GVariant varargs format string * @...: arguments, as per @format_string @@ -4516,30 +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_ARRAY); + * 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, @@ -4567,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 @@ -4593,8 +5456,6 @@ g_variant_get_child (GVariant *value, * @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. @@ -4606,13 +5467,9 @@ g_variant_get_child (GVariant *value, * responsibility of the caller to free all of the values returned by * the unpacking process. * - * See the section on GVariant - * Format Strings. - * - * - * 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) * { @@ -4626,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 @@ -4670,8 +5534,6 @@ g_variant_iter_next (GVariantIter *iter, * @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. @@ -4691,15 +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. * - * See the section on GVariant - * Format Strings. + * 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) * { @@ -4713,11 +5575,11 @@ 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 * } * } - * - * + * ]| * * For most cases you should use g_variant_iter_next(). * @@ -4730,6 +5592,15 @@ g_variant_iter_next (GVariantIter *iter, * 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 **/ gboolean @@ -4844,7 +5715,6 @@ g_variant_deep_copy (GVariant *value) /** * g_variant_get_normal_form: * @value: a #GVariant - * @returns: (transfer full): a trusted #GVariant * * Gets a #GVariant instance that has the same value as @value and is * trusted to be in normal form. @@ -4863,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 * @@ -4882,7 +5754,6 @@ g_variant_get_normal_form (GVariant *value) /** * g_variant_byteswap: * @value: a #GVariant - * @returns: (transfer full): 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 @@ -4896,6 +5767,8 @@ 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 * @@ -4914,7 +5787,7 @@ g_variant_byteswap (GVariant *value) { GVariantSerialised serialised; GVariant *trusted; - GBuffer *buffer; + GBytes *bytes; trusted = g_variant_get_normal_form (value); serialised.type_info = g_variant_get_type_info (trusted); @@ -4925,9 +5798,9 @@ g_variant_byteswap (GVariant *value) g_variant_serialised_byteswap (serialised); - 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); + 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 */ @@ -4944,7 +5817,6 @@ g_variant_byteswap (GVariant *value) * @trusted: %TRUE if @data is definitely in normal form * @notify: (scope async): function to call when @data is no longer needed * @user_data: data for @notify - * @returns: (transfer none): a new floating #GVariant of type @type * * Creates a new #GVariant instance from serialised data. * @@ -4963,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 * @@ -4978,18 +5856,18 @@ 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; }