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, 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:

  • Contacts

    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.

  • Aliasing

    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.

  • Avatars

    Used to request and watch for changes to contacts' avatars. Also used by the Account Manager to set your own avatar.

  • ContactCapabilities

    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.

  • ContactInfo

    Describe me

  • Location

    Allows you to publish information about your physical location as well as retrieve the location of contacts on your roster.

  • Balance

    Provides access to any monetary balance, e.g. call credit for making PSTN calls on protocols that support it.

  • Anonymity

    Describe me

  • Renaming

    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: