ConnectionManager interface

ConnectionManager interface — client-side wrappers for ConnectionManager core functionality

Synopsis

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

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

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);
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);
void                (*tp_cli_protocol_callback_for_identify_account)
                                                        (TpProxy *proxy,
                                                         const gchar *out_Account_ID,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
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);
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);
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);
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);
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);

Description

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

Details

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.

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"> <p>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.</p> <p><strong>Most applications should not use this method</strong>: 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.</p> <p>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.</p> <p>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.</p> <p>Connection manager authors SHOULD avoid introducing parameters whose default values would not be serializable in a <code>.manager</code> file.</p> <tp:rationale> <p>The same serialization format is used in Mission Control to store accounts.</p> </tp:rationale> <p>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.</p>

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.

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.

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"> <p>Return a string which uniquely identifies the account to which the given parameters would connect.</p> <tp:rationale> <p>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.</p> </tp:rationale>

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"> <p>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>.</p> <p>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.</p> <tp:rationale> <p>One common example of a best-effort offline normalization differing from the ideal normalization is XMPP.</p> <p>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.</p> <p>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.</p> </tp:rationale> <p>This method MAY simply raise NotImplemented on some protocols.</p> <tp:rationale> <p>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.</p> </tp:rationale>

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.

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 &quot;best-effort&quot; identification of the account.</p> <tp:rationale> <p>For a pathological case, consider a user signing in as 'meexample.com' with 'server' set to either jabber1.example.com or jabber2.example.com. Both of these should result in meexample.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.

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"> <p>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>. </p> <p>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.</p> <p>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>.</p> <tp:rationale> <p>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.</p> </tp:rationale> <p>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&amp;message=Hello</code> would be normalized to <code>aim:addbuddy?screenname=romeom</code>.</p> <p>This method MAY simply raise NotImplemented on some protocols, if it has no use.</p>

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"> <p>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>. </p> <p>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.</p> <p>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>.</p> <p>This method MAY simply raise NotImplemented on some protocols, if it has no use.</p>

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.

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.

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

See Also

TpConnectionManager