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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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