Utilities

## Utilities Utilities — Non-Telepathy utility functions |

## Synopsis

    #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);
    void                tp_g_ptr_array_extend               (GPtrArray *target,
                                                             GPtrArray *source);
    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);
    GValue *            tp_g_value_slice_new_byte           (guchar n);
    void                tp_g_value_slice_free               (GValue *value);
    GValue *            tp_g_value_slice_dup                (const GValue *value);
    gboolean            tp_str_empty                        (const gchar *s);
    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);
    gulong              tp_g_signal_connect_object          (gpointer instance,
                                                             const gchar *detailed_signal,
                                                             GCallback c_handler,
                                                             gpointer gobject,
                                                             GConnectFlags connect_flags);
    GValueArray *       tp_value_array_build                (gsize length,
                                                             GType type,
                                                             ...);
    void                tp_value_array_unpack               (GValueArray *array,
                                                             gsize len,
                                                             ...);
                        TpWeakRef;
    TpWeakRef *         tp_weak_ref_new                     (gpointer object,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy);
    gpointer            tp_weak_ref_dup_object              (TpWeakRef *self);
    gpointer            tp_weak_ref_get_user_data           (TpWeakRef *self);
    void                tp_weak_ref_destroy                 (TpWeakRef *self);
    #define             tp_clear_pointer                    (pp,
                                                             destroy)
    #define             tp_clear_object                     (op)
    #define             tp_clear_boxed                      (gtype,
                                                             pp)
    void                tp_simple_async_report_success_in_idle
                                                            (GObject *source,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data,
                                                             gpointer source_tag);
    gint64              tp_user_action_time_from_x11        (guint32 x11_time);
    gboolean            tp_user_action_time_should_present  (gint64 user_action_time,
                                                             guint32 *x11_time);
    gchar *             tp_utf8_make_valid                  (const gchar *name);

## Description

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

## Details

### tp_verify()

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

This macro will be deprecated in a future telepathy-glib release. Please use GLib 2.20's `G_STATIC_ASSERT()` macro in new code.

`R` : | a requirement (constant expression) to be checked at compile-time

Since 0.7.34

### tp_verify_true()

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

This macro will be deprecated in a future telepathy-glib release. Please use GLib 2.20's `G_STATIC_ASSERT()` macro in new code.

`R` : | a requirement (constant expression) to be checked at compile-time
Returns : | 1

Since 0.7.34

### tp_verify_statement()

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

This macro will be deprecated in a future telepathy-glib release. Please use GLib 2.20's `G_STATIC_ASSERT()` macro in new code.

`R` : | a requirement (constant expression) to be checked at compile-time

Since 0.7.34

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

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

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

`target` : | a GPtrArray to copy items to
`source` : | a GPtrArray to copy items from

Since 0.14.3

### tp_g_value_slice_new ()

    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

### tp_g_value_slice_new_boolean ()

    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

### tp_g_value_slice_new_boxed ()

    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

### tp_g_value_slice_new_static_boxed ()

    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

### tp_g_value_slice_new_take_boxed ()

    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

### tp_g_value_slice_new_double ()

    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

### tp_g_value_slice_new_int ()

    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

### tp_g_value_slice_new_int64 ()

    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

### tp_g_value_slice_new_string ()

    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

### tp_g_value_slice_new_static_string ()

    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

### tp_g_value_slice_new_take_string ()

    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

### tp_g_value_slice_new_uint ()

    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

### tp_g_value_slice_new_uint64 ()

    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

### tp_g_value_slice_new_byte ()

    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.

`n` : | an unsigned integer
Returns : | 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

### tp_g_value_slice_free ()

    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

### tp_g_value_slice_dup ()

    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

### tp_str_empty ()

    gboolean            tp_str_empty                        (const gchar *s);

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

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

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

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

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

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

`name` : | The string to be escaped
Returns : | the escaped string, which must be freed by the caller with g_free

### tp_strv_contains ()

    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

### tp_g_key_file_get_int64 ()

    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

### tp_g_key_file_get_uint64 ()

    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

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

`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_value_array_build ()

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

`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.
Returns : | a newly created GValueArray, free with g_value_array_free.

Since 0.9.2

### tp_value_array_unpack ()

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

`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

### 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 or a GValueArray.

Since 0.11.3

### tp_weak_ref_new ()

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

Return a new weak reference wrapper for `object`.

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

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

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

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

`self` : | a weak reference

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

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

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

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

`source` : | the source object
`callback` : | the callback
`user_data` : | user data for `callback`
`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.x and Clutter 1.0; it may or may not work with other toolkits or versions.

`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.x 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 `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.

`name` : | string to coerce into UTF8
Returns : | a new valid UTF8 string

Since 0.13.15