![]() |
![]() |
![]() |
telepathy-glib 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 |
#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.
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
|
Returns : |
a boolean value for key
|
Since 0.7.9
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
);
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
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
);
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. |
Since 0.7.9
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
);
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
|
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
);
|
|
|
|
|
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
|
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
);
|
|
|
|
|
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
|
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
);
|
|
|
|
|
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
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
);
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
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
);
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
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
);
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
|
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
);
|
|
|
|
|
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
|
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
);
|
|
|
|
|
const GValue * tp_asv_lookup (const GHashTable *asv
,const gchar *key
);
|
|
|
|
Returns : |