This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
The name of a connection manager, found in its well-known bus name and object path. This must be a non-empty string of ASCII letters, digits and underscores, starting with a letter. This is typically the name of the executable with any "telepathy-" prefix removed, and any hyphen/minus signs replaced by underscores.
Connection manager names SHOULD NOT be the same as the name of the protocol they implement.
This is likely to lead to conflicts between different implementations of the same protocol (or indeed inability to distinguish between the different implementations!). The Telepathy project traditionally uses some sort of pun (Haze is based on libpurple, Salut implements a protocol often called Bonjour, and Wilde implements the OSCAR protocol).
Connection manager names SHOULD NOT be the same as the name of a library on which they are based.
We often abbreviate, for instance, telepathy-haze as "Haze", but abbreviating telepathy-sofiasip to "Sofia-SIP" would cause confusion between the connection manager and the library it uses. Please don't repeat that mistake.
An instant messaging protocol. It must consist only of ASCII letters, digits and hyphen/minus signs (U+002D "-"), and must start with a letter. Where possible, this SHOULD be chosen from the following well-known values:
This parameter should be considered private or secret; for instance, clients should store it in a "password safe" like gnome-keyring or kwallet, omit it from debug logs, and use a text input widget that hides the value of the parameter.
(Clients that support older connection managers may also treat any parameter whose name contains "password" as though it had this flag.)
Request a Connection object representing a given account on a given protocol with the given parameters. The method returns the bus name and the object path where the new Connection object can be found, which should have the status of Connection_Status_Disconnected, to allow signal handlers to be attached before connecting is started with the Connect method.
In order to allow Connection objects to be discovered by new clients,
the object path and well-known bus name must be of the form
/org/freedesktop/Telepathy/Connection/cmname/proto/account
and
org.freedesktop.Telepathy.Connection.cmname.proto.account
where:
Clients MUST NOT attempt to parse the account part of the bus name. Connection managers MAY use any unique string for this part.
The parameters which must and may be provided in the parameters dictionary can be discovered with the GetParameters method. These parameters, their types, and their default values may be cached in files so that all available connection managers do not need to be started to discover which protocols are available.
To request values for these parameters from the user, a client must have prior knowledge of the meaning of the parameter names, so the following well-known names and types should be used where appropriate:
Every successful RequestConnection call will cause the emission of a NewConnection signal for the same newly created connection. The requester can use the returned object path and service name independently of the emission of that signal. In that case this signal emission is most useful for, e.g. other processes that are monitoring the creation of new connections.
A list of the extra interfaces provided by this connection manager (i.e. extra functionality that can be provided even before a connection has been created).
No interfaces suitable for listing in this property are currently defined; it's provided as a hook for possible future functionality.
To be compatible with older connection managers, if retrieving this property fails, clients SHOULD assume that its value is an empty list.
A D-Bus service which allows connections to be created. The manager processes are intended to be started by D-Bus service activation.
For service discovery, each Telepathy connection manager must have
a connection manager name (see
The connection manager must then provide a well-known bus name of
org.freedesktop.Telepathy.ConnectionManager.cmname
where cmname is its connection manager name. If it makes sense
to start the connection manager using D-Bus service activation, it
must register that well-known name for service activation by installing
a .service file.
Clients can list the running connection managers by calling the ListNames method on the D-Bus daemon's org.freedesktop.DBus interface and looking for names matching the above pattern; they can list the activatable connection managers by calling ListActivatableNames, and they should usually combine the two lists to get a complete list of running or activatable connection managers.
When the connection manager is running, it must have an object
implementing the ConnectionManager interface at the object path
/org/freedesktop/Telepathy/ConnectionManager/cmname.
Connection managers' capabilities can be determined dynamically by calling their ListProtocols method, then for each protocol of interest, calling GetParameters to discover the required and optional parameters. However, since it is inefficient to activate all possible connection managers on the system just to find out what they can do, there is a standard mechanism to store static information about CMs in ".manager files".
To look up a connection manager's supported protocols, clients
should search the data directories specified by
the
freedesktop.org XDG Base Directory Specification ($XDG_DATA_HOME,
defaulting to $HOME/.local/share if unset, followed by
colon-separated paths from $XDG_DATA_DIRS, defaulting to
/usr/local/share:/usr/share if unset) for the first file named
telepathy/managers/cmname.manager that can be
read without error. This file has the same syntax as a
freedesktop.org Desktop Entry file.
Clients must still support connection managers for which no
.manager file can be found, which they can do by activating
the connection manager and calling its methods; the
.manager file is merely an optimization. Connection managers
whose list of protocols can change at any time (for instance, via
a plugin architecture) should not install a .manager
file.
For each protocol name proto that would be returned by
ListProtocols, the .manager file contains a group
headed [Protocol proto]. For each parameter
p that would be returned by GetParameters(proto), the
.manager file contains a key param-p with a value
consisting of a D-Bus signature (a single complete type), optionally
followed by a space and a space-separated list of flags. The supported
flags are:
required, corresponding to
Conn_Mgr_Param_Flag_Requiredregister, corresponding
to Conn_Mgr_Param_Flag_Registersecret, corresponding
to Conn_Mgr_Param_Flag_SecretThe group may also contain a key default-p
whose value is a string form of the default value for the parameter.
If this key exists, it sets the default, and also sets the flag
Conn_Mgr_Param_Flag_Has_Default. The default value is formatted
according to the D-Bus signature as follows:
Currently, no other D-Bus signatures are allowed to have default values,
but clients parsing the .manager file MUST ignore defaults
that they cannot parse, and treat them as if the
default-p key was not present at all.
It is not required that a connection manager be able to support multiple protocols, or even multiple connections. When a connection is made, a service name where the connection object can be found is returned. A manager which can only make one connection may then remove itself from its well-known bus name, causing a new connection manager to be activated when somebody attempts to make a new connection.