telepathy-glib API Reference Manual: Connection ContactCapabilities and Capabilities interfaces

Connection ContactCapabilities and Capabilities interfaces

Connection ContactCapabilities and Capabilities interfaces — client-side wrappers for the capabilities interfaces

Functions

void	(*tp_cli_connection_interface_contact_capabilities1_callback_for_update_capabilities) ()
TpProxyPendingCall *	tp_cli_connection_interface_contact_capabilities1_call_update_capabilities ()
void	(*tp_cli_connection_interface_contact_capabilities1_signal_callback_contact_capabilities_changed) ()
TpProxySignalConnection *	tp_cli_connection_interface_contact_capabilities1_connect_to_contact_capabilities_changed ()

Object Hierarchy

Includes

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

Description

Some instant messaging protocols allow discovery of the capabilities of a user's client. In Telepathy, this is represented by the ContactCapabilities interface, which lets applications advertise extra capabilities for the local user, and query the interfaces supported by their contacts.

The Capabilities interface is an older API with similar functionality.

This section documents the auto-generated C wrappers for the ContactCapabilities and Capabilities interfaces, used with TpConnection objects.

Functions

tp_cli_connection_interface_contact_capabilities1_callback_for_update_capabilities ()

void
(*tp_cli_connection_interface_contact_capabilities1_callback_for_update_capabilities)
                               (TpConnection *proxy,
                                const GError *error,
                                gpointer user_data,
                                GObject *weak_object);

Signature of the callback called when a UpdateCapabilities method call succeeds or fails.

Parameters

proxy	the proxy on which the call was made
error	`NULL` on success, or an error on failure
user_data	user-supplied data
weak_object	user-supplied object

tp_cli_connection_interface_contact_capabilities1_call_update_capabilities ()

TpProxyPendingCall *
tp_cli_connection_interface_contact_capabilities1_call_update_capabilities
                               (TpConnection *proxy,
                                gint timeout_ms,
                                const GPtrArray *in_Handler_Capabilities,
                                tp_cli_connection_interface_contact_capabilities1_callback_for_update_capabilities callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object);

Start a UpdateCapabilities method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Alter the connection's advertised capabilities to include the intersection of the given clients' capabilities with what the connection manager is able to implement. On connections managed by the ChannelDispatcher, processes other than the ChannelDispatcher SHOULD NOT call this method, and the ChannelDispatcher SHOULD use this method to advertise the capabilities of all the registered <tp:dbus-ref namespace="im.telepathy.v1">Client.Handler</tp:dbus-ref> implementations.On connections not managed by the ChannelDispatcher, clients MAY use this method directly, to indicate the channels they will handle and the extra capabilities they have. Upon a successful invocation of this method, the connection manager will only emit the <tp:member-ref>ContactCapabilitiesChanged</tp:member-ref> signal for the user's <tp:dbus-ref namespace="im.telepathy.v1.Connection">SelfHandle</tp:dbus-ref> if, in the underlying protocol, the new capabilities are distinct from the previous state. <tp:rationale> The connection manager will essentially intersect the provided capabilities and the channel classes it implements. Therefore, certain properties which are never fixed for a channel class (such as the target handle, or the Parameters property of a tube channel) will almost certainly not be advertised. </tp:rationale> This method MAY be called on a newly-created connection while it is still in the DISCONNECTED state, to request that when the connection connects, it will do so with the appropriate capabilities. Doing so MUST NOT fail.

Parameters

proxy	the TpProxy
timeout_ms	the timeout in milliseconds, or -1 to use the default
in_Handler_Capabilities	Used to pass an 'in' argument: <p>The capabilities of one or more clients.</p> <p>For each client in the given list, any capabilities previously advertised for the same client name are discarded, then replaced by the capabilities indicated.</p> <p>As a result, if a client becomes unavailable, this method SHOULD be called with a <tp:type>Handler_Capabilities</tp:type> structure containing its name, an empty list of channel classes, and an empty list of capabilities. When this is done, the connection manager SHOULD free all memory associated with that client name.</p> <tp:rationale> <p>This method takes a list of clients so that when the channel dispatcher first calls it (with a list of all the Handlers that are initially available), the changes can be made atomically, with only one transmission of updated capabilities to the network. Afterwards, the channel dispatcher will call this method with a single-element list every time a Handler becomes available or unavailable.</p> </tp:rationale> <p>The connection manager MUST ignore any channel classes and client capabilities for which there is no representation in the protocol or no support in the connection manager.</p>
callback	called when the method call succeeds or fails; may be `NULL` to make a "fire and forget" call with no reply tracking
user_data	user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
destroy	called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
weak_object	If not `NULL`, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be `NULL` if `callback` is `NULL`

Returns

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_connection_interface_contact_capabilities1_signal_callback_contact_capabilities_changed ()

void
(*tp_cli_connection_interface_contact_capabilities1_signal_callback_contact_capabilities_changed)
                               (TpConnection *proxy,
                                GHashTable *arg_caps,
                                gpointer user_data,
                                GObject *weak_object);

Represents the signature of a callback for the signal ContactCapabilitiesChanged.

Parameters

proxy	The proxy on which `tp_cli_connection_interface_contact_capabilities1_connect_to_contact_capabilities_changed()` was called
arg_caps	<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> All the capabilities of the contacts
user_data	User-supplied data
weak_object	User-supplied weakly referenced object

tp_cli_connection_interface_contact_capabilities1_connect_to_contact_capabilities_changed ()

TpProxySignalConnection *
tp_cli_connection_interface_contact_capabilities1_connect_to_contact_capabilities_changed
                               (TpConnection *proxy,
                                tp_cli_connection_interface_contact_capabilities1_signal_callback_contact_capabilities_changed callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object,
                                GError **error);

Connect a handler to the signal ContactCapabilitiesChanged.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Announce that there has been a change of capabilities on the given handles. A single signal can be emitted for several contacts. <tp:rationale> The underlying protocol can get several contacts' capabilities at the same time. </tp:rationale>

Parameters

proxy	A TpConnection or subclass
callback	Callback to be called when the signal is received
user_data	User-supplied data for the callback
destroy	Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns `NULL`
weak_object	A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected
error	If not `NULL`, used to raise an error if `NULL` is returned

Returns

a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or NULL if the proxy does not have the desired interface or has become invalid.

Connection ContactCapabilities and Capabilities interfaces

Functions

Object Hierarchy

Includes

Description

Functions

tp_cli_connection_interface_contact_capabilities1_callback_for_update_capabilities ()

Parameters

tp_cli_connection_interface_contact_capabilities1_call_update_capabilities ()

Parameters

Returns

tp_cli_connection_interface_contact_capabilities1_signal_callback_contact_capabilities_changed ()

Parameters

tp_cli_connection_interface_contact_capabilities1_connect_to_contact_capabilities_changed ()

Parameters

Returns

Types and Values

See Also