## Connection Sidecars interface

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

## Synopsis

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

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

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

## Details

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

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

`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