Connection ContactCapabilities and Capabilities interfaces

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

Functions

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"> <p>Returns an array of requestable channel classes for the given contact handles, representing the channel requests that are expected to succeed.</p>

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"> <p>Alter the connection's advertised capabilities to include the intersection of the given clients' capabilities with what the connection manager is able to implement.</p> <p>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.</p> <p>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.</p> <tp:rationale> <p>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.</p> </tp:rationale> <p>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.</p>

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"> <p>Announce that there has been a change of capabilities on the given handles. A single signal can be emitted for several contacts.</p> <tp:rationale> <p>The underlying protocol can get several contacts' capabilities at the same time.</p> </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"> <p>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.</p> <p>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.</p> <p>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.</p>

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"> <p>Announce that there has been a change of capabilities on the given handle.</p> <p>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.</p>

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

 

See Also

TpConnection