Obtaining a Connection

5.2.1. From the Account Manager

The AccountManager and Account interfaces are implemented in Mission Control 5.

Mission Control 4 implements a completely different interface which is not documented here.

In general, Telepathy clients will want to share the same set of already-configured accounts rather than managing their own accounts and setting up their own connections. The Account Manager manages connections for configured accounts which can be retrieved as a property from each Account object.

Connections are created and managed by the Account Manager for valid, online accounts. The Account Manager is available via the well known D-Bus name org.freedesktop.Telepathy.AccountManager and object path /org/freedesktop/Telepathy/AccountManager.

Valid, connectable (or connected) accounts are available via the ValidAccounts property of the Account Manager. This property contains a list of D-Bus object paths the Account Manager exports. An account's current presence can be read via the CurrentPresence property.

To bring an account online, set RequestedPresence to an online state (e.g. Connection_Presence_Type_Available (the account must also be Enabled). Equally, to take an account offline, set the RequestedPresence property to Connection_Presence_Type_Offline.

Automatically Onlining Accounts

Mission Control will automatically bring online any Enabled account when a channel is requested for that account via the Channel Dispatcher. This is done by setting RequestedPresence to the value set in AutomaticPresence.

See Section 3.2.1.2 ― On Demand for more information.

The Connection property gives the object path for the connection associated with the account. A value of / indicates that no connection has been created.

The well-known bus name of the connection can be determined from the object path by removing the leading forward-slash and replacing the remaining slashes with periods (for example, /org/freedesktop/Telepathy/Connection/gabble/jabber/bob_40example_2ecom_2ftelepathy becomes org.freedesktop.Telepathy.Connection.gabble.jabber.bob_40example_2ecom_2ftelepathy). Note that doing this conversion is not normally required, as most Telepathy bindings are able to do it for you (e.g. tp_connection_new).

5.2.1.1. telepathy-glib

When an account is connected, a TpConnection can be retrieved from a prepared TpAccount. The TpConnection will itself require preparation.

The TpAccount status-changed signal is used to watch for changes to the connection status.

5.2.2. From a Connection Manager

Usually you want the Account Manager to request the Connection from the Connection Manager for you from a configured Account.

There might be times when you are using Telepathy without an Account Manager and need to manually set up your own connections using the Connection Manager. For example, a status reporting client that runs as its own user without a desktop session might only run itself, dbus-daemon and a Connection Manager.

To setup your own connection to the remote server (e.g. your Jabber IM account) you need to call RequestConnection on the appropriate Connection Manager (e.g. gabble), providing a map of connection details. Assuming the connection succeeds this method will return the bus name and object path of a newly created Telepathy Connection object.

To determine what parameters are required or optional for a given Connection Manager its GetParameters method should be called with the relevant protocol. Example 5-2 shows how this is done. Some common, "well-known" parameters names are shown in Table 5-1.

Example 5-2Getting Connection Parameters
import telepathy
from telepathy.interfaces import CONN_MGR_INTERFACE
from telepathy.constants import CONN_MGR_PARAM_FLAG_DBUS_PROPERTY, \
                                CONN_MGR_PARAM_FLAG_HAS_DEFAULT, \
                                CONN_MGR_PARAM_FLAG_REGISTER, \
                                CONN_MGR_PARAM_FLAG_REQUIRED, \
                                CONN_MGR_PARAM_FLAG_SECRET

def print_params (params):
    for name, flags, signature, default in params:
        print "%s (%s)" % (name, signature),
    
        if flags & CONN_MGR_PARAM_FLAG_REQUIRED: print "required",
        if flags & CONN_MGR_PARAM_FLAG_REGISTER: print "register",
        if flags & CONN_MGR_PARAM_FLAG_SECRET: print "secret",
        if flags & CONN_MGR_PARAM_FLAG_DBUS_PROPERTY: print "dbus-property",
        if flags & CONN_MGR_PARAM_FLAG_HAS_DEFAULT: print "has-default(%s)" % default,
    
        print

    loop.quit ()

def error_cb (*args):
    print "Error:", args
    loop.quit ()

reg = telepathy.client.ManagerRegistry()
reg.LoadManagers()

# get the gabble Connection Manager
cm = reg.GetManager('gabble')

# get the parameters required to make a Jabber connection
cm[CONN_MGR_INTERFACE].GetParameters('jabber',
    reply_handler = print_params, error_handler = error_cb)

Complete Source Code

Table 5-1Well-Known Connection Parameters for RequestConnection
Property Type Description Example
account String The identifier for the user's account on the server. bob@example.com
server String A fully qualified domain name or numeric IPv4 or IPv6 address. xmpp.example.com
port uint16 A TCP/UDP network port. 8080
require-encryption Boolean Require encryption for this connection. False
register Boolean This account should be created on the server if it does not already exist. False
ident String The local username to report to the server. bmcbadgers
fullname String The user's full name. Bob McBadgers
stun-server String A fully qualified domain name or numeric IPv4 or IPv6 address of a STUN server to use for NAT traversal. stun.example.com
stun-port uint16 A UDP network port for the STUN server. 1337

The new connection will not actually attempt to establish a network connection until its Connect method has been called. The connection will be ready to use after the StatusChanged signal returns a Connection_Status of Connected.

Example 5-3 shows how to manually establish a connection.

Example 5-3Establishing a Connection