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.