Telepathy D-Bus Interface Specification

Version 0.17.9

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.Contacts
• org.freedesktop.Telepathy.Connection.Interface.SimplePresence
• org.freedesktop.Telepathy.Connection.Interface.Presence
• org.freedesktop.Telepathy.Connection.Interface.Renaming
• org.freedesktop.Telepathy.Connection.Interface.Requests.DRAFT
• org.freedesktop.Telepathy.ChannelBundle.DRAFT
• 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.

D-Bus core Properties:

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

Interfaces − as, read-only

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.

Added in version 0.17.8.

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 the GetInterfaces method.

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 using GetKnownAvatarTokens; if the self handle is not in the returned map, the client should re-set the avatar. If the self handle's avatar token is known, but the avatar has been changed locally since the last connection, the client should upload the new avatar; if the avatar has not changed locally, then the client should download the avatar from the server if its token differs from the that of the local 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 pertain to particular contact handles, and represent activities such as having a text chat or a voice call with the user. 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.

Changed in version 0.17.8: Previously, this interface also expressed capabilities of the connection itself, indicating what sorts of channels could be requested (for instance, the ability to open chatroom lists or chatrooms). However, this was never very well-defined or consistent, and as far as we know it was never implemented correctly. This usage is now deprecated.

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

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Connection

This interface allows many attributes of many contacts to be obtained in a single D-Bus round trip.

Each contact attribute has an string identifier (Contact_Attribute), which is namespaced by the D-Bus interface which defines it.

An initial set of contact attributes is defined here:

org.freedesktop.Telepathy.Connection/contact-id (type s)

The same string that would be returned by InspectHandles (always present in the result)

org.freedesktop.Telepathy.Connection.Interface.Aliasing/alias (type s)

The same string that would be returned by GetAliases (always present with some value, possibly the same as Connection/contact-id, if information from the Aliasing interface was requested)

org.freedesktop.Telepathy.Connection.Interface.Avatars/token (type s)

The same string that would be returned by GetKnownAvatarTokens (omitted from the result if the contact's avatar token is not known, present as an empty string if the contact is known not to have an avatar). Unlike in the GetKnownAvatarTokens method, the avatar tokens for the self handle aren't required to be present. This attribute should not be used to determine whether or not the Avatar needs to be set.

org.freedesktop.Telepathy.Connection.Interface.SimplePresence/presence (type (uss), Simple_Presence)

The same struct that would be returned by GetPresences (always present with some value if information from the SimplePresence interface was requested)

org.freedesktop.Telepathy.Connection.Interface.Capabilities/caps (type a(usuu), Contact_Capability)

The same structs that would be returned by GetCapabilities (all of them will redundantly have the contact's handle as the first member). Omitted from the result if the contact's capabilities are not known; present in the result as an empty array if the contact is known to have no capabilities at all.

Added in version 0.17.9.

Methods:

Interface has no signals.

Interface has no Telepathy properties.

D-Bus core Properties:

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

ContactAttributeInterfaces − as (DBus_Interface[]), read-only

A list of D-Bus interfaces for which GetContactAttributes is expected to work. This cannot change during the lifetime of the Connection.

Simple types

Mapping types

org.freedesktop.Telepathy.Connection.Interface.SimplePresence

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.

Presence on an individual (yourself or one of your contacts) is modelled as a status and a status message. Valid statuses are defined per connection, and a list of those that can be set on youself can be obtained from the Statuses property.

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 should be used where possible to allow clients to identify common choices:

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.

As well as the normal status identifiers, there are two special ones that may be present: 'unknown' with type Unknown and 'error' with type Error. 'unknown' indicates that it is impossible to determine the presence of a contact at this time, for example because it's not on the 'subscribe' list and the protocol only allows one to determine the presence of contacts you're subscribed to. 'error' indicates that there was a failure in determining the status of a contact.

If the connection has a 'subscribe' contact list, PresencesChanged 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.

Methods:

Signals:

Interface has no Telepathy properties.

D-Bus core Properties:

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

Statuses − a{s(ubb)} (Simple_Status_Spec_Map), read-only

A dictionary where the keys are the presence statuses that the user can set on themselves for this connection, and the values are the corresponding presence types.

While the connection is in the DISCONNECTED state, it contains the set of presence statuses allowed to be set before connecting. The connection manager will attempt to set the appropriate status when the connection becomes connected, but cannot necessarily guarantee it. The available statuses cannot change until the connection status changes, so there is no change notification.

While the connection is in the CONNECTED state, this property contains the set of presence statuses which are actually available on this protocol. This set is constant for the remaining lifetime of the connection, so again, there is no change notification.

While the connection is in the CONNECTING state, the value of this property is undefined and SHOULD NOT be used. It can change at any time without notification (in particular, any cached values from when the connection was in the DISCONNECTED or CONNECTING state MUST NOT be assumed to still be correct when the state has become CONNECTED).

This property MUST include the special statuses "unknown" and "error" if and only if the connection manager can emit them as a contact's status.

For instance, connection managers for local-xmpp (XEP-0174) would omit "unknown" since there is no such concept.

Structure types

Mapping types

org.freedesktop.Telepathy.Connection.Interface.Presence

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Connection

This interface will become deprecated in future versions. New client implementations MAY use org.freedesktop.Telepathy.Connection.Interface.SimplePresence instead; new connection managers SHOULD implement both Presence and SimplePresence.

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.

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 (corresponding to Connection_Presence_Type_Available)
• away (corresponding to Connection_Presence_Type_Away)
• brb (Be Right Back) (corresponding to Connection_Presence_Type_Away, but more specific)
• busy (corresponding to Connection_Presence_Type_Busy)
• dnd (Do Not Disturb) (corresponding to Connection_Presence_Type_Busy, but more specific)
• xa (Extended Away) (corresponding to Connection_Presence_Type_Extended_Away)
• hidden (aka Invisible) (corresponding to Connection_Presence_Type_Hidden)
• offline (corresponding to Connection_Presence_Type_Offline)
• unknown (corresponding to Connection_Presence_Type_Unknown)
• error (corresponding to Connection_Presence_Type_Error)

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. This value MUST NOT appear in the result of GetStatuses, or in the Statuses property of the SimplePresence interface.

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.

Connection_Presence_Type_Unknown = 7

Unknown, unable to determine presence for this contact, for example if the protocol only allows presence of subscribed contacts.

Added in version 0.17.8.

Connection_Presence_Type_Error = 8

Error, an error occurred while trying to determine presence. The message, if set, is an error from the server.

Added in version 0.17.8.

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.Connection.Interface.Requests.DRAFT

This interface is experimental 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

An enhanced version of the Telepathy connection interface, which can represent bundles of channels that should be dispatched together, and does not assume any particular properties by which channels are uniquely identifiable.

Added in version 0.17.9.

Methods:

Signals:

Interface has no Telepathy properties.

D-Bus core Properties:

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

Channels − a(oa{sv}) (Channel_Details[]), read-only

A list of all the channels which currently exist on this connection. Change notification is via the NewChannels and ChannelClosed signals.

RequestableChannelClasses − a(a{sv}as) (Requestable_Channel_Class[]), read-only

The classes of channel that are expected to be available on this connection, i.e. those for which CreateChannel can reasonably be expected to succeed. User interfaces can use this information to show or hide UI components.

This property cannot change after the connection has gone to state Connection_Status_Connected, so there is no change notification (if the connection has context-dependent capabilities, it SHOULD advertise support for all classes of channel that it might support during its lifetime). Before this state has been reached, the value of this property is undefined.

This is not on an optional interface, because connection managers can always offer some sort of clue about the channel classes they expect to support (at worst, they can announce support for everything for which they have code).

Structure types

Mapping types

org.freedesktop.Telepathy.ChannelBundle.DRAFT

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

A group of related channels, which should all be dispatched to the same handler if possible.

Bundles currently have no functionality of their own, so clients SHOULD NOT examine this interface, but should instead treat the bundle object-path as an opaque identifier. If more functionality is added to bundles in future, this interface will be used for capability discovery.

The lifetime of a bundle is defined by its component channels - as long as one or more channels whose Bundle property is B exist, the bundle B will also exist.

Interface has no methods.

Interface has no signals.

Interface has no Telepathy properties.

D-Bus core Properties:

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

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

A list of the extra interfaces provided by this channel bundle.

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.

When requesting a channel, the request MUST specify a channel type, and the request MUST fail if the specified channel type cannot be supplied.

Common sense.

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.

When requesting a channel with a particular value for this property, the request must fail without side-effects unless the connection manager expects to be able to provide a channel whose interfaces include at least the interfaces requested.

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.

If this is present in a channel request, it must be nonzero, TargetHandleType MUST be present and not Handle_Type_None, and TargetID MUST NOT be present.

The channel that satisfies the request MUST either:

• have the specified TargetHandle property; or
• have TargetHandleType = Handle_Type_None, TargetHandle = 0, and be configured such that it could communicate with the specified handle in some other way (e.g. have the requested contact handle in its Group interface)

Added in version 0.17.7.

TargetID − s, read-only

The string that would result from inspecting the TargetHandle property (i.e. the identifier in the IM protocol of the contact, room, etc. with which this channel communicates), or the empty string if the TargetHandle is 0.

The presence of this property avoids the following race condition:

• New channel C is signalled with target handle T
• Client calls InspectHandles(CONTACT, [T])
• Channel C closes, removing the last reference to handle T
• InspectHandles(CONTACT, [T]) returns an error

If this is present in a channel request, TargetHandleType MUST be present and not Handle_Type_None, and TargetHandle MUST NOT be present. The request MUST fail with error InvalidHandle, without side-effects, if the requested TargetID would not be accepted by RequestHandles.

The returned channel must be related to the handle corresponding to the given identifier, in the same way as if TargetHandle had been part of the request instead.

Requesting channels with a string identifier saves a round-trip (the call to RequestHandles). It also allows the channel dispatcher to accept a channel request for an account that is not yet connected (and thus has no valid handles), bring the account online, and pass on the same parameters to the new connection's CreateChannel method.

Added in version 0.17.9.

TargetHandleType − u (Handle_Type), read-only

The type of TargetHandle.

If this is omitted from a channel request, connection managers SHOULD treat this as equivalent to Handle_Type_None.

If this is omitted or is Handle_Type_None, TargetHandle and TargetID MUST be omitted from the request.

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.

Interface has no methods.

Interface has no signals.

Interface has no Telepathy properties.

D-Bus core Properties:

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

Requested − b, read-only

True if this channel was created in response to a call to Connection.RequestChannel, or Connection.Interface.Requests.DRAFT.CreateChannel.

The idea of this property is to distinguish between "incoming" and "outgoing" channels, in a way that doesn't break down when considering special cases like contact lists that are automatically created on connection to the server, or chatrooms that an IRC proxy/bouncer like irssi-proxy or bip was already in.

The reason we want to make that distinction is that UIs for things that the user explicitly requested should start up automatically, whereas for incoming messages and VoIP calls we should first ask the user whether they want to open the messaging UI or accept the call.

If the channel was not explicitly requested (even if it was created as a side-effect of a call to one of those functions, e.g. because joining a Tube in a MUC context on XMPP implies joining that MUC), then this property is false.

For compatibility with older connection managers, clients SHOULD assume that this property is true if they see a channel announced by the Connection.NewChannel signal with the suppress_handler parameter set to true.

In a correct connection manager, the only way to get such a channel is to request it.

Clients MAY additionally assume that this property is false if they see a channel announced by the NewChannel signal with the suppress_handler parameter set to false.

This is more controversial, since it's possible to get that parameter set to false by requesting a channel. However, there's no good reason to do so, and we've deprecated this practice.

In the particular case of the channel dispatcher, the only side-effect of wrongly thinking a channel is unrequested is likely to be that the user has to confirm that they want to use it, so it seems fairly harmless to assume in the channel dispatcher that channels with suppress_handler false are indeed unrequested.

InitiatorHandle − u (Contact_Handle), read-only

The contact who initiated the channel. For channels requested by the local user, this MUST be the same thing as would be returned by Connection.GetSelfHandle() at the time the channel was created.

The careful wording about the self-handle is because the Renaming interface can cause the return from Connection.GetSelfHandle to change. It's something of a specification bug that we don't signal this in the Connection interface yet.

For channels requested by a remote user, this MUST be their handle. If unavailable or not applicable, this MUST be 0 (for instance, contact lists are not really initiated by anyone in particular, and it's easy to imagine a protocol where chatroom invitations can be anonymous).

For channels with the Group interface, this SHOULD be the same contact who is signalled as the "Actor" causing the self-handle to be placed in the local-pending set.

This SHOULD NOT be a channel-specific handle, if possible.

It does not make sense for this property to be in channel requests - the initiator will always be the local user - so it MUST NOT be accepted.

Added in version 0.17.7. (in Channel.FUTURE pseudo-interface)

InitiatorID − s, read-only

The string that would result from inspecting the InitiatorHandle property (i.e. the initiator's identifier in the IM protocol).

The presence of this property avoids the following race condition:

• New StreamedMedia channel C is signalled with initiator handle I
• Client calls InspectHandles(CONTACT, [I])
• Channel C closes, removing the last reference to handle I
• InspectHandles(CONTACT, [I]) returns an error
• Client can indicate that a call was missed, but not who called!

It does not make sense for this property to be in channel requests - the initiator will always be the local user - so it MUST NOT be accepted.

Added in version 0.17.7. (in Channel.FUTURE pseudo-interface)

Bundle − o, read-only

The ChannelBundle to which this channel belongs.

A channel's Bundle property can never change.

Older connection managers might not have this property. Clients (particularly the channel dispatcher) SHOULD recover by considering each channel to be in a bundle containing only that channel, distinct from all other bundles, which has no additional interfaces.

Added in version 0.17.9. (in Channel.FUTURE pseudo-interface)

org.freedesktop.Telepathy.Channel.Type.ContactList

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Channel
• org.freedesktop.Telepathy.Channel.Interface.Group

A channel type for representing a list of people on the server which is not used for communication. This is intended for use with the interface Channel.Interface.Group for managing buddy lists and privacy lists on the server. This channel type has no methods because all of the functionality it represents is available via the group interface.

There are currently two types of contact list: HANDLE_TYPE_LIST is a "magic" server-defined list, and HANDLE_TYPE_GROUP is a user-defined contact group.

For server-defined lists like the subscribe list, singleton instances of this channel type should be created by the connection manager at connection time if the list exists on the server, or may be requested by using the appropriate handle. These handles can be obtained using RequestHandles with a handle type of HANDLE_TYPE_LIST and one of the following identifiers:

• subscribe - the group of contacts for whom you wish to receive presence
• publish - the group of contacts who may receive your presence
• hide - a group of contacts who are on the publish list but are temporarily disallowed from receiving your presence
• allow - a group of contacts who may send you messages
• deny - a group of contacts who may not send you messages

These contact list channels may not be closed.

For user-defined contact groups, instances of this channel type should be created by the connection manager at connection time for each group that exists on the server. New, empty groups can be created by calling RequestHandles with a handle type of HANDLE_TYPE_GROUP and with the name set to the human-readable UTF-8 name of the group.

User-defined groups may be deleted by closing the channel, but only if the group is already empty. Closing a channel to a non-empty group is not allowed; its members must be set to the empty set first.

On some protocols (e.g. XMPP) empty groups are not represented on the server, so disconnecting from the server and reconnecting might cause empty groups to vanish.

Interface has no methods.

Interface has no signals.

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

org.freedesktop.Telepathy.Channel.Type.StreamedMedia

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Channel
• org.freedesktop.Telepathy.Channel.Interface.Group

A channel that can send and receive streamed media such as audio or video. Provides a number of methods for listing and requesting new streams, and signals to indicate when streams have been added, removed and changed status.

Channels of this type are expected to provide the Group interface and be "anonymous" (have no associated handle). To make a media call to a contact, clients should request a new, empty streamed media channel, then call AddMembers to add the contact to the channel. The local user should be in the group's members, while the contact should be absent from the channel until a call is made, appear in "remote pending" from when the call is attempted until the call is accepted, then move to the group's members.

Similarly, incoming calls should be signalled as having handle type 0 and handle 0. The remote contact should be in the group's members, with the local user in the "local pending" members; to accept the call, AddMembers can be used to move the local user to the group's members.

In general this should be used in conjunction with the MediaSignalling interface to exchange connection candidates and codec choices with whichever component is responsible for the streams. However, in certain applications where no candidate exchange is necessary (eg the streams are handled by specialised hardware which is controlled directly by the connection manager), the signalling interface can be omitted and this channel type used simply to control the streams.

Methods:

Signals:

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

Simple types

Enumerated types:

Media_Stream_Type

Media_Stream_Type_Audio = 0

An audio stream

Media_Stream_Type_Video = 1

A video stream

Media_Stream_State

Media_Stream_State_Disconnected = 0

The stream is disconnected.

Media_Stream_State_Connecting = 1

The stream is trying to connect.

Media_Stream_State_Connected = 2

The stream is connected.

Media_Stream_Direction

Media_Stream_Direction_None = 0

Media are not being sent or received

Media_Stream_Direction_Send = 1

Media are being sent, but not received

Media_Stream_Direction_Receive = 2

Media are being received, but not sent

Media_Stream_Direction_Bidirectional = 3

Media are being sent and received

Sets of flags:

Media_Stream_Pending_Send

Media_Stream_Pending_Local_Send = 1

The local user has been asked to send media by the remote user. Call RequestStreamDirection to indicate whether or not this is acceptable.

Media_Stream_Pending_Remote_Send = 2

The remote user has been asked to send media by the local user. The StreamDirectionChanged signal will be emitted when the remote user accepts or rejects this change.

Channel_Media_Capabilities

Channel_Media_Capability_Audio = 1

The handle is capable of using audio streams within a media channel.

Channel_Media_Capability_Video = 2

The handle is capable of using video streams within a media channel.

Channel_Media_Capability_NAT_Traversal_STUN = 4

The handle is capable of performing STUN to traverse NATs.

Channel_Media_Capability_NAT_Traversal_GTalk_P2P = 8

The handle is capable of establishing Google Talk peer-to-peer connections (as implemented in libjingle 0.3) to traverse NATs.

Structure types

org.freedesktop.Telepathy.Channel.Type.RoomList

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Channel

A channel type for listing named channels available on the server. Once the ListRooms method is called, it emits signals for rooms present on the server, until you Close this channel. In some cases, it may not be possible to stop the deluge of information from the server. This channel should be closed when the room information is no longer being displayed, so that the room handles can be freed.

This channel type may be implemented as a singleton on some protocols, so clients should be prepared for the eventuality that they are given a channel that is already in the middle of listing channels. The ListingRooms signal, or GetListingRooms method, can be used to check this.

Methods:

Signals:

Interface has no Telepathy properties.

D-Bus core Properties:

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

Server − s, read-only

For protocols with a concept of chatrooms on multiple servers with different DNS names (like XMPP), the DNS name of the server whose rooms are listed by this channel, e.g. "conference.jabber.org". Otherwise, the empty string. This property cannot change during the lifetime of the channel.

Structure types

org.freedesktop.Telepathy.Channel.Type.Text

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Channel

A channel type for sending and receiving messages in plain text, with no formatting. In future specifications, channels for sending and receiving messages that can be reduced to plain text (i.e. formatted text) should also have this type.

When a message is received, an identifier is assigned and a Received signal emitted, and the message placed in a pending queue which can be inspected with ListPendingMessages. A client which has handled the message by showing it to the user (or equivalent) should acknowledge the receipt using the AcknowledgePendingMessage method, and the message will then be removed from the pending queue. Numeric identifiers for received messages may be reused over the lifetime of the channel.

Each message has an associated 'type' value, which should be one of the values allowed by ChannelTextMessageType.

Each message also has a flags value, which is a bitwise OR of the flags given in ChannelTextMessageFlags.

Sending messages can be requested using the Send method, which will return successfully and emit the Sent signal when the message has been delivered to the server, or return an error with no signal emission if there is a failure. If a message is sent but delivery of the message later fails, this is indicated with the SendError signal.

On protocols where additional contacts cannot be invited into a one-to-one chat, or where a one-to-one chat is just a series of individual personal messages rather than being represented by some object on the server (i.e. most protocols), one-to-one chats should be represented by a Text channel with handle type CONTACT.

Named chat rooms whose identity can be saved and used again later (IRC channels, Jabber MUCs) are expected to be represented by Text channels with handle type ROOM and the Group interface; they should usually also have the Properties interface.

Unnamed, transient chat rooms defined only by their members (e.g. on MSN) are expected to be represented by Text channels with handle type 0, handle 0, the Group interface, and optionally the Properties interface.

On protocols where a conversation with a user is actually just a nameless chat room starting with exactly two members, to which more members can be invited, calling RequestChannel with type Text and handle type CONTACT should continue to succeed, but may return a channel with handle type 0, handle 0, the group interface, and the local and remote contacts in its members.

Methods:

Signals:

Telepathy Properties:

Accessed using the Telepathy Properties interface.

anonymous − b

True if people may join the channel without other members being made aware of their identity.

invite-only − b

True if people may not join the channel until they have been invited.

limit − u

The limit to the number of members, if limited is true.

limited − b

True if there is a limit to the number of channel members.

moderated − b

True if channel membership is not sufficient to allow participation.

name − s

A human-visible name for the channel, if it differs from the string version of the channel's handle.

description − s

A human-readable description of the channel's overall purpose.

password − s

The password required to enter the channel if password-required is true.

password-required − b

True if a password must be provided to enter the channel.

persistent − b

True if the channel will remain in existence on the server after all members have left it.

private − b

True if the channel is not visible to non-members.

subject − s

A human-readable description of the current subject of conversation in the channel, similar to /topic in IRC.

subject-contact − u

A contact handle representing who last modified the subject, or 0 if it isn't known.

subject-timestamp − u

A unix timestamp indicating when the subject was last modified.

Interface has no D-Bus core properties.

Simple types

Enumerated types:

Channel_Text_Send_Error

Channel_Text_Send_Error_Unknown = 0

An unknown error occurred

Channel_Text_Send_Error_Offline = 1

The requested contact was offline

Channel_Text_Send_Error_Invalid_Contact = 2

The requested contact is not valid

Channel_Text_Send_Error_Permission_Denied = 3

The user does not have permission to speak on this channel

Channel_Text_Send_Error_Too_Long = 4

The outgoing message was too long and was rejected by the server

Channel_Text_Send_Error_Not_Implemented = 5

The channel doesn't support sending text messages to the requested contact

Channel_Text_Message_Type

Channel_Text_Message_Type_Normal = 0

An ordinary chat message. Unknown types SHOULD be treated like this.

Channel_Text_Message_Type_Action = 1

An action which might be presented to the user as "* <sender> <action>", such as an IRC CTCP ACTION (typically selected by the "/me" command). For example, the text of the message might be "drinks more coffee".

Channel_Text_Message_Type_Notice = 2

A one-off or automated message not necessarily expecting a reply

Channel_Text_Message_Type_Auto_Reply = 3

An automatically-generated reply message.

Channel_Text_Message_Type_Delivery_Report = 4

This message type MUST NOT appear unless the channel supports the DeliveryReporting interface. The message MUST be as defined by the DeliveryReporting interface.

Sets of flags:

Channel_Text_Message_Flags

Channel_Text_Message_Flag_Truncated = 1

The incoming message was truncated to a shorter length by the server or the connection manager.

Channel_Text_Message_Flag_Non_Text_Content = 2

The incoming message contained non-text content which cannot be represented by this interface, but has been signalled in the Messages interface.

Connection managers SHOULD only set this flag if the non-text content appears to be relatively significant (exactly how significant is up to the implementor). The intention is that if this flag is set, clients using this interface SHOULD inform the user that part of the message was not understood.

Structure types

org.freedesktop.Telepathy.Channel.Type.Tubes

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Channel

A "tube" is a mechanism for arbitrary data transfer. Two types of data transfer are currently specified: D-Bus messages, and streams of bytes. Each tube has a service name, which is a string specifying the kind of communication that takes place over it, and a dictionary of arbitrary parameters. Tube parameters are commonly used for bootstrap information such as usernames and passwords. Each tube is identified by a locally unique identifier.

The Tubes channel type may be requested for handles of type HANDLE_TYPE_CONTACT and HANDLE_TYPE_ROOM.

Stream tubes specify listening addresses using pairs of parameters with signature 'u', 'v', where the integer 'u' is a member of Socket_Address_Type and the v is dependent on the type of address.

Methods:

Signals:

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

Simple types

Enumerated types:

Tube_Type

Tube_Type_DBus = 0

An ordered reliable transport, for transporting D-Bus traffic.

For each D-Bus tube, the connection manager listens on a D-Bus server address, as detailed in the D-Bus specification. On this address, it emulates a bus upon which each tube participant appears as an endpoint.

The objects and interfaces which are expected to exist on the emulated bus depend on the well-known name; typically, either the participant who initiated the tube is expected to export the same objects/interfaces that would be exported by a service of that name on a bus, or all participants are expected to export those objects/interfaces.

In a multi-user context (Handle_Type_Room) the tube behaves like the D-Bus bus daemon, so participants can send each other private messages, or can send broadcast messages which are received by everyone in the tube (including themselves). Each participant has a D-Bus unique name; connection managers must prevent participants from sending messages with the wrong sender unique name, and should attempt to avoid participants receiving messages not intended for them.

In a 1-1 context (Handle_Type_Contact) the tube behaves like a peer-to-peer D-Bus connection - arbitrary D-Bus messages with any sender and/or destination can be sent by each participant, and each participant receives all messages sent by the other participant.

Tube_Type_Stream = 1

A transport for ordered, reliable data transfer, similar to SOCK_STREAM sockets.

When accepting a Stream Unix tube, a new listening local socket is created. Each time the client connects to this socket, the connection manager of the initiator of the tube opens a new connection to its local socket. Both sides can then use this pair of sockets to communicate together.

Tube_State

Tube_State_Local_Pending = 0

The tube is waiting to be accepted/closed locally.

Tube_State_Remote_Pending = 1

The tube is waiting to be accepted/closed remotely.

Tube_State_Open = 2

The tube is open for traffic.

Socket_Address_Type

Socket_Address_Type_Unix = 0

A Unix socket. The variant contains a byte-array, signature 'ay', containing the path of the socket.

Socket_Address_Type_Abstract_Unix = 1

An abstract Unix socket. The variant contains a byte-array, signature 'ay', containing the path of the socket including the leading null byte.

Socket_Address_Type_IPv4 = 2

An IPv4 socket. The variant contains a Socket_Address_IPv4, i.e. a structure with signature (sq) in which the string is an IPv4 dotted-quad address literal (and must not be a DNS name), while the 16-bit unsigned integer is the port number.

Socket_Address_Type_IPv6 = 3

An IPv6 socket. The variant contains a Socket_Address_IPv6, i.e. a structure with signature (sq) in which the string is an IPv6 address literal as specified in RFC2373 (and must not be a DNS name), while the 16-bit unsigned integer is the port number.

Socket_Access_Control

Socket_Access_Control_Localhost = 0

The IP or Unix socket can be accessed by any local user (e.g. a Unix socket that accepts all local connections, or an IP socket listening on 127.0.0.1 (or ::1) or rejecting connections not from that address). The associated variant must be ignored.

Socket_Access_Control_Port = 1

May only be used on IP sockets. The associated variant must contain a struct Socket_Address_IPv4 (or Socket_Address_IPv6) containing the string form of an IP address of the appropriate version, and a port number. The socket can only be accessed if the connecting process has that address and port number; all other connections will be rejected.

Socket_Access_Control_Netmask = 2

May only be used on IP sockets. The associated variant must contain a struct Socket_Netmask_IPv4 (or Socket_Netmask_IPv6) with signature (sy), containing the string form of an IP address of the appropriate version, and a prefix length "n". The socket can only be accessed if the first n bits of the connecting address match the first n bits of the given address.

Socket_Access_Control_Credentials = 3

The connecting process must send a single zero (NUL) byte when it first connects, which is not considered to be part of the data stream. If the operating system uses sendmsg() with SCM_CREDS or SCM_CREDENTIALS to pass credentials over sockets, the connecting process must do so if possible; if not, it must still send the byte.

The listening process will disconnect the connection unless it can determine by OS-specific means that the connecting process has the same user ID as the listening process.

The associated variant must be ignored.

Structure types

Mapping types

org.freedesktop.Telepathy.Channel.Interface.CallMerging

This interface is not yet API-stable 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.Channel.Type.StreamedMedia

Interface for streamed media channels that can be merged and split in the same sort of way as in GSM or PBX telephony.

Added in version 0.17.1.

Methods:

Interface has no signals.

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

org.freedesktop.Telepathy.Channel.Interface.CallState

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Channel.Type.StreamedMedia

Added in version 0.17.2.

Methods:

Signals:

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

Sets of flags:

Channel_Call_State_Flags

Channel_Call_State_Ringing = 1

The contact has been alerted about the call but has not responded (e.g. 180 Ringing in SIP).

Channel_Call_State_Queued = 2

The contact is temporarily unavailable, and the call has been placed in a queue (e.g. 182 Queued in SIP, or call-waiting in telephony).

Channel_Call_State_Held = 4

The contact has placed the call on hold, and will not receive media from the local user or any other participants until they unhold the call again.

Mapping types

org.freedesktop.Telepathy.Channel.Interface.ChatState

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Channel

Methods:

Signals:

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

Enumerated types:

Channel_Chat_State

Channel_Chat_State_Gone = 0

The contact has effectively ceased participating in the chat.

Channel_Chat_State_Inactive = 1

The contact has not been active for some time.

Channel_Chat_State_Active = 2

The contact is actively participating in the chat.

Channel_Chat_State_Paused = 3

The contact has paused composing a message.

Channel_Chat_State_Composing = 4

The contact is composing a message to be sent to the chat.

org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting.DRAFT

This interface is experimental 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.Channel.Type.Text
• org.freedesktop.Telepathy.Channel.Interface.Messages

This interface extends the Text and Messages interfaces with improved sent-message status reporting.

This interface replaces Text.SendError, adding support for protocols where the message content is not echoed back to the sender on failure. It also adds support for receiving positive acknowledgements, and uses the Messages queue for state-recovery (ensuring that incoming delivery reports are not lost if there is not currently a process handling them).

If this interface and the Messages interface are both present, clients that support it SHOULD listen for the MessageReceived signal to get delivery reports, and ignore the SendError signal on the Text interface.

Delivery reports appear as messages of type Channel_Text_Message_Type_Delivery_Report in the Text and Messages interfaces. The message in the Text interface SHOULD have the Non_Text_Content flag.

Whenever a message of type Channel_Text_Message_Type_Delivery_Report is signalled for a delivery error report, Channel.Type.Text.SendError SHOULD also be emitted; whenever Channel.Type.Text.SendError is emitted by a channel which supports this interface, a message of type Channel_Text_Message_Type_Delivery_Report MUST also be emitted.

The corresponding message in the Messages interface MUST contain "headers" for the delivery report, as specified below, in its first Message_Part.

interface (s - DBus_Interface, as defined in the Messages interface)

MUST be the name of this interface.

message-sender (u - Contact_Handle, as defined in the Messages interface)

MUST be the intended recipient of the original message, if available (zero or omitted otherwise), even if the delivery report actually came from an intermediate server.

message-type (u - Channel_Text_Message_Type, as defined in the Messages interface)

MUST be Channel_Text_Message_Type_Delivery_Report.

delivery-status (u - Delivery_Status)

The status of the message. All delivery reports MUST contain this key in the first Message_Part.

delivery-token (s - Sent_Message_Token)

An identifier for the message to which this delivery report refers. MUST NOT be an empty string. Omitted if not available.

Clients may match this against the token produced by the SendMessage method and MessageSent signal on the Messages interface. A status report with no token could match any sent message, and a sent message with an empty token could match any status report. If multiple sent messages match, clients SHOULD use some reasonable heuristic.

In an ideal world, we could unambiguously match reports against messages; however, deployed protocols are not ideal, and not all reports and messages can be matched.

delivery-error (u - Channel_Text_Send_Error)

The reason for the failure. MUST be omitted if this was a successful delivery; SHOULD be omitted if it would be Channel_Text_Send_Error_Unknown.

delivery-echo (aa{sv} - Message_Part[])

The message content, as defined by the Messages interface. Omitted if no content is available. Content MAY have been truncated, message parts MAY have been removed, and message parts MAY have had their content removed (i.e. the message part metadata is present, but the 'content' key is not).

Some protocols, like XMPP, echo the failing message back to the sender. This is sometimes the only way to match it against the sent message, so we include it here.

Unlike in the Messages interface, content not visible in the value for this key cannot be retrieved by another means, so the connection manager SHOULD be more aggressive about including (possibly truncated) message content in the 'content' key.

The Messages interface needs to allow all content to be retrieved, but in this interface, the content we provide is merely a hint; so some is better than none, and it doesn't seem worth providing an API as complex as Messages' GetPendingMessageContent for the echoed message.

The second and subsequent Message_Part dictionaries, if present, are a human-readable report from the IM service.

It is an error for this interface to appear on channels of type other than Text, or on Text channels without the Messages interface. Clients MUST recover from this error by ignoring the presence of the DeliveryReporting interface.

Some example delivery reports in a Python-like syntax (in which arrays are indicated by [a, b] and dictionaries by {k1: v1, k2: v2}) follow.

A minimal delivery report indicating permanent failure of the sent message whose token was b9a991bd-8845-4d7f-a704-215186f43bb4 for an unknown reason

[{
# header
'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
'message-sender': 123,
'message-type': Channel_Text_Message_Type_Delivery_Report,
'delivery-status': Delivery_Status_Permanently_Failed,
'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
}
# no body
]

A delivery report where the failed message is echoed back to the sender rather than being referenced by ID, and the failure reason is that this protocol cannot send messages to offline contacts such as the contact with handle 123

[{ # header
'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
'message-sender': 123,
'message-type': Channel_Text_Message_Type_Delivery_Report,
'delivery-status': Delivery_Status_Temporarily_Failed,
'delivery-error': Channel_Text_Send_Error_Offline,
'delivery-echo':
    [{ # header of original message
    'message-sender': 1,
    'message-sent': 1210067943,
    },
    { # body of original message
    'type': 'text/plain',
    'content': 'Hello, world!',
    }]
  ],

# no body
]

A maximally complex delivery report: the server reports a bilingual human-readable failure message because the user sent a message "Hello, world!" with token b9a991bd-8845-4d7f-a704-215186f43bb4 to a contact with handle 123, but that handle represents a contact who does not actually exist

[{ # header
'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
'message-sender': 123,
'message-type': Channel_Text_Message_Type_Delivery_Report,
'delivery-status': Delivery_Status_Permanently_Failed,
'delivery-error': Channel_Text_Send_Error_Invalid_Contact,
'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
'delivery-echo':
    [{ # header of original message
    'message-sender': 1,
    'message-sent': 1210067943,
    },
    { # body of original message
    'type': 'text/plain',
    'content': 'Hello, world!',
    }]
  ],
},
{ # message from server (alternative in English)
'alternative': '404',
'type': 'text/plain',
'lang': 'en',
'content': 'I have no contact with that name',
},
{ # message from server (alternative in German)
'alternative': '404'.
'type': 'text/plain',
'lang': 'de',
'content', 'Ich habe keinen Kontakt mit diesem Namen',
}
]

A minimal delivery report indicating successful delivery of the sent message whose token was b9a991bd-8845-4d7f-a704-215186f43bb4

[{
# header
'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
'message-sender': 123,
'message-type': Channel_Text_Message_Type_Delivery_Report,
'delivery-status': Delivery_Status_Delivered,
'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
}
# no body
]

Added in version 0.17.5. (draft version, not API-stable)

Methods:

Interface has no signals.

Interface has no Telepathy properties.

D-Bus core Properties:

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

DeliveryReportingSupport − u (Delivery_Reporting_Support_Flags), read-only

A bitfield indicating features supported by this channel.

Enumerated types:

Delivery_Status

Delivery_Status_Unknown = 0

The message's disposition is unknown. Clients SHOULD consider all messages to have status Delivery_Status_Unknown unless otherwise specified; connection managers SHOULD NOT signal this delivery status explicitly.

Delivery_Status_Delivered = 1

The message has been delivered to the intended recipient.

Delivery_Status_Temporarily_Failed = 2

Delivery of the message has failed. Clients SHOULD notify the user, but MAY automatically try sending another copy of the message.

Similar to errors with type="wait" in XMPP; analogous to 4xx errors in SMTP.

Delivery_Status_Permanently_Failed = 3

Delivery of the message has failed. Clients SHOULD NOT try again unless by specific user action. If the user does not modify the message or alter configuration before re-sending, this error is likely to happen again.

Similar to errors with type="cancel", type="modify" or type="auth" in XMPP; analogous to 5xx errors in SMTP.

Sets of flags:

Delivery_Reporting_Support_Flags

Delivery_Reporting_Support_Flag_Receive_Failures = 1

Clients MAY expect to receive negative delivery reports if Message_Sending_Flag_Report_Delivery is specified when sending.

If senders want delivery reports, they should ask for them. If they don't want delivery reports, they can just ignore them, so there's no need to have capability discovery for what will happen if a delivery report isn't requested.

Delivery_Reporting_Support_Flag_Receive_Successes = 2

Clients MAY expect to receive positive delivery reports if Message_Sending_Flag_Report_Delivery is specified when sending.

Same rationale as Receive_Failures.

Delivery_Reporting_Support_Flag_Send_Failures = 4

Clients MAY expect that sending a negative delivery report will succeed, and will actually get a message to the sender.

Delivery_Reporting_Support_Flag_Send_Successes = 8

Clients MAY expect that sending a positive delivery report will succeed, and will actually get a message to the sender.

org.freedesktop.Telepathy.Channel.Interface.DTMF

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Channel.Type.StreamedMedia

Methods:

Interface has no signals.

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

Enumerated types:

DTMF_Event

DTMF_Event_Digit_0 = 0

0

DTMF_Event_Digit_1 = 1

1

DTMF_Event_Digit_2 = 2

2

DTMF_Event_Digit_3 = 3

3

DTMF_Event_Digit_4 = 4

4

DTMF_Event_Digit_5 = 5

5

DTMF_Event_Digit_6 = 6

6

DTMF_Event_Digit_7 = 7

7

DTMF_Event_Digit_8 = 8

8

DTMF_Event_Digit_9 = 9

9

DTMF_Event_Asterisk = 10

*

DTMF_Event_Hash = 11

#

DTMF_Event_Letter_A = 12

A

DTMF_Event_Letter_B = 13

B

DTMF_Event_Letter_C = 14

C

DTMF_Event_Letter_D = 15

D

org.freedesktop.Telepathy.Channel.Interface.Group

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Channel

Interface for channels which have multiple members, and where the members of the channel can change during its lifetime. Your presence in the channel cannot be presumed by the channel's existence (for example, a channel you may request membership of but your request may not be granted).

This interface implements three lists: a list of current members, and two lists of local pending and remote pending members. Contacts on the remote pending list have been invited to the channel, but the remote user has not accepted the invitation. Contacts on the local pending list have requested membership of the channel, but the local user of the framework must accept their request before they may join. A single contact should never appear on more than one of the three lists. The lists are empty when the channel is created, and the MembersChanged signal should be emitted when information is retrieved from the server, or changes occur.

Addition of members to the channel may be requested by using AddMembers. If remote acknowledgement is required, use of the AddMembers method will cause users to appear on the remote pending list. If no acknowledgement is required, AddMembers will add contacts to the member list directly. If a contact is awaiting authorisation on the local pending list, AddMembers will grant their membership request.

Removal of contacts from the channel may be requested by using RemoveMembers. If a contact is awaiting authorisation on the local pending list, RemoveMembers will refuse their membership request. If a contact is on the remote pending list but has not yet accepted the invitation, RemoveMembers will rescind the request if possible.

It should not be presumed that the requester of a channel implementing this interface is immediately granted membership, or indeed that they are a member at all, unless they appear in the list. They may, for instance, be placed into the remote pending list until a connection has been established or the request acknowledged remotely.

If the local user joins a Group channel whose members or other state cannot be discovered until the user joins (e.g. many chat room implementations), the connection manager should ensure that the channel is, as far as possible, in a consistent state before adding the local contact to the members set; until this happens, the local contact should be in the remote-pending set. For instance, if the connection manager queries the server to find out the initial members list for the channel, it should leave the local contact in the remote-pending set until it has finished receiving the initial members list.

If the protocol provides no reliable way to tell whether the complete initial members list has been received yet, the connection manager should make a best-effort attempt to wait for the full list (in the worst case, waiting for a suitable arbitrary timeout) rather than requiring user interfaces to do so on its behalf.

Methods:

Signals:

Interface has no Telepathy properties.

D-Bus core Properties:

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

GroupFlags − u (Channel_Group_Flags), read-only

An integer representing the bitwise-OR of flags on this channel. The user interface can use this to present information about which operations are currently valid. Change notification is via the GroupFlagsChanged signal.

Added in version 0.17.6. For backwards compatibility, clients should fall back to calling GetGroupFlags if Channel_Group_Flag_Properties is not present.

HandleOwners − a{uu} (Handle_Owner_Map), read-only

A map from channel-specific handles to their owners, including at least all of the channel-specific handles in this channel's members, local-pending or remote-pending sets as keys. Any handle not in the keys of this mapping is not channel-specific in this channel. Handles which are channel-specific, but for which the owner is unknown, MUST appear in this mapping with 0 as owner. Change notification is via the HandleOwnersChanged signal.

Added in version 0.17.6.

LocalPendingMembers − a(uuus) (Local_Pending_Info[]), read-only

An array of structs containing handles representing contacts requesting channel membership and awaiting local approval with AddMembers.

Added in version 0.17.6. If Channel_Group_Flag_Properties is not present, clients should fall back to using the deprecated GetLocalPendingMembersWithInfo method, or fall back from that to the deprecated GetAllMembers method.

Members − au (Contact_Handle[]), read-only

The members of this channel.

Added in version 0.17.6. If Channel_Group_Flag_Properties is not set, fall back to calling GetAllMembers.

RemotePendingMembers − au (Contact_Handle[]), read-only

An array of handles representing contacts who have been invited to the channel and are awaiting remote approval.

Added in version 0.17.6. If Channel_Group_Flag_Properties is not set, fall back to calling GetAllMembers.

SelfHandle − u (Contact_Handle), read-only

The handle for the user on this channel (which can also be a local or remote pending member), or 0 if the user is not a member at all (which is likely to be the case, for instance, on ContactList channels). Note that this is different from the connection GetSelfHandle on some protocols, so the value of this handle should always be used with the methods of this interface.

Added in version 0.17.6. For backwards compatibility, clients should fall back to calling GetSelfHandle if Channel_Group_Flag_Properties is not present.

Enumerated types:

Channel_Group_Change_Reason

Channel_Group_Change_Reason_None = 0

No reason was provided for this change.

Channel_Group_Change_Reason_Offline = 1

The change is due to a user going offline. Also used when user is already offline, but this wasn't known previously.

Channel_Group_Change_Reason_Kicked = 2

The change is due to a kick operation.

Channel_Group_Change_Reason_Busy = 3

The change is due to a busy indication.

Channel_Group_Change_Reason_Invited = 4

The change is due to an invitation.

Channel_Group_Change_Reason_Banned = 5

The change is due to a kick+ban operation.

Channel_Group_Change_Reason_Error = 6

The change is due to an error occurring.

Channel_Group_Change_Reason_Invalid_Contact = 7

The change is because the requested contact does not exist.

Channel_Group_Change_Reason_No_Answer = 8

The change is because the requested contact did not respond.

Channel_Group_Change_Reason_Renamed = 9

The change is because a contact's unique identifier changed. There must be exactly one handle in the removed set and exactly one handle in one of the added sets. The Renamed signal on the Renaming interface will have been emitted for the same handles, shortly before this MembersChanged signal is emitted.

Channel_Group_Change_Reason_Permission_Denied = 10

The change is because there was no permission to contact the requested handle.

Channel_Group_Change_Reason_Separated = 11

If members are removed with this reason code, the change is because the group has split into unconnected parts which can only communicate within themselves (e.g. netsplits on IRC use this reason code).

If members are added with this reason code, the change is because unconnected parts of the group have rejoined. If this channel carries messages (e.g. Text or Tubes channels) applications must assume that the contacts being added are likely to have missed some messages as a result of the separation, and that the contacts in the group are likely to have missed some messages from the contacts being added.

Note that from the added contacts' perspective, they have been in the group all along, and the contacts we indicate to be in the group (including the local user) have just rejoined the group with reason Separated. Application protocols in Tubes should be prepared to cope with this situation.

Sets of flags:

Channel_Group_Flags

Channel_Group_Flag_Can_Add = 1

The AddMembers method can be used to add or invite members who are not already in the local pending list (which is always valid).

Channel_Group_Flag_Can_Remove = 2

The RemoveMembers method can be used to remove channel members (removing those on the pending local list is always valid).

Channel_Group_Flag_Can_Rescind = 4

The RemoveMembers method can be used on people on the remote pending list.

Channel_Group_Flag_Message_Add = 8

A message may be sent to the server when calling AddMembers on contacts who are not currently pending members.

Channel_Group_Flag_Message_Remove = 16

A message may be sent to the server when calling RemoveMembers on contacts who are currently channel members.

Channel_Group_Flag_Message_Accept = 32

A message may be sent to the server when calling AddMembers on contacts who are locally pending.

Channel_Group_Flag_Message_Reject = 64

A message may be sent to the server when calling RemoveMembers on contacts who are locally pending.

Channel_Group_Flag_Message_Rescind = 128

A message may be sent to the server when calling RemoveMembers on contacts who are remote pending.

Channel_Group_Flag_Channel_Specific_Handles = 256

The members of this group have handles which are specific to this channel, and are not valid as general-purpose handles on the connection. Depending on the channel, it may be possible to call GetHandleOwners to find the owners of these handles, which should be done if you wish to eg subscribe to the contact's presence.

Connection managers must ensure that any given handle is not simultaneously a general-purpose handle and a channel-specific handle.

Channel_Group_Flag_Only_One_Group = 512

Placing a contact in multiple groups of this type is not allowed and will raise NotAvailable (on services where contacts may only be in one user-defined group, user-defined groups will have this flag).

Channel_Group_Flag_Handle_Owners_Not_Available = 1024

In rooms with channel specific handles (ie Channel_Specific_Handles flag is set), this flag indicates that no handle owners are available, apart from the owner of the SelfHandle.

This used to be an important optimization to avoid repeated GetHandleOwners calls, before we introduced the HandleOwner property and HandleOwnerChanged signal.

Channel_Group_Flag_Properties = 2048

This flag indicates that all the properties introduced in specification 0.17.6 are fully supported.

Structure types

Mapping types

org.freedesktop.Telepathy.Channel.Interface.Hold

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Channel.Type.StreamedMedia

Interface for channels where you may put the channel on hold. This only makes sense for channels where you are streaming media to or from the members.

If you place a channel on hold, this indicates that you do not wish to be sent media streams by any of its members and will be ignoring any media streams you continue to receive. It also requests that the connection manager free up any resources that are only needed for an actively used channel (e.g. in a GSM or PBX call, it will be necessary to place an active call on hold before you can start another call).

Changed in version 0.17.4: first API-stable version

Methods:

Signals:

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

Enumerated types:

Local_Hold_State

Local_Hold_State_Unheld = 0

All streams are unheld (the call is active). New channels SHOULD have this hold state.

Local_Hold_State_Held = 1

All streams are held (the call is on hold)

Local_Hold_State_Pending_Hold = 2

The connection manager is attempting to move to state Held, but has not yet completed that operation. It is unspecified whether any, all or none of the streams making up the channel are on hold.

Local_Hold_State_Pending_Unhold = 3

The connection manager is attempting to move to state Held, but has not yet completed that operation. It is unspecified whether any, all or none of the streams making up the channel are on hold.

Local_Hold_State_Reason

Local_Hold_State_Reason_None = 0

The reason cannot be described by any of the predefined values (connection managers SHOULD avoid this reason, but clients MUST handle it gracefully)

Local_Hold_State_Reason_Requested = 1

The change is in response to a user request

Local_Hold_State_Reason_Resource_Not_Available = 2

The change is because some resource was not available

org.freedesktop.Telepathy.Channel.Interface.HTML.DRAFT

This interface is unfinished 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.Channel.Type.Text
• org.freedesktop.Telepathy.Channel.Interface.Messages

This interface extends the Messages interface to support capability discovery, so clients can decide what subset of HTML is supported.

(However, the capability discovery mechanism has not been written yet, so this interface MUST NOT be used. It exists only to indicate what direction we intend to go in.)

If this interface is present, clients MAY send XHTML formatted text in message parts with type "text/html", and SHOULD interpret "text/html" message parts received in reply.

Client authors SHOULD pay careful attention to the security considerations in XEP-0071, "XHTML-IM", to avoid exposing client users to security risks. Clients MUST NOT assume that connection managers will filter messages to remove unsafe HTML.

To avoid misleading users, clients SHOULD only present UI for the subset of HTML that is indicated to be supported by this interface. It follows that clients SHOULD NOT send unsupported markup to the connection manager. However, even if the connection manager cannot send arbitrary XHTML, it MUST cope gracefully with being given arbitrary XHTML by a client.

Clients MUST NOT send HTML that is not well-formed XML, but connection managers MAY signal HTML that is malformed or invalid. Clients SHOULD attempt to parse messages as XHTML, but fall back to using a permissive "tag-soup" HTML parser if that fails. (FIXME: or should the presence of this interface imply that the CM fixes up "text/html" to be XHTML? In practice that would result in all the CMs having to link against libxml2 or something... the rationale above no longer applies here, since dropping a malformed message is "safe")

Added in version 0.17.5. (draft version, not API-stable)

Interface has no methods.

Interface has no signals.

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

org.freedesktop.Telepathy.Channel.Interface.Password

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Channel

Interface for channels that may have a password set that users need to provide before being able to join, or may be able to view or change once they have joined the channel.

The GetPasswordFlags method and the associated PasswordFlagsChanged signal indicate whether the channel has a password, whether the user must now provide it to join, and whether it can be viewed or changed by the user.

Methods:

Signals:

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

Sets of flags:

Channel_Password_Flags

Channel_Password_Flag_Provide = 8

The ProvidePassword method must be called now for the user to join the channel

org.freedesktop.Telepathy.Channel.Interface.MediaSignalling

Implementations of this interface must also implement:

• org.freedesktop.Telepathy.Channel
• org.freedesktop.Telepathy.Channel.Type.StreamedMedia

Methods:

Signals:

Telepathy Properties:

Accessed using the Telepathy Properties interface.

nat-traversal − s

A string indicating the NAT traversal techniques employed by the streams within this channel. Can be protocol-specific values, but the following values should be used if appropriate:

none

No attempt should be made at NAT traversal.

stun

If appropriate, a STUN request should be made to the given server to open a UDP port mapping and determine the external IP.

gtalk-p2p

Google Talk peer-to-peer connectivity establishment should be used, as implemented in libjingle 0.3.

stun-server − s

The IP address or hostname of the STUN server to use for NAT traversal.

stun-port − q

The UDP port number to use on the provided STUN server.

gtalk-p2p-relay-token − s

The authentication token for use with the Google Talk peer-to-peer relay server.

Interface has no D-Bus core properties.

Simple types

Structure types

org.freedesktop.Telepathy.Channel.Interface.Messages.DRAFT

This interface is experimental 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.Channel.Type.Text

This interface extends the Text interface to support more general messages, including:

• messages with attachments (like MIME multipart/mixed)
• groups of alternatives (like MIME multipart/alternative)
• delivery reports
• any extra types of message we need in future

It also provides a hook for improved sent message status notification, to be used by the DeliveryReporting interface.

Although this specification supports formatted (rich-text) messages with unformatted alternatives, implementations SHOULD NOT attempt to send formatted messages until the Telepathy specification has also been extended to cover capability discovery for message formatting.

If this interface is present, clients that support it SHOULD listen for the MessageSent and MessageReceived signals, and ignore the Sent and Received signal on the Text interface (which are guaranteed to duplicate signals from this interface).

Added in version 0.17.5. (draft version, not API-stable)

Methods:

Signals:

Interface has no Telepathy properties.

D-Bus core Properties:

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

SupportedContentTypes − as, read-only

A list of MIME types supported by this channel, with more preferred MIME types appearing earlier in the list. The list MAY include "*/*" to indicate that attachments with arbitrary MIME types can be sent. If the list is empty, this indicates that messages may only include a single "text/plain" part.

MessagePartSupportFlags − u (Message_Part_Support_Flags), read-only

Flags indicating the level of support for message parts on this channel.

PendingMessages − aaa{sv} (Message_Part[][]), read-only

A list of incoming messages that have neither been acknowledged nor rejected. This list is a superset of the one returned by ListPendingMessages on the Text interface; its items can be removed using AcknowledgePendingMessages on that interface.

Simple types

Sets of flags:

Message_Part_Support_Flags

Flags indicating the level of support for message parts on this channel. They are designed such that setting more flags always implies that the channel has more capabilities.

It is assumed that messages containing a textual message body (only), like the messages the Text interface was designed for, are always supported.

There is no flag indicating support for alternatives. This is because the SendMessage implementation can always accept messages containing alternatives, even if the underlying protocol does not, by deleting all alternatives except the first (most preferred) that is supported.

Message_Part_Support_Flag_Data_Only = 1

SendMessage will accept messages containing a single part of any type listed in the SupportedContentTypes property, with no accompanying text.

Message_Part_Support_Flag_One_Attachment = 2

SendMessage will accept messages containing a textual message body, plus a single attachment of any type listed in the SupportedContentTypes property. It does not make sense for this flag to be set if Message_Part_Support_Flag_Data_Only is not also set (because the connection manager can trivially provide an empty text part if necessary).

Message_Part_Support_Flag_Multiple_Attachments = 4

SendMessage will accept messages containing a textual message body, plus an arbitrary number of attachments of any type listed in the SupportedContentTypes property. It does not make sense for this flag to be set if Message_Part_Support_Flag_One_Attachment is not also set.

Message_Sending_Flags

Message_Sending_Flag_Report_Delivery = 1

Provide a delivery report via the DeliveryReporting interface, if possible, even if this is not the default for this protocol. Ignored if delivery reports are not possible on this protocol.

In some protocols, like XMPP, it is not conventional to request or send delivery notifications.

Mapping types

[
  {
    'message-sender': 42,
    'message-sent': 1210067943,
    'message-received': 1210067947,
    'message-type': 0,
    'pending-message-id': 437,
  },
  { 'alternative': 'main',
    'type': 'text/html',
    'content': 'Here is a photo of my cat:<br />' +
               '<img src="cid:catphoto" alt="lol!" />' +
               '<br />Isn't it cute?',
  },
  { 'alternative': 'main',
    'type': 'text/plain',
    'content': 'Here is a photo of my cat:\n[IMG: lol!]\nIsn't it cute?',
  },
  { 'identifier': 'catphoto',
    'type': 'image/jpeg',
    'size': 101000,
    'needs-retrieval': True,
  },
]
          

org.freedesktop.Telepathy.Media.SessionHandler

Methods:

Signals:

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

org.freedesktop.Telepathy.Media.StreamHandler

Methods:

Signals:

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

Enumerated types:

Media_Stream_Error

Media_Stream_Error_Unknown = 0

An unknown error occured.

Media_Stream_Error_EOS = 1

The end of the stream was reached.

Media_Stream_Base_Proto

Media_Stream_Base_Proto_UDP = 0

UDP (User Datagram Protocol)

Media_Stream_Base_Proto_TCP = 1

TCP (Transmission Control Protocol)

Media_Stream_Transport_Type

Media_Stream_Transport_Type_Local = 0

A local address

Media_Stream_Transport_Type_Derived = 1

An external address derived by a method such as STUN

Media_Stream_Transport_Type_Relay = 2

An external stream relay

Structure types

org.freedesktop.Telepathy.Properties

Interface for channels and other objects, to allow querying and setting properties. ListProperties returns which properties are valid for the given channel, including their type, and an integer handle used to refer to them in GetProperties, SetProperties, and the PropertiesChanged signal. The values are represented by D-Bus variant types, and are accompanied by flags indicating whether or not the property is readable or writable.

Each property also has a flags value to indicate what methods are available. This is a bitwise OR of PropertyFlags values.

Methods:

Signals:

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

Simple types

Sets of flags:

Property_Flags

Property_Flag_Read = 1

The property can be read

Property_Flag_Write = 2

The property can be written

Structure types

org.freedesktop.Telepathy.AccountManager

The account manager is a central service used to store account details.

The current account manager is defined to be the process that owns the well-known bus name org.freedesktop.Telepathy.AccountManager on the session bus. This process must export an /org/freedesktop/Telepathy/AccountManager object with the AccountManager interface.

Added in version 0.17.2.

Methods:

Signals:

Interface has no Telepathy properties.

D-Bus core Properties:

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

Interfaces − as, read-only

A list of the interfaces provided by the account manager object.

ValidAccounts − ao, read-only

A list of the valid (complete, usable) accounts. Change notification is via AccountValidityChanged.

This split between valid and invalid accounts makes it easy to ignore the invalid ones. The only things that should be manipulating invalid accounts are account-editing UIs, which might be able to rescue them.

InvalidAccounts − ao, read-only

A list of incomplete or otherwise unusable accounts. Change notification is via AccountValidityChanged.

org.freedesktop.Telepathy.Account

An Account object encapsulates the necessary details to make a Telepathy connection.

Accounts are uniquely identified by object path. The object path of an Account MUST take the form /org/freedesktop/Telepathy/Account/cm/proto/acct, where:

• cm is the same Connection_Manager_Name that appears in the connection manager's well-known bus name and object path
• proto is the Protocol name as seen in ConnectionManager.ListProtocols, but with "-" replaced with "_" (i.e. the same as in the object-path of a Connection)
• acct is an arbitrary string of ASCII letters, digits and underscores, starting with a letter or underscore, which uniquely identifies this account
• Clients SHOULD parse the object path to discover the connection manager and protocol
• Clients MUST NOT attempt to parse acct
• Clients MUST NOT assume that acct matches the connection-specific part of a Connection's object-path and bus name
• The account manager SHOULD choose acct such that if an account is deleted, its object path will be re-used if and only if the new account is in some sense "the same" (incorporating the 'account' parameter in some way is recommended)

Added in version 0.17.2.

Changed in version 0.17.6: moved the Avatar property to a separate interface

Methods:

Signals:

Interface has no Telepathy properties.

D-Bus core Properties:

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

Interfaces − as, read-only

A list of the extra interfaces provided by this account.

DisplayName − s, read/write

The user-visible name of this account. This SHOULD be chosen by the user at account creation time. The account creation user interface is responsible for setting a reasonable default value in the user's locale; something like "Jabber (bob@example.com)" would be sensible.

This approximately corresponds to "display name" in NMC 4.x and Decibel.

Icon − s, read/write

The name of an icon in the system's icon theme, such as "im-msn", or the empty string to not specify an icon. If the icon is set to an empty string, the account manager or any client MAY derive a default icon, for instance from the protocol.

This approximately corresponds to mc_profile_get_icon_name (or possibly mc_profile_get_branding_icon_name) in NMC 4.x. It's accessed via the account rather than the profile because we no longer have profiles as a core concept.

Valid − b, read-only

If true, this account is considered by the account manager to be complete and usable. If false, user action is required to make it usable, and it will never attempt to connect (for instance, this might be caused by the absence of a required parameter).

For connection managers with a plugin architecture, like telepathy-haze, we have little or no control over the parameters offered; for platforms with package management, we have little or no control over the CMs offered. NMC 4.x would just pretend the account didn't exist in these circumstances, but silent data loss is bad, and UIs with CM-specific knowledge (or a user filling in newly-required parameters) might be able to rescue a broken account.

Enabled − b, read/write

This property gives the users the possibility to prevent an account from being used. This flag does not change the validity of the account.

A disabled account can never be put online.

Use cases:

• user has two or more accounts capable of calling contact X, but he doesn't want the UI to prompt him everytime about which one he wants to use for the call. He can then disable all the equivalent accounts but one.
• There is some temporary server error and the user doesn't want to be be bother by error messages, or change the account configuration: temporarily disabling the account is quicker.

The AccountManager SHOULD allow this property to be set on invalid accounts, but MUST NOT attempt to put invalid accounts online even if they become Enabled.

There doesn't seem to be any good reason not to allow this.

Nickname − as, read/write

The nickname to set on this account for display to other contacts, as set by the user. When the account becomes connected, the account manager SHOULD set this as the user's alias using SetAliases if appropriate.

In a later specification revision, we plan to separate the concepts of a contact's nickname as set by themselves, and the local name for them in our contact list (a "handle" or "pet name" as described in XEP-0165 and its references). The terminology change from alias to nickname here is a step in that direction. This corresponds to NMC 4.x mc_account_get_alias.

Parameters − a{sv}, read-only

A map from connection manager parameter names (as in the ConnectionManager interface) to their values. This property includes only those parameters that are stored for this account, and SHOULD only include those parameters that the user has explicitly set.

This property cannot be altered using Set() - use UpdateParameters instead.

This avoids NMC being tied to gconf as a matter of API.

AutomaticPresence − (uss) (Simple_Presence), read/write

The presence status that this account should have if it is brought online.

Setting this property MUST NOT actually change the account's status until the next time it is (re)connected for some reason.

The Connection_Presence_Type in the structure SHOULD NOT be Offline or Unset.

In ITOS2007 and ITOS2008 this is a global preference, not visible on D-Bus (the "default presence"). "Automatic presence" better describes when it is used.

ConnectAutomatically − b, read/write

If true, the account manager SHOULD attempt to put this account online with the AutomaticPresence whenever possible (in the base Account interface this is deliberately left vague). If false, it MUST NOT put the account online automatically in response to, for instance, connectivity changes, but SHOULD still put the account online with the AutomaticPresence if requested by the user (for instance, if the user tries to start a conversation using this account).

This approximately corresponds to NMC 4.x "enabled" and Decibel "autoreconnect".

Connection − s, read-only

Either the well-known bus name of the connection to this account, or the empty string if there is no connection.

ConnectionStatus − u, read-only

If the Connection property is non-empty, the status of that connection. If the Connection property is the empty string, this property may either be Disconnected (indicating that the account manager is not attempting to bring it online), or Connecting (indicating that the account manager is attempting to connect). The account manager is expected to set this by observing signals from the Connection.

If the AM is doing some sort of backoff/delay on reconnection attempts, the account's status is conceptually "Connecting" even though there is no Connection. This vaguely corresponds to GetCurrentStatus in NMC 4.x.

ConnectionStatusReason − u, read-only

The reason for the last change to ConnectionStatus. The account manager is expected to set this by observing signals from the Connection.

If you weren't watching the Connection at the time it failed, you can't tell why - unless the AM can tell you. This is part of GetCurrentStatus in NMC 4.x.

CurrentPresence − (uss) (Simple_Presence), read-only

The actual presence. If the connection is not online, this should be (Connection_Presence_Type_Offline, "", ""). If the connection is online but does not support the Presence interface, this should be (Connection_Presence_Type_Unset, "", ""). The account manager is expected to set this by observing signals from the Connection.

This corresponds to GetPresenceActual in NMC 4.x.

RequestedPresence − (uss) (Simple_Presence), read/write

The requested presence for this account. When this is changed, the account manager should attempt to manipulate the connection manager to make CurrentPresence match RequestedPresence as closely as possible. It should not be saved to any sort of persistent storage.

When the account manager automatically connects an account, it must signal this by setting the RequestedPresence to the same thing as the AutomaticPresence.

This corresponds to e.g. GetPresence and GetPresenceMessage in NMC 4.x.

NormalizedName − s, read-only

The normalized user ID of the local user on this account (i.e. the string returned when the InspectHandle method is called on the result of GetSelfHandle() for an active connection).

It is unspecified whether this user ID is globally unique.

As currently implemented, IRC user IDs are only unique within the same IRCnet. On some saner protocols, the user ID includes a DNS name which provides global uniqueness.

If this value is not known yet (which will always be the case for accounts that have never been online), it will be an empty string.

It is possible that this value will change if the connection manager's normalization algorithm changes, although this SHOULD be avoided.

It's not always completely clear what normalization algorithm should be used; for instance, in Gabble, we currently use JIDs, but it would also have been reasonable to use xmpp URIs.

org.freedesktop.Telepathy.ChannelHandler

An interface exported by client applications which are able to handle incoming channels.

Added in version 0.17.0.

Methods:

Interface has no signals.

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

Generic types

Simple types

Mapping types

Errors

org.freedesktop.Telepathy.Error.NetworkError

org.freedesktop.Telepathy.Error.NotImplemented

org.freedesktop.Telepathy.Error.InvalidArgument

org.freedesktop.Telepathy.Error.NotAvailable

org.freedesktop.Telepathy.Error.PermissionDenied

org.freedesktop.Telepathy.Error.Disconnected

org.freedesktop.Telepathy.Error.InvalidHandle

org.freedesktop.Telepathy.Error.Channel.Banned

org.freedesktop.Telepathy.Error.Channel.Full

org.freedesktop.Telepathy.Error.Channel.InviteOnly

Index

Index of 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.Contacts
• org.freedesktop.Telepathy.Connection.Interface.SimplePresence
• org.freedesktop.Telepathy.Connection.Interface.Presence
• org.freedesktop.Telepathy.Connection.Interface.Renaming
• org.freedesktop.Telepathy.Connection.Interface.Requests.DRAFT
• org.freedesktop.Telepathy.ChannelBundle.DRAFT
• 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

Index of types

• Alias_Map − a{ u → s }
• Alias_Pair − ( u, s )
• Avatar_Token_Map − a{ u → s }
• Capability_Change − ( u, s, u, u, u, u )
• Capability_Pair − ( s, u )
• Channel_Call_State_Flags − u
• Channel_Call_State_Map − a{ u → u }
• Channel_Chat_State − u
• Channel_Class − a{ s → v }
• Channel_Details − ( o, a{sv} )
• Channel_Group_Change_Reason − u
• Channel_Group_Flags − u
• Channel_Info − ( o, s, u, u )
• Channel_Media_Capabilities − u
• Channel_Password_Flags − u
• Channel_Text_Message_Flags − u
• Channel_Text_Message_Type − u
• Channel_Text_Send_Error − u
• Conn_Mgr_Param_Flags − u
• Connection_Alias_Flags − u
• Connection_Capability_Flags − u
• Connection_Manager_Name − s
• Connection_Presence_Type − u
• Connection_Status − u
• Connection_Status_Reason − u
• Contact_Attribute − s
• Contact_Attributes_Map − a{ u → a{sv} }
• Contact_Capability − ( u, s, u, u )
• Contact_Handle − u
• Contact_Presences − a{ u → (ua{sa{sv}}) }
• DBus_Bus_Name − s
• DBus_Interface − s
• DBus_Member − s
• DBus_Qualified_Member − s
• DBus_Signature − s
• DBus_Tube_Member − ( u, s )
• DBus_Unique_Name − s
• DTMF_Event − y
• Delivery_Reporting_Support_Flags − u
• Delivery_Status − u
• Group_Handle − u
• Handle − u
• Handle_Owner_Map − a{ u → u }
• Handle_Type − u
• Last_Activity_And_Statuses − ( u, a{sa{sv}} )
• List_Handle − u
• Local_Hold_State − u
• Local_Hold_State_Reason − u
• Local_Pending_Info − ( u, u, u, s )
• Media_Session_Handler_Info − ( o, s )
• Media_Session_Type − s
• Media_Stream_Base_Proto − u
• Media_Stream_Direction − u
• Media_Stream_Error − u
• Media_Stream_Handler_Candidate − ( s, a(usuussduss) )
• Media_Stream_Handler_Codec − ( u, s, u, u, u, a{ss} )
• Media_Stream_Handler_Transport − ( u, s, u, u, s, s, d, u, s, s )
• Media_Stream_Info − ( u, u, u, u, u, u )
• Media_Stream_Pending_Send − u
• Media_Stream_State − u
• Media_Stream_Transport_Type − u
• Media_Stream_Type − u
• Message_ID − u
• Message_Part − a{ s → v }
• Message_Part_Support_Flags − u
• Message_Sending_Flags − u
• Multiple_Status_Map − a{ s → a{sv} }
• Param_Spec − ( s, u, s, v )
• Pending_Text_Message − ( u, u, u, u, u, s )
• Property_Flags − u
• Property_Flags_Change − ( u, u )
• Property_ID − u
• Property_Spec − ( u, s, s, u )
• Property_Value − ( u, v )
• Protocol − s
• Qualified_Property_Value_Map − a{ s → v }
• Requestable_Channel_Class − ( a{sv}, as )
• Room_Handle − u
• Room_Info − ( u, s, a{sv} )
• Sent_Message_Token − s
• Simple_Contact_Presences − a{ u → (uss) }
• Simple_Presence − ( u, s, s )
• Simple_Status_Spec − ( u, b, b )
• Simple_Status_Spec_Map − a{ s → (ubb) }
• Single_Contact_Attributes_Map − a{ s → v }
• Socket_Access_Control − u
• Socket_Address_IPv4 − ( s, q )
• Socket_Address_IPv6 − ( s, q )
• Socket_Address_Type − u
• Socket_Netmask_IPv4 − ( s, y )
• Socket_Netmask_IPv6 − ( s, y )
• Status_Spec − ( u, b, b, a{ss} )
• Status_Spec_Map − a{ s → (ubba{ss}) }
• Stream_ID − u
• String_String_Map − a{ s → s }
• String_Variant_Map − a{ s → v }
• Supported_Socket_Map − a{ u → au }
• Tube_ID − u
• Tube_Info − ( u, u, u, s, a{sv}, u )
• Tube_State − u
• Tube_Type − u
• Unix_Timestamp − u