 |
 |
 |
telepathy-glib API Reference Manual |  |
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Implemented Interfaces | Properties | ||||
TpDynamicHandleRepoTpDynamicHandleRepo — general handle repository implementation, with dynamic handle allocation and recycling |
Synopsis
#include <telepathy-glib/telepathy-glib.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);
void tp_dynamic_handle_repo_set_normalize_async
(TpDynamicHandleRepo *self,
TpDynamicHandleRepoNormalizeAsync normalize_async,
TpDynamicHandleRepoNormalizeFinish normalize_finish);
gchar * (*TpDynamicHandleRepoNormalizeFunc) (TpHandleRepoIface *repo,
const gchar *id,
gpointer context,
GError **error);
void (*TpDynamicHandleRepoNormalizeAsync)
(TpHandleRepoIface *repo,
TpBaseConnection *connection,
const gchar *id,
gpointer context,
GAsyncReadyCallback callback,
gpointer user_data);
gchar * (*TpDynamicHandleRepoNormalizeFinish)
(TpHandleRepoIface *repo,
GAsyncResult *result,
GError **error);
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_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.
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).
|
The handle repository |
|
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);
|
The handle type |
|
The function to be used to normalize and validate handles,
or NULL to accept all handles as-is |
|
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().
|
A TpDynamicHandleRepo |
|
a TpDynamicHandleRepoNormalizeAsync |
|
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.
|
The repository on which tp_handle_lookup() or tp_handle_ensure()
was called |
|
The name to be normalized |
|
Arbitrary context passed to tp_handle_lookup() or
tp_handle_ensure()
|
|
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().
|
The repository on which tp_handle_ensure_async() was called |
|
the TpBaseConnection using this handle repo |
|
The name to be normalized |
|
Arbitrary context passed to tp_handle_ensure_async()
|
|
a callback to call when the operation finishes |
|
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.
|
The repository on which tp_handle_ensure_async() was called |
|
a GAsyncResult |
|
a GError to fill |
Since 0.19.2
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).