Interface ConnectionManager

Interface Index (Compact) | Summary | Description | Methods | Signals | Properties | Types

Methods

GetParameters (s: Protocol) → a(susv): Parameters
ListProtocols () → as: Protocols
RequestConnection (s: Protocol, a{sv}: Parameters) → s: Bus_Name, o: Object_Path

Signals

NewConnection (s: Bus_Name, o: Object_Path, s: Protocol)

Properties

Protocols a{sa{sv}} (Protocol_Properties_Map) Read only
Interfaces as Read only

Types

Connection_Manager_Name Simple Type s
Protocol Simple Type s
Connection_Parameter_Name Simple Type s
Conn_Mgr_Param_Flags Flags u
Protocol_Properties_Map Mapping a{sa{sv}}
Param_Spec Struct (susv)
Changed in 0.17.2. Prior to version 0.17.2, support for CMs with no .manager file was not explicitly required.
Changed in 0.17.16. Prior to version 0.17.16 the serialization of string arrays (signature 'as') was not defined

Description

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 Connection_Manager_Name for syntax).

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.

The .manager file SHOULD have a group headed [ConnectionManager], containing a key Interfaces representing Interfaces as a sequence of strings each followed by a semicolon (the "localestrings" type from the Desktop Entry Specification).

The [ConnectionManager] group SHOULD NOT contain keys ObjectPath or BusName. If it does, they MUST be ignored.

Rationale:

The object path and bus name are derivable from the connection manager's name, which is part of the filename, so these keys are redundant. They were required in very old versions of Telepathy.

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:

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

s (string)
The UTF-8 string, with the standard backslash escape sequences supported by the Desktop Entry Specification (the "localestring" type from the Desktop Entry Specification)
o (object path)
The object path as an ASCII string
b (boolean)
"true" (case-insensitively) or "1" means True, "false" (case-insensitively) or "0" means False; when writing a file, "true" and "false" SHOULD be used
y, q, u, t (8-, 16-, 32-, 64-bit unsigned integer)
ASCII decimal integer
n, i, x (16-, 32-, 64-bit signed integer)
ASCII decimal integer, optionally prefixed with "-"
d (double-precision floating point)
ASCII decimal number
as (array of string)
A sequence of UTF-8 strings each followed by a semicolon, with any semicolons they contain escaped with a backslash (the "localestrings" type from the Desktop Entry Specification)

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.

Methods

(Permalink)

GetParameters (s: Protocol) → a(susv): Parameters

Parameters

  • Protocol — s (Protocol)
    • The required protocol name

Returns

  • Parameters — a(susv) (Param_Spec_List)
    • An array of structs representing possible parameters.
Get a list of the parameters which may be specified in the Parameters of an Account (or, for specialised applications which do not use the account manager, passed to RequestConnection). Some parameters are mandatory, and some parameters only make sense when registering new accounts with the server; see the Param_Spec documentation for more details.

Possible Errors

(Permalink)

ListProtocols () → as: Protocols

Returns

Get a list of protocol identifiers that are implemented by this connection manager.
(Permalink)

RequestConnection (s: Protocol, a{sv}: Parameters) → s: Bus_Name, o: Object_Path

Parameters

Returns

  • Bus_Name — s (DBus_Bus_Name)
    • A D-Bus service name where the new Connection object can be found
  • Object_Path — o
    • The D-Bus object path to the Connection on this service

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.

Most applications should not use this method: they should instead use the the Connection property on an Account object obtained from the AccountManager. This method is used internally by the account manager to create connections when needed.

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 well-known names and types defined by the Connection_Parameter_Name type should be used where appropriate.

Connection manager authors SHOULD avoid introducing parameters whose default values would not be serializable in a .manager file.

Rationale:

The same serialization format is used in Mission Control to store accounts.

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.

Possible Errors

Signals

(Permalink)

NewConnection (s: Bus_Name, o: Object_Path, s: Protocol)

Parameters

  • Bus_Name — s (DBus_Bus_Name)
    • The D-Bus service where the connection object can be found
  • Object_Path — o
    • The object path of the Connection object on this service
  • Protocol — s (Protocol)
    • The identifier for the protocol this connection uses
Emitted when a new Connection object is created.

Properties

Accessed using the org.freedesktop.DBus.Properties interface.
(Permalink)

Protocols — a{sa{sv}} (Protocol_Properties_Map)

Read only

A map from protocol identifiers supported by this connection manager to the immutable properties of the corresponding Protocol objects.

Rationale:

Providing the immutable properties here means that when the API of Protocol objects has been finalized, most clients will only need one D-Bus round trip to interrogate the ConnectionManager about all its protocols.

If this map is empty or missing, clients SHOULD fall back to calling ListProtocols and GetParameters.

(Permalink)

Interfaces — as

Read only
Added in 0.17.8.

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.

Connection managers with a non-empty list of Interfaces MUST represent them in the .manager file, if they have one, as an Interfaces key in the group headed [ConnectionManager], whose value is a list of strings each followed by a semicolon.

Types

Simple Type (Permalink)

Connection_Manager_Name — s

Changed in 0.17.1. Prior to version 0.17.1, the allowed characters were not specified

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.

Rationale:

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.

Rationale:

We often abbreviate, for instance, telepathy-haze as “Haze”, but abbreviating telepathy-sofiasip—since renamed to telepathy-rakia for exactly this reason—to “Sofia-SIP” caused confusion between the connection manager and the library it uses. Please don't repeat that mistake.

Simple Type (Permalink)

Protocol — s

Changed in 0.17.1. Prior to version 0.17.1, the allowed characters were not specified

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:

  • aim - AOL Instant Messenger (OSCAR or TOC)
  • gadugadu - Gadu-Gadu
  • groupwise - Novell Groupwise
  • icq - ICQ (OSCAR)
  • irc - Internet Relay Chat (RFC 1459, 2810-2813)
  • jabber - XMPP (RFC 3920, 3921) or Jabber
  • local-xmpp - Link-local XMPP (XEP-0174) (Bonjour, Salut)
  • msn - MSNP (Windows Live Messenger)
  • myspace - MySpaceIM
  • mxit - MXit
  • napster - Napster
  • qq - Tencent QQ
  • sametime - IBM Lotus Sametime
  • silc - SILC
  • sip - Session Initiation Protocol (SIP), with or without SIMPLE support
  • skype - Skype
  • tel - telephony (the PSTN, including GSM, CDMA and fixed-line telephony)
  • trepia - Trepia
  • yahoo - YMSG (Yahoo! Messenger)
  • yahoojp - Japanese version of YMSG
  • zephyr - Zephyr
Simple Type (Permalink)

Connection_Parameter_Name — s

Added in 0.21.2.

Well-known connection parameter names, along with their expected type. Where possible, connection managers should use names and types from this list in the Parameters that may be passed to RequestConnection.

account (s)
The identifier for the user's account on the server
server (s)
A fully qualified domain name or numeric IPv4 or IPv6 address. Using the fully-qualified domain name form is recommended whenever possible. If this parameter is specified and the account for that protocol also specifies a server, this parameter should override that in the user id.
port (q)
A TCP or UDP port number. If this parameter is specified and the account for that protocol also specifies a port, this parameter should override that in the account.
password (s)
A password associated with the account.
require-encryption (b)
Require encryption for this connection. A connection should fail to connect if require-encryption is set and an encrypted connection is not possible.
register (b)
This account should be created on the server if it does not already exist.
ident (s)
The local username to report to the server if necessary, such as in IRC.
fullname (s)
The user's full name if the service requires this when authenticating or registering.
stun-server (s)
The IP address or FQDN of a STUN server to use for NAT traversal, without any ":port" suffix.
stun-port (q)
The UDP port number on the stun-server to use for STUN. Only significant if the stun-server is also supplied.
keepalive-interval (u)

The time in seconds between pings sent to the server to ensure that the connection is still alive, or 0 to disable such pings.

This parameter is superseded by the KeepaliveInterval property, which can be updated on an already-established connection as well as being specified when requesting the connection. Clients SHOULD provide that parameter instead, if allowed; new connection managers SHOULD implement it in preference to this one.

The following well-known parameter names correspond to D-Bus properties, and thus their Conn_Mgr_Param_Flags should include DBus_Property. See that flag for more details on this kind of parameter.

Flags (Permalink)

Conn_Mgr_Param_Flags — u

  • Required (1)
    • This parameter is required for connecting to the server.
  • Register (2)
    • This parameter is required for registering an account on the server.
  • Has_Default (4)
    • This parameter has a default value, which is returned in GetParameters; not providing this parameter is equivalent to providing the default.
  • Secret (8)
    • Added in 0.17.2.

    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.)

  • DBus_Property (16)
    • Added in 0.17.16.

    This parameter is also a D-Bus property on the resulting Connection; a parameter named com.example.Duck.Macaroni with this flag corresponds to the Macaroni property on the com.example.Duck interface. Its value can be queried and possibly changed on an existing Connection using methods on the org.freedesktop.DBus.Properties interface.

    When a new value for a parameter with this flag is passed to Account.UpdateParameters, the account manager will attempt to update its value on any running connections. Similarly, if the parameter also has the Has_Default flag, and is passed in the second argument to UpdateParameters, the default value will be applied to any running connections. Thus, clients generally do not need to directly access or update the connection property; instead, they SHOULD manipulate Account.Parameters.

    Rationale:

    This allows runtime-configurable options to be stored and maintained by the AccountManager, without needing to invent a separate account preference for “properties that should be set on the connection as soon as it is created”. It was originally invented to manage Cellular preferences.

Mapping (Permalink)

Protocol_Properties_Map — a{sa{sv}}

A map from protocol identifiers supported by a connection manager to the immutable properties of the corresponding Protocol objects.

Struct (Permalink)

Param_Spec — (susv)

A struct representing an allowed parameter, as returned by GetParameters on the ConnectionManager interface.
  • Name — s
    • A string parameter name
  • Flags — u (Conn_Mgr_Param_Flags)
    • A bitwise OR of the parameter flags
  • Signature — s (DBus_Signature)
    • A string containing the D-Bus type signature for this parameter
  • Default_Value — v
    • The default value (if the Has_Default flag is not present, there is no default and this takes some dummy value, which SHOULD be of the appropriate D-Bus type)