telepathy/ Documentation/ File Formats

File Formats

  1. 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. New implementations do not need to support this location.

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

These are documented by the ConnectionManager section of the Telepathy specification.

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