Utilities

Utilities — Non-Telepathy utility functions

Functions

Types and Values

Object Hierarchy


Includes

#include <telepathy-glib/telepathy-glib.h>

Description

Some utility functions used in telepathy-glib which could have been in GLib, but aren't.

Functions

tp_g_hash_table_update ()

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.

Parameters

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


tp_g_ptr_array_contains ()

gboolean
tp_g_ptr_array_contains (GPtrArray *haystack,
                         gpointer needle);

Parameters

haystack

The pointer array to be searched

 

needle

The pointer to look for

 

Returns

TRUE if needle is one of the elements of haystack


tp_g_ptr_array_extend ()

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 .

Parameters

target

a GPtrArray to copy items to

 

source

a GPtrArray to copy items from

 

Since 0.14.3


tp_str_empty ()

gboolean
tp_str_empty (const gchar *s);

Return TRUE if s is empty, counting NULL as empty.

Parameters

s

a string.

[type utf8][transfer none]

Returns

TRUE if s is either NULL or "".

[type boolean]

Since 0.11.1


tp_strdiff ()

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.

Parameters

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


tp_mixin_offset_cast ()

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.

Parameters

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


tp_mixin_class_get_offset ()

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.

Parameters

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


tp_mixin_instance_get_offset ()

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.

Parameters

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


tp_escape_as_identifier ()

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).

Parameters

name

The string to be escaped

 

Returns

the escaped string, which must be freed by the caller with g_free.

[transfer full]


tp_strv_contains ()

gboolean
tp_strv_contains (const gchar * const *strv,
                  const gchar *str);

Parameters

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


tp_g_signal_connect_object ()

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.

Parameters

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 c_handler .

 

connect_flags

a combination of GConnectFlags. Only G_CONNECT_AFTER and G_CONNECT_SWAPPED are supported by this function.

 

Returns

the handler id

Since 0.9.2


tp_weak_ref_new ()

TpWeakRef *
tp_weak_ref_new (gpointer object,
                 gpointer user_data,
                 GDestroyNotify destroy);

Return a new weak reference wrapper for object .

Parameters

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 user_data , called when the weak ref is freed

 

Returns

a new weak-reference wrapper

Free-function: tp_weak_ref_destroy().

[transfer full]

Since 0.11.3


tp_weak_ref_dup_object ()

gpointer
tp_weak_ref_dup_object (TpWeakRef *self);

If the weakly referenced object still exists, return a new reference to it. Otherwise, return NULL.

Parameters

self

a weak reference

 

Returns

a new reference, or NULL.

[type GObject.Object][transfer full]

Since 0.11.3


tp_weak_ref_get_user_data ()

gpointer
tp_weak_ref_get_user_data (TpWeakRef *self);

Return the additional data that was passed to tp_weak_ref_new().

Parameters

self

a weak reference

 

Returns

the additional data supplied in tp_weak_ref_new(), which may be NULL

Since 0.11.3


tp_weak_ref_destroy ()

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.

Parameters

self

a weak reference.

[transfer full]

Since 0.11.3


tp_clear_pointer()

#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);

Parameters

pp

a pointer to a variable, struct member etc. holding a pointer

 

destroy

a function to which a gpointer can be passed, to destroy *pp (if calling this macro from C++, explicitly casting the function to GDestroyNotify may be necessary)

 

Since 0.11.7


tp_clear_object()

#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.

Parameters

op

a pointer to a variable, struct member etc. holding a GObject

 

Since 0.11.7


tp_clear_boxed()

#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.

Parameters

gtype

the GType of *pp , e.g. G_TYPE_HASH_TABLE.

[type GObject.Type]

pp

a pointer to a variable, struct member etc. holding a boxed object

 

Since 0.11.7


tp_simple_async_report_success_in_idle ()

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().

Parameters

source

the source object.

[allow-none]

callback

the callback.

[scope async]

user_data

user data for callback .

[closure]

source_tag

the source tag for the GSimpleAsyncResult

 

Since 0.11.9


tp_user_action_time_from_x11 ()

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.

Parameters

x11_time

an X11 timestamp, or 0 to indicate the current time

 

Returns

a nonzero Telepathy user action time, or TP_USER_ACTION_TIME_CURRENT_TIME

Since 0.11.13


tp_user_action_time_should_present ()

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.

Parameters

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 FALSE is returned, the value placed here is not meaningful.

[out][allow-none]

Returns

TRUE if it would be appropriate to present a window

Since 0.11.13


tp_utf8_make_valid ()

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.

Parameters

name

string to coerce into UTF8

 

Returns

a new valid UTF8 string.

[transfer full]

Since 0.13.15

Types and Values

TpWeakRef

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.

Since 0.11.3