File Formats

Contents

File Formats

Introduction

This page describes the various file formats that Telepathy applications use. These files should be installed with the components they describe.

These file formats are based on the XDG desktop file format. All keys and values are case sensitive. Unknown values are considered to be an error and the file may be ignored completely, unless otherwise specified.

Where this document discusses names, they are required to be of the form [a-z][a-z0-9-]*, and must not end in a hyphen (-).

When fields in a file are prefixed with an underscore (_) this means the field is translatable using the mechanisms defined for XDG desktop files format.

File Locations

Packages should install the files in PREFIX/share/telepathy, in a subdirectory depending on the file type. For example, a connection manager named "foo" should install a file PREFIX/share/telepathy/managers/foo.manager. PREFIX is typically /usr or /usr/local.

Users of these files should search in directories listed in the $XDG_DATA_HOME and $XDG_DATA_DIRS variables, as specified in the XDG Base Directory Specification.

Historically, the $HOME/.telepathy location was used; implementations supporting this location should search it before other locations.

When searching for connection managers, channel handlers and profiles by name, the first file found should be used, given that directories are searched in descending order of importance. When a file cannot be read because of an error, the next file is used in order, until no more files are left, in which case it should be considered that no matching file was found.

For example, assuming that $XDG_DATA_HOME and $XDG_DATA_DIRS are unset, an implementation looking up a connection manager called "badger" would look for the following files:

$HOME/.telepathy/managers/badger.manager (legacy; optional)
$HOME/.local/share/telepathy/managers/badger.manager ($XDG_DATA_HOME default)
/usr/local/share/telepathy/managers/badger.manager ($XDG_DATA_DIRS default)
/usr/share/telepathy/managers/badger.manager ($XDG_DATA_DIRS default)

Connection Manager Files

Purpose

These files are installed by connection managers to allow for 'offline' retreival of the connection parameters. This remove the needs to start and query each available connection manager just to be able to generate the UI or other simple tasks.

The content of the .manager file and the actual CM is guaranteed to be similar since the file comes with the CM package and is upgraded when the package gets upgraded.

The MC will use the data in this file to know what key to store in the underlying configuration storage backend, and also to know key defaults and avoid storing them.

Format

Location: these files are located in the managers subdirectory.

Naming: these files should be named name`.manager, where name is the unique name for the connection manager.

As required in the Telepathy D-Bus specification, the unique name of the manager should be used to form the bus name and the object path where the manager can be found, according to the following formats:

Bus name: org.freedesktop.Telepathy.ConnectionManager.%s
Object path: /org/freedesktop/Telepathy/ConnectionManager/%s

Each file contains one or more Protocol stanzas. A ConnectionManager stanza may also be present; this stanza is obsolete and should be ignored.

Protocol stanzas have a name of the form Protocol name. Each stanza contains a set of parameters. Each parameter is defined by a key-value pair of the form:

param-name = signature flag*

where

name -- a name for the parameter
signature -- a DBus signature for the parameter
flag -- a named flag

Recognised flags are:

required -- the parameter is mandatory
register -- the parameter is mandatory when registering (i.e. when the register parameter is true)

In addition, each parameter may have a default value, which is represented using a key-value pair of the form:

default-name = value

The default key may only appear after the param- key it refers to.

Example

[Protocol jabber]
param-account = s required register
param-password = s required register
param-server = s
param-resource = s
default-server = jabber.org

Profile Files

This section is a DRAFT.

Purpose

Each connection manager can provide one or more protocols. Each protocol can have different 'profiles'.

A profile is a set of default key-value to be used as parameters in a connection manager for a particular (connection manager, protocol) pair.

For example a connection manager providing jabber protocol, can also provide a profile for a Google talk connection (pre-setting ssl connection, stun server and jabber server). Another example can be an enterprise-deployed profile pre-setting some proxy and server foo, or stun server inside the enterprise.

The MC should reason in terms of profiles rather than protocols. Each profile can have a translatable name and description (key prefixed with underscore as defined at the beginning of the document).

Profiles without any key-value definitions are said to be 'vanilla' profiles. MC can choose to filter two equivalent profiles (same connection manager and protocol). A mechanism to filter out same protocols with different connection managers for a vanilla profile is up to the MC implementation, it can be just 'Take the first available one', or user-configurable prioritization.

Non-vanilla profiles should all be presented, since there is no way to determine equivalence.

Format

Location: these files are located in the profiles subdirectory.

Naming: the file name must end in .profile.

The file must contain a section called "Profile". This section should contain all of the following keys:

_Name: the short name of the profile (=protocol most of the times).
_Description: the description of the profile in free text.
Manager: the connection manager on which this profile is defined.
Protocol: the protocol name to use for this profile's defaults. The connection
- manager defined above must support this protocol
IconPath: the path to the base icon for this profile. It should be in svg format to allow for
- several sizes and compositions to be generated.

Followed by any number of key-value for option defaults as follows:

Default-$name=$value
- $name is the name of the parameter to be set, as found in the corresponding

connection manager's .manager file

$value is the value to be set for the key while connecting.

Example

[Profile]
Manager=gabble
Protocol=jabber
_Name=Google Talk
_Description=Google's Jabber Network
Icon=/usr/share/icons/googletalk.svg
Default-old-ssl=true
Default-server=talk.google.com
Default-old-ssl=true
Default-ignore-ssl-errors=true
Default-port=5223

This .profile file defines the profile for a Google Talk connection using Gabble's Jabber support. The UI can then display Google Talk as 'protocol' when one has to choose a protocol, and the configuration for the connection parameter values will be preset as defaults.

[Profile]
Manager=salut
Protocol=link-local
_Name=Salut
_Description=Avahi Link-local messaging
Icon=/usr/share/icons/butterfly.svg

This could be for example a vanilla profile for the link-local connection-manager using Avahi discovery. It is a vanilla profile because it doesn't contain any key-value definitions.

Channel Handler Files

This section is a DRAFT.

Purpose

These files are installed by telepathy components other than connection managers. Current examples include end-user clients, programs that need to sync incoming buddy-lists with anything, global logger program.

The MC will read every available .chandler file and generate a list of activatable processes for each existing type of incoming channel.

For example, if a logger program wants to be invoked each time a TextChannel is created, it will need to put a .chandler file stating the process dbus name to be invoked, the channel type on which to react.

In the long term, this mechanism may be complemente or replaced by a full featured configurable process activation API, to allow the user or developper to choose with more fine-grain control what gets activated, maybe through match rules on more than the channel type, or any other mechanism.

Format

Location: these files live in the chandlers subdirectory.

Naming: these files are named name.chandler.

The file must contain a section called "ChannelHandler". This section should contain all of the following keys:

BusName: the dbus name of the activatable service to be triggered
ObjectPath: the dbus object path of the activatable service
ChannelType: the channel type string that will trigger the activation (as
- defined in the telepathy spec) to be matched against incoming channels.
HandleType: a comma separated list of handle types (as strings defined in the telepathy spec, ie group/contact/...) to be matched against incoming channels.

For a channel handler to be activated, both ChannelType and HandleType have to be matching.

Example

[ChannelHandler]
BusName=org.freedesktop.Telepathy.Cohoba.BigBrotherChannelHandler
ObjectPath=/org/freedesktop/Telepathy/Cohoba/BigBrotherChannelHandler
ChannelType=org.freedesktop.Telepathy.Channel.Type.Text
HandleType=contact,room

The dbus service 'org.freedesktop.Telepathy.Cohoba.BigBrotherChannelHandler' will be activated on each occurence of a Text channel.

Invoked Method (FIXME)

Each activatable channel handler service should implement the 'org.freedesktop.Telepathy.ChannelHandler' interface

HandleChannel(s:conn_name, o:conn_obj, s:channel_type, o:chan_obj, u:handle_type, u:handle) -> void
  conn_name: the telepathy connection dbus name
  conn_obj: the telepathy connection dbus object path
  channel_type: the channel type of the incoming channel as defined in the spec
  chan_obj: the telepathy channel dbus object path of the incoming channel
  handle_Type: the type of the handle as defined in the spec for the 'handle' argument
  handle: the handle, when applicable, for the incoming channel