TpDynamicHandleRepo

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

Functions

Properties

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

Types and Values

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 “entity-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 entity types except TP_ENTITY_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 (TpEntityType entity_type,
                            TpDynamicHandleRepoNormalizeFunc normalize_func,
                            gpointer default_normalize_context);

Parameters

entity_type

The entity 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

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

TpDynamicHandleRepo

typedef struct _TpDynamicHandleRepo TpDynamicHandleRepo;

A dynamic handle repository. The contents of the struct are private.


TpDynamicHandleRepoClass

typedef struct _TpDynamicHandleRepoClass TpDynamicHandleRepoClass;

The class of a dynamic handle repository. The contents of the struct are private.

Property Details

The “default-normalize-context” property

  “default-normalize-context” gpointer

An optional default context given to the “normalize-function” if NULL is passed as context to the ensure or lookup functions, e.g. when RequestHandle is called via D-Bus. The default is NULL.

Flags: Read / Write / Construct Only


The “normalize-function” property

  “normalize-function”       gpointer

An optional TpDynamicHandleRepoNormalizeFunc used to validate and normalize handle IDs. If NULL (which is the default), any handle ID is accepted as-is (equivalent to supplying a pointer to a function that just calls g_strdup).

Flags: Read / Write / Construct Only

See Also

TpHandleRepoIface, TpStaticHandleRepo