Telepathy D-Bus Interface Specification

Version 0.17.7

Interfaces

• org.freedesktop.Telepathy.ConnectionManager
• org.freedesktop.Telepathy.Connection
• org.freedesktop.Telepathy.Connection.Interface.Aliasing
• org.freedesktop.Telepathy.Connection.Interface.Avatars
• org.freedesktop.Telepathy.Connection.Interface.Capabilities
• org.freedesktop.Telepathy.Connection.Interface.Presence
• org.freedesktop.Telepathy.Connection.Interface.Renaming
• org.freedesktop.Telepathy.Channel
• org.freedesktop.Telepathy.Channel.FUTURE
• org.freedesktop.Telepathy.Channel.Type.ContactList
• org.freedesktop.Telepathy.Channel.Type.StreamedMedia
• org.freedesktop.Telepathy.Channel.Type.RoomList
• org.freedesktop.Telepathy.Channel.Type.Text
• org.freedesktop.Telepathy.Channel.Type.Tubes
• org.freedesktop.Telepathy.Channel.Interface.CallMerging
• org.freedesktop.Telepathy.Channel.Interface.CallState
• org.freedesktop.Telepathy.Channel.Interface.ChatState
• org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting.DRAFT
• org.freedesktop.Telepathy.Channel.Interface.DTMF
• org.freedesktop.Telepathy.Channel.Interface.Group
• org.freedesktop.Telepathy.Channel.Interface.Hold
• org.freedesktop.Telepathy.Channel.Interface.HTML.DRAFT
• org.freedesktop.Telepathy.Channel.Interface.Password
• org.freedesktop.Telepathy.Channel.Interface.MediaSignalling
• org.freedesktop.Telepathy.Channel.Interface.Messages.DRAFT
• org.freedesktop.Telepathy.Media.SessionHandler
• org.freedesktop.Telepathy.Media.StreamHandler
• org.freedesktop.Telepathy.Properties
• org.freedesktop.Telepathy.AccountManager
• org.freedesktop.Telepathy.Account
• org.freedesktop.Telepathy.ChannelHandler

org.freedesktop.Telepathy.ConnectionManager

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.

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_Required
• register, corresponding to Conn_Mgr_Param_Flag_Register
• secret, corresponding to Conn_Mgr_Param_Flag_Secret

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

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

q, u, t (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

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.

Changed in version 0.17.2: Prior to version 0.17.2, support for CMs with no .manager file was not explicitly required.

Methods:

Signals:

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

Simple types

Sets of flags:

Conn_Mgr_Param_Flags

Conn_Mgr_Param_Flag_Required = 1

This parameter is required for connecting to the server.

Conn_Mgr_Param_Flag_Register = 2

This parameter is required for registering an account on the server.

Conn_Mgr_Param_Flag_Has_Default = 4

This parameter has a default value, which is returned in GetParameters; not providing this parameter is equivalent to providing the default.

Conn_Mgr_Param_Flag_Secret = 8

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

Added in version 0.17.2.

Structure types

org.freedesktop.Telepathy.Connection

This models a connection to a single user account on a communication service. Its basic capability is to provide the facility to request and receive channels of differing types (such as text channels or streaming media channels) which are used to carry out further communication.

As well as the methods and signatures below, arbitrary interfaces may be provided by the Connection object to represent extra connection-wide functionality, such as the Connection.Interface.Presence for receiving and reporting presence information, and Connection.Interface.Aliasing for connections where contacts may set and change an alias for themselves. These interfaces can be discovered using GetInterfaces after the connection, has been established and must not change subsequently at runtime.

Contacts, rooms, and server-stored lists (such as subscribed contacts, block lists, or allow lists) on a service are all represented by immutable handles, which are unsigned non-zero integers which are valid only for the lifetime of the connection object, and are used throughout the protocol where these entities are represented, allowing simple testing of equality within clients.

Zero as a handle value is sometimes used as a "null" value to mean the absence of a contact, room, etc.

Handles have per-type uniqueness, meaning that every (handle type, handle number) tuple is guaranteed to be unique within a connection and that a handle alone (without its type) is meaningless or ambiguous. Connection manager implementations should reference count these handles to determine if they are in use either by any active clients or any open channels, and may deallocate them when this ceases to be true. Clients may request handles of a given type and name with the RequestHandles method, inspect the entity name of handles with the InspectHandles method, keep handles from being released with HoldHandles, and notify that they are no longer storing handles with ReleaseHandles.

Methods:

Signals:

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

Simple types

Enumerated types:

Handle_Type

Handle_Type_None = 0

A "null" handle type used to indicate the absence of a handle. When a handle type and a handle appear as a pair, if the handle type is zero, the handle must also be zero.

Handle_Type_Contact = 1

A contact

Handle_Type_Room = 2

A chat room

Handle_Type_List = 3

A server-generated contact list (see Channel.Interface.Group)

Handle_Type_Group = 4

A user-defined contact list (see Channel.Interface.Group)

Connection_Status

Connection_Status_Connected = 0

The connection is alive and all methods are available.

Connection_Status_Connecting = 1

The connection has not yet been established, or has been severed and reconnection is being attempted. Some methods may fail until the connection has been established.

Connection_Status_Disconnected = 2

The connection has been severed and no method calls are valid. The object may be removed from the bus at any time.

Connection_Status_Reason

Connection_Status_Reason_None_Specified = 0

There is no reason set for this state change.

Connection_Status_Reason_Requested = 1

The change is in response to a user request.

Connection_Status_Reason_Network_Error = 2

There was an error sending or receiving on the network socket.

Connection_Status_Reason_Authentication_Failed = 3

The username or password was invalid.

Connection_Status_Reason_Encryption_Error = 4

There was an error negotiating SSL on this connection, or encryption was unavailable and require-encryption was set when the connection was created.

Connection_Status_Reason_Name_In_Use = 5

Someone is already connected to the server using the name you are trying to connect with.

Connection_Status_Reason_Cert_Not_Provided = 6

The server did not provide a SSL certificate.

Connection_Status_Reason_Cert_Untrusted = 7

The server's SSL certificate could not be trusted.

Connection_Status_Reason_Cert_Expired = 8

The server's SSL certificate has expired.

Connection_Status_Reason_Cert_Not_Activated = 9

The server's SSL certificate is not yet valid.

Connection_Status_Reason_Cert_Hostname_Mismatch = 10

The server's SSL certificate did not match its hostname.

Connection_Status_Reason_Cert_Fingerprint_Mismatch = 11

The server's SSL certificate does not have the expected fingerprint.

Connection_Status_Reason_Cert_Self_Signed = 12

The server's SSL certificate is self-signed.

Connection_Status_Reason_Cert_Other_Error = 13

There was some other error validating the server's SSL certificate.

Structure types

org.freedesktop.Telepathy.Connection.Interface.Aliasing

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Connection

An interface on connections to support protocols where contacts have an alias which they can change at will. Provides a method for the user to set their own alias, and a signal which should be emitted when a contact's alias is changed or first discovered.

On connections where the user is allowed to set aliases for contacts and store them on the server, the GetAliasFlags method will have the CONNECTION_ALIAS_FLAG_USER_SET flag set, and the SetAliases method may be called on contact handles other than the user themselves.

Aliases are intended to be used as the main displayed name for the contact, where available.

Methods:

Signals:

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

Sets of flags:

Connection_Alias_Flags

Connection_Alias_Flag_User_Set = 1

The aliases of contacts on this connection may be changed by the user of the service, not just by the contacts themselves. This is the case on Jabber, for instance.

It is possible that aliases can be changed by the contacts too - which alias takes precedence is not defined by this specification, and depends on the server and/or connection manager implementation.

This flag only applies to the aliases of "globally valid" contact handles. At this time, clients should not expect to be able to change the aliases corresponding to any channel-specific handles. If this becomes possible in future, a new flag will be defined.

Structure types

Mapping types

org.freedesktop.Telepathy.Connection.Interface.Avatars

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Connection

An interface for requesting avatars for contacts on a given connection, receiving notification when avatars are changed, and publishing your own avatar.

Avatars are identified by a unique (per contact) token which represents a hash or timestamp (depending on the protocol) of the contacts' avatar data. An empty token means that an avatar has not been set for this contact, and a changed token implies the contact's avatar has changed, but the strings should otherwise be considered opaque by clients.

A client should use GetKnownAvatarTokens to request the tokens for the avatars of all the contacts it is interested in when it connects. The avatars can then be requested using RequestAvatars for the contacts. Clients should bind to the AvatarChanged signal and request a new copy of the avatar when a contacts' avatar token changes. Clients should cache the token and data of each contact's avatar between connections, to avoid repeatedly retrieving the same avatar.

To publish an avatar, a client should use SetAvatar to provide an image which meets the requirements returned by the GetAvatarRequirements function. On some protocols the avatar is stored on the server, so setting the avatar is persistent, but on others it is transferred via a peer to peer mechanism, so needs to be set every connection. Hence, on every connection, clients should inspect the avatar token of the connection's self handle, and set the avatar if it is an empty string (and may optionally replace it if the token corresponds to a different avatar).

To remove the published avatar on protocols which have persistent avatars, a client should use the ClearAvatar method. This method can safely be used even if there is no avatar for this connection.

Methods:

Signals:

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

Mapping types

org.freedesktop.Telepathy.Connection.Interface.Capabilities

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Connection

An interface for connections where it is possible to know what channel types may be requested before the request is made to the connection object. Each capability represents a commitment by the connection manager that it will ordinarily be able to create a channel when given a request with the given type and handle.

Capabilities can pertain to a certain contact handle, representing activities such as having a text chat or a voice call with the user, or can be on the connection itself (where the handle will be zero), where they represent the ability to create channels for chat rooms or activities such as searching and room listing. The activities are represented by the D-Bus interface name of the channel type for that activity.

The generic capability flags are defined by Connection_Capability_Flags.

In addition, channel types may have type specific capability flags of their own, which are described in the documentation for each channel type.

This interface also provides for user interfaces notifying the connection manager of what capabilities to advertise for the user. This is done by using the AdvertiseCapabilities method, and deals with the interface names of channel types and the type specific flags pertaining to them which are implemented by available client processes.

Methods:

Signals:

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

Sets of flags:

Connection_Capability_Flags

Connection_Capability_Flag_Create = 1

The given channel type and handle can be given to RequestChannel to create a new channel of this type.

Connection_Capability_Flag_Invite = 2

The given contact can be invited to an existing channel of this type.

Structure types

org.freedesktop.Telepathy.Connection.Interface.Presence

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Connection

This interface is for services which have a concept of presence which can be published for yourself and monitored on your contacts. Telepathy's definition of presence is based on that used by the Galago project (see http://www.galago-project.org/).

Presence on an individual (yourself or one of your contacts) is modelled as a last activity time along with a set of zero or more statuses, each of which may have arbitrary key/value parameters. Valid statuses are defined per connection, and a list of them can be obtained with the GetStatuses method.

Each status has an arbitrary string identifier which should have an agreed meaning between the connection manager and any client which is expected to make use of it. The following well-known values (in common with those in Galago) should be used where possible to allow clients to identify common choices:

• available
• away
• brb (Be Right Back)
• busy
• dnd (Do Not Disturb),
• xa (Extended Away)
• hidden (aka Invisible)
• offline

As well as these well-known status identifiers, every status also has a numerical type value chosen from ConnectionPresenceType which can be used by the client to classify even unknown statuses into different fundamental types.

These numerical types exist so that even if a client does not understand the string identifier being used, and hence cannot present the presence to the user to set on themselves, it may display an approximation of the presence if it is set on a contact.

The dictionary of variant types allows the connection manager to exchange further protocol-specific information with the client. It is recommended that the string (s) argument 'message' be interpreted as an optional message which can be associated with a presence status.

If the connection has a 'subscribe' contact list, PresenceUpdate signals should be emitted to indicate changes of contacts on this list, and should also be emitted for changes in your own presence. Depending on the protocol, the signal may also be emitted for others such as people with whom you are communicating, and any user interface should be updated accordingly.

On some protocols, RequestPresence may only succeed on contacts on your 'subscribe' list, and other contacts will cause a PermissionDenied error. On protocols where there is no 'subscribe' list, and RequestPresence succeeds, a client may poll the server intermittently to update any display of presence information.

Methods:

Signals:

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

Enumerated types:

Connection_Presence_Type

Connection_Presence_Type_Unset = 0

An invalid presence type used as a null value

Connection_Presence_Type_Offline = 1

Offline

Connection_Presence_Type_Available = 2

Available

Connection_Presence_Type_Away = 3

Away

Connection_Presence_Type_Extended_Away = 4

Away for an extended time

Connection_Presence_Type_Hidden = 5

Hidden (invisible)

Connection_Presence_Type_Busy = 6

Busy, Do Not Disturb.

Added in version 0.17.0.

Structure types

Mapping types

org.freedesktop.Telepathy.Connection.Interface.Renaming

This interface is not well-tested and is likely to cause havoc to your API/ABI if bindings are generated. Don't include it in libraries that care about compatibility.

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Connection

Methods:

Signals:

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

org.freedesktop.Telepathy.Channel

All communication in the Telepathy framework is carried out via channel objects which are created and managed by connections. This interface must be implemented by all channel objects, along with one single channel type, such as Channel.Type.ContactList which represents a list of people (such as a buddy list) or a Channel.Type.Text which represents a channel over which textual messages are sent and received.

Each channel may have an immutable handle associated with it, which may be any handle type, such as a contact, room or list handle, indicating that the channel is for communicating with that handle.

If a channel does not have a handle (an "anonymous channel" with Target_Handle = 0 and Target_Handle_Type = Handle_Type_None), it means that the channel is defined by some other terms, such as it may be a transient group defined only by its members as visible through the Channel.Interface.Group interface.

Other optional interfaces can be implemented to indicate other available functionality, such as Channel.Interface.Group if the channel contains a number of contacts, Channel.Interface.Password to indicate that a channel may have a password set to require entry, and Properties for extra data about channels which represent chat rooms or voice calls. The interfaces implemented may not vary after the channel's creation has been signalled to the bus (with the connection's NewChannel signal).

Specific connection manager implementations may implement channel types and interfaces which are not contained within this specification in order to support further functionality. To aid interoperability between client and connection manager implementations, the interfaces specified here should be used wherever applicable, and new interfaces made protocol-independent wherever possible. Because of the potential for 3rd party interfaces adding methods or signals with conflicting names, the D-Bus interface names should always be used to invoke methods and bind signals.

Changed in version 0.17.7: Previously we guaranteed that, for any handle type other than Handle_Type_None, and for any channel type and any handle, there would be no more than one channel with that combination of channel type, handle type and handle. This guarantee has now been removed in order to accommodate features like message threads.

Methods:

Signals:

Interface has no Telepathy properties.

D-Bus core Properties:

Accessed using the org.freedesktop.DBus.Properties interface.

ChannelType - s(DBus_Interface), read-only

The channel's type. This cannot change once the channel has been created.

For compatibility between older connection managers and newer clients, if this is unavailable or is an empty string, clients MUST use the result of calling GetChannelType.

The GetAll method lets clients retrieve all properties in one round-trip, which is desirable.

Added in version 0.17.7.

Interfaces - as(DBus_Interface[]), read-only

Extra interfaces provided by this channel. This SHOULD NOT include the channel type and the Channel interface itself, and cannot change once the channel has been created.

For compatibility between older connection managers and newer clients, if this is unavailable, or if this is an empty list and ChannelType is an empty string, clients MUST use the result of calling GetInterfaces instead. If this is an empty list but ChannelType is non-empty, clients SHOULD NOT call GetInterfaces; this implies that connection managers that implement the ChannelType property MUST also implement the Interfaces property correctly.

The GetAll method lets clients retrieve all properties in one round-trip, which is desirable.

Added in version 0.17.7.

TargetHandle - u(Handle), read-only

The handle (a representation for the identifier) of the contact, chatroom, etc. with which this handle communicates. Its type is given by the TargetHandleType property.

This is fixed for the lifetime of the channel, so channels which could potentially be used to communicate with multiple contacts (such as streamed media calls defined by their members, or ad-hoc chatrooms like MSN switchboards) must have TargetHandleType set to Handle_Type_None and TargetHandle set to 0.

Unlike in the telepathy-spec 0.16 API, there is no particular uniqueness guarantee - there can be many channels with the same (channel type, handle type, handle) tuple. This is necessary to support conversation threads in XMPP and SIP, for example.

Added in version 0.17.7.

TargetHandleType - u(Handle_Type), read-only

The type of TargetHandle.

Added in version 0.17.7.

org.freedesktop.Telepathy.Channel.FUTURE

This interface is a staging area for future Channel functionality and is likely to cause havoc to your API/ABI if bindings are generated. Don't include it in libraries that care about compatibility.

This interface contains functionality which we intend to incorporate into the Channel interface in future. It should be considered to be conceptually part of the core Channel interface, but without API or ABI guarantees.