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:

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.