Manipulating a{sv} mappings: telepathy-glib API Reference Manual

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

## Functions

#define | tp_asv_size()
GHashTable * | tp_asv_new ()
gboolean | tp_asv_get_boolean ()
void | tp_asv_set_boolean ()
gpointer | tp_asv_get_boxed ()
void | tp_asv_set_boxed ()
void | tp_asv_take_boxed ()
void | tp_asv_set_static_boxed ()
const GArray * | tp_asv_get_bytes ()
void | tp_asv_set_bytes ()
void | tp_asv_take_bytes ()
gdouble | tp_asv_get_double ()
void | tp_asv_set_double ()
gint32 | tp_asv_get_int32 ()
void | tp_asv_set_int32 ()
gint64 | tp_asv_get_int64 ()
void | tp_asv_set_int64 ()
const gchar * | tp_asv_get_object_path ()
void | tp_asv_set_object_path ()
void | tp_asv_take_object_path ()
void | tp_asv_set_static_object_path ()
const gchar * | tp_asv_get_string ()
void | tp_asv_set_string ()
void | tp_asv_take_string ()
void | tp_asv_set_static_string ()
const gchar * const * | tp_asv_get_strv ()
void | tp_asv_set_strv ()
guint32 | tp_asv_get_uint32 ()
void | tp_asv_set_uint32 ()
guint64 | tp_asv_get_uint64 ()
void | tp_asv_set_uint64 ()
const GValue * | tp_asv_lookup ()
void | tp_asv_dump ()

## Includes

    #include <telepathy-glib/telepathy-glib.h>

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

## Functions

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

#### Parameters

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_unref()`.

[skip]

#### Parameters

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_unref()`.

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`.

#### Parameters

asv | A GHashTable where the keys are strings and the values are GValues. | [element-type utf8 GObject.Value]
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. | [out]

#### 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()`

[skip]

#### Parameters

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.

#### Parameters

asv | A GHashTable where the keys are strings and the values are GValues. | [element-type utf8 GObject.Value]
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`.

[transfer none][allow-none]

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()`

[skip]

#### Parameters

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()`

[skip]

#### Parameters

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()`

[skip]

#### Parameters

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.

#### Parameters

asv | A GHashTable where the keys are strings and the values are GValues. | [element-type utf8 GObject.Value]
key | The key to look up |

#### Returns

the string value of `key` , or `NULL`.

[transfer none][allow-none][element-type guint8]

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()`

[skip]

#### Parameters

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()`

[skip]

#### Parameters

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`.

#### Parameters

asv | A GHashTable where the keys are strings and the values are GValues. | [element-type utf8 GObject.Value]
key | The key to look up |
valid | Either `NULL`, or a location in which to store `TRUE` on success or `FALSE` on failure. | [out]

#### 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()`

[skip]

#### Parameters

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`.

#### Parameters

asv | A GHashTable where the keys are strings and the values are GValues. | [element-type utf8 GObject.Value]
key | The key to look up |
valid | Either `NULL`, or a location in which to store `TRUE` on success or `FALSE` on failure. | [out]

#### 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()`

[skip]

#### Parameters

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`.

#### Parameters

asv | A GHashTable where the keys are strings and the values are GValues. | [element-type utf8 GObject.Value]
key | The key to look up |
valid | Either `NULL`, or a location in which to store `TRUE` on success or `FALSE` on failure. | [out]

#### 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()`

[skip]

#### Parameters

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.

#### Parameters

asv | A GHashTable where the keys are strings and the values are GValues. | [element-type utf8 GObject.Value]
key | The key to look up |

#### Returns

the object-path value of `key` , or `NULL`.

[transfer none][allow-none]

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()`

[skip]

#### Parameters

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()`

[skip]

#### Parameters

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()`

[skip]

#### Parameters

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.

#### Parameters

asv | A GHashTable where the keys are strings and the values are GValues. | [element-type utf8 GObject.Value]
key | The key to look up |

#### Returns

the string value of `key` , or `NULL`.

[transfer none][allow-none]

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()`

[skip]

#### Parameters

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()`

[skip]

#### Parameters

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()`

[skip]

#### Parameters

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.

#### Parameters

asv | A GHashTable where the keys are strings and the values are GValues. | [element-type utf8 GObject.Value]
key | The key to look up |

#### Returns

the `NULL`-terminated string-array value of `key` , or `NULL`.

[transfer none][allow-none]

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()`

[skip]

#### Parameters

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`.

#### Parameters

asv | A GHashTable where the keys are strings and the values are GValues. | [element-type utf8 GObject.Value]
key | The key to look up |
valid | Either `NULL`, or a location in which to store `TRUE` on success or `FALSE` on failure. | [out]

#### 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()`

[skip]

#### Parameters

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`.

#### Parameters

asv | A GHashTable where the keys are strings and the values are GValues. | [element-type utf8 GObject.Value]
key | The key to look up |
valid | Either `NULL`, or a location in which to store `TRUE` on success or `FALSE` on failure. | [out]

#### 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()`

[skip]

#### Parameters

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.

[skip]

#### Parameters

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.

[skip]

#### Parameters

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