![]() |
![]() |
![]() |
telepathy-glib Reference Manual | ![]() |
---|---|---|---|---|
#include <telepathy-glib/util.h> #define tp_verify (R) #define tp_verify_true (R) #define tp_verify_statement (R) void tp_g_hash_table_update (GHashTable *target, GHashTable *source, GBoxedCopyFunc key_dup, GBoxedCopyFunc value_dup); gboolean tp_g_ptr_array_contains (GPtrArray *haystack, gpointer needle); GValue* tp_g_value_slice_new (GType type); GValue* tp_g_value_slice_new_boolean (gboolean b); GValue* tp_g_value_slice_new_boxed (GType type, gconstpointer p); GValue* tp_g_value_slice_new_static_boxed (GType type, gconstpointer p); GValue* tp_g_value_slice_new_take_boxed (GType type, gpointer p); GValue* tp_g_value_slice_new_double (double d); GValue* tp_g_value_slice_new_int (gint n); GValue* tp_g_value_slice_new_int64 (gint64 n); GValue* tp_g_value_slice_new_string (const gchar *string); GValue* tp_g_value_slice_new_static_string (const gchar *string); GValue* tp_g_value_slice_new_take_string (gchar *string); GValue* tp_g_value_slice_new_uint (guint n); GValue* tp_g_value_slice_new_uint64 (guint64 n); void tp_g_value_slice_free (GValue *value); GValue* tp_g_value_slice_dup (const GValue *value); gboolean tp_strdiff (const gchar *left, const gchar *right); gpointer tp_mixin_offset_cast (gpointer instance, guint offset); guint tp_mixin_class_get_offset (gpointer klass, GQuark quark); guint tp_mixin_instance_get_offset (gpointer instance, GQuark quark); gchar* tp_escape_as_identifier (const gchar *name); gboolean tp_strv_contains (const gchar * const *strv, const gchar *str); gint64 tp_g_key_file_get_int64 (GKeyFile *key_file, const gchar *group_name, const gchar *key, GError **error); guint64 tp_g_key_file_get_uint64 (GKeyFile *key_file, const gchar *group_name, const gchar *key, GError **error);
Some utility functions used in telepathy-glib which could have been in GLib, but aren't.
# define tp_verify(R) extern int (* tp_verify_function__ (void)) [tp_verify_true (R)]
Make an assertion at compile time, like C++0x's proposed static_assert
keyword. If R
is determined to be true, there is no overhead at runtime;
if R
is determined to be false, compilation will fail.
This macro can be used at file scope (it expands to a dummy extern declaration).
(This is gnulib's verify macro, written by Paul Eggert, Bruno Haible and Jim Meyering.)
R : |
a requirement (constant expression) to be checked at compile-time |
#define tp_verify_true(R)
Make an assertion at compile time, like C++0x's proposed static_assert
keyword. If R
is determined to be true, there is no overhead at runtime,
and the macro evaluates to 1 as an integer constant expression;
if R
is determined to be false, compilation will fail.
This macro can be used anywhere that an integer constant expression would be allowed.
(This is gnulib's verify_true macro, written by Paul Eggert, Bruno Haible and Jim Meyering.)
R : |
a requirement (constant expression) to be checked at compile-time |
#define tp_verify_statement(R) ((void) tp_verify_true (R))
Make an assertion at compile time, like C++0x's proposed static_assert
keyword. If R
is determined to be true, there is no overhead at runtime;
if R
is determined to be false, compilation will fail.
This macro can be used anywhere that a statement would be allowed; it is equivalent to ((void) tp_verify_true (R)).
R : |
a requirement (constant expression) to be checked at compile-time |
void tp_g_hash_table_update (GHashTable *target, GHashTable *source, GBoxedCopyFunc key_dup, GBoxedCopyFunc value_dup);
Add each item in source
to target
, replacing any existing item with the
same key. key_dup
and value_dup
are used to duplicate the items; in
principle they could also be used to convert between types.
target : |
The hash table to be updated |
source : |
The hash table to update it with (read-only) |
key_dup : |
function to duplicate a key from source so it can be be stored
in target . If NULL, the key is not copied, but is used as-is
|
value_dup : |
function to duplicate a value from source so it can be stored
in target . If NULL, the value is not copied, but is used as-is
|
Since 0.7.0
gboolean tp_g_ptr_array_contains (GPtrArray *haystack, gpointer needle);
haystack : |
The pointer array to be searched |
needle : |
The pointer to look for |
Returns : | TRUE if needle is one of the elements of haystack
|
GValue* tp_g_value_slice_new (GType type);
Slice-allocate an empty GValue. tp_g_value_slice_new_boolean()
and similar
functions are likely to be more convenient to use for the types supported.
type : |
The type desired for the new GValue |
Returns : | a newly allocated, newly initialized GValue, to be freed with
tp_g_value_slice_free() or g_slice_free() .
|
Since 0.5.14
GValue* tp_g_value_slice_new_boolean (gboolean b);
Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.
b : |
a boolean value |
Returns : | a GValue of type G_TYPE_BOOLEAN with value b , to be freed with
tp_g_value_slice_free() or g_slice_free()
|
Since 0.7.27
GValue* tp_g_value_slice_new_boxed (GType type, gconstpointer p);
Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.
type : |
a boxed type |
p : |
a pointer of type type , which will be copied
|
Returns : | a GValue of type type whose value is a copy of p ,
to be freed with tp_g_value_slice_free() or g_slice_free()
|
Since 0.7.27
GValue* tp_g_value_slice_new_static_boxed (GType type, gconstpointer p);
Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.
type : |
a boxed type |
p : |
a pointer of type type , which must remain valid forever
|
Returns : | a GValue of type type whose value is p ,
to be freed with tp_g_value_slice_free() or g_slice_free()
|
Since 0.7.27
GValue* tp_g_value_slice_new_take_boxed (GType type, gpointer p);
Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.
type : |
a boxed type |
p : |
a pointer of type type which will be freed with g_boxed_free() by the
returned GValue (the caller must own it before calling this function, but
no longer owns it after this function returns)
|
Returns : | a GValue of type type whose value is p ,
to be freed with tp_g_value_slice_free() or g_slice_free()
|
Since 0.7.27
GValue* tp_g_value_slice_new_double (double d);
Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.
d : |
a number |
Returns : | a GValue of type G_TYPE_DOUBLE with value n , to be freed with
tp_g_value_slice_free() or g_slice_free()
|
Since 0.7.27
GValue* tp_g_value_slice_new_int (gint n);
Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.
n : |
an integer |
Returns : | a GValue of type G_TYPE_INT with value n , to be freed with
tp_g_value_slice_free() or g_slice_free()
|
Since 0.7.27
GValue* tp_g_value_slice_new_int64 (gint64 n);
Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.
n : |
a 64-bit integer |
Returns : | a GValue of type G_TYPE_INT64 with value n , to be freed with
tp_g_value_slice_free() or g_slice_free()
|
Since 0.7.27
GValue* tp_g_value_slice_new_string (const gchar *string);
Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.
string : |
a string to be copied into the value |
Returns : | a GValue of type G_TYPE_STRING whose value is a copy of string ,
to be freed with tp_g_value_slice_free() or g_slice_free()
|
Since 0.7.27
GValue* tp_g_value_slice_new_static_string (const gchar *string);
Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.
string : |
a static string which must remain valid forever, to be pointed to by the value |
Returns : | a GValue of type G_TYPE_STRING whose value is string ,
to be freed with tp_g_value_slice_free() or g_slice_free()
|
Since 0.7.27
GValue* tp_g_value_slice_new_take_string (gchar *string);
Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.
string : |
a string which will be freed with g_free() by the returned GValue
(the caller must own it before calling this function, but no longer owns
it after this function returns)
|
Returns : | a GValue of type G_TYPE_STRING whose value is string ,
to be freed with tp_g_value_slice_free() or g_slice_free()
|
Since 0.7.27
GValue* tp_g_value_slice_new_uint (guint n);
Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.
n : |
an unsigned integer |
Returns : | a GValue of type G_TYPE_UINT with value n , to be freed with
tp_g_value_slice_free() or g_slice_free()
|
Since 0.7.27
GValue* tp_g_value_slice_new_uint64 (guint64 n);
Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.
n : |
a 64-bit unsigned integer |
Returns : | a GValue of type G_TYPE_UINT64 with value n , to be freed with
tp_g_value_slice_free() or g_slice_free()
|
Since 0.7.27
void tp_g_value_slice_free (GValue *value);
Unset and free a slice-allocated GValue.
(GDestroyNotify) tp_g_value_slice_free
can be used
as a destructor for values in a GHashTable, for example.
value : |
A GValue which was allocated with the g_slice API |
GValue* tp_g_value_slice_dup (const GValue *value);
value : |
A GValue |
Returns : | a newly allocated copy of value , to be freed with
tp_g_value_slice_free() or g_slice_free() .
|
Since 0.5.14
gboolean tp_strdiff (const gchar *left, const gchar *right);
Return TRUE
if the given strings are different. Unlike strcmp this
function will handle null pointers, treating them as distinct from any
string.
left : |
The first string to compare (may be NULL) |
right : |
The second string to compare (may be NULL) |
Returns : | FALSE if left and right are both NULL , or if
neither is NULL and both have the same contents; TRUE otherwise
|
gpointer tp_mixin_offset_cast (gpointer instance, guint offset);
Extend a pointer by an offset, provided the offset is not 0. This is used to cast from an object instance to one of the telepathy-glib mixin classes.
instance : |
A pointer to a structure |
offset : |
The offset of a structure member in bytes, which must not be 0 |
Returns : | a pointer offset bytes beyond instance
|
guint tp_mixin_class_get_offset (gpointer klass, GQuark quark);
If the type of klass
, or any of its ancestor types, has had an offset
attached using qdata with the given quark
, return that offset. If not,
this indicates a programming error and results are undefined.
This is used to implement the telepathy-glib mixin classes.
klass : |
A pointer to a GObjectClass-derived class structure |
quark : |
A quark that was used to store the offset with g_type_set_qdata()
|
Returns : | the offset of the mixin class |
guint tp_mixin_instance_get_offset (gpointer instance, GQuark quark);
If the type of instance
, or any of its ancestor types, has had an offset
attached using qdata with the given quark
, return that offset. If not,
this indicates a programming error and results are undefined.
This is used to implement the telepathy-glib mixin classes.
instance : |
A pointer to a GObject-derived instance structure |
quark : |
A quark that was used to store the offset with g_type_set_qdata()
|
Returns : | the offset of the mixin |
gchar* tp_escape_as_identifier (const gchar *name);
Escape an arbitrary string so it follows the rules for a C identifier, and hence an object path component, interface element component, bus name component or member name in D-Bus.
Unlike g_strcanon this is a reversible encoding, so it preserves distinctness.
The escaping consists of replacing all non-alphanumerics, and the first character if it's a digit, with an underscore and two lower-case hex digits:
"0123abc_xyz\x01\xff" -> _30123abc_5fxyz_01_ff
i.e. similar to URI encoding, but with _ taking the role of %, and a smaller allowed set. As a special case, "" is escaped to "_" (just for completeness, really).
name : |
The string to be escaped |
Returns : | the escaped string, which must be freed by the caller with g_free |
gboolean tp_strv_contains (const gchar * const *strv, const gchar *str);
strv : |
a NULL-terminated array of strings, or NULL (which is treated as an
empty strv)
|
str : |
a non-NULL string |
Returns : | TRUE if str is an element of strv , according to strcmp() .
|
Since 0.7.15
gint64 tp_g_key_file_get_int64 (GKeyFile *key_file, const gchar *group_name, const gchar *key, GError **error);
Returns the value associated with key
under group_name
as a signed
64-bit integer. This is similar to g_key_file_get_integer()
but can return
64-bit results without truncation.
key_file : |
a non-NULL GKeyFile
|
group_name : |
a non-NULL group name
|
key : |
a non-NULL key
|
error : |
return location for a GError |
Returns : | the value associated with the key as a signed 64-bit integer, or 0 if the key was not found or could not be parsed. |
Since 0.7.31
guint64 tp_g_key_file_get_uint64 (GKeyFile *key_file, const gchar *group_name, const gchar *key, GError **error);
Returns the value associated with key
under group_name
as an unsigned
64-bit integer. This is similar to g_key_file_get_integer()
but can return
large positive results without truncation.
key_file : |
a non-NULL GKeyFile
|
group_name : |
a non-NULL group name
|
key : |
a non-NULL key
|
error : |
return location for a GError |
Returns : | the value associated with the key as an unsigned 64-bit integer, or 0 if the key was not found or could not be parsed. |
Since 0.7.31