ConnectionManager interface

ConnectionManager interface — client-side wrappers for ConnectionManager core functionality

Functions

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"> <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>

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"> <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>

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"> <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>

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 &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.

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"> <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>

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"> <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>

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

 

Types and Values

See Also

TpConnectionManager