Top |
Some utility functions used in telepathy-glib which could have been in GLib, but aren't.
#define tp_verify(R) G_STATIC_ASSERT (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.)
This macro will be deprecated in a future telepathy-glib release. Please
use GLib 2.20's G_STATIC_ASSERT()
macro in new code.
Since: 0.7.34
#define tp_verify_true(R) (((void) G_STATIC_ASSERT_EXPR (R)), 1)
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.)
This macro will be deprecated in a future telepathy-glib release. Please
use GLib 2.20's G_STATIC_ASSERT()
macro in new code.
Since: 0.7.34
#define tp_verify_statement(R) ((void) G_STATIC_ASSERT_EXPR (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)).
This macro will be deprecated in a future telepathy-glib release. Please
use GLib 2.20's G_STATIC_ASSERT()
macro in new code.
Since: 0.7.34
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.
[skip]
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 |
|
value_dup |
function to duplicate a value from |
Since: 0.7.0
gboolean tp_g_ptr_array_contains (GPtrArray *haystack
,gpointer needle
);
[skip]
void tp_g_ptr_array_extend (GPtrArray *target
,GPtrArray *source
);
Appends all elements of source
to target
. Note that this only copies the
pointers from source
; any duplication or reference-incrementing must be
performed by the caller.
After this function has been called, it is safe to call
g_ptr_array_free()
on source
and also free the actual pointer array,
as long as doing so does not free the data pointed to by the new
items in target
.
[skip]
Since: 0.14.3
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.
[skip]
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.
[skip]
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.
[skip]
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.
[skip]
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.
[skip]
type |
a boxed type |
|
p |
a pointer of type |
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.
[skip]
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.
[skip]
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.
[skip]
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.
[skip]
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.
[skip]
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.
[skip]
string |
a string which will be freed with |
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.
[skip]
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.
[skip]
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
GValue *
tp_g_value_slice_new_byte (guchar n
);
Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.
[skip]
a GValue of type G_TYPE_UCHAR
with value n
, to be freed with
tp_g_value_slice_free()
or g_slice_free()
Since: 0.11.0
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.
[skip]
GValue *
tp_g_value_slice_dup (const GValue *value
);
[skip]
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_str_empty (const gchar *s
);
Return TRUE
if s
is empty, counting NULL
as empty.
[skip]
Since: 0.11.1
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.
[skip]
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.
[skip]
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,
return 0.
In older telepathy-glib versions, calling this function on an instance that did not have the mixin was considered to be a programming error. Since version 0.13.9, 0 is returned, without error.
This is used to implement the telepathy-glib mixin classes.
[skip]
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,
return 0.
In older telepathy-glib versions, calling this function on an instance that did not have the mixin was considered to be a programming error. Since version 0.13.9, 0 is returned, without error.
This is used to implement the telepathy-glib mixin classes.
[skip]
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).
gboolean tp_strv_contains (const gchar * const *strv
,const gchar *str
);
[skip]
strv |
a NULL-terminated array of strings, or |
|
str |
a non-NULL string |
Since: 0.7.15
gint64 tp_g_key_file_get_int64 (GKeyFile *key_file
,const gchar *group_name
,const gchar *key
,GError **error
);
tp_g_key_file_get_int64
is deprecated and should not be used in newly-written code.
Since 0.21.0. Use g_key_file_get_int64()
instead.
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.
[skip]
key_file |
a non- |
|
group_name |
a non- |
|
key |
a non- |
|
error |
return location for a GError |
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
);
tp_g_key_file_get_uint64
is deprecated and should not be used in newly-written code.
Since 0.21.0. Use g_key_file_get_uint64()
instead.
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.
[skip]
key_file |
a non- |
|
group_name |
a non- |
|
key |
a non- |
|
error |
return location for a GError |
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
gulong tp_g_signal_connect_object (gpointer instance
,const gchar *detailed_signal
,GCallback c_handler
,gpointer gobject
,GConnectFlags connect_flags
);
Connects a GCallback function to a signal for a particular object, as if
with g_signal_connect()
. Additionally, arranges for the signal handler to be
disconnected if gobject
is destroyed.
This is similar to g_signal_connect_data()
, but uses a closure which
ensures that the gobject
stays alive during the call to c_handler
by temporarily adding a reference count to gobject
.
This is similar to g_signal_connect_object()
, but doesn't have the
documented bug that everyone is too scared to fix. Also, it does not allow
you to pass in NULL as gobject
This is intended to be a convenient way for objects to use themselves as user_data for callbacks without having to explicitly disconnect all the handlers in their finalizers.
Changed in 0.10.4 and 0.11.3: G_CONNECT_AFTER
is now respected.
[skip]
instance |
the instance to connect to. |
|
detailed_signal |
a string of the form "signal-name::detail". |
|
c_handler |
the GCallback to connect. |
|
gobject |
the object to pass as data to |
|
connect_flags |
a combination of GConnectFlags. Only
|
Since: 0.9.2
GValueArray * tp_value_array_build (gsize length
,GType type
,...
);
Creates a new GValueArray for use with structs, containing the values passed in as parameters. The values are copied or reffed as appropriate for their type.
Example 3. using tp_value_array_build
1 2 3 4 |
GValueArray *array = tp_value_array_build (2, G_TYPE_STRING, host, G_TYPE_UINT, port, G_TYPE_INVALID); |
[skip]
length |
The number of elements that should be in the array |
|
type |
The type of the first argument. |
|
... |
The value of the first item in the struct followed by a list of type, value pairs terminated by G_TYPE_INVALID. |
Since: 0.9.2
void tp_value_array_unpack (GValueArray *array
,gsize len
,...
);
Unpacks a GValueArray into separate variables.
The contents of the values aren't copied into the variables, and so become
invalid when array
is freed.
Example 4. using tp_value_array_unpack
1 2 3 4 5 6 |
const gchar *host; guint port; tp_value_array_unpack (array, 2, &host, &port); |
[skip]
array |
the array to unpack |
|
len |
The number of elements that should be in the array |
|
... |
a list of correctly typed pointers to store the values in |
Since: 0.11.0
void
tp_value_array_free (GValueArray *va
);
Free va
. This is exactly the same as g_value_array_free()
, but does not
provoke deprecation warnings from GLib when used in conjunction with
tp_value_array_build()
and tp_value_array_unpack()
.
Since: 0.23.0
TpWeakRef * tp_weak_ref_new (gpointer object
,gpointer user_data
,GDestroyNotify destroy
);
Return a new weak reference wrapper for object
.
[skip]
object |
an object to which to take a weak reference. |
[type GObject.Object] |
user_data |
optional additional data to store alongside the weak ref |
|
destroy |
destructor for |
Since: 0.11.3
gpointer
tp_weak_ref_dup_object (TpWeakRef *self
);
If the weakly referenced object still exists, return a new reference to
it. Otherwise, return NULL
.
[skip]
Since: 0.11.3
gpointer
tp_weak_ref_get_user_data (TpWeakRef *self
);
Return the additional data that was passed to tp_weak_ref_new()
.
[skip]
Since: 0.11.3
void
tp_weak_ref_destroy (TpWeakRef *self
);
Free a weak reference wrapper. This drops the weak reference to the object (if it still exists), and frees the user data with the user-supplied destructor function if one was provided.
[skip]
Since: 0.11.3
#define tp_clear_pointer(pp, destroy)
Set a variable holding a pointer to NULL
. If it was not already NULL
,
unref or destroy the object it previously pointed to with destroy
.
More precisely, if *pp
is non-NULL
, set *pp
to NULL
, then
call destroy
on the object that *pp
previously pointed to.
This is analogous to g_clear_error()
for non-error objects, but also
ensures that pp
is already NULL
before the destructor is run.
Typical usage is something like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
typedef struct { TpConnection *conn; GError *error; GHashTable *table; MyStruct *misc; } Foo; Foo *foo; ... tp_clear_object (&foo->conn); g_clear_error (&foo->error); tp_clear_boxed (G_TYPE_HASH_TABLE, &foo->table); tp_clear_pointer (&foo->misc, my_struct_destroy); |
pp |
a pointer to a variable, struct member etc. holding a pointer |
|
destroy |
a function to which a gpointer can be passed, to destroy * |
Since: 0.11.7
#define tp_clear_object(op) tp_clear_pointer ((op), g_object_unref)
Set a variable holding a GObject to NULL
. If it was not already NULL
,
unref the object it previously pointed to.
This is exactly equivalent to calling tp_clear_pointer()
on op
,
with destroy
= g_object_unref()
. See tp_clear_pointer()
for example usage.
Since: 0.11.7
#define tp_clear_boxed(gtype, pp)
Set a variable holding a boxed object to NULL
. If it was not already NULL
,
destroy the boxed object it previously pointed to, as appropriate for
gtype
.
More precisely, if *pp
is non-NULL
, set *pp
to NULL
, then
call g_boxed_free()
on the object that *pp
previously pointed to.
This is similar to tp_clear_pointer()
; see that function's documentation
for typical usage.
gtype |
the GType of * |
[type GObject.Type] |
pp |
a pointer to a variable, struct member etc. holding a boxed object |
Since: 0.11.7
void tp_simple_async_report_success_in_idle (GObject *source
,GAsyncReadyCallback callback
,gpointer user_data
,gpointer source_tag
);
Create a new GSimpleAsyncResult with no operation result, and call
g_simple_async_result_complete_in_idle()
on it.
This is like a successful version of g_simple_async_report_error_in_idle()
,
suitable for asynchronous functions that (conceptually) either succeed and
return nothing, or raise an error, such as tp_proxy_prepare_async()
.
The corresponding finish function should not call a function that attempts
to get a result, such as g_simple_async_result_get_op_res_gpointer()
.
source |
the source object. |
[allow-none] |
callback |
the callback. |
[scope async] |
user_data |
user data for |
[closure] |
source_tag |
the source tag for the GSimpleAsyncResult |
Since: 0.11.9
gint64
tp_user_action_time_from_x11 (guint32 x11_time
);
Convert an X11 timestamp into a user action time as used in Telepathy.
This also works for the timestamps used by GDK 2, GDK 3 and Clutter 1.0; it may or may not work with other toolkits or versions.
Since: 0.11.13
gboolean tp_user_action_time_should_present (gint64 user_action_time
,guint32 *x11_time
);
Interpret a Telepathy user action time to decide whether a Handler should
attempt to gain focus. If TRUE
is returned, it would be appropriate to
call gtk_window_present_with_time()
using x11_time
as input, for instance.
x11_time
is used to return a timestamp in the right format for X11,
GDK 2, GDK 3 and Clutter 1.0; it may or may not work with other
toolkits or versions.
user_action_time |
the Telepathy user action time. |
[type gint64] |
x11_time |
a pointer to guint32 used to
return an X11 timestamp, or 0 to indicate the current time; if
|
[out][allow-none] |
Since: 0.11.13
gchar *
tp_utf8_make_valid (const gchar *name
);
Validate that the provided string is valid UTF8. If not, replace all invalid bytes with unicode replacement character (U+FFFD).
This method is a verbatim copy of glib's internal _g_utf8_make_valid() function, and will be deprecated as soon as the glib one becomes public.
Since: 0.13.15
typedef struct _TpWeakRef TpWeakRef;
A simple wrapper for a weak reference to a GObject, suitable for use in asynchronous calls which should only affect the object if it hasn't already been freed.
As well as wrapping a weak reference to an object, this structure can contain an extra pointer to arbitrary data. This is useful for asynchronous calls which act on an object and some second piece of data, which are quite common in practice.
If more than one piece of auxiliary data is required, the user_data
argument to the constructor can be a struct or a GValueArray.
Since: 0.11.3