Method

GLibVariantIternext

Declaration

gboolean
g_variant_iter_next (
  GVariantIter* iter,
  const gchar* format_string,
  ...
)

Description

Gets the next item in the container and unpacks it into the variable argument list according to format_string, returning TRUE.

If no more items remain then FALSE is returned.

All of the pointers given on the variable arguments list of this function are assumed to point at uninitialised memory. It is the responsibility of the caller to free all of the values returned by the unpacking process.

Here is an example for memory management with g_variant_iter_next():

  // Iterates a dictionary of type 'a{sv}'
  void
  iterate_dictionary (GVariant *dictionary)
  {
    GVariantIter iter;
    GVariant *value;
    gchar *key;

    g_variant_iter_init (&iter, dictionary);
    while (g_variant_iter_next (&iter, "{sv}", &key, &value))
      {
        g_print ("Item '%s' has type '%s'\n", key,
                 g_variant_get_type_string (value));

        // 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].

Available since:2.24
This method is not directly available to language bindings.

Parameters

format_string

Type: const gchar*

A GVariant format string.

The data is owned by the caller of the function.
The value is a NUL terminated UTF-8 string.
...

Type: 

The arguments to unpack the value into.

Return value

Type: gboolean

TRUE if a value was unpacked, or FALSE if there as no value.