## Connection Capabilities interface

Connection Capabilities interface — client-side wrappers for the Capabilities interface

## Synopsis

    #include <telepathy-glib/connection.h>

    gboolean            tp_cli_connection_interface_capabilities_run_advertise_capabilities
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             const GPtrArray *in_Add,
                                                             const gchar **in_Remove,
                                                             GPtrArray **out_Self_Capabilities,
                                                             GError **error,
                                                             GMainLoop **loop);
    gboolean            tp_cli_connection_interface_capabilities_run_get_capabilities
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             const GArray *in_Handles,
                                                             GPtrArray **out_Contact_Capabilities,
                                                             GError **error,
                                                             GMainLoop **loop);
    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);
    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);
    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);
    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);
    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);
    void                (*tp_cli_connection_interface_capabilities_signal_callback_capabilities_changed)
                                                            (TpConnection *proxy,
                                                             const GPtrArray *arg_Caps,
                                                             gpointer user_data,
                                                             GObject *weak_object);

## Description

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

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

## Details

### tp_cli_connection_interface_capabilities_run_advertise_capabilities ()

    gboolean            tp_cli_connection_interface_capabilities_run_advertise_capabilities
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             const GPtrArray *in_Add,
                                                             const gchar **in_Remove,
                                                             GPtrArray **out_Self_Capabilities,
                                                             GError **error,
                                                             GMainLoop **loop);

Call the method AdvertiseCapabilities and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

<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>

`proxy` : | A TpConnection or subclass
`timeout_ms` : | Timeout in milliseconds, or -1 for 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
`out_Self_Capabilities` : | Used to return an 'out' argument if `TRUE` is returned: 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` : | If not `NULL`, used to return errors if `FALSE` is returned
`loop` : | If not `NULL`, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with `g_main_loop_quit()`, causing a return of `FALSE` with `error` set to `TP_DBUS_ERROR_CANCELLED`
Returns : | TRUE on success, FALSE and sets `error` on error

### tp_cli_connection_interface_capabilities_run_get_capabilities ()

    gboolean            tp_cli_connection_interface_capabilities_run_get_capabilities
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             const GArray *in_Handles,
                                                             GPtrArray **out_Contact_Capabilities,
                                                             GError **error,
                                                             GMainLoop **loop);

Call the method GetCapabilities and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

Returns an array of capabilities for the given contact handles.

`proxy` : | A TpConnection or subclass
`timeout_ms` : | Timeout in milliseconds, or -1 for 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>

`out_Contact_Capabilities` : | Used to return an 'out' argument if `TRUE` is returned: <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` : | If not `NULL`, used to return errors if `FALSE` is returned
`loop` : | If not `NULL`, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with `g_main_loop_quit()`, causing a return of `FALSE` with `error` set to `TP_DBUS_ERROR_CANCELLED`
Returns : | TRUE on success, FALSE and sets `error` on error

### 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>

`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.

`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.

`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.

`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>

`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.

`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