Conn.FUTURE — Telepathy D-Bus Interface Specification

# Interface Connection.FUTURE

Interface Index (Compact) | Summary | Methods

### Methods

EnsureSidecar | (s: Main_Interface) | → | o: Path, a{sv}: Properties |

WARNING: This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Do not include this interface in libraries that care about compatibility.
Objects implementing this interface must also implement:

- org.freedesktop.Telepathy.Connection

# Methods

(Permalink)

## EnsureSidecar (s: Main_Interface) → o: Path, a{sv}: Properties

Added in 0.19.0. (as a draft)

### Parameters

- Main_Interface — s (DBus_Interface)
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 `com.example.PrivacyLists`.

### Returns

- Path — o
The object path of the sidecar, exported by the same bus name as the Connection to which it is attached.
- Properties — a{sv} (Qualified_Property_Value_Map)
Immutable properties of the sidecar.

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 Connection_Status 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).

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

### Possible Errors

- Not Implemented
The requested sidecar is not implemented by this connection manager, or a necessary server-side component does not exist. (FIXME: split these two errors out? Then again, once we list the guaranteed and possible sidecars on a Protocol object, clients can tell the difference themselves, because they shouldn't be calling this in the first case.)
- Service Busy
A server-side component needed by the requested sidecar reported it is currently too busy, or did not respond for some implementation-defined time. The caller may wish to try again later.
- Cancelled
The connection was disconnected while the sidecar was being set up.