Connection Sidecars interface: telepathy-glib API Reference Manual

Connection Sidecars interface

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

Functions

TpProxyPendingCall *	tp_cli_connection_interface_sidecars1_call_ensure_sidecar ()
void	(*tp_cli_connection_interface_sidecars1_callback_for_ensure_sidecar) ()

Includes

#include <telepathy-glib/telepathy-glib-dbus.h>

Description

Some Telepathy connection managers have a plugin API, with plugins providing plugin-specific channel types and other D-Bus APIs. It is technically difficult for plugins to add interfaces analogous to Aliasing, Avatars etc. to a Connection. The Sidecars1 interface provides an alternative, by attaching plugin-provided interfaces to a secondary object.

Functions

tp_cli_connection_interface_sidecars1_call_ensure_sidecar ()

TpProxyPendingCall *
tp_cli_connection_interface_sidecars1_call_ensure_sidecar
                               (TpConnection *proxy,
                                gint timeout_ms,
                                const gchar *in_Main_Interface,
                                tp_cli_connection_interface_sidecars1_callback_for_ensure_sidecar callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object);

Start a EnsureSidecar method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Request an object with a particular interface providing additional connection-specific functionality, together with its immutable properties. These will often be implemented by plug-ins to the connection managers; for example, support for an XMPP XEP for which no generic Telepathy interface exists might be implemented by a Gabble plugin exposing a sidecar with a particular interface. This method may be called at any point during the lifetime of a connection, even before its <tp:type>Connection_Status</tp:type> changes to Connected. It MAY take a long time to return—perhaps it needs to wait for a connection to be established and for all the services supported by the server to be discovered before determining whether necessary server-side support is available—so callers SHOULD override the default method timeout (25 seconds) with a much higher value (perhaps even MAX_INT32, meaning “no timeout” in recent versions of libdbus). <tp:rationale> There is an implicit assumption that any connection manager plugin will only want to export one “primary” object per feature it implements, since there is a one-to-one mapping between interface and object. This is reasonable since Sidecars are (intended to be) analogous to extra interfaces on the connection, providing once-per-connection shared functionality; it also makes client code straightforward (look up the interface you care about in a dictionary, build a proxy object from the value). More “plural” plugins are likely to want to implement new types of <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref> instead. </tp:rationale>

Parameters

proxy	the TpProxy
timeout_ms	the timeout in milliseconds, or -1 to use the default
in_Main_Interface	Used to pass an 'in' argument: The "primary" interface implemented by an object attached to a connection. For example, a Gabble plugin implementing fine-grained control of XEP-0016 privacy lists might expose an object implementing <tt>com.example.PrivacyLists</tt>.
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_sidecars1_callback_for_ensure_sidecar ()

void
(*tp_cli_connection_interface_sidecars1_callback_for_ensure_sidecar)
                               (TpConnection *proxy,
                                const gchar *out_Path,
                                GHashTable *out_Properties,
                                const GError *error,
                                gpointer user_data,
                                GObject *weak_object);

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

Parameters

proxy	the proxy on which the call was made
out_Path	Used to return an 'out' argument if `error` is `NULL`: The object path of the sidecar, exported by the same bus name as the Connection to which it is attached.
out_Properties	Used to return an 'out' argument if `error` is `NULL`: Immutable properties of the sidecar.
error	`NULL` on success, or an error on failure
user_data	user-supplied data
weak_object	user-supplied object