|
|
|
telepathy-glib Reference Manual | |
|---|---|---|---|---|
#include <telepathy-glib/handle-repo.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[NUM_TP_HANDLE_TYPES],
TpHandleType handle_type,
const GArray *handles,
gboolean allow_zero,
GError **error);
void 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);
TpHandleSet;
void (*TpHandleSetMemberFunc) (TpHandleSet *set,
TpHandle handle,
gpointer userdata);
TpHandleSet* tp_handle_set_new (TpHandleRepoIface *repo);
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 (TpHandleSet *set,
TpHandle handle);
void tp_handle_set_foreach (TpHandleSet *set,
TpHandleSetMemberFunc func,
gpointer userdata);
int tp_handle_set_size (TpHandleSet *set);
GArray* tp_handle_set_to_array (TpHandleSet *set);
TpIntSet* tp_handle_set_update (TpHandleSet *set,
const TpIntSet *add);
TpIntSet* tp_handle_set_difference_update (TpHandleSet *set,
const TpIntSet *remove);
TpHandleRepoIface is implemented by TpDynamicHandleRepo and TpStaticHandleRepo.
Abstract interface of a repository for handles, supporting operations which include checking for validity, reference counting, lookup by string value and lookup by numeric value. See TpDynamicHandleRepo and TpStaticHandleRepo for concrete implementations.
typedef struct _TpHandleRepoIface TpHandleRepoIface;
Dummy typedef representing any implementation of this interface.
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.
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
|
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
|
gboolean tp_handles_supported_and_valid (TpHandleRepoIface *repos[NUM_TP_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.
|
void tp_handle_ref (TpHandleRepoIface *self, TpHandle handle);
Increase the reference count of the given handle, which must be present in the repository. For repository implementations which never free handles (like TpStaticHandleRepo) this has no effect.
self : |
A handle repository implementation |
handle : |
A handle of the type stored in the repository |
void tp_handles_ref (TpHandleRepoIface *self, const GArray *handles);
Increase the reference count of the given handles. If a handle appears
multiple times in handles it will be referenced that many times. If
any zero entries appear in handles they will be ignored without error;
it is an error for any other invalid handle to appear in handles.
self : |
A handle repository implementation |
handles : |
A GArray of TpHandle representing handles |
void tp_handle_unref (TpHandleRepoIface *self, TpHandle handle);
Decrease the reference count of the given handle. If it reaches zero, delete the handle. It is an error to attempt to unref a handle which is not present in the repository.
For repository implementations which never free handles (like TpStaticHandleRepo) this has no effect.
self : |
A handle repository implementation |
handle : |
A handle of the type stored in the repository |
void tp_handles_unref (TpHandleRepoIface *self, const GArray *handles);
Decrease the reference count of the given handles. If a handle appears
multiple times in handles it will be dereferenced that many times. If
any zero entries appear in handles they will be ignored without error;
it is an error for any other invalid handle to appear in handles.
self : |
A handle repository implementation |
handles : |
A GArray of TpHandle representing handles |
gboolean tp_handle_client_hold (TpHandleRepoIface *self, const gchar *client, TpHandle handle, GError **error);
Hold the given handle on behalf of the named client. If the client leaves the bus, the reference is automatically discarded.
Handles held multiple times are the same as handles held
once: the client either holds a handle or it doesn't. In particular,
if you call tp_handle_client_hold() multiple times, then call
tp_handle_client_release() just once, the client no longer holds the handle.
It is an error for handle not to be present in the repository.
self : |
A handle repository implementation |
client : |
The unique bus name of a D-Bus peer |
handle : |
A handle of the type stored in the repository |
error : |
Set if FALSE is returned
|
| Returns : | TRUE if the client name is valid; else FALSE with error set.
|
gboolean tp_handles_client_hold (TpHandleRepoIface *self, const gchar *client, const GArray *handles, GError **error);
Hold the given handles on behalf of the named client. If the client leaves the bus, the reference is automatically discarded.
If any of the handles are zero they will be ignored without error.
It is an error for any other invalid handle to be in handles:
the caller is expected to have validated them first, e.g. using
tp_handles_are_valid().
Handles appearing multiple times are the same as handles appearing once: the client either holds a handle or it doesn't.
If FALSE is returned, the reference counts of all handles are unaffected
(the function either fails completely or succeeds completely).
self : |
A handle repository implementation |
client : |
The D-Bus unique name of a client |
handles : |
A GArray of TpHandle representing handles |
error : |
Used to return an error if FALSE is returned
|
| Returns : | TRUE if the client name is valid; else FALSE with error set.
|
gboolean tp_handle_client_release (TpHandleRepoIface *self, const gchar *client, TpHandle handle, GError **error);
If the named client holds the given handle, release it. If this causes the reference count to become zero, delete the handle.
For repository implementations which never free handles (like TpStaticHandleRepo) this has no effect.
self : |
A handle repository implementation |
client : |
The unique bus name of a D-Bus peer |
handle : |
A handle of the type stored in the repository |
error : |
Set if FALSE is returned
|
| Returns : | TRUE if the client name is valid and the client previously held
a reference to the handle, else FALSE.
|
gboolean tp_handles_client_release (TpHandleRepoIface *self, const gchar *client, const GArray *handles, GError **error);
Releases a reference to the given handles on behalf of the named client.
If any of the handles are zero they will be ignored without error.
It is an error for any other invalid handle to be in handles:
the caller is expected to have validated them first, e.g. using
tp_handles_are_valid().
If FALSE is returned, the reference counts of all handles are unaffected
(the function either fails completely or succeeds completely).
self : |
A handle repository implementation |
client : |
The D-Bus unique name of a client |
handles : |
A GArray of TpHandle representing handles |
error : |
Used to return an error if FALSE is returned
|
| Returns : | TRUE if the client name is valid and the client previously held
a reference to all the handles, else FALSE.
|
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. |
void tp_handle_set_qdata (TpHandleRepoIface *repo, TpHandle handle, GQuark key_id, gpointer data, GDestroyNotify destroy);
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.
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. |
gpointer tp_handle_get_qdata (TpHandleRepoIface *repo, TpHandle handle, GQuark key_id);
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.
|
TpHandle tp_handle_ensure (TpHandleRepoIface *self, const gchar *id, gpointer context, GError **error);
Return a new reference to the handle for the given string. The handle is normalized, if possible. If no such handle exists it will be 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 return an error if 0 is returned |
| Returns : | the handle corresponding to the given string, or 0 if it is invalid. |
TpHandle tp_handle_lookup (TpHandleRepoIface *self, const gchar *id, gpointer context, GError **error);
Return the handle for the given string, without incrementing its reference count. The handle 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 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 |
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.
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()
|
TpHandleSet* tp_handle_set_new (TpHandleRepoIface *repo);
Creates a new TpHandleSet
repo : |
TpHandleRepo that holds the handles to be reffed by this set |
| Returns : | A new TpHandleSet |
void tp_handle_set_destroy (TpHandleSet *set);
Delete a TpHandleSet and unreference any handles that it holds
set : |
TpHandleSet to destroy |
TpIntSet* tp_handle_set_peek (TpHandleSet *set);
set : |
TpHandleSet to peek at |
| Returns : | the underlying TpIntSet used by this TpHandleSet |
void tp_handle_set_add (TpHandleSet *set, TpHandle handle);
Add a handle to a TpHandleSet,and reference it in the attched TpHandleRepo
set : |
TpHandleSet to add this handle to |
handle : |
handle to add |
gboolean tp_handle_set_remove (TpHandleSet *set, TpHandle handle);
Remove a handle to a TpHandleSet,and unreference it in the attched TpHandleRepo
set : |
TpHandleSet to remove this handle from |
handle : |
handle to remove |
| Returns : | FALSE if the handle was invalid, or was not in this set |
gboolean tp_handle_set_is_member (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 |
void tp_handle_set_foreach (TpHandleSet *set, TpHandleSetMemberFunc func, gpointer userdata);
Call func(set, handle, userdata) for each handle in set.
set : |
A set of handles |
func : |
A callback |
userdata : |
Arbitrary data to pass to func
|
int tp_handle_set_size (TpHandleSet *set);
set : |
A set of handles |
| Returns : | the number of handles in this set |
GArray* tp_handle_set_to_array (TpHandleSet *set);
set : |
A handle set |
| Returns : | a newly-allocated GArray of guint representing the handles in the set |
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)
|
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).
|