Description
A sidecar is an object with a particular interface which provides additional connection-specific functionality. This interface serves as a way to ensure these sidecars.
Methods
EnsureSidecar (s: Main_Interface) → o: Path, a{sv}: Properties
Parameters
- Main_Interface — s (DBus_Interface)
Returns
- Path — o
- Properties — a{sv} (Qualified_Property_Value_Map)
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
- Service Busy
- Cancelled