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

Connection ContactCapabilities and Capabilities interfaces

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

Functions

void	(*tp_cli_connection_interface_contact_capabilities_callback_for_get_contact_capabilities) ()
TpProxyPendingCall *	tp_cli_connection_interface_contact_capabilities_call_get_contact_capabilities ()
void	(*tp_cli_connection_interface_contact_capabilities_callback_for_update_capabilities) ()
TpProxyPendingCall *	tp_cli_connection_interface_contact_capabilities_call_update_capabilities ()
void	(*tp_cli_connection_interface_contact_capabilities_signal_callback_contact_capabilities_changed) ()
TpProxySignalConnection *	tp_cli_connection_interface_contact_capabilities_connect_to_contact_capabilities_changed ()
TpProxyPendingCall *	tp_cli_connection_interface_capabilities_call_advertise_capabilities ()
TpProxyPendingCall *	tp_cli_connection_interface_capabilities_call_get_capabilities ()
void	(*tp_cli_connection_interface_capabilities_callback_for_advertise_capabilities) ()
void	(*tp_cli_connection_interface_capabilities_callback_for_get_capabilities) ()
TpProxySignalConnection *	tp_cli_connection_interface_capabilities_connect_to_capabilities_changed ()
void	(*tp_cli_connection_interface_capabilities_signal_callback_capabilities_changed) ()

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

void
(*tp_cli_connection_interface_contact_capabilities_callback_for_get_contact_capabilities)
                               (TpConnection *proxy,
                                GHashTable *out_Contact_Capabilities,
                                const GError *error,
                                gpointer user_data,
                                GObject *weak_object);

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

Parameters

proxy	the proxy on which the call was made
out_Contact_Capabilities	Used to return an 'out' argument if `error` is `NULL`: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A map from contact handles to lists of requestable channel classes, representing the channel requests that are expected to succeed for that contact.</p> <p>Contacts listed among Handles whose capabilities are unknown SHOULD be omitted from this map; contacts known to have an empty set of capabilities SHOULD be included in the keys of this map, with an empty array as the corresponding value.</p>
error	`NULL` on success, or an error on failure
user_data	user-supplied data
weak_object	user-supplied object

tp_cli_connection_interface_contact_capabilities_call_get_contact_capabilities ()

TpProxyPendingCall *
tp_cli_connection_interface_contact_capabilities_call_get_contact_capabilities
                               (TpConnection *proxy,
                                gint timeout_ms,
                                const GArray *in_Handles,
                                tp_cli_connection_interface_contact_capabilities_callback_for_get_contact_capabilities callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object);

Start a GetContactCapabilities method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Returns an array of requestable channel classes for the given contact handles, representing the channel requests that are expected to succeed.

Parameters

proxy	the TpProxy
timeout_ms	the timeout in milliseconds, or -1 to use the default
in_Handles	Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An array of contact handles for this connection.</p> <p>The handle zero MUST NOT be included in the request.</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_capabilities_callback_for_update_capabilities ()

void
(*tp_cli_connection_interface_contact_capabilities_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_capabilities_call_update_capabilities ()

TpProxyPendingCall *
tp_cli_connection_interface_contact_capabilities_call_update_capabilities
                               (TpConnection *proxy,
                                gint timeout_ms,
                                const GPtrArray *in_Handler_Capabilities,
                                tp_cli_connection_interface_contact_capabilities_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="org.freedesktop.Telepathy">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="org.freedesktop.Telepathy.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_capabilities_signal_callback_contact_capabilities_changed ()

void
(*tp_cli_connection_interface_contact_capabilities_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_capabilities_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_capabilities_connect_to_contact_capabilities_changed ()

TpProxySignalConnection *
tp_cli_connection_interface_contact_capabilities_connect_to_contact_capabilities_changed
                               (TpConnection *proxy,
                                tp_cli_connection_interface_contact_capabilities_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.

tp_cli_connection_interface_capabilities_call_advertise_capabilities ()

TpProxyPendingCall *
tp_cli_connection_interface_capabilities_call_advertise_capabilities
                               (TpConnection *proxy,
                                gint timeout_ms,
                                const GPtrArray *in_Add,
                                const gchar **in_Remove,
                                tp_cli_connection_interface_capabilities_callback_for_advertise_capabilities callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object);

Start a AdvertiseCapabilities method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Used by user interfaces to indicate which channel types they are able to handle on this connection. Because these may be provided by different client processes, this method accepts channel types to add and remove from the set already advertised on this connection. The type of advertised capabilities (create versus invite) is protocol-dependent and hence cannot be set by the this method. In the case of a client adding an already advertised channel type but with new channel type specific flags, the connection manager should simply add the new flags to the set of advertised capabilities. Upon a successful invocation of this method, the <tp:member-ref>CapabilitiesChanged</tp:member-ref> signal will be emitted for the user's own handle ( <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.GetSelfHandle</tp:dbus-ref>) by the connection manager to indicate the changes that have been made. This signal should also be monitored to ensure that the set is kept accurate - for example, a client may remove capabilities or type specific capability flags when it exits which are still provided by another client. On connections managed by the <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>, this method SHOULD NOT be used by clients other than the ChannelDispatcher itself.

Parameters

proxy	the TpProxy
timeout_ms	the timeout in milliseconds, or -1 to use the default
in_Add	Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> An array of structures containing: <ul> <li>a string channel type</li> <li>a bitwise OR of type specific capability flags</li> </ul>
in_Remove	Used to pass an 'in' argument: An array of D-Bus interface names of channel types to remove
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_capabilities_call_get_capabilities ()

TpProxyPendingCall *
tp_cli_connection_interface_capabilities_call_get_capabilities
                               (TpConnection *proxy,
                                gint timeout_ms,
                                const GArray *in_Handles,
                                tp_cli_connection_interface_capabilities_callback_for_get_capabilities callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object);

Start a GetCapabilities method call.

Returns an array of capabilities for the given contact handles.

Parameters

proxy	the TpProxy
timeout_ms	the timeout in milliseconds, or -1 to use the default
in_Handles	Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An array of contact handles for this connection.</p> <p>This may include zero, which originally meant a query for capabilities available on the connection itself. This usage is deprecated; clients SHOULD NOT do this, and connection managers SHOULD proceed as though zero had not been present in this list.</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_capabilities_callback_for_advertise_capabilities ()

void
(*tp_cli_connection_interface_capabilities_callback_for_advertise_capabilities)
                               (TpConnection *proxy,
                                const GPtrArray *out_Self_Capabilities,
                                const GError *error,
                                gpointer user_data,
                                GObject *weak_object);

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

Parameters

proxy	the proxy on which the call was made
out_Self_Capabilities	Used to return an 'out' argument if `error` is `NULL`: An array of structures describing the current capabilities containing: <ul> <li>a string channel type</li> <li>a bitwise OR of type specific capability flags</li> </ul>
error	`NULL` on success, or an error on failure
user_data	user-supplied data
weak_object	user-supplied object

tp_cli_connection_interface_capabilities_callback_for_get_capabilities ()

void
(*tp_cli_connection_interface_capabilities_callback_for_get_capabilities)
                               (TpConnection *proxy,
                                const GPtrArray *out_Contact_Capabilities,
                                const GError *error,
                                gpointer user_data,
                                GObject *weak_object);

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

Parameters

proxy	the proxy on which the call was made
out_Contact_Capabilities	Used to return an 'out' argument if `error` is `NULL`: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> An array of structures containing: <ul> <li>an integer handle representing the contact</li> <li>a string channel type</li> <li>a bitwise OR of generic capability flags for the type</li> <li>a bitwise OR of type specific capability flags for the type</li> </ul>
error	`NULL` on success, or an error on failure
user_data	user-supplied data
weak_object	user-supplied object

tp_cli_connection_interface_capabilities_connect_to_capabilities_changed ()

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

Connect a handler to the signal CapabilitiesChanged.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Announce that there has been a change of capabilities on the given handle. If the handle is zero, the capabilities refer to the connection itself, in some poorly defined way. This usage is deprecated and clients should ignore it.

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.

tp_cli_connection_interface_capabilities_signal_callback_capabilities_changed ()

void
(*tp_cli_connection_interface_capabilities_signal_callback_capabilities_changed)
                               (TpConnection *proxy,
                                const GPtrArray *arg_Caps,
                                gpointer user_data,
                                GObject *weak_object);

Represents the signature of a callback for the signal CapabilitiesChanged.

Parameters

proxy	The proxy on which `tp_cli_connection_interface_capabilities_connect_to_capabilities_changed()` was called
arg_Caps	<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> An array of structures containing: <ul> <li>an integer handle representing the contact</li> <li>a string channel type</li> <li>a bitwise OR of the contact's old generic capability flags</li> <li>a bitwise OR of the contact's new generic capability flags</li> <li>a bitwise OR of the contact's old type specific capability flags</li> <li>a bitwise OR of the contact's new type specific capability flags</li> </ul>
user_data	User-supplied data
weak_object	User-supplied weakly referenced object