Connection Sidecars interface

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

Functions

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"> <p>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.</p> <p>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).</p> <tp:rationale> <p>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.</p> </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 &quot;primary&quot; 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

 

See Also

TpConnection