telepathy-glib API Reference Manual | ||||
---|---|---|---|---|
Top | Description |
Connection Sidecars interfaceConnection Sidecars interface — client-side wrappers for the Sidecars interface |
#include <telepathy-glib/telepathy-glib-dbus.h> 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
); 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
);
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="org.freedesktop.Telepathy">Channel</tp:dbus-ref> instead.</p> </tp:rationale>
|
the TpProxy |
|
the timeout in milliseconds, or -1 to use the default |
|
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>. |
|
called when the method call succeeds or fails;
may be NULL to make a "fire and forget" call with no
reply tracking |
|
user-supplied data passed to the callback;
must be NULL if callback is NULL
|
|
called with the user_data as argument, after the
call has succeeded, failed or been cancelled;
must be NULL if callback is NULL
|
|
If not NULL , a GObject which will be
weakly referenced; if it is destroyed, this call
will automatically be cancelled. Must be NULL if
callback is NULL
|
Returns : |
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.
|
the proxy on which the call was made |
|
Used to return an 'out' argument if error is NULL : The object path of the sidecar, exported by the same bus name as the Connection to which it is attached. |
|
Used to return an 'out' argument if error is NULL : Immutable properties of the sidecar. |
|
NULL on success, or an error on failure |
|
user-supplied data |
|
user-supplied object |