Manipulating a{sv} mappings

## Manipulating a{sv} mappings Manipulating a{sv} mappings — Functions to manipulate mappings from string to variant, as represented in dbus-glib by a GHashTable from string to GValue |

## Synopsis

    #include <telepathy-glib/dbus.h>

    #define             tp_asv_size                         (asv)
    GHashTable *        tp_asv_new                          (const gchar *first_key,
                                                             ...);
    gboolean            tp_asv_get_boolean                  (const GHashTable *asv,
                                                             const gchar *key,
                                                             gboolean *valid);
    void                tp_asv_set_boolean                  (GHashTable *asv,
                                                             const gchar *key,
                                                             gboolean value);
    gpointer            tp_asv_get_boxed                    (const GHashTable *asv,
                                                             const gchar *key,
                                                             GType type);
    void                tp_asv_set_boxed                    (GHashTable *asv,
                                                             const gchar *key,
                                                             GType type,
                                                             gconstpointer value);
    void                tp_asv_take_boxed                   (GHashTable *asv,
                                                             const gchar *key,
                                                             GType type,
                                                             gpointer value);
    void                tp_asv_set_static_boxed             (GHashTable *asv,
                                                             const gchar *key,
                                                             GType type,
                                                             gconstpointer value);
    const GArray *      tp_asv_get_bytes                    (const GHashTable *asv,
                                                             const gchar *key);
    void                tp_asv_set_bytes                    (GHashTable *asv,
                                                             const gchar *key,
                                                             guint length,
                                                             gconstpointer bytes);
    void                tp_asv_take_bytes                   (GHashTable *asv,
                                                             const gchar *key,
                                                             GArray *value);
    gdouble             tp_asv_get_double                   (const GHashTable *asv,
                                                             const gchar *key,
                                                             gboolean *valid);
    void                tp_asv_set_double                   (GHashTable *asv,
                                                             const gchar *key,
                                                             gdouble value);
    gint32              tp_asv_get_int32                    (const GHashTable *asv,
                                                             const gchar *key,
                                                             gboolean *valid);
    void                tp_asv_set_int32                    (GHashTable *asv,
                                                             const gchar *key,
                                                             gint32 value);
    gint64              tp_asv_get_int64                    (const GHashTable *asv,
                                                             const gchar *key,
                                                             gboolean *valid);
    void                tp_asv_set_int64                    (GHashTable *asv,
                                                             const gchar *key,
                                                             gint64 value);
    const gchar *       tp_asv_get_object_path              (const GHashTable *asv,
                                                             const gchar *key);
    void                tp_asv_set_object_path              (GHashTable *asv,
                                                             const gchar *key,
                                                             const gchar *value);
    void                tp_asv_take_object_path             (GHashTable *asv,
                                                             const gchar *key,
                                                             gchar *value);
    void                tp_asv_set_static_object_path       (GHashTable *asv,
                                                             const gchar *key,
                                                             const gchar *value);
    const gchar *       tp_asv_get_string                   (const GHashTable *asv,
                                                             const gchar *key);
    void                tp_asv_set_string                   (GHashTable *asv,
                                                             const gchar *key,
                                                             const gchar *value);
    void                tp_asv_take_string                  (GHashTable *asv,
                                                             const gchar *key,
                                                             gchar *value);
    void                tp_asv_set_static_string            (GHashTable *asv,
                                                             const gchar *key,
                                                             const gchar *value);
    const gchar * const * tp_asv_get_strv                   (const GHashTable *asv,
                                                             const gchar *key);
    void                tp_asv_set_strv                     (GHashTable *asv,
                                                             const gchar *key,
                                                             gchar **value);
    guint32             tp_asv_get_uint32                   (const GHashTable *asv,
                                                             const gchar *key,
                                                             gboolean *valid);
    void                tp_asv_set_uint32                   (GHashTable *asv,
                                                             const gchar *key,
                                                             guint32 value);
    guint64             tp_asv_get_uint64                   (const GHashTable *asv,
                                                             const gchar *key,
                                                             gboolean *valid);
    void                tp_asv_set_uint64                   (GHashTable *asv,
                                                             const gchar *key,
                                                             guint64 value);
    const GValue *      tp_asv_lookup                       (const GHashTable *asv,
                                                             const gchar *key);
    void                tp_asv_dump                         (GHashTable *asv);

## Description

Mappings from string to variant (D-Bus signature a{sv}) are commonly used to provide extensibility, but in dbus-glib they're somewhat awkward to deal with.

These functions provide convenient access to the values in such a mapping.

They also work around the fact that none of the GHashTable public API takes a const pointer to a GHashTable, even the read-only methods that logically ought to.

Parts of telepathy-glib return const pointers to GHashTable, to encourage the use of this API.

## Details

### tp_asv_size()

    #define tp_asv_size(asv) _tp_asv_size_inline (asv)

Return the size of `asv` as if via `g_hash_table_size()`.

The only difference is that this version takes a const GHashTable and casts it.

`asv` : | a GHashTable

Since 0.7.12

### tp_asv_new ()

    GHashTable *        tp_asv_new                          (const gchar *first_key,
                                                             ...);

Creates a new GHashTable for use with a{sv} maps, containing the values passed in as parameters.

The GHashTable is synonymous with:

    1
    2
    GHashTable *asv = g_hash_table_new_full (g_str_hash, g_str_equal,
       NULL, (GDestroyNotify) tp_g_value_slice_free);

Followed by manual insertion of each of the parameters.

Parameters are stored in slice-allocated GValues and should be set using tp_asv_set_*() and retrieved using tp_asv_get_*().

`tp_g_value_slice_new()` and `tp_g_value_slice_dup()` may also be used to insert into the map if required.

    1
    2
    g_hash_table_insert (parameters, "account",
       tp_g_value_slice_new_string ("bob@mcbadgers.com"));

Example 1. Using `tp_asv_new()`

    1
    2
    3
    4
    GHashTable *parameters = tp_asv_new (
       "answer", G_TYPE_INT, 42,
       "question", G_TYPE_STRING, "We just don't know",
       NULL);

Allocated values will be automatically free'd when overwritten, removed or the hash table destroyed with `g_hash_table_destroy()`.

`first_key` : | the name of the first key (or NULL)
`...` : | type and value for the first key, followed by a NULL-terminated list of (key, type, value) tuples
Returns : | a newly created GHashTable for storing a{sv} maps, free with `g_hash_table_destroy()`.

Since 0.7.29

### tp_asv_get_boolean ()

    gboolean            tp_asv_get_boolean                  (const GHashTable *asv,
                                                             const gchar *key,
                                                             gboolean *valid);

If a value for `key` in `asv` is present and boolean, return it, and set *`valid` to `TRUE` if `valid` is not `NULL`.

Otherwise return `FALSE`, and set *`valid` to `FALSE` if `valid` is not `NULL`.

`asv` : | A GHashTable where the keys are strings and the values are GValues
`key` : | The key to look up
`valid` : | Either `NULL`, or a location to store `TRUE` if the key actually exists and has a boolean value
Returns : | a boolean value for `key`

Since 0.7.9

### tp_asv_set_boolean ()

    void                tp_asv_set_boolean                  (GHashTable *asv,
                                                             const gchar *key,
                                                             gboolean value);

Stores the value in the map.

The value is stored as a slice-allocated GValue.

See Also: `tp_asv_new()`, `tp_asv_get_boolean()`, `tp_g_value_slice_new_boolean()`

`asv` : | a GHashTable created with `tp_asv_new()`
`key` : | string key
`value` : | value

Since 0.7.29

### tp_asv_get_boxed ()

    gpointer            tp_asv_get_boxed                    (const GHashTable *asv,
                                                             const gchar *key,
                                                             GType type);

If a value for `key` in `asv` is present and is of the desired type, return it.

Otherwise return `NULL`.

The returned value is not copied, and is only valid as long as the value for `key` in `asv` is not removed or altered. Copy it, for instance with `g_boxed_copy()`, if you need to keep it for longer.

`asv` : | A GHashTable where the keys are strings and the values are GValues
`key` : | The key to look up
`type` : | The type that the key's value should have, which must be derived from `G_TYPE_BOXED`
Returns : | the value of `key`, or `NULL`

Since 0.7.9

### tp_asv_set_boxed ()

    void                tp_asv_set_boxed                    (GHashTable *asv,
                                                             const gchar *key,
                                                             GType type,
                                                             gconstpointer value);

Stores the value in the map.

The value is stored as a slice-allocated GValue.

See Also: `tp_asv_new()`, `tp_asv_get_boxed()`, `tp_g_value_slice_new_boxed()`

`asv` : | a GHashTable created with `tp_asv_new()`
`key` : | string key
`type` : | the type of the key's value, which must be derived from `G_TYPE_BOXED`
`value` : | value

Since 0.7.29

### tp_asv_take_boxed ()

    void                tp_asv_take_boxed                   (GHashTable *asv,
                                                             const gchar *key,
                                                             GType type,
                                                             gpointer value);

Stores the value in the map.

The value is stored as a slice-allocated GValue.

See Also: `tp_asv_new()`, `tp_asv_get_boxed()`, `tp_g_value_slice_new_take_boxed()`

`asv` : | a GHashTable created with `tp_asv_new()`
`key` : | string key
`type` : | the type of the key's value, which must be derived from `G_TYPE_BOXED`
`value` : | value

Since 0.7.29

### tp_asv_set_static_boxed ()

    void                tp_asv_set_static_boxed             (GHashTable *asv,
                                                             const gchar *key,
                                                             GType type,
                                                             gconstpointer value);

Stores the value in the map.

The value is stored as a slice-allocated GValue.

See Also: `tp_asv_new()`, `tp_asv_get_boxed()`, `tp_g_value_slice_new_static_boxed()`

`asv` : | a GHashTable created with `tp_asv_new()`
`key` : | string key
`type` : | the type of the key's value, which must be derived from `G_TYPE_BOXED`
`value` : | value

Since 0.7.29

### tp_asv_get_bytes ()

    const GArray *      tp_asv_get_bytes                    (const GHashTable *asv,
                                                             const gchar *key);

If a value for `key` in `asv` is present and is an array of bytes (its GType is `DBUS_TYPE_G_UCHAR_ARRAY`), return it.

Otherwise return `NULL`.

The returned value is not copied, and is only valid as long as the value for `key` in `asv` is not removed or altered. Copy it with g_boxed_copy (DBUS_TYPE_G_UCHAR_ARRAY, ...) if you need to keep it for longer.

`asv` : | A GHashTable where the keys are strings and the values are GValues
`key` : | The key to look up
Returns : | the string value of `key`, or `NULL`

Since 0.7.9

### tp_asv_set_bytes ()

    void                tp_asv_set_bytes                    (GHashTable *asv,
                                                             const gchar *key,
                                                             guint length,
                                                             gconstpointer bytes);

Stores the value in the map.

The value is stored as a slice-allocated GValue.

See Also: `tp_asv_new()`, `tp_asv_get_bytes()`, `tp_g_value_slice_new_bytes()`

`asv` : | a GHashTable created with `tp_asv_new()`
`key` : | string key
`length` : | the number of bytes to copy
`bytes` : | location of an array of bytes to be copied (this may be `NULL` if and only if length is 0)

Since 0.7.29

### tp_asv_take_bytes ()

    void                tp_asv_take_bytes                   (GHashTable *asv,
                                                             const gchar *key,
                                                             GArray *value);

Stores the value in the map.

The value is stored as a slice-allocated GValue.

See Also: `tp_asv_new()`, `tp_asv_get_bytes()`, `tp_g_value_slice_new_take_bytes()`

`asv` : | a GHashTable created with `tp_asv_new()`
`key` : | string key
`value` : | a non-NULL GArray of `guchar`, ownership of which will be taken by the GValue

Since 0.7.29

### tp_asv_get_double ()

    gdouble             tp_asv_get_double                   (const GHashTable *asv,
                                                             const gchar *key,
                                                             gboolean *valid);

If a value for `key` in `asv` is present and has any numeric type used by dbus-glib (guchar, gint, guint, gint64, guint64 or gdouble), return it as a double, and if `valid` is not `NULL`, set *`valid` to `TRUE`.

Otherwise, return 0.0, and if `valid` is not `NULL`, set *`valid` to `FALSE`.

`asv` : | A GHashTable where the keys are strings and the values are GValues
`key` : | The key to look up
`valid` : | Either `NULL`, or a location in which to store `TRUE` on success or `FALSE` on failure
Returns : | the double precision floating-point value of `key`, or 0.0

Since 0.7.9

### tp_asv_set_double ()

    void                tp_asv_set_double                   (GHashTable *asv,
                                                             const gchar *key,
                                                             gdouble value);

Stores the value in the map.

The value is stored as a slice-allocated GValue.

See Also: `tp_asv_new()`, `tp_asv_get_double()`, `tp_g_value_slice_new_double()`

`asv` : | a GHashTable created with `tp_asv_new()`
`key` : | string key
`value` : | value

Since 0.7.29

### tp_asv_get_int32 ()

    gint32              tp_asv_get_int32                    (const GHashTable *asv,
                                                             const gchar *key,
                                                             gboolean *valid);

If a value for `key` in `asv` is present, has an integer type used by dbus-glib (guchar, gint, guint, gint64 or guint64) and fits in the range of a gint32, return it, and if `valid` is not `NULL`, set *`valid` to `TRUE`.

Otherwise, return 0, and if `valid` is not `NULL`, set *`valid` to `FALSE`.

`asv` : | A GHashTable where the keys are strings and the values are GValues
`key` : | The key to look up
`valid` : | Either `NULL`, or a location in which to store `TRUE` on success or `FALSE` on failure
Returns : | the 32-bit signed integer value of `key`, or 0

Since 0.7.9

### tp_asv_set_int32 ()

    void                tp_asv_set_int32                    (GHashTable *asv,
                                                             const gchar *key,
                                                             gint32 value);

Stores the value in the map.

The value is stored as a slice-allocated GValue.

See Also: `tp_asv_new()`, `tp_asv_get_int32()`, `tp_g_value_slice_new_int()`

`asv` : | a GHashTable created with `tp_asv_new()`
`key` : | string key
`value` : | value

Since 0.7.29

### tp_asv_get_int64 ()

    gint64              tp_asv_get_int64                    (const GHashTable *asv,
                                                             const gchar *key,
                                                             gboolean *valid);

If a value for `key` in `asv` is present, has an integer type used by dbus-glib (guchar, gint, guint, gint64 or guint64) and fits in the range of a gint64, return it, and if `valid` is not `NULL`, set *`valid` to `TRUE`.

Otherwise, return 0, and if `valid` is not `NULL`, set *`valid` to `FALSE`.

`asv` : | A GHashTable where the keys are strings and the values are GValues
`key` : | The key to look up
`valid` : | Either `NULL`, or a location in which to store `TRUE` on success or `FALSE` on failure
Returns : | the 64-bit signed integer value of `key`, or 0

Since 0.7.9

### tp_asv_set_int64 ()

    void                tp_asv_set_int64                    (GHashTable *asv,
                                                             const gchar *key,
                                                             gint64 value);

Stores the value in the map.

The value is stored as a slice-allocated GValue.

See Also: `tp_asv_new()`, `tp_asv_get_int64()`, `tp_g_value_slice_new_int64()`

`asv` : | a GHashTable created with `tp_asv_new()`
`key` : | string key
`value` : | value

Since 0.7.29

### tp_asv_get_object_path ()

    const gchar *       tp_asv_get_object_path              (const GHashTable *asv,
                                                             const gchar *key);

If a value for `key` in `asv` is present and is an object path, return it.

Otherwise return `NULL`.

The returned value is not copied, and is only valid as long as the value for `key` in `asv` is not removed or altered. Copy it with `g_strdup()` if you need to keep it for longer.

`asv` : | A GHashTable where the keys are strings and the values are GValues
`key` : | The key to look up
Returns : | the object-path value of `key`, or `NULL`

Since 0.7.9

### tp_asv_set_object_path ()

    void                tp_asv_set_object_path              (GHashTable *asv,
                                                             const gchar *key,
                                                             const gchar *value);

Stores the value in the map.

The value is stored as a slice-allocated GValue.

See Also: `tp_asv_new()`, `tp_asv_get_object_path()`, `tp_g_value_slice_new_object_path()`

`asv` : | a GHashTable created with `tp_asv_new()`
`key` : | string key
`value` : | value

Since 0.7.29

### tp_asv_take_object_path ()

    void                tp_asv_take_object_path             (GHashTable *asv,
                                                             const gchar *key,
                                                             gchar *value);

Stores the value in the map.

The value is stored as a slice-allocated GValue.

See Also: `tp_asv_new()`, `tp_asv_get_object_path()`, `tp_g_value_slice_new_take_object_path()`

`asv` : | a GHashTable created with `tp_asv_new()`
`key` : | string key
`value` : | value

Since 0.7.29

### tp_asv_set_static_object_path ()

    void                tp_asv_set_static_object_path       (GHashTable *asv,
                                                             const gchar *key,
                                                             const gchar *value);

Stores the value in the map.

The value is stored as a slice-allocated GValue.

See Also: `tp_asv_new()`, `tp_asv_get_object_path()`, `tp_g_value_slice_new_static_object_path()`

`asv` : | a GHashTable created with `tp_asv_new()`
`key` : | string key
`value` : | value

Since 0.7.29

### tp_asv_get_string ()

    const gchar *       tp_asv_get_string                   (const GHashTable *asv,
                                                             const gchar *key);

If a value for `key` in `asv` is present and is a string, return it.

Otherwise return `NULL`.

The returned value is not copied, and is only valid as long as the value for `key` in `asv` is not removed or altered. Copy it with `g_strdup()` if you need to keep it for longer.

`asv` : | A GHashTable where the keys are strings and the values are GValues
`key` : | The key to look up
Returns : | the string value of `key`, or `NULL`

Since 0.7.9

### tp_asv_set_string ()

    void                tp_asv_set_string                   (GHashTable *asv,
                                                             const gchar *key,
                                                             const gchar *value);

Stores the value in the map.

The value is stored as a slice-allocated GValue.

See Also: `tp_asv_new()`, `tp_asv_get_string()`, `tp_g_value_slice_new_string()`

`asv` : | a GHashTable created with `tp_asv_new()`
`key` : | string key
`value` : | value

Since 0.7.29

### tp_asv_take_string ()

    void                tp_asv_take_string                  (GHashTable *asv,
                                                             const gchar *key,
                                                             gchar *value);

Stores the value in the map.

The value is stored as a slice-allocated GValue.

See Also: `tp_asv_new()`, `tp_asv_get_string()`, `tp_g_value_slice_new_take_string()`

`asv` : | a GHashTable created with `tp_asv_new()`
`key` : | string key
`value` : | value

Since 0.7.29

### tp_asv_set_static_string ()

    void                tp_asv_set_static_string            (GHashTable *asv,
                                                             const gchar *key,
                                                             const gchar *value);

Stores the value in the map.

The value is stored as a slice-allocated GValue.

See Also: `tp_asv_new()`, `tp_asv_get_string()`, `tp_g_value_slice_new_static_string()`

`asv` : | a GHashTable created with `tp_asv_new()`
`key` : | string key
`value` : | value

Since 0.7.29

### tp_asv_get_strv ()

    const gchar * const * tp_asv_get_strv                   (const GHashTable *asv,
                                                             const gchar *key);

If a value for `key` in `asv` is present and is an array of strings (strv), return it.

Otherwise return `NULL`.

The returned value is not copied, and is only valid as long as the value for `key` in `asv` is not removed or altered. Copy it with `g_strdupv()` if you need to keep it for longer.

`asv` : | A GHashTable where the keys are strings and the values are GValues
`key` : | The key to look up
Returns : | the `NULL`-terminated string-array value of `key`, or `NULL`

Since 0.7.9

### tp_asv_set_strv ()

    void                tp_asv_set_strv                     (GHashTable *asv,
                                                             const gchar *key,
                                                             gchar **value);

Stores the value in the map.

The value is stored as a slice-allocated GValue.

See Also: `tp_asv_new()`, `tp_asv_get_strv()`

`asv` : | a GHashTable created with `tp_asv_new()`
`key` : | string key
`value` : | a `NULL`-terminated string array

Since 0.7.29

### tp_asv_get_uint32 ()

    guint32             tp_asv_get_uint32                   (const GHashTable *asv,
                                                             const gchar *key,
                                                             gboolean *valid);

If a value for `key` in `asv` is present, has an integer type used by dbus-glib (guchar, gint, guint, gint64 or guint64) and fits in the range of a guint32, return it, and if `valid` is not `NULL`, set *`valid` to `TRUE`.

Otherwise, return 0, and if `valid` is not `NULL`, set *`valid` to `FALSE`.

`asv` : | A GHashTable where the keys are strings and the values are GValues
`key` : | The key to look up
`valid` : | Either `NULL`, or a location in which to store `TRUE` on success or `FALSE` on failure
Returns : | the 32-bit unsigned integer value of `key`, or 0

Since 0.7.9

### tp_asv_set_uint32 ()

    void                tp_asv_set_uint32                   (GHashTable *asv,
                                                             const gchar *key,
                                                             guint32 value);

Stores the value in the map.

The value is stored as a slice-allocated GValue.

See Also: `tp_asv_new()`, `tp_asv_get_uint32()`, `tp_g_value_slice_new_uint()`

`asv` : | a GHashTable created with `tp_asv_new()`
`key` : | string key
`value` : | value

Since 0.7.29

### tp_asv_get_uint64 ()

    guint64             tp_asv_get_uint64                   (const GHashTable *asv,
                                                             const gchar *key,
                                                             gboolean *valid);

If a value for `key` in `asv` is present, has an integer type used by dbus-glib (guchar, gint, guint, gint64 or guint64) and is non-negative, return it, and if `valid` is not `NULL`, set *`valid` to `TRUE`.

Otherwise, return 0, and if `valid` is not `NULL`, set *`valid` to `FALSE`.

`asv` : | A GHashTable where the keys are strings and the values are GValues
`key` : | The key to look up
`valid` : | Either `NULL`, or a location in which to store `TRUE` on success or `FALSE` on failure
Returns : | the 64-bit unsigned integer value of `key`, or 0

Since 0.7.9

### tp_asv_set_uint64 ()

    void                tp_asv_set_uint64                   (GHashTable *asv,
                                                             const gchar *key,
                                                             guint64 value);

Stores the value in the map.

The value is stored as a slice-allocated GValue.

See Also: `tp_asv_new()`, `tp_asv_get_uint64()`, `tp_g_value_slice_new_uint64()`

`asv` : | a GHashTable created with `tp_asv_new()`
`key` : | string key
`value` : | value

Since 0.7.29

### tp_asv_lookup ()

    const GValue *      tp_asv_lookup                       (const GHashTable *asv,
                                                             const gchar *key);

If a value for `key` in `asv` is present, return it. Otherwise return `NULL`.

The returned value is not copied, and is only valid as long as the value for `key` in `asv` is not removed or altered. Copy it with (for instance) `g_value_copy()` if you need to keep it for longer.

`asv` : | A GHashTable where the keys are strings and the values are GValues
`key` : | The key to look up
Returns : | the value of `key`, or `NULL`

Since 0.7.9

### tp_asv_dump ()

    void                tp_asv_dump                         (GHashTable *asv);

Dumps the a{sv} map to the debugging console.

The purpose of this function is give the programmer the ability to easily inspect the contents of an a{sv} map for debugging purposes.

`asv` : | a GHashTable created with `tp_asv_new()`