![]() |
![]() |
![]() |
telepathy-glib Reference Manual | ![]() |
---|---|---|---|---|
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 |
#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);
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.
asv : |
a GHashTable |
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:
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.
g_hash_table_insert (parameters, "account", tp_g_value_slice_new_string ("[email protected]"));
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_destroy()
.
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_destroy() .
|
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 |
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
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()
asv : |
a GHashTable created with tp_asv_new()
|
key : |
string key |
value : |
value |
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 |
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
|
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()
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
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()
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
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()
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
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 |
key : |
The key to look up |
Returns : | the string value of key , or NULL
|
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()
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
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()
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
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 |
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
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()
asv : |
a GHashTable created with tp_asv_new()
|
key : |
string key |
value : |
value |
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 |
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
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()
asv : |
a GHashTable created with tp_asv_new()
|
key : |
string key |
value : |
value |
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 |
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
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()
asv : |
a GHashTable created with tp_asv_new()
|
key : |
string key |
value : |
value |
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 |
key : |
The key to look up |
Returns : | the object-path value of key , or NULL
|
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()
asv : |
a GHashTable created with tp_asv_new()
|
key : |
string key |
value : |
value |
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()
asv : |
a GHashTable created with tp_asv_new()
|
key : |
string key |
value : |
value |
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()
asv : |
a GHashTable created with tp_asv_new()
|
key : |
string key |
value : |
value |
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 |
key : |
The key to look up |
Returns : | the string value of key , or NULL
|
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()
asv : |
a GHashTable created with tp_asv_new()
|
key : |
string key |
value : |
value |
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()
asv : |
a GHashTable created with tp_asv_new()
|
key : |
string key |
value : |
value |
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()
asv : |
a GHashTable created with tp_asv_new()
|
key : |
string key |
value : |
value |
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 |
key : |
The key to look up |
Returns : | the NULL -terminated string-array value of key , or NULL
|
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()
asv : |
a GHashTable created with tp_asv_new()
|
key : |
string key |
value : |
a NULL -terminated string array
|
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 |
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
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()
asv : |
a GHashTable created with tp_asv_new()
|
key : |
string key |
value : |
value |
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 |
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
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()
asv : |
a GHashTable created with tp_asv_new()
|
key : |
string key |
value : |
value |
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.
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
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.
asv : |
a GHashTable created with tp_asv_new()
|