Top |
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 |
#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 () |
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.
#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.
Since: 0.7.12
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]
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 |
Since: 0.7.29
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 |
[out] |
Since: 0.7.9
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]
Since: 0.7.29
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 |
Since: 0.7.9
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]
asv |
a GHashTable created with |
|
key |
string key |
|
type |
the type of the key's value, which must be derived from |
|
value |
value |
Since: 0.7.29
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]
asv |
a GHashTable created with |
|
key |
string key |
|
type |
the type of the key's value, which must be derived from |
|
value |
value |
Since: 0.7.29
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]
asv |
a GHashTable created with |
|
key |
string key |
|
type |
the type of the key's value, which must be derived from |
|
value |
value |
Since: 0.7.29
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 |
Since: 0.7.9
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]
asv |
a GHashTable created with |
|
key |
string key |
|
length |
the number of bytes to copy |
|
bytes |
location of an array of bytes to be copied (this may be |
Since: 0.7.29
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]
asv |
a GHashTable created with |
|
key |
string key |
|
value |
a non-NULL GArray of |
Since: 0.7.29
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 |
[out] |
Since: 0.7.9
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]
Since: 0.7.29
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 |
[out] |
Since: 0.7.9
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]
Since: 0.7.29
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 |
[out] |
Since: 0.7.9
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]
Since: 0.7.29
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 |
Since: 0.7.9
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]
Since: 0.7.29
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]
Since: 0.7.29
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]
Since: 0.7.29
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 |
Since: 0.7.9
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]
Since: 0.7.29
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]
Since: 0.7.29
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]
Since: 0.7.29
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 |
Since: 0.7.9
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]
asv |
a GHashTable created with |
|
key |
string key |
|
value |
a |
Since: 0.7.29
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 |
[out] |
Since: 0.7.9
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]
Since: 0.7.29
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 |
[out] |
Since: 0.7.9
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]
Since: 0.7.29
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]
asv |
A GHashTable where the keys are strings and the values are GValues |
|
key |
The key to look up |
Since: 0.7.9