This section aims to be a glossary of the different terms you will encounter in Telepathy. Each of these concepts is explained in more detail later in the manual.
The design of Telepathy is heavily influenced by D-Bus, so much of its terminology is shared in common with D-Bus. For those unfamiliar with D-Bus, a quick primer is presented in Section 2.2 ― Using D-Bus. For more indepth information, consult A MANUAL THAT PROBABLY HASN'T BEEN WRITTEN YET.
Mission Control provides the Account Manager and Channel Dispatcher.
This manual is specifically concerned with Mission Control 5. There are earlier versions of Mission Control, but they are extremely different to the version documented here.
It's possible that a particular device uses a different Account Manager or Channel Dispatcher from Mission Control, but this may still be referred to by the name Mission Control.
The Account Manager is responsible for maintaining the list of configured accounts for a user and setting up Connection's to those accounts.
In general, a client will request available Accounts and Connections, and control the user's online presence via the Account Manager.
The Account Manager is documented in Chapter 3 ― Accounts and AccountManager.
The Channel Dispatcher handles incoming Channels from the various Connections known to the Account Manager and dispatches them to the appropriate Telepathy Client (e.g. chat client, VoIP client, Tube application).
The Channel Dispatcher may also be used to request Channels that you want another client to handle (e.g. a program wanting to open a text-chat to a user, but not wanting to handle the chat itself).
The Channel Dispatcher is documented in Chapter 4 ― Channel Dispatcher and Clients.
Connection managers are simply factories for connections. In general, there is little need for a client to interact much with the ConnectionManager interface. Most of the work in obtaining and managing connections should be done via the Account Manager.
The term “connection manager” is often used to mean the process that provides the connection manager service. Each connection has its own D-Bus service name (e.g. org.freedesktop.Telepathy.ConnectionManager.gabble), but it's common for the connection manager service to run in the same process as its connections. It's also common for the connection manager object to provide only the main connection manager interface (the common D-Bus introspection and properties interfaces excepted).
More about Connection Managers is given in Section 5.1 ― Connection Managers.
A Client is the name for a program that is registered with the Channel Dispatcher to do something with Telepathy Channels. There are three types of Clients: Observers, Approvers and Handlers. Most people reading this manual will be developing a Telepathy Client.
More on Clients is available in Section 4.1 ― Telepathy Clients.
Connections represent active protocol sessions. A connection has a set of parameters that it is requested with. Although the parameters used vary from protocol to protocol, some parameter names have a standard meaning. A notable example is the account parameter, used to specify a persistent identity, usually stored on a server. Some protocols, however, do not have accounts, in which case the account parameter will be absent.
The connection interface (org.freedesktop.Telepathy.Connection) is mainly concerned with the management of Handles and Channels. It's common for connections to have a number of other interfaces, such as the aliasing, avatars and presence interfaces.
Connection objects cease to exist when the Disconnect method is called. If the connection wasn't already in the Disconnected state, a StatusChanged signal is emitted.
Setting up and using connections is documented in Chapter 5 ― Connections.
A Channel is used by Telepathy to exchange data between local applications and remote servers. A Channel has a type, depending on what it's used for (e.g. Text, ContactList, StreamedMedia). Channels are either created automatically by a Connection, created by request of the client application or created in response to incoming communication.
A complete explanation of channels is presented in Chapter 6 ― Channels.
Handles are used to represent various kinds of protocol resources (e.g. contacts, chatrooms, contact lists, etc.). Each handle has an associated string identifier. Handles are used to avoid normalisation problems in string identifiers.
The use of handles is documented in Section 2.5 ― Handles.
A D-Bus Interface.
Telepathy makes extensive use of D-Bus interfaces. Telepathy uses interfaces both to indicate an object's type and its capabilities so it is not uncommon for an object to implement several Telepathy D-Bus interfaces. For instance, an object might implement org.freedesktop.Telepathy.Channel, org.freedesktop.Telepathy.Channel.Type.Text, org.freedesktop.Telepathy.Channel.Interface.Messages, org.freedesktop.Telepathy.Channel.Interface.Group and org.freedesktop.Telepathy.Channel.Interface.Password, which would indicate the object is a password-protected multi-user chat (MUC) channel.
The Interfaces property says what interfaces a given object implements.
Because an object can implement so many interfaces, Telepathy API bindings do not require you to specify an interface when requesting a proxy object. Instead this is done when making a method call or connecting a signal. Telepathy API bindings provide named constants for the available interfaces.