TpDynamicHandleRepo

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

Synopsis


#include <telepathy-glib/handle-repo-dynamic.h>

                    TpDynamicHandleRepo;
                    TpDynamicHandleRepoClass;
TpHandle            tp_dynamic_handle_repo_lookup_exact (TpHandleRepoIface *irepo,
                                                         const char *id);
TpHandleRepoIface*  tp_dynamic_handle_repo_new          (TpHandleType handle_type,
                                                         TpDynamicHandleRepoNormalizeFunc normalize_func,
                                                         gpointer default_normalize_context);
gchar*              (*TpDynamicHandleRepoNormalizeFunc) (TpHandleRepoIface *repo,
                                                         const gchar *id,
                                                         gpointer context,
                                                         GError **error);

Object Hierarchy

  GObject
   +----TpDynamicHandleRepo

Implemented Interfaces

TpDynamicHandleRepo implements TpHandleRepoIface.

Properties

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

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

Details

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.


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

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

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

TpDynamicHandleRepoNormalizeFunc ()

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

Signature of the normalization function optionally used by TpDynamicHandleRepo instances.

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

Property Details

The "default-normalize-context" property

  "default-normalize-context" gpointer              : Read / Write / Construct Only

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.


The "normalize-function" property

  "normalize-function"       gpointer              : Read / Write / Construct Only

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

See Also

TpHandleRepoIface, TpStaticHandleRepo