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

## See Also

TpConnection