## 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)
    gboolean            tp_asv_get_boolean                  (const GHashTable *asv,
                                                             const gchar *key,
                                                             gboolean *valid);
    gpointer            tp_asv_get_boxed                    (const GHashTable *asv,
                                                             const gchar *key,
                                                             GType type);
    const GArray*       tp_asv_get_bytes                    (const GHashTable *asv,
                                                             const gchar *key);
    gdouble             tp_asv_get_double                   (const GHashTable *asv,
                                                             const gchar *key,
                                                             gboolean *valid);
    gint32              tp_asv_get_int32                    (const GHashTable *asv,
                                                             const gchar *key,
                                                             gboolean *valid);
    gint64              tp_asv_get_int64                    (const GHashTable *asv,
                                                             const gchar *key,
                                                             gboolean *valid);
    const gchar*        tp_asv_get_object_path              (const GHashTable *asv,
                                                             const gchar *key);
    const gchar*        tp_asv_get_string                   (const GHashTable *asv,
                                                             const gchar *key);
    const gchar* const * tp_asv_get_strv                    (const GHashTable *asv,
                                                             const gchar *key);
    guint32             tp_asv_get_uint32                   (const GHashTable *asv,
                                                             const gchar *key,
                                                             gboolean *valid);
    guint64             tp_asv_get_uint64                   (const GHashTable *asv,
                                                             const gchar *key,
                                                             gboolean *valid);
    const GValue*       tp_asv_lookup                       (const GHashTable *asv,
                                                             const gchar *key);

## 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_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_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_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_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_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_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_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_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_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_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_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_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