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)

asv :

tp_asv_new ()

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

first_key :

... :

Returns :

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

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);

asv :

key :

value :

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. 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);

asv :

key :

type :

value :

tp_asv_take_boxed ()

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

asv :

key :

type :

value :

tp_asv_set_static_boxed ()

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

asv :

key :

type :

value :

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. 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_bytes ()

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

asv :

key :

length :

bytes :

tp_asv_take_bytes ()

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

asv :

key :

value :

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

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);

asv :

key :

value :

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

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);

asv :

key :

value :

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

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);

asv :

key :

value :

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. 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);

asv :

key :

value :

tp_asv_take_object_path ()

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

asv :

key :

value :

tp_asv_set_static_object_path ()

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

asv :

key :

value :

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. 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);

asv :

key :

value :

tp_asv_take_string ()

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

asv :

key :

value :

tp_asv_set_static_string ()

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

asv :

key :

value :

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. 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);

asv :

key :

value :

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

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);

asv :

key :

value :

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

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);

asv :

key :

value :

tp_asv_lookup ()

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

asv :

key :

Returns :

tp_asv_dump ()

void                tp_asv_dump                         (GHashTable *asv);

asv :
Generated by GTK-Doc V1.14