| Top | |
|
|
|
Connection Sidecars interfaceConnection Sidecars interface — client-side wrappers for the Sidecars interface |
Some Telepathy connection managers have a plugin API, with plugins providing plugin-specific channel types and other D-Bus APIs. It is technically difficult for plugins to add interfaces analogous to Aliasing, Avatars etc. to a Connection. The Sidecars1 interface provides an alternative, by attaching plugin-provided interfaces to a secondary object.
TpProxyPendingCall * tp_cli_connection_interface_sidecars1_call_ensure_sidecar (TpConnection *proxy,gint timeout_ms,const gchar *in_Main_Interface,tp_cli_connection_interface_sidecars1_callback_for_ensure_sidecar callback,gpointer user_data,GDestroyNotify destroy,GObject *weak_object);
Start a EnsureSidecar method call.
<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>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.</p> <p>This method may be called at any point during the lifetime of a connection, even before its <tp:type>Connection_Status</tp:type> 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).</p> <tp:rationale> <p>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 <tp:dbus-ref namespace="im.telepathy.v1">Channel</tp:dbus-ref> instead.</p> </tp:rationale>
proxy |
the TpProxy |
|
timeout_ms |
the timeout in milliseconds, or -1 to use the default |
|
in_Main_Interface |
Used to pass an 'in' argument: 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 <tt>com.example.PrivacyLists</tt>. |
|
callback |
called when the method call succeeds or fails;
may be |
|
user_data |
user-supplied data passed to the callback;
must be |
|
destroy |
called with the user_data as argument, after the
call has succeeded, failed or been cancelled;
must be |
|
weak_object |
If not |
a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.
void (*tp_cli_connection_interface_sidecars1_callback_for_ensure_sidecar) (TpConnection *proxy,const gchar *out_Path,GHashTable *out_Properties,const GError *error,gpointer user_data,GObject *weak_object);
Signature of the callback called when a EnsureSidecar method call succeeds or fails.
proxy |
the proxy on which the call was made |
|
out_Path |
Used to return an 'out' argument if |
|
out_Properties |
Used to return an 'out' argument if |
|
error |
|
|
user_data |
user-supplied data |
|
weak_object |
user-supplied object |