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
Generated by GTK-Doc V1.10