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.
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 18.104.22.168 ― 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).
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.
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)
|account||String||The identifier for the user's account on the email@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.