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

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

Owner: TpDynamicHandleRepo

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

Owner: TpDynamicHandleRepo

Flags: Read / Write / Construct Only

## See Also

TpHandleRepoIface, TpStaticHandleRepo