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

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.