A Connection object in Telepathy represents an active (or activatable) protocol session. Connections are created by the appropriate Connection Manager (usually in response to a request by the Account Manager).
A connection can be located on the D-Bus session bus via the well-known name org.freedesktop.Telepathy.Connection.cm.proto.account, where cm is the name of the Connection Manager that created the connection (e.g. gabble, salut) and proto is the name of a Telepathy Protocol (e.g. jabber, msn, irc). The connection object can then be retrieved from the path /org/freedesktop/Telepathy/Connection/cm/proto/account.
Depending on what features are supported by the protocol, a given connection will implement more interfaces than just Connection. The interfaces supported by a given connection can be retreived using the Interfaces property once the connection is in the CONNECTED state. The supported list of interfaces doesn't change during the life on a connection, so it is expected that a client will retreive this once the connection is CONNECTED.
Interfaces that a connection might support include:
The Contacts interface is a sort of proxy to other interfaces on the connection. It is used to gather as much information about a contact as required in a single D-Bus roundtrip. It is documented in Section 7.1 ― Contacts.
Used to retrieve and watch for changes to the aliases (screen names) that contacts set for themselves. Also allows the user to set their own aliases for contacts on supported protocols.
Used to request and watch for changes to contacts' avatars. Also used by the Account Manager to set your own avatar.
Used to determine what types of channels you can request to another contact (e.g. text channels, VoIP calls, file transfer, Tubes). Also used by the Channel Dispatcher to update your own capabilities.
Describe me
Allows you to publish information about your physical location as well as retrieve the location of contacts on your roster.
Provides access to any monetary balance, e.g. call credit for making PSTN calls on protocols that support it.
Describe me
Renaming is implemented for protocols that can allow handles to be renamed (e.g. IRC). It is documented in Section 5.4 ― Handle Renaming.
The following interfaces should be present on a connection, but in general are only used by the Account Manager and Channel Dispatcher and should not be accessed directly:
The Requests interface is used to obtain channels, which are how data is exchanged in Telepathy. Its use is documented in Section 6.1 ― Requesting Channels.
The SimplePresence interface is used to set and obtain presence information on a given Connection. It is documented in Section 5.3 ― Presence and Section 7.2 ― Presence.