telepathy-glib API Reference Manual: ConnectionManager interface

ConnectionManager interface

ConnectionManager interface — client-side wrappers for ConnectionManager core functionality

Functions

void	(*tp_cli_connection_manager_callback_for_request_connection) ()
TpProxyPendingCall *	tp_cli_connection_manager_call_request_connection ()
void	(*tp_cli_connection_manager_signal_callback_new_connection) ()
TpProxySignalConnection *	tp_cli_connection_manager_connect_to_new_connection ()
TpProxyPendingCall *	tp_cli_protocol_call_identify_account ()
TpProxyPendingCall *	tp_cli_protocol_call_normalize_contact ()
void	(*tp_cli_protocol_callback_for_identify_account) ()
void	(*tp_cli_protocol_callback_for_normalize_contact) ()
TpProxyPendingCall *	tp_cli_protocol_interface_addressing1_call_normalize_contact_uri ()
TpProxyPendingCall *	tp_cli_protocol_interface_addressing1_call_normalize_vcard_address ()
void	(*tp_cli_protocol_interface_addressing1_callback_for_normalize_contact_uri) ()
void	(*tp_cli_protocol_interface_addressing1_callback_for_normalize_vcard_address) ()

Object Hierarchy

Includes

#include <telepathy-glib/cli-misc.h>

Description

This section documents the auto-generated C wrappers for the ConnectionManager D-Bus interface.

Functions

tp_cli_connection_manager_callback_for_request_connection ()

void
(*tp_cli_connection_manager_callback_for_request_connection)
                               (TpConnectionManager *proxy,
                                const gchar *out_Bus_Name,
                                const gchar *out_Object_Path,
                                const GError *error,
                                gpointer user_data,
                                GObject *weak_object);

Signature of the callback called when a RequestConnection method call succeeds or fails.

Parameters

proxy	the proxy on which the call was made
out_Bus_Name	Used to return an 'out' argument if `error` is `NULL`: A D-Bus service name where the new Connection object can be found
out_Object_Path	Used to return an 'out' argument if `error` is `NULL`: The D-Bus object path to the Connection on this service
error	`NULL` on success, or an error on failure
user_data	user-supplied data
weak_object	user-supplied object

tp_cli_connection_manager_call_request_connection ()

TpProxyPendingCall *
tp_cli_connection_manager_call_request_connection
                               (TpConnectionManager *proxy,
                                gint timeout_ms,
                                const gchar *in_Protocol,
                                GHashTable *in_Parameters,
                                tp_cli_connection_manager_callback_for_request_connection callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object);

Start a RequestConnection method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Request a <tp:dbus-ref namespace="im.telepathy.v1">Connection</tp:dbus-ref> object representing a given account on a given protocol with the given parameters. The method returns the bus name and the object path where the new Connection object can be found, which should have the status of Connection_Status_Disconnected, to allow signal handlers to be attached before connecting is started with the <tp:dbus-ref namespace="im.telepathy.v1.Connection">Connect</tp:dbus-ref> method. Most applications should not use this method: they should instead use the the <tp:dbus-ref namespace="imt1.Account">Connection</tp:dbus-ref> property on an <tp:dbus-ref namespace="imt1">Account</tp:dbus-ref> object obtained from the <tp:dbus-ref namespace="imt1">AccountManager</tp:dbus-ref>. This method is used internally by the account manager to create connections when needed. The parameters which must and may be provided in the parameters dictionary can be discovered by looking at the <tp:dbus-ref namespace="imt1.Protocol">Parameters</tp:dbus-ref> property by getting the <tp:member-ref>Protocols</tp:member-ref> property. These parameters, their types, and their default values may be cached in files so that all available connection managers do not need to be started to discover which protocols are available. To request values for these parameters from the user, a client must have prior knowledge of the meaning of the parameter names, so the well-known names and types defined by the <tp:type>Connection_Parameter_Name</tp:type> type should be used where appropriate. Connection manager authors SHOULD avoid introducing parameters whose default values would not be serializable in a <code>.manager</code> file. <tp:rationale> The same serialization format is used in Mission Control to store accounts. </tp:rationale> Every successful RequestConnection call will cause the emission of a <tp:member-ref>NewConnection</tp:member-ref> signal for the same newly created connection. The requester can use the returned object path and service name independently of the emission of that signal. In that case this signal emission is most useful for, e.g. other processes that are monitoring the creation of new connections.

Parameters

proxy	the TpProxy
timeout_ms	the timeout in milliseconds, or -1 to use the default
in_Protocol	Used to pass an 'in' argument: The protocol identifier
in_Parameters	Used to pass an 'in' argument: A dictionary mapping parameter names to values of the appropriate type, as indicated by the <tp:dbus-ref namespace="imt1.Protocol">Parameters</tp:dbus-ref> property (which can be retrieved by getting the <tp:member-ref>Protocols</tp:member-ref> property) and the well-known list of names and value types documented on the <tp:type>Connection_Parameter_Name</tp:type> type.
callback	called when the method call succeeds or fails; may be `NULL` to make a "fire and forget" call with no reply tracking
user_data	user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
destroy	called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
weak_object	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.

tp_cli_connection_manager_signal_callback_new_connection ()

void
(*tp_cli_connection_manager_signal_callback_new_connection)
                               (TpConnectionManager *proxy,
                                const gchar *arg_Bus_Name,
                                const gchar *arg_Object_Path,
                                const gchar *arg_Protocol,
                                gpointer user_data,
                                GObject *weak_object);

Represents the signature of a callback for the signal NewConnection.

Parameters

proxy	The proxy on which `tp_cli_connection_manager_connect_to_new_connection()` was called
arg_Bus_Name	The D-Bus service where the connection object can be found
arg_Object_Path	The object path of the Connection object on this service
arg_Protocol	The identifier for the protocol this connection uses
user_data	User-supplied data
weak_object	User-supplied weakly referenced object

tp_cli_connection_manager_connect_to_new_connection ()

TpProxySignalConnection *
tp_cli_connection_manager_connect_to_new_connection
                               (TpConnectionManager *proxy,
                                tp_cli_connection_manager_signal_callback_new_connection callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object,
                                GError **error);

Connect a handler to the signal NewConnection.

Emitted when a new <tp:dbus-ref namespace="im.telepathy.v1">Connection</tp:dbus-ref> object is created.

Parameters

proxy	A TpConnectionManager or subclass
callback	Callback to be called when the signal is received
user_data	User-supplied data for the callback
destroy	Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns `NULL`
weak_object	A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected
error	If not `NULL`, used to raise an error if `NULL` is returned

Returns

a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or NULL if the proxy does not have the desired interface or has become invalid.

tp_cli_protocol_call_identify_account ()

TpProxyPendingCall *
tp_cli_protocol_call_identify_account (gpointer proxy,
                                       gint timeout_ms,
                                       GHashTable *in_Parameters,
                                       tp_cli_protocol_callback_for_identify_account callback,
                                       gpointer user_data,
                                       GDestroyNotify destroy,
                                       GObject *weak_object);

Start a IdentifyAccount method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Return a string which uniquely identifies the account to which the given parameters would connect. <tp:rationale> For many protocols, this would return the well-known 'account' parameter. However, for IRC the returned string would be composed from the 'account' (i.e. nickname) and 'server' parameters. AccountManager implementations can use this to form the account-specific part of an Account's object path. </tp:rationale>

Parameters

proxy	the TpProxy
timeout_ms	the timeout in milliseconds, or -1 to use the default
in_Parameters	Used to pass an 'in' argument: A set of parameters as would be provided to <tp:dbus-ref namespace="im.telepathy.v1.ConnectionManager">RequestConnection</tp:dbus-ref>
callback	called when the method call succeeds or fails; may be `NULL` to make a "fire and forget" call with no reply tracking
user_data	user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
destroy	called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
weak_object	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.

tp_cli_protocol_call_normalize_contact ()

TpProxyPendingCall *
tp_cli_protocol_call_normalize_contact
                               (gpointer proxy,
                                gint timeout_ms,
                                const gchar *in_Contact_ID,
                                tp_cli_protocol_callback_for_normalize_contact callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object);

Start a NormalizeContact method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Attempt to normalize the given contact ID. Where possible, this SHOULD return the same thing that would be returned by <tp:dbus-ref namespace="imt1.Connection">GetContactByID</tp:dbus-ref> on a connected <tp:dbus-ref namespace="im.telepathy.v1">Connection</tp:dbus-ref>. If full normalization requires network activity or is otherwise impossible to do without a <tp:dbus-ref namespace="im.telepathy.v1">Connection</tp:dbus-ref>, this method SHOULD perform a best-effort normalization. <tp:rationale> One common example of a best-effort offline normalization differing from the ideal normalization is XMPP. On XMPP, contacts' JIDs should normally have the resource removed during normalization, but for contacts in a MUC (chatroom), the resource is an integral part of the JID - so the contact JID aliceexample.com /Empathy should normalize to aliceexample.com , but the in-MUC JID wonderlandconference.example.com /Alice should normalize to itself. While online, the connection manager has enough context to know which chatrooms the user is in, and can infer from that whether to remove resources, but the best-effort normalization performed while offline does not have this context, so the best that can be done is to remove the resource from all JIDs. </tp:rationale> This method MAY simply raise NotImplemented on some protocols. <tp:rationale> In link-local XMPP, you can't talk to someone who isn't present on your local network, so normalizing identifiers in advance is meaningless. </tp:rationale>

Parameters

proxy	the TpProxy
timeout_ms	the timeout in milliseconds, or -1 to use the default
in_Contact_ID	Used to pass an 'in' argument: The identifier of a contact in this protocol
callback	called when the method call succeeds or fails; may be `NULL` to make a "fire and forget" call with no reply tracking
user_data	user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
destroy	called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
weak_object	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.

tp_cli_protocol_callback_for_identify_account ()

void
(*tp_cli_protocol_callback_for_identify_account)
                               (TpProxy *proxy,
                                const gchar *out_Account_ID,
                                const GError *error,
                                gpointer user_data,
                                GObject *weak_object);

Signature of the callback called when a IdentifyAccount method call succeeds or fails.

Parameters

proxy	the proxy on which the call was made
out_Account_ID	Used to return an 'out' argument if `error` is `NULL`: <p>An opaque string suitable for use as the account-specific part of an <tp:dbus-ref namespace="im.telepathy.v1">Account</tp:dbus-ref>'s object path. This is not necessarily globally unique, but should represent a "best-effort" identification of the account.</p> <tp:rationale> <p>For a pathological case, consider a user signing in as 'me`example.com` ' with 'server' set to either jabber1.example.com or jabber2.example.com. Both of these should result in me`example.com` being returned from this method, even if the user can actually be signed in to those two servers simultaneously.</p> </tp:rationale>
error	`NULL` on success, or an error on failure
user_data	user-supplied data
weak_object	user-supplied object

tp_cli_protocol_callback_for_normalize_contact ()

void
(*tp_cli_protocol_callback_for_normalize_contact)
                               (TpProxy *proxy,
                                const gchar *out_Normalized_Contact_ID,
                                const GError *error,
                                gpointer user_data,
                                GObject *weak_object);

Signature of the callback called when a NormalizeContact method call succeeds or fails.

Parameters

proxy	the proxy on which the call was made
out_Normalized_Contact_ID	Used to return an 'out' argument if `error` is `NULL`: The identifier of a contact in this protocol, normalized as much as possible
error	`NULL` on success, or an error on failure
user_data	user-supplied data
weak_object	user-supplied object

tp_cli_protocol_interface_addressing1_call_normalize_contact_uri ()

TpProxyPendingCall *
tp_cli_protocol_interface_addressing1_call_normalize_contact_uri
                               (gpointer proxy,
                                gint timeout_ms,
                                const gchar *in_URI,
                                tp_cli_protocol_interface_addressing1_callback_for_normalize_contact_uri callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object);

Start a NormalizeContactURI method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Attempt to normalize the given contact URI. Where possible, this SHOULD return an address that would appear in the <code>im.telepathy.v1.Connection.Interface.Addressing1/uris</code> attribute for a contact on a connected <tp:dbus-ref namespace="im.telepathy.v1">Connection</tp:dbus-ref>. If full normalization requires network activity or is otherwise impossible to do without a <tp:dbus-ref namespace="im.telepathy.v1">Connection</tp:dbus-ref>, this method SHOULD perform a best-effort normalization. If the URI has extra information beyond what's necessary to identify a particular contact, such as an XMPP resource or an action to carry out, this extra information SHOULD be removed. If all URIs in a scheme contain a verb or action (like <code>aim</code>, <code>ymsgr</code> and <code>msnim</code> URIs), then the verb SHOULD be replaced with the one specified in <tp:member-ref>AddressableURISchemes</tp:member-ref>. <tp:rationale> This method is intended to normalize URIs stored in address books, for instance. In protocols like XMPP, if you vary the resource or action (query string), the URI still refers to the same high-level contact. </tp:rationale> For instance, <code>xmpp:romeoExample.Com /Empathy?message;body=Hello</code> would be normalized to <code>xmpp:romeoexample.com </code>, and <code>aim:goim?screenname=Romeo20M&message=Hello</code> would be normalized to <code>aim:addbuddy?screenname=romeom</code>. This method MAY simply raise NotImplemented on some protocols, if it has no use.

Parameters

proxy	the TpProxy
timeout_ms	the timeout in milliseconds, or -1 to use the default
in_URI	Used to pass an 'in' argument: <p>The URI to normalize, which is assumed to refer to a contact (as opposed to, for instance, a chatroom or a server).</p> <tp:rationale> <p>In some protocols, like XMPP, there is no way to tell whether a given URI refers to a contact or a chatroom by looking at its syntax.</p> </tp:rationale> <p>The URI's scheme (i.e. the part before the first colon) MUST appear in <tp:member-ref>AddressableURISchemes</tp:member-ref>.</p>
callback	called when the method call succeeds or fails; may be `NULL` to make a "fire and forget" call with no reply tracking
user_data	user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
destroy	called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
weak_object	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.

tp_cli_protocol_interface_addressing1_call_normalize_vcard_address ()

TpProxyPendingCall *
tp_cli_protocol_interface_addressing1_call_normalize_vcard_address
                               (gpointer proxy,
                                gint timeout_ms,
                                const gchar *in_VCard_Field,
                                const gchar *in_VCard_Address,
                                tp_cli_protocol_interface_addressing1_callback_for_normalize_vcard_address callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object);

Start a NormalizeVCardAddress method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Attempt to normalize the given vCard address. Where possible, this SHOULD return an address that would appear in the <code>im.telepathy.v1.Connection.Interface.Addressing1/addresses</code> attribute for a contact on a connected <tp:dbus-ref namespace="im.telepathy.v1">Connection</tp:dbus-ref>. If full normalization requires network activity or is otherwise impossible to do without a <tp:dbus-ref namespace="im.telepathy.v1">Connection</tp:dbus-ref>, this method SHOULD perform a best-effort normalization. An example would be a vCard TEL field with a formatted number in the form of <code>+1 (206) 555 1234</code>, this would be normalized to <code>+12065551234</code>. This method MAY simply raise NotImplemented on some protocols, if it has no use.

Parameters

proxy	the TpProxy
timeout_ms	the timeout in milliseconds, or -1 to use the default
in_VCard_Field	Used to pass an 'in' argument: The vCard field of the address we are normalizing. The field name SHOULD be in lower case, and MUST appear in <tp:member-ref>AddressableVCardFields</tp:member-ref>.
in_VCard_Address	Used to pass an 'in' argument: The address to normalize, which is assumed to belong to a contact (and not, for instance, a chatroom or server).
callback	called when the method call succeeds or fails; may be `NULL` to make a "fire and forget" call with no reply tracking
user_data	user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
destroy	called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
weak_object	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.

tp_cli_protocol_interface_addressing1_callback_for_normalize_contact_uri ()

void
(*tp_cli_protocol_interface_addressing1_callback_for_normalize_contact_uri)
                               (TpProxy *proxy,
                                const gchar *out_Normalized_URI,
                                const GError *error,
                                gpointer user_data,
                                GObject *weak_object);

Signature of the callback called when a NormalizeContactURI method call succeeds or fails.

Parameters

proxy	the proxy on which the call was made
out_Normalized_URI	Used to return an 'out' argument if `error` is `NULL`: A URI, normalized as much as possible.
error	`NULL` on success, or an error on failure
user_data	user-supplied data
weak_object	user-supplied object

tp_cli_protocol_interface_addressing1_callback_for_normalize_vcard_address ()

void
(*tp_cli_protocol_interface_addressing1_callback_for_normalize_vcard_address)
                               (TpProxy *proxy,
                                const gchar *out_Normalized_VCard_Address,
                                const GError *error,
                                gpointer user_data,
                                GObject *weak_object);

Signature of the callback called when a NormalizeVCardAddress method call succeeds or fails.

Parameters

proxy	the proxy on which the call was made
out_Normalized_VCard_Address	Used to return an 'out' argument if `error` is `NULL`: The vCard address, normalized as much as possible.
error	`NULL` on success, or an error on failure
user_data	user-supplied data
weak_object	user-supplied object

ConnectionManager interface

Functions

Object Hierarchy

Includes

Description

Functions

tp_cli_connection_manager_callback_for_request_connection ()

Parameters

tp_cli_connection_manager_call_request_connection ()

Parameters

Returns

tp_cli_connection_manager_signal_callback_new_connection ()

Parameters

tp_cli_connection_manager_connect_to_new_connection ()

Parameters

Returns

tp_cli_protocol_call_identify_account ()

Parameters

Returns

tp_cli_protocol_call_normalize_contact ()

Parameters

Returns

tp_cli_protocol_callback_for_identify_account ()

Parameters

tp_cli_protocol_callback_for_normalize_contact ()

Parameters

tp_cli_protocol_interface_addressing1_call_normalize_contact_uri ()

Parameters

Returns

tp_cli_protocol_interface_addressing1_call_normalize_vcard_address ()

Parameters

Returns

tp_cli_protocol_interface_addressing1_callback_for_normalize_contact_uri ()

Parameters

tp_cli_protocol_interface_addressing1_callback_for_normalize_vcard_address ()

Parameters

Types and Values

See Also