telepathy-glib API Reference Manual | ||||
---|---|---|---|---|
Top | Description |
Manipulating a{sv} mappingsManipulating 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/telepathy-glib.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)
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.
|
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()
.
|
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
.
|
A GHashTable where the keys are strings and the values are GValues. [element-type utf8 GObject.Value] |
|
The key to look up |
|
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()
|
a GHashTable created with tp_asv_new()
|
|
string key |
|
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.
|
A GHashTable where the keys are strings and the values are GValues. [element-type utf8 GObject.Value] |
|
The key to look up |
|
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()
|
a GHashTable created with tp_asv_new()
|
|
string key |
|
the type of the key's value, which must be derived from G_TYPE_BOXED
|
|
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()
|
a GHashTable created with tp_asv_new()
|
|
string key |
|
the type of the key's value, which must be derived from G_TYPE_BOXED
|
|
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()
|
a GHashTable created with tp_asv_new()
|
|
string key |
|
the type of the key's value, which must be derived from G_TYPE_BOXED
|
|
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.
|
A GHashTable where the keys are strings and the values are GValues. [element-type utf8 GObject.Value] |
|
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()
|
a GHashTable created with tp_asv_new()
|
|
string key |
|
the number of bytes to copy |
|
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()
|
a GHashTable created with tp_asv_new()
|
|
string key |
|
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
.
|
A GHashTable where the keys are strings and the values are GValues. [element-type utf8 GObject.Value] |
|
The key to look up |
|
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()
|
a GHashTable created with tp_asv_new()
|
|
string key |
|
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
.
|
A GHashTable where the keys are strings and the values are GValues. [element-type utf8 GObject.Value] |
|
The key to look up |
|
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()
|
a GHashTable created with tp_asv_new()
|
|
string key |
|
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
.
|
A GHashTable where the keys are strings and the values are GValues. [element-type utf8 GObject.Value] |
|
The key to look up |
|
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()
|
a GHashTable created with tp_asv_new()
|
|
string key |
|
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.
|
A GHashTable where the keys are strings and the values are GValues. [element-type utf8 GObject.Value] |
|
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()
|
a GHashTable created with tp_asv_new()
|
|
string key |
|
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()
|
a GHashTable created with tp_asv_new()
|
|
string key |
|
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()
|
a GHashTable created with tp_asv_new()
|
|
string key |
|
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.
|
A GHashTable where the keys are strings and the values are GValues. [element-type utf8 GObject.Value] |
|
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()
|
a GHashTable created with tp_asv_new()
|
|
string key |
|
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()
|
a GHashTable created with tp_asv_new()
|
|
string key |
|
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()
|
a GHashTable created with tp_asv_new()
|
|
string key |
|
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.
|
A GHashTable where the keys are strings and the values are GValues. [element-type utf8 GObject.Value] |
|
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()
|
a GHashTable created with tp_asv_new()
|
|
string key |
|
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
.
|
A GHashTable where the keys are strings and the values are GValues. [element-type utf8 GObject.Value] |
|
The key to look up |
|
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()
|
a GHashTable created with tp_asv_new()
|
|
string key |
|
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
.
|
A GHashTable where the keys are strings and the values are GValues. [element-type utf8 GObject.Value] |
|
The key to look up |
|
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()
|
a GHashTable created with tp_asv_new()
|
|
string key |
|
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.
|
A GHashTable where the keys are strings and the values are GValues |
|
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.
|
a GHashTable created with tp_asv_new()
|