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.

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

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.

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)

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.