TpHandleRepoIface

TpHandleRepoIface — abstract interface for handle allocation

Functions

Properties

guint handle-type Read / Write / Construct Only

Types and Values

Object Hierarchy

    GBoxed
    ╰── TpHandleSet
    GInterface
    ╰── TpHandleRepoIface

Prerequisites

TpHandleRepoIface requires GObject.

Known Implementations

TpHandleRepoIface is implemented by TpDynamicHandleRepo and TpStaticHandleRepo.

Includes

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

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.

Functions

tp_handle_is_valid ()

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

[skip]

Parameters

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

[skip]

Parameters

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.

[skip]

Parameters

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

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.

[skip]

Parameters

self

not used

 

handle

not used

 

Returns

the same handle


tp_handles_ref ()

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

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.

[skip]

Parameters

self

not used

 

handles

not used

 

tp_handle_unref ()

void
tp_handle_unref (TpHandleRepoIface *self,
                 TpHandle handle);

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.

[skip]

Parameters

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

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.

[skip]

Parameters

self

not used

 

handles

not used

 

tp_handle_client_hold ()

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

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.

[skip]

Parameters

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

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.

[skip]

Parameters

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

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.

[skip]

Parameters

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

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.

[skip]

Parameters

self

ignored

 

client

ignored

 

handles

ignored

 

error

ignored

 

Returns

TRUE


tp_handle_inspect ()

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

[skip]

Parameters

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

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.

[skip]

Parameters

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

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.

[skip]

Parameters

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.

Parameters

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.

[skip]

Parameters

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.

[skip]

Parameters

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

[skip]

Parameters

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


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

[skip]

Parameters

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

[skip]

Parameters

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.

[skip]

Parameters

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

[skip]

Parameters

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.

[skip]

Parameters

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 .

[skip]

Parameters

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.

[skip]

Parameters

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

[skip]

Parameters

set

TpHandleSet to destroy

 

tp_handle_set_peek ()

TpIntset *
tp_handle_set_peek (TpHandleSet *set);

[skip]

Parameters

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

[skip]

Parameters

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

[skip]

Parameters

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

[skip]

Parameters

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 .

[skip]

Parameters

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.

[skip]

Parameters

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

[skip]

Parameters

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

[skip]

Parameters

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.

Parameters

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.

[skip]

Parameters

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.

[skip]

Parameters

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.

Parameters

self

a handle set

 

Returns

a string representation of the handle set suitable for debug output.

[transfer full][type utf8]

Types and Values

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.


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

Property Details

The “handle-type” property

  “handle-type”              guint

The TpHandleType held in this handle repository.

Owner: TpHandleRepoIface

Flags: Read / Write / Construct Only

Default value: 0

See Also

TpDynamicHandleRepo, TpStaticHandleRepo