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 **out0,
                                                         GError **error,
                                                         GMainLoop **loop);
gboolean            tp_cli_connection_interface_capabilities_run_get_capabilities
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         const GArray *in_handles,
                                                         GPtrArray **out0,
                                                         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 *out0,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                (*tp_cli_connection_interface_capabilities_callback_for_get_capabilities)
                                                        (TpConnection *proxy,
                                                         const GPtrArray *out0,
                                                         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 **out0,
                                                         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 CapabilitiesChanged signal will be emitted for the user's own handle (as returned by GetSelfHandle) the 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

out0 :

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 **out0,
                                                         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, or the connection itself (where handle is zero).

proxy :

A TpConnection or subclass

timeout_ms :

Timeout in milliseconds, or -1 for default

in_handles :

Used to pass an 'in' argument: An array of contact handles for this connection, or zero to query capabilities available on the connection itself

out0 :

Used to return an 'out' argument if TRUE is returned: 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 CapabilitiesChanged signal will be emitted for the user's own handle (as returned by GetSelfHandle) the 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, or the connection itself (where handle is zero).

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

in_handles :

Used to pass an 'in' argument: An array of contact handles for this connection, or zero to query capabilities available on the connection itself

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 *out0,
                                                         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

out0 :

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 *out0,
                                                         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

out0 :

Used to return an 'out' argument if error is NULL: 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.

Announce that there has been a change of capabilities on the given handle, or on the connection itself if the handle is zero.

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