TpConnection

TpConnection — proxy object for a Telepathy connection

Synopsis


#include <telepathy-glib/connection.h>

void                (*TpConnectionNameListCb)           (const gchar * const *names,
                                                         gsize n,
                                                         const gchar * const *cms,
                                                         const gchar * const *protocols,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                tp_list_connection_names            (TpDBusDaemon *bus_daemon,
                                                         TpConnectionNameListCb callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
TpConnection*       tp_connection_new                   (TpDBusDaemon *dbus,
                                                         const gchar *bus_name,
                                                         const gchar *object_path,
                                                         GError **error);
gboolean            tp_connection_run_until_ready       (TpConnection *self,
                                                         gboolean connect,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*TpConnectionWhenReadyCb)          (TpConnection *connection,
                                                         const GError *error,
                                                         gpointer user_data);
void                tp_connection_call_when_ready       (TpConnection *self,
                                                         TpConnectionWhenReadyCb callback,
                                                         gpointer user_data);
gboolean            tp_connection_is_ready              (TpConnection *self);
TpConnectionStatus  tp_connection_get_status            (TpConnection *self,
                                                         TpConnectionStatusReason *reason);
TpHandle            tp_connection_get_self_handle       (TpConnection *self);
void                (*TpConnectionRequestHandlesCb)     (TpConnection *connection,
                                                         TpHandleType handle_type,
                                                         guint n_handles,
                                                         const TpHandle *handles,
                                                         const gchar * const *ids,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                tp_connection_request_handles       (TpConnection *self,
                                                         gint timeout_ms,
                                                         TpHandleType handle_type,
                                                         const gchar * const *ids,
                                                         TpConnectionRequestHandlesCb callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*TpConnectionHoldHandlesCb)        (TpConnection *connection,
                                                         TpHandleType handle_type,
                                                         guint n_handles,
                                                         const TpHandle *handles,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                tp_connection_get_contact_attributes
                                                        (TpConnection *self,
                                                         gint timeout_ms,
                                                         guint n_handles,
                                                         const TpHandle *handles,
                                                         const gchar * const *interfaces,
                                                         gboolean hold,
                                                         tp_cli_connection_interface_contacts_callback_for_get_contact_attributes callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                tp_connection_hold_handles          (TpConnection *self,
                                                         gint timeout_ms,
                                                         TpHandleType handle_type,
                                                         guint n_handles,
                                                         const TpHandle *handles,
                                                         TpConnectionHoldHandlesCb callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                tp_connection_unref_handles         (TpConnection *self,
                                                         TpHandleType handle_type,
                                                         guint n_handles,
                                                         const TpHandle *handles);
void                tp_connection_init_known_interfaces (void);
gint                tp_connection_presence_type_cmp_availability
                                                        (TpConnectionPresenceType p1,
                                                         TpConnectionPresenceType p2);
gboolean            tp_connection_parse_object_path     (TpConnection *self,
                                                         gchar **protocol,
                                                         gchar **cm_name);
                    TpConnection;
                    TpConnectionClass;
#define             TP_UNKNOWN_CONNECTION_STATUS
#define             TP_ERRORS_DISCONNECTED


void                (*tp_cli_connection_callback_for_connect)
                                                        (TpConnection *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall* tp_cli_connection_call_connect      (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_connection_callback_for_connect callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_connect       (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_callback_for_disconnect)
                                                        (TpConnection *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall* tp_cli_connection_call_disconnect   (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_connection_callback_for_disconnect callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_disconnect    (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_callback_for_get_interfaces)
                                                        (TpConnection *proxy,
                                                         const gchar **out_Interfaces,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall* tp_cli_connection_call_get_interfaces
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_connection_callback_for_get_interfaces callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_get_interfaces
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         gchar ***out_Interfaces,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_callback_for_get_protocol)
                                                        (TpConnection *proxy,
                                                         const gchar *out_Protocol,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall* tp_cli_connection_call_get_protocol (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_connection_callback_for_get_protocol callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_get_protocol  (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         gchar **out_Protocol,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_callback_for_get_self_handle)
                                                        (TpConnection *proxy,
                                                         guint out_Self_Handle,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall* tp_cli_connection_call_get_self_handle
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_connection_callback_for_get_self_handle callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_get_self_handle
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint *out_Self_Handle,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_callback_for_get_status)
                                                        (TpConnection *proxy,
                                                         guint out_Status,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall* tp_cli_connection_call_get_status   (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_connection_callback_for_get_status callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_get_status    (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint *out_Status,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_callback_for_hold_handles)
                                                        (TpConnection *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall* tp_cli_connection_call_hold_handles (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const GArray *in_Handles,
                                                         tp_cli_connection_callback_for_hold_handles callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_hold_handles  (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const GArray *in_Handles,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_callback_for_inspect_handles)
                                                        (TpConnection *proxy,
                                                         const gchar **out_Identifiers,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall* tp_cli_connection_call_inspect_handles
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const GArray *in_Handles,
                                                         tp_cli_connection_callback_for_inspect_handles callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_inspect_handles
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const GArray *in_Handles,
                                                         gchar ***out_Identifiers,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_callback_for_list_channels)
                                                        (TpConnection *proxy,
                                                         const GPtrArray *out_Channel_Info,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall* tp_cli_connection_call_list_channels
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_connection_callback_for_list_channels callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_list_channels (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         GPtrArray **out_Channel_Info,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_callback_for_release_handles)
                                                        (TpConnection *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall* tp_cli_connection_call_release_handles
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const GArray *in_Handles,
                                                         tp_cli_connection_callback_for_release_handles callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_release_handles
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const GArray *in_Handles,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_callback_for_request_channel)
                                                        (TpConnection *proxy,
                                                         const gchar *out_Object_Path,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall* tp_cli_connection_call_request_channel
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Type,
                                                         guint in_Handle_Type,
                                                         guint in_Handle,
                                                         gboolean in_Suppress_Handler,
                                                         tp_cli_connection_callback_for_request_channel callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_request_channel
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Type,
                                                         guint in_Handle_Type,
                                                         guint in_Handle,
                                                         gboolean in_Suppress_Handler,
                                                         gchar **out_Object_Path,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_callback_for_request_handles)
                                                        (TpConnection *proxy,
                                                         const GArray *out_Handles,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall* tp_cli_connection_call_request_handles
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const gchar **in_Identifiers,
                                                         tp_cli_connection_callback_for_request_handles callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_request_handles
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const gchar **in_Identifiers,
                                                         GArray **out_Handles,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_signal_callback_new_channel)
                                                        (TpConnection *proxy,
                                                         const gchar *arg_Object_Path,
                                                         const gchar *arg_Channel_Type,
                                                         guint arg_Handle_Type,
                                                         guint arg_Handle,
                                                         gboolean arg_Suppress_Handler,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection* tp_cli_connection_connect_to_new_channel
                                                        (TpConnection *proxy,
                                                         tp_cli_connection_signal_callback_new_channel callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
void                (*tp_cli_connection_signal_callback_self_handle_changed)
                                                        (TpConnection *proxy,
                                                         guint arg_Self_Handle,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection* tp_cli_connection_connect_to_self_handle_changed
                                                        (TpConnection *proxy,
                                                         tp_cli_connection_signal_callback_self_handle_changed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
void                (*tp_cli_connection_signal_callback_status_changed)
                                                        (TpConnection *proxy,
                                                         guint arg_Status,
                                                         guint arg_Reason,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection* tp_cli_connection_connect_to_status_changed
                                                        (TpConnection *proxy,
                                                         tp_cli_connection_signal_callback_status_changed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
void                (*tp_cli_connection_signal_callback_connection_error)
                                                        (TpConnection *proxy,
                                                         const gchar *arg_Error,
                                                         GHashTable *arg_Details,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection* tp_cli_connection_connect_to_connection_error
                                                        (TpConnection *proxy,
                                                         tp_cli_connection_signal_callback_connection_error callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Object Hierarchy

  GObject
   +----TpProxy
         +----TpConnection

Properties

  "connection-ready"         gboolean              : Read
  "self-handle"              guint                 : Read
  "status"                   guint                 : Read
  "status-reason"            guint                 : Read

Description

TpConnection objects represent Telepathy instant messaging connections accessed via D-Bus.

Compared with a simple proxy for method calls, they add the following features:

  • connection status tracking
  • calling GetInterfaces() automatically

Details

TpConnectionNameListCb ()

void                (*TpConnectionNameListCb)           (const gchar * const *names,
                                                         gsize n,
                                                         const gchar * const *cms,
                                                         const gchar * const *protocols,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback supplied to tp_list_connection_names().

names : NULL-terminated array of n connection bus names, or NULL on error
n : number of names (not including the final NULL), or 0 on error
cms : NULL-terminated array of n connection manager names (e.g. "gabble") in the same order as names, or NULL on error
protocols : NULL-terminated array of n protocol names as defined in the Telepathy spec (e.g. "jabber") in the same order as names, or NULL on error
error : NULL on success, or an error that occurred
user_data : user-supplied data
weak_object : user-supplied weakly referenced object

Since 0.7.1


tp_list_connection_names ()

void                tp_list_connection_names            (TpDBusDaemon *bus_daemon,
                                                         TpConnectionNameListCb callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

List the bus names of all the connections that currently exist, together with the connection manager name and the protocol name for each connection. Call the callback when done.

The bus names passed to the callback can be used to construct TpConnection objects for any connections that are of interest.

bus_daemon : proxy for the D-Bus daemon
callback : callback to be called when listing the connections succeeds or fails; not called if the D-Bus connection fails completely or if the weak_object goes away
user_data : user-supplied data for the callback
destroy : callback to destroy the user-supplied data, called after callback, but also if the D-Bus connection fails or if the weak_object goes away
weak_object : if not NULL, will be weakly referenced; the callback will not be called if the object has vanished

Since 0.7.1


tp_connection_new ()

TpConnection*       tp_connection_new                   (TpDBusDaemon *dbus,
                                                         const gchar *bus_name,
                                                         const gchar *object_path,
                                                         GError **error);

dbus : a D-Bus daemon; may not be NULL
bus_name : the well-known or unique name of the connection process; if well-known, this function will make a blocking call to the bus daemon to resolve the unique name. May be NULL if object_path is not, in which case a well-known name will be derived from object_path.
object_path : the object path of the connection process. May be NULL if bus_name is a well-known name, in which case the object path will be derived from bus_name.
error : used to indicate the error if NULL is returned
Returns : a new connection proxy, or NULL if unique-name resolution fails or on invalid arguments

Since 0.7.1


tp_connection_run_until_ready ()

gboolean            tp_connection_run_until_ready       (TpConnection *self,
                                                         gboolean connect,
                                                         GError **error,
                                                         GMainLoop **loop);

If self is connected and ready for use, return immediately. Otherwise, call Connect() (unless connect is FALSE) and re-enter the main loop until the connection becomes invalid, the connection connects successfully and is introspected, or the main loop stored via loop is cancelled.

self : a connection
connect : if TRUE, call Connect() if it appears to be necessary; if FALSE, rely on Connect() to be called by another client
error : if not NULL and FALSE is returned, used to raise an error
loop : if not NULL, a GMainLoop is placed here while it is being run (so calling code can call g_main_loop_quit() to abort), and NULL is placed here after the loop has been run
Returns : TRUE if the connection is now connected and ready for use, FALSE if the connection has become invalid.

Since 0.7.1


TpConnectionWhenReadyCb ()

void                (*TpConnectionWhenReadyCb)          (TpConnection *connection,
                                                         const GError *error,
                                                         gpointer user_data);

Signature of a callback passed to tp_connection_call_when_ready(), which will be called exactly once, when the connection becomes ready or invalid (whichever happens first)

connection : the connection (which may be in the middle of being disposed, if error is non-NULL, error->domain is TP_DBUS_ERRORS and error->code is TP_DBUS_ERROR_PROXY_UNREFERENCED)
error : NULL if the connection is ready for use, or the error with which it was invalidated if it is now invalid
user_data : whatever was passed to tp_connection_call_when_ready()

tp_connection_call_when_ready ()

void                tp_connection_call_when_ready       (TpConnection *self,
                                                         TpConnectionWhenReadyCb callback,
                                                         gpointer user_data);

If self is ready for use or has been invalidated, call callback immediately, then return. Otherwise, arrange for callback to be called when self either becomes ready for use or becomes invalid.

Note that if the connection is not in state CONNECTED, the callback will not be called until the connection either goes to state CONNECTED or is invalidated (e.g. by going to state DISCONNECTED or by becoming unreferenced). In particular, this method does not call Connect(). Call tp_cli_connection_call_connect() too, if you want to do that.

self : a connection
callback : called when the connection becomes ready or invalidated, whichever happens first
user_data : arbitrary user-supplied data passed to the callback

Since 0.7.7


tp_connection_is_ready ()

gboolean            tp_connection_is_ready              (TpConnection *self);

Returns the same thing as the "connection-ready" property.

self : a connection
Returns : TRUE if introspection has completed

Since 0.7.17


tp_connection_get_status ()

TpConnectionStatus  tp_connection_get_status            (TpConnection *self,
                                                         TpConnectionStatusReason *reason);

If reason is not NULL it is set to the reason why "status" changed to its current value, or TP_CONNECTION_STATUS_REASON_NONE_SPECIFIED if unknown.

self : a connection
reason : a TpConnectionStatusReason, or NULL
Returns : This connection's status, or TP_UNKNOWN_CONNECTION_STATUS if we don't know yet.

Since 0.7.14


tp_connection_get_self_handle ()

TpHandle            tp_connection_get_self_handle       (TpConnection *self);

Return the TP_HANDLE_TYPE_CONTACT handle of the local user on this connection, or 0 if the connection is not ready (the TpConnection:connection-ready property is false) or has become invalid (the TpProxy::invalidated signal).

The returned handle is not necessarily valid forever (the notify::self-handle signal will be emitted if it changes, which can happen on protocols such as IRC). Construct a TpContact object if you want to track the local user's identifier in the protocol, or other information like their presence status, over time.

self : a connection
Returns : the value of the TpConnection:self-handle property

Since 0.7.26


TpConnectionRequestHandlesCb ()

void                (*TpConnectionRequestHandlesCb)     (TpConnection *connection,
                                                         TpHandleType handle_type,
                                                         guint n_handles,
                                                         const TpHandle *handles,
                                                         const gchar * const *ids,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when tp_connection_request_handles() succeeds or fails.

On success, the caller has one reference to each handle in handles, which may be released later with tp_connection_unref_handles(). If not released, the handles will remain valid until connection becomes invalid (signalled by TpProxy::invalidated).

For convenience, the handle type and IDs requested by the caller are passed through to this callback, so the caller does not have to include them in user_data.

connection : the connection
handle_type : the handle type that was passed to tp_connection_request_handles()
n_handles : the number of IDs that were passed to tp_connection_request_handles() on success, or 0 on failure
handles : the n_handles handles corresponding to ids, in the same order, or NULL on failure
ids : a copy of the array of n_handles IDs that was passed to tp_connection_request_handles() on success, or NULL on failure
error : NULL on success, or an error on failure
user_data : the same arbitrary pointer that was passed to tp_connection_request_handles()
weak_object : the same object that was passed to tp_connection_request_handles()

tp_connection_request_handles ()

void                tp_connection_request_handles       (TpConnection *self,
                                                         gint timeout_ms,
                                                         TpHandleType handle_type,
                                                         const gchar * const *ids,
                                                         TpConnectionRequestHandlesCb callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Request the handles corresponding to the given identifiers, and if they are valid, hold (ensure a reference to) the corresponding handles.

If they are valid, the callback will later be called with the given handles; if not all of them are valid, the callback will be called with an error.

self : a connection
timeout_ms : the timeout in milliseconds, or -1 to use the default
handle_type : the handle type
ids : an array of string identifiers for which handles are required, terminated by NULL (must not be NULL or empty)
callback : called on success or failure (unless weak_object has become unreferenced)
user_data : arbitrary user-supplied data
destroy : called to destroy user_data after calling callback, or when weak_object becomes unreferenced (whichever occurs sooner)
weak_object : if not NULL, an object to be weakly referenced: if it is destroyed, callback will not be called

TpConnectionHoldHandlesCb ()

void                (*TpConnectionHoldHandlesCb)        (TpConnection *connection,
                                                         TpHandleType handle_type,
                                                         guint n_handles,
                                                         const TpHandle *handles,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when tp_connection_hold_handles() succeeds or fails.

On success, the caller has one reference to each handle in handles, which may be released later with tp_connection_unref_handles(). If not released, the handles will remain valid until connection becomes invalid (signalled by "invalidated").

For convenience, the handle type and handles requested by the caller are passed through to this callback on success, so the caller does not have to include them in user_data.

connection : the connection
handle_type : the handle type that was passed to tp_connection_hold_handles()
n_handles : the number of handles that were passed to tp_connection_hold_handles() on success, or 0 on failure
handles : a copy of the array of n_handles handles that was passed to tp_connection_hold_handles() on success, or NULL on failure
error : NULL on success, or an error on failure
user_data : the same arbitrary pointer that was passed to tp_connection_hold_handles()
weak_object : the same object that was passed to tp_connection_hold_handles()

tp_connection_get_contact_attributes ()

void                tp_connection_get_contact_attributes
                                                        (TpConnection *self,
                                                         gint timeout_ms,
                                                         guint n_handles,
                                                         const TpHandle *handles,
                                                         const gchar * const *interfaces,
                                                         gboolean hold,
                                                         tp_cli_connection_interface_contacts_callback_for_get_contact_attributes callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Return (via a callback) any number of attributes of the given handles, and if they are valid and hold is TRUE, hold a reference to them.

This is a thin wrapper around the GetContactAttributes D-Bus method, and should be used in preference to tp_cli_connection_interface_contacts_get_contact_attributes(); mixing this function, tp_connection_hold_handles(), tp_connection_unref_handles(), and TpContact with direct use of the RequestHandles, HoldHandles and GetContactAttributes D-Bus methods is unwise, as TpConnection and TpContact perform client-side reference counting of handles. The TpContact API provides a higher-level abstraction which should usually be used instead.

callback will later be called with the attributes of those of the given handles that were valid. Invalid handles are simply omitted from the parameter to the callback.

If hold is TRUE, the callback is given one reference to each handle that appears as a key in the callback's attributes parameter.

self : a connection
timeout_ms : the timeout in milliseconds, or -1 to use the default
n_handles : the number of handles in handles (must be at least 1)
handles : an array of handles
interfaces : a GStrv of interfaces
hold : if TRUE, the callback will hold one reference to each valid handle
callback : called on success or failure (unless weak_object has become unreferenced)
user_data : arbitrary user-supplied data
destroy : called to destroy user_data after calling callback, or when weak_object becomes unreferenced (whichever occurs sooner)
weak_object : if not NULL, an object to be weakly referenced: if it is destroyed, callback will not be called

tp_connection_hold_handles ()

void                tp_connection_hold_handles          (TpConnection *self,
                                                         gint timeout_ms,
                                                         TpHandleType handle_type,
                                                         guint n_handles,
                                                         const TpHandle *handles,
                                                         TpConnectionHoldHandlesCb callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Hold (ensure a reference to) the given handles, if they are valid.

If they are valid, the callback will later be called with the given handles; if not all of them are valid, the callback will be called with an error.

This function, along with tp_connection_unref_handles(), tp_connection_get_contact_attributes() and TpContact, keeps a client-side reference count of handles; you should not use the RequestHandles, HoldHandles and GetContactAttributes D-Bus methods directly as well as these functions.

self : a connection
timeout_ms : the timeout in milliseconds, or -1 to use the default
handle_type : the handle type
n_handles : the number of handles in handles (must be at least 1)
handles : an array of handles
callback : called on success or failure (unless weak_object has become unreferenced)
user_data : arbitrary user-supplied data
destroy : called to destroy user_data after calling callback, or when weak_object becomes unreferenced (whichever occurs sooner)
weak_object : if not NULL, an object to be weakly referenced: if it is destroyed, callback will not be called

tp_connection_unref_handles ()

void                tp_connection_unref_handles         (TpConnection *self,
                                                         TpHandleType handle_type,
                                                         guint n_handles,
                                                         const TpHandle *handles);

Release the reference to the handles in handles that was obtained by calling tp_connection_hold_handles() or tp_connection_request_handles().

This function might release any references held by calling tp_cli_connection_call_request_handles(), tp_cli_connection_run_request_handles(), tp_cli_connection_call_hold_handles(), tp_cli_connection_run_hold_handles(), tp_cli_connection_interface_contacts_call_get_contact_attributes() or tp_cli_connection_interface_contacts_run_get_contact_attributes() directly. Those functions should be avoided in favour of using TpContact, tp_connection_hold_handles(),