## Manipulating a{sv} mappings

Manipulating a{sv} mappings — Functions to manipulate mappings from string to variant, as represented in GVariant by a `G_VARIANT_TYPE_VARDICT`

## Synopsis

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

    gboolean            tp_vardict_get_boolean              (GVariant *variant,
                                                             const gchar *key,
                                                             gboolean *valid);
    gdouble             tp_vardict_get_double               (GVariant *variant,
                                                             const gchar *key,
                                                             gboolean *valid);
    gint32              tp_vardict_get_int32                (GVariant *variant,
                                                             const gchar *key,
                                                             gboolean *valid);
    gint64              tp_vardict_get_int64                (GVariant *variant,
                                                             const gchar *key,
                                                             gboolean *valid);
    const gchar *       tp_vardict_get_object_path          (GVariant *variant,
                                                             const gchar *key);
    const gchar *       tp_vardict_get_string               (GVariant *variant,
                                                             const gchar *key);
    guint32             tp_vardict_get_uint32               (GVariant *variant,
                                                             const gchar *key,
                                                             gboolean *valid);
    guint64             tp_vardict_get_uint64               (GVariant *variant,
                                                             const gchar *key,
                                                             gboolean *valid);

## Description

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

## Details

### tp_vardict_get_boolean ()

    gboolean            tp_vardict_get_boolean              (GVariant *variant,
                                                             const gchar *key,
                                                             gboolean *valid);

If a value for `key` in `variant` 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`.

`variant` : | a GVariant of type `G_VARIANT_TYPE_VARDICT`
`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.19.10

### tp_vardict_get_double ()

    gdouble             tp_vardict_get_double               (GVariant *variant,
                                                             const gchar *key,
                                                             gboolean *valid);

If a value for `key` in `variant` is present and has any numeric type used by GVariant (gint32, guint32, 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`.

`variant` : | a GVariant of type `G_VARIANT_TYPE_VARDICT`
`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.19.10

### tp_vardict_get_int32 ()

    gint32              tp_vardict_get_int32                (GVariant *variant,
                                                             const gchar *key,
                                                             gboolean *valid);

If a value for `key` in `variant` is present, has an integer type used by GVariant (gint32, guint32, 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`.

`variant` : | a GVariant of type `G_VARIANT_TYPE_VARDICT`
`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.19.10

### tp_vardict_get_int64 ()

    gint64              tp_vardict_get_int64                (GVariant *variant,
                                                             const gchar *key,
                                                             gboolean *valid);

If a value for `key` in `variant` is present, has an integer type used by GVariant (gint32, guint32, 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`.

`variant` : | a GVariant of type `G_VARIANT_TYPE_VARDICT`
`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.19.10

### tp_vardict_get_object_path ()

    const gchar *       tp_vardict_get_object_path          (GVariant *variant,
                                                             const gchar *key);

If a value for `key` in `variant` 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 `variant` is kept. Copy it with `g_strdup()` if you need to keep it for longer.

`variant` : | a GVariant of type `G_VARIANT_TYPE_VARDICT`
`key` : | The key to look up
Returns : | the object path value of `key`, or `NULL`. [transfer none][allow-none]

Since 0.19.10

### tp_vardict_get_string ()

    const gchar *       tp_vardict_get_string               (GVariant *variant,
                                                             const gchar *key);

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

Otherwise return `NULL`.

The returned value is not copied, and is only valid as long as `variant` is kept. Copy it with `g_strdup()` if you need to keep it for longer.

`variant` : | a GVariant of type `G_VARIANT_TYPE_VARDICT`
`key` : | The key to look up
Returns : | the string value of `key`, or `NULL`. [transfer none][allow-none]

Since 0.19.10

### tp_vardict_get_uint32 ()

    guint32             tp_vardict_get_uint32               (GVariant *variant,
                                                             const gchar *key,
                                                             gboolean *valid);

If a value for `key` in `variant` is present, has an integer type used by GVariant (gint32, guint32, 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`.

`variant` : | a GVariant of type `G_VARIANT_TYPE_VARDICT`
`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.19.10

### tp_vardict_get_uint64 ()

    guint64             tp_vardict_get_uint64               (GVariant *variant,
                                                             const gchar *key,
                                                             gboolean *valid);

If a value for `key` in `variant` is present, has an integer type used by GVariant (gint32, guint32, 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`.

`variant` : | a GVariant of type `G_VARIANT_TYPE_VARDICT`
`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.19.10