## TpHandleRepoIface

TpHandleRepoIface — abstract interface for handle allocation

## Synopsis

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

                        TpHandleRepoIface;
                        TpHandleRepoIfaceClass;
    gboolean            tp_handle_is_valid                  (TpHandleRepoIface *self,
                                                             TpHandle handle,
                                                             GError **error);
    gboolean            tp_handles_are_valid                (TpHandleRepoIface *self,
                                                             const GArray *handles,
                                                             gboolean allow_zero,
                                                             GError **error);
    gboolean            tp_handles_supported_and_valid      (TpHandleRepoIface *repos[TP_NUM_HANDLE_TYPES],
                                                             TpHandleType handle_type,
                                                             const GArray *handles,
                                                             gboolean allow_zero,
                                                             GError **error);
    TpHandle            tp_handle_ref                       (TpHandleRepoIface *self,
                                                             TpHandle handle);
    void                tp_handles_ref                      (TpHandleRepoIface *self,
                                                             const GArray *handles);
    void                tp_handle_unref                     (TpHandleRepoIface *self,
                                                             TpHandle handle);
    void                tp_handles_unref                    (TpHandleRepoIface *self,
                                                             const GArray *handles);
    gboolean            tp_handle_client_hold               (TpHandleRepoIface *self,
                                                             const gchar *client,
                                                             TpHandle handle,
                                                             GError **error);
    gboolean            tp_handles_client_hold              (TpHandleRepoIface *self,
                                                             const gchar *client,
                                                             const GArray *handles,
                                                             GError **error);
    gboolean            tp_handle_client_release            (TpHandleRepoIface *self,
                                                             const gchar *client,
                                                             TpHandle handle,
                                                             GError **error);
    gboolean            tp_handles_client_release           (TpHandleRepoIface *self,
                                                             const gchar *client,
                                                             const GArray *handles,
                                                             GError **error);
    const char *        tp_handle_inspect                   (TpHandleRepoIface *self,
                                                             TpHandle handle);
    void                tp_handle_set_qdata                 (TpHandleRepoIface *repo,
                                                             TpHandle handle,
                                                             GQuark key_id,
                                                             gpointer data,
                                                             GDestroyNotify destroy);
    gpointer            tp_handle_get_qdata                 (TpHandleRepoIface *repo,
                                                             TpHandle handle,
                                                             GQuark key_id);
    TpHandle            tp_handle_ensure                    (TpHandleRepoIface *self,
                                                             const gchar *id,
                                                             gpointer context,
                                                             GError **error);
    TpHandle            tp_handle_lookup                    (TpHandleRepoIface *self,
                                                             const gchar *id,
                                                             gpointer context,
                                                             GError **error);
    void                tp_handle_ensure_async              (TpHandleRepoIface *self,
                                                             TpBaseConnection *connection,
                                                             const gchar *id,
                                                             gpointer context,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    TpHandle            tp_handle_ensure_finish             (TpHandleRepoIface *self,
                                                             GAsyncResult *result,
                                                             GError **error);

                        TpHandleSet;
    #define             TP_TYPE_HANDLE_SET
    void                (*TpHandleSetMemberFunc)            (TpHandleSet *set,
                                                             TpHandle handle,
                                                             gpointer userdata);
    TpHandleSet *       tp_handle_set_new                   (TpHandleRepoIface *repo);
    TpHandleSet *       tp_handle_set_new_containing        (TpHandleRepoIface *repo,
                                                             TpHandle handle);
    TpHandleSet *       tp_handle_set_new_from_array        (TpHandleRepoIface *repo,
                                                             const GArray *array);
    TpHandleSet *       tp_handle_set_new_from_intset       (TpHandleRepoIface *repo,
                                                             const TpIntset *intset);
    TpHandleSet *       tp_handle_set_copy                  (const TpHandleSet *other);
    void                tp_handle_set_clear                 (TpHandleSet *set);
    void                tp_handle_set_destroy               (TpHandleSet *set);
    TpIntset *          tp_handle_set_peek                  (TpHandleSet *set);
    void                tp_handle_set_add                   (TpHandleSet *set,
                                                             TpHandle handle);
    gboolean            tp_handle_set_remove                (TpHandleSet *set,
                                                             TpHandle handle);
    gboolean            tp_handle_set_is_member             (const TpHandleSet *set,
                                                             TpHandle handle);
    void                tp_handle_set_foreach               (TpHandleSet *set,
                                                             TpHandleSetMemberFunc func,
                                                             gpointer user_data);
    gboolean            tp_handle_set_is_empty              (const TpHandleSet *set);
    int                 tp_handle_set_size                  (const TpHandleSet *set);
    GArray *            tp_handle_set_to_array              (const TpHandleSet *set);
    GHashTable *        tp_handle_set_to_identifier_map     (TpHandleSet *self);
    TpIntset *          tp_handle_set_update                (TpHandleSet *set,
                                                             const TpIntset *add);
    TpIntset *          tp_handle_set_difference_update     (TpHandleSet *set,
                                                             const TpIntset *remove);
    gchar *             tp_handle_set_dump                  (const TpHandleSet *self);

## Object Hierarchy

      GInterface
       +----TpHandleRepoIface

      GBoxed
       +----TpHandleSet

## Prerequisites

TpHandleRepoIface requires GObject.

## Known Implementations

TpHandleRepoIface is implemented by TpDynamicHandleRepo and TpStaticHandleRepo.

## Properties

      "handle-type"              guint                 : Read / Write / Construct Only

## Description

Abstract interface of a repository for handles, supporting operations which include checking for validity, lookup by string value and lookup by numeric value. See TpDynamicHandleRepo and TpStaticHandleRepo for concrete implementations.

## Details

### TpHandleRepoIface

    typedef struct _TpHandleRepoIface TpHandleRepoIface;

Dummy typedef representing any implementation of this interface.

### TpHandleRepoIfaceClass

    typedef struct _TpHandleRepoIfaceClass TpHandleRepoIfaceClass;

The class of a handle repository interface. The structure layout is only available within telepathy-glib, for the handle repository implementations' benefit.

### tp_handle_is_valid ()

    gboolean            tp_handle_is_valid                  (TpHandleRepoIface *self,
                                                             TpHandle handle,
                                                             GError **error);

`self` : | A handle repository implementation
`handle` : | A handle of the type stored in the repository `self`
`error` : | Set to InvalidHandle if `FALSE` is returned
Returns : | `TRUE` if the handle is nonzero and is present in the repository, else `FALSE`

### tp_handles_are_valid ()

    gboolean            tp_handles_are_valid                (TpHandleRepoIface *self,
                                                             const GArray *handles,
                                                             gboolean allow_zero,
                                                             GError **error);

`self` : | A handle repository implementation
`handles` : | Array of TpHandle representing handles of the type stored in the repository `self`
`allow_zero` : | If `TRUE`, zero is treated like a valid handle
`error` : | Set to InvalidHandle if `FALSE` is returned
Returns : | `TRUE` if the handle is present in the repository, else `FALSE`

### tp_handles_supported_and_valid ()

    gboolean            tp_handles_supported_and_valid      (TpHandleRepoIface *repos[TP_NUM_HANDLE_TYPES],
                                                             TpHandleType handle_type,
                                                             const GArray *handles,
                                                             gboolean allow_zero,
                                                             GError **error);

Return `TRUE` if the given handle type is supported (i.e. repos[handle_type] is not `NULL`) and the given handles are all valid in that repository. If not, set `error` and return `FALSE`.

`repos` : | An array of possibly null pointers to handle repositories, indexed by handle type, where a null pointer means an unsupported handle type
`handle_type` : | The handle type
`handles` : | A GArray of guint representing handles of the given type
`allow_zero` : | If `TRUE`, zero is treated like a valid handle
`error` : | Used to return an error if `FALSE` is returned
Returns : | `TRUE` if the handle type is supported and the handles are all valid.

### tp_handle_ref ()

    TpHandle            tp_handle_ref                       (TpHandleRepoIface *self,
                                                             TpHandle handle);

### Warning

`tp_handle_ref` is deprecated and should not be used in newly-written code. This is no-op so can be safely removed.

Do nothing. Since version 0.13.8, handles always last as long as the connection; previously, this function provided refcounting for handles.

Changed in 0.13.6: `handle` is now returned; previously, this function didn't return anything.

`self` : | not used
`handle` : | not used
Returns : | the same `handle`

### tp_handles_ref ()

    void                tp_handles_ref                      (TpHandleRepoIface *self,
                                                             const GArray *handles);

### Warning

`tp_handles_ref` is deprecated and should not be used in newly-written code. This is no-op so can be safely removed.

Do nothing. Since version 0.13.8, handles always last as long as the connection; previously, this function provided refcounting for handles.

`self` : | not used
`handles` : | not used

### tp_handle_unref ()

    void                tp_handle_unref                     (TpHandleRepoIface *self,
                                                             TpHandle handle);

### Warning

`tp_handle_unref` is deprecated and should not be used in newly-written code. This is no-op so can be safely removed.

Do nothing. Since version 0.13.8, handles always last as long as the connection; previously, this function provided refcounting for handles.

`self` : | A handle repository implementation
`handle` : | A handle of the type stored in the repository

### tp_handles_unref ()

    void                tp_handles_unref                    (TpHandleRepoIface *self,
                                                             const GArray *handles);

### Warning

`tp_handles_unref` is deprecated and should not be used in newly-written code. This is no-op so can be safely removed.

Do nothing. Since version 0.13.8, handles always last as long as the connection; previously, this function provided refcounting for handles.

`self` : | not used
`handles` : | not used

### tp_handle_client_hold ()

    gboolean            tp_handle_client_hold               (TpHandleRepoIface *self,
                                                             const gchar *client,
                                                             TpHandle handle,
                                                             GError **error);

### Warning

`tp_handle_client_hold` is deprecated and should not be used in newly-written code. This is no-op so can be safely removed.

Do nothing. Since version 0.13.8, handles always last as long as the connection; previously, this function provided refcounting for handles.

`self` : | not used
`client` : | not used
`handle` : | not used
`error` : | not set
Returns : | `TRUE`

### tp_handles_client_hold ()

    gboolean            tp_handles_client_hold              (TpHandleRepoIface *self,
                                                             const gchar *client,
                                                             const GArray *handles,
                                                             GError **error);

### Warning

`tp_handles_client_hold` is deprecated and should not be used in newly-written code. This is no-op so can be safely removed.

Do nothing. Since version 0.13.8, handles always last as long as the connection; previously, this function provided refcounting for handles.

`self` : | ignored
`client` : | ignored
`handles` : | ignored
`error` : | ignored
Returns : | `TRUE`

### tp_handle_client_release ()

    gboolean            tp_handle_client_release            (TpHandleRepoIface *self,
                                                             const gchar *client,
                                                             TpHandle handle,
                                                             GError **error);

### Warning

`tp_handle_client_release` is deprecated and should not be used in newly-written code. This is no-op so can be safely removed.

Do nothing. Since version 0.13.8, handles always last as long as the connection; previously, this function provided refcounting for handles.

`self` : | ignored
`client` : | ignored
`handle` : | ignored
`error` : | ignored
Returns : | `TRUE`

### tp_handles_client_release ()

    gboolean            tp_handles_client_release           (TpHandleRepoIface *self,
                                                             const gchar *client,
                                                             const GArray *handles,
                                                             GError **error);

### Warning

`tp_handles_client_release` is deprecated and should not be used in newly-written code. This is no-op so can be safely removed.

Do nothing. Since version 0.13.8, handles always last as long as the connection; previously, this function provided refcounting for handles.

`self` : | ignored
`client` : | ignored
`handles` : | ignored
`error` : | ignored
Returns : | `TRUE`

### tp_handle_inspect ()

    const char *        tp_handle_inspect                   (TpHandleRepoIface *self,
                                                             TpHandle handle);

`self` : | A handle repository implementation
`handle` : | A handle of the type stored in the repository
Returns : | the string represented by the given handle, or NULL if the handle is absent from the repository. The string is owned by the handle repository and will remain valid as long as a reference to the handle exists.

### tp_handle_set_qdata ()

    void                tp_handle_set_qdata                 (TpHandleRepoIface *repo,
                                                             TpHandle handle,
                                                             GQuark key_id,
                                                             gpointer data,
                                                             GDestroyNotify destroy);

### Warning

`tp_handle_set_qdata` is deprecated and should not be used in newly-written code. Since 0.19.9. It is not recommended to use this function because the associated data won't be freed until the connection disconnects.

Associates a blob of data with a given handle and a given key

If `destroy` is set, then the data is freed when the handle is freed.

Since version 0.13.8, handles always last as long as the connection, so `destroy` will not be called until the connection disconnects.

`repo` : | A handle repository implementation
`handle` : | A handle to set data on
`key_id` : | Key id to associate data with
`data` : | data to associate with handle
`destroy` : | A GDestroyNotify to call to destroy the data, or NULL if not needed.

### tp_handle_get_qdata ()

    gpointer            tp_handle_get_qdata                 (TpHandleRepoIface *repo,
                                                             TpHandle handle,
                                                             GQuark key_id);

### Warning

`tp_handle_get_qdata` is deprecated and should not be used in newly-written code. Since 0.19.9. It is not recommended to use this function because the associated data won't be freed until the connection disconnects.

`repo` : | A handle repository implementation
`handle` : | A handle to get data from
`key_id` : | Key id of data to fetch
Returns : | the data associated with a given key on a given handle; `NULL` if there is no associated data.

### tp_handle_ensure ()

    TpHandle            tp_handle_ensure                    (TpHandleRepoIface *self,
                                                             const gchar *id,
                                                             gpointer context,
                                                             GError **error);

Return a handle for the given string, creating one if necessary. The string is normalized, if possible.

`self` : | A handle repository implementation
`id` : | A string whose handle is required
`context` : | User data to be passed to the normalization callback
`error` : | Used to return an error if 0 is returned
Returns : | the handle corresponding to the given string, or 0 if it is invalid.

### tp_handle_lookup ()

    TpHandle            tp_handle_lookup                    (TpHandleRepoIface *self,
                                                             const gchar *id,
                                                             gpointer context,
                                                             GError **error);

Return the handle for the given string. The string is normalized if possible. If no handle already exists for the string, none is created.

`self` : | A handle repository implementation
`id` : | A string whose handle is required
`context` : | User data to be passed to the normalization callback
`error` : | Used to raise an error if the handle does not exist or is invalid
Returns : | the handle corresponding to the given string, or 0 if it does not exist or is invalid

### tp_handle_ensure_async ()

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

Asyncronously normalize an identifier and create an handle for it. This could involve a server round-trip. This should be used instead of `tp_handle_ensure()` for user provided contact identifiers, but it is not necessary for identifiers from the server.

`self` : | A handle repository implementation
`connection` : | the TpBaseConnection using this handle repo
`id` : | A string whose handle is required
`context` : | User data to be passed to the normalization callback
`callback` : | a callback to call when the operation finishes
`user_data` : | data to pass to `callback`

Since 0.19.2

### tp_handle_ensure_finish ()

    TpHandle            tp_handle_ensure_finish             (TpHandleRepoIface *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes `tp_handle_ensure_async()`

`self` : | A handle repository implementation
`result` : | a GAsyncResult
`error` : | a GError to fill
Returns : | non-0 TpHandle if the operation was successful, otherwise 0.

Since 0.19.2

### TpHandleSet

    typedef struct _TpHandleSet TpHandleSet;

A set of handles. This is similar to a TpIntset (and implemented using one), but adding a handle to the set also references it.

### TP_TYPE_HANDLE_SET

    #define TP_TYPE_HANDLE_SET (tp_handle_set_get_type ())

The boxed type of a TpHandleSet.

Since 0.11.6

### TpHandleSetMemberFunc ()

    void                (*TpHandleSetMemberFunc)            (TpHandleSet *set,
                                                             TpHandle handle,
                                                             gpointer userdata);

Signature of the callback used to iterate over the handle set in `tp_handle_set_foreach()`.

`set` : | The set of handles on which `tp_handle_set_foreach()` was called
`handle` : | A handle in the set
`userdata` : | Arbitrary user data as supplied to `tp_handle_set_foreach()`

### tp_handle_set_new ()

    TpHandleSet *       tp_handle_set_new                   (TpHandleRepoIface *repo);

Creates a new TpHandleSet

`repo` : | TpHandleRepoIface that holds the handles to be reffed by this set
Returns : | A new TpHandleSet. [transfer full]

### tp_handle_set_new_containing ()

    TpHandleSet *       tp_handle_set_new_containing        (TpHandleRepoIface *repo,
                                                             TpHandle handle);

Creates a new TpHandleSet from a specified handle repository and single handle.

`repo` : | TpHandleRepoIface that holds the handles to be reffed by this set
`handle` : | a valid handle
Returns : | A new TpHandleSet. [transfer full]

Since 0.13.0

### tp_handle_set_new_from_array ()

    TpHandleSet *       tp_handle_set_new_from_array        (TpHandleRepoIface *repo,
                                                             const GArray *array);

Creates a new TpHandleSet

`repo` : | TpHandleRepoIface that holds the handles to be reffed by this set
`array` : | array of handles to be referenced by this set. [element-type uint]
Returns : | A new TpHandleSet. [transfer full]

Since 0.11.7

### tp_handle_set_new_from_intset ()

    TpHandleSet *       tp_handle_set_new_from_intset       (TpHandleRepoIface *repo,
                                                             const TpIntset *intset);

Creates a new TpHandleSet from a specified handle repository and set of handles.

`repo` : | TpHandleRepoIface that holds the handles to be reffed by this set
`intset` : | a set of handles, which must all be valid
Returns : | A new TpHandleSet. [transfer full]

Since 0.13.0

### tp_handle_set_copy ()

    TpHandleSet *       tp_handle_set_copy                  (const TpHandleSet *other);

Creates a new TpHandleSet with the same contents as `other`.

`other` : | another handle set
Returns : | a new set

Since 0.11.6

### tp_handle_set_clear ()

    void                tp_handle_set_clear                 (TpHandleSet *set);

Remove every handle from `set`, releasing the references it holds.

`set` : | TpHandleSet to clear

Since 0.11.6

### tp_handle_set_destroy ()

    void                tp_handle_set_destroy               (TpHandleSet *set);

Delete a TpHandleSet and unreference any handles that it holds

`set` : | TpHandleSet to destroy

### tp_handle_set_peek ()

    TpIntset *          tp_handle_set_peek                  (TpHandleSet *set);

`set` : | TpHandleSet to peek at
Returns : | the underlying TpIntset used by this TpHandleSet. [transfer none]

### tp_handle_set_add ()

    void                tp_handle_set_add                   (TpHandleSet *set,
                                                             TpHandle handle);

Add a handle to a TpHandleSet, and reference it in the attached TpHandleRepoIface

`set` : | TpHandleSet to add this handle to
`handle` : | handle to add

### tp_handle_set_remove ()

    gboolean            tp_handle_set_remove                (TpHandleSet *set,
                                                             TpHandle handle);

Remove a handle from a TpHandleSet, and unreference it in the attached TpHandleRepoIface

`set` : | TpHandleSet to remove this handle from
`handle` : | handle to remove
Returns : | FALSE if the handle was invalid, or was not in this set

### tp_handle_set_is_member ()

    gboolean            tp_handle_set_is_member             (const TpHandleSet *set,
                                                             TpHandle handle);

Check if the handle is in this set

`set` : | A TpHandleSet
`handle` : | handle to check
Returns : | TRUE if the handle is in this set

### tp_handle_set_foreach ()

    void                tp_handle_set_foreach               (TpHandleSet *set,
                                                             TpHandleSetMemberFunc func,
                                                             gpointer user_data);

Call `func`(`set`, `handle`, `userdata`) for each handle in `set`.

`set` : | A set of handles
`func` : | A callback. [scope call]
`user_data` : | Arbitrary data to pass to `func`

### tp_handle_set_is_empty ()

    gboolean            tp_handle_set_is_empty              (const TpHandleSet *set);

Return the same thing as `(tp_handle_set_size (set) == 0)`, but calculated more efficiently.

`set` : | TpHandleSet to check
Returns : | `TRUE` if the set has no members

Since 0.11.6

### tp_handle_set_size ()

    int                 tp_handle_set_size                  (const TpHandleSet *set);

`set` : | A set of handles
Returns : | the number of handles in this set

### tp_handle_set_to_array ()

    GArray *            tp_handle_set_to_array              (const TpHandleSet *set);

`set` : | A handle set
Returns : | a newly-allocated GArray of guint representing the handles in the set. [element-type uint]

### tp_handle_set_to_identifier_map ()

    GHashTable *        tp_handle_set_to_identifier_map     (TpHandleSet *self);

Returns a dictionary mapping each handle in `self` to the corresponding identifier, as if retrieved by calling `tp_handle_inspect()` on each handle. The type of the returned value is described as `Handle_Identifier_Map` in the Telepathy specification.

`self` : | a handle set
Returns : | a map from the handles in `self` to the corresponding identifier. [transfer full][element-type TpHandle utf8]

### tp_handle_set_update ()

    TpIntset *          tp_handle_set_update                (TpHandleSet *set,
                                                             const TpIntset *add);

Add a set of handles to a handle set, referencing those which are not already members. The TpIntset returned must be freed with tp_intset_destroy.

`set` : | a TpHandleSet to update
`add` : | a TpIntset of handles to add
Returns : | the handles which were added (some subset of `add`)

### tp_handle_set_difference_update ()

    TpIntset *          tp_handle_set_difference_update     (TpHandleSet *set,
                                                             const TpIntset *remove);

Remove a set of handles from a handle set, dereferencing those which are members. The TpIntset returned must be freed with tp_intset_destroy.

If you want to be able to inspect the handles in the set returned, you must ensure that this function does not cause their refcount to drop to zero, for instance by temporarily taking a reference to all the handles in `remove`, calling this function, doing something with the result and discarding the temporary references.

`set` : | a TpHandleSet to update
`remove` : | a TpIntset of handles to remove
Returns : | the handles which were dereferenced and removed (some subset of `remove`).

### tp_handle_set_dump ()

    gchar *             tp_handle_set_dump                  (const TpHandleSet *self);

Format a TpHandleSet for debug output.

`self` : | a handle set
Returns : | a string representation of the handle set suitable for debug output. [transfer full][type utf8]

## Property Details

### The `"handle-type"` property

      "handle-type"              guint                 : Read / Write / Construct Only

The TpHandleType held in this handle repository.

Default value: 0

## See Also

TpDynamicHandleRepo, TpStaticHandleRepo