TpDynamicHandleRepo: telepathy-glib API Reference Manual

TpDynamicHandleRepo

TpDynamicHandleRepo — general handle repository implementation, with dynamic handle allocation and recycling

Functions

TpHandle	tp_dynamic_handle_repo_lookup_exact ()
TpHandleRepoIface *	tp_dynamic_handle_repo_new ()
void	tp_dynamic_handle_repo_set_normalize_async ()
gchar *	(*TpDynamicHandleRepoNormalizeFunc) ()
void	(*TpDynamicHandleRepoNormalizeAsync) ()
gchar *	(*TpDynamicHandleRepoNormalizeFinish) ()

Properties

gpointer	default-normalize-context	Read / Write / Construct Only
gpointer	normalize-function	Read / Write / Construct Only

Types and Values

	TpDynamicHandleRepo
	TpDynamicHandleRepoClass

Object Hierarchy

    GObject
    ╰── TpDynamicHandleRepo

Implemented Interfaces

TpDynamicHandleRepo implements TpHandleRepoIface.

Includes

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

Description

A dynamic handle repository will accept arbitrary handles, which can be created and destroyed at runtime.

The “handle-type” property must be set at construction time; the “normalize-function” property may be set to perform validation and normalization on handle ID strings.

Most connection managers will use this for all supported handle types except TP_HANDLE_TYPE_LIST.

Changed in 0.13.8: handles are no longer reference-counted, and the reference-count-related functions are stubs. Instead, handles remain valid until the handle repository is destroyed.

Functions

tp_dynamic_handle_repo_lookup_exact ()

TpHandle
tp_dynamic_handle_repo_lookup_exact (TpHandleRepoIface *irepo,
                                     const char *id);

Look up a name in the repository, returning the corresponding handle if it is present in the repository, without creating a new reference.

Unlike tp_handle_lookup() this function does not perform any normalization; it just looks for the literal string you requested. This can be useful to call from normalization callbacks (for instance, Gabble's contacts repository uses it to see whether we already know that a JID belongs to a multi-user chat room member).

Parameters

irepo	The handle repository
id	The name to be looked up

Returns

the handle corresponding to the given ID, or 0 if not present

tp_dynamic_handle_repo_new ()

TpHandleRepoIface *
tp_dynamic_handle_repo_new (TpHandleType handle_type,
                            TpDynamicHandleRepoNormalizeFunc normalize_func,
                            gpointer default_normalize_context);

Parameters

handle_type	The handle type
normalize_func	The function to be used to normalize and validate handles, or `NULL` to accept all handles as-is
default_normalize_context	The context pointer to be passed to the `normalize_func` if a `NULL` context is passed to `tp_handle_lookup()` and `tp_handle_ensure()`; this may itself be `NULL`

Returns

a new dynamic handle repository

tp_dynamic_handle_repo_set_normalize_async ()

void
tp_dynamic_handle_repo_set_normalize_async
                               (TpDynamicHandleRepo *self,
                                TpDynamicHandleRepoNormalizeAsync normalize_async,
                                TpDynamicHandleRepoNormalizeFinish normalize_finish);

Set an asynchronous normalization function. This is to be used if handle normalization requires a server round-trip. See tp_handle_ensure_async().

Parameters

self	A TpDynamicHandleRepo
normalize_async	a TpDynamicHandleRepoNormalizeAsync
normalize_finish	a TpDynamicHandleRepoNormalizeFinish

Since: 0.19.2

TpDynamicHandleRepoNormalizeFunc ()

gchar *
(*TpDynamicHandleRepoNormalizeFunc) (TpHandleRepoIface *repo,
                                     const gchar *id,
                                     gpointer context,
                                     GError **error);

Signature of the normalization function optionally used by TpDynamicHandleRepo instances.

Parameters

repo	The repository on which `tp_handle_lookup()` or `tp_handle_ensure()` was called
id	The name to be normalized
context	Arbitrary context passed to `tp_handle_lookup()` or `tp_handle_ensure()`
error	Used to raise the Telepathy error InvalidHandle with an appropriate message if NULL is returned

Returns

a normalized version of id (to be freed with g_free by the caller), or NULL if id is not valid for this repository

TpDynamicHandleRepoNormalizeAsync ()

void
(*TpDynamicHandleRepoNormalizeAsync) (TpHandleRepoIface *repo,
                                      TpBaseConnection *connection,
                                      const gchar *id,
                                      gpointer context,
                                      GAsyncReadyCallback callback,
                                      gpointer user_data);

Signature of a function to asynchronously normalize an identifier. See tp_dynamic_handle_repo_set_normalize_async().

Parameters

repo	The repository on which `tp_handle_ensure_async()` was called
connection	the TpBaseConnection using this handle repo
id	The name to be normalized
context	Arbitrary context passed to `tp_handle_ensure_async()`
callback	a callback to call when the operation finishes
user_data	data to pass to `callback`

Since: 0.19.2

TpDynamicHandleRepoNormalizeFinish ()

gchar *
(*TpDynamicHandleRepoNormalizeFinish) (TpHandleRepoIface *repo,
                                       GAsyncResult *result,
                                       GError **error);

Signature of a function to finish the operation started with TpDynamicHandleRepoNormalizeAsync.

Parameters

repo	The repository on which `tp_handle_ensure_async()` was called
result	a GAsyncResult
error	a GError to fill

Since: 0.19.2

Types and Values