Telepathy D-Bus Interface Specification version 0.17.25

# Telepathy D-Bus Interface Specification

## Version 0.17.25

Copyright © 2005-2009 Collabora Limited
Copyright © 2005-2009 Nokia Corporation
Copyright © 2006 INdT

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

## 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.ContactCapabilities.DRAFT`
- `org.freedesktop.Telepathy.Connection.Interface.ContactInfo.DRAFT`
- `org.freedesktop.Telepathy.Connection.Interface.Contacts`
- `org.freedesktop.Telepathy.Connection.Interface.Location.DRAFT`
- `org.freedesktop.Telepathy.Connection.Interface.Presence`
- `org.freedesktop.Telepathy.Connection.Interface.Renaming`
- `org.freedesktop.Telepathy.Connection.Interface.Requests`
- `org.freedesktop.Telepathy.Connection.Interface.SimplePresence`
- `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.StreamedMedia.FUTURE`
- `org.freedesktop.Telepathy.Channel.Type.RoomList`
- `org.freedesktop.Telepathy.Channel.Type.Text`
- `org.freedesktop.Telepathy.Channel.Type.Tubes`
- `org.freedesktop.Telepathy.Channel.Type.StreamTube`
- `org.freedesktop.Telepathy.Channel.Type.DBusTube`
- `org.freedesktop.Telepathy.Channel.Type.FileTransfer`
- `org.freedesktop.Telepathy.Channel.Type.ContactSearch.DRAFT`
- `org.freedesktop.Telepathy.Channel.Interface.CallMerging`
- `org.freedesktop.Telepathy.Channel.Interface.CallState`
- `org.freedesktop.Telepathy.Channel.Interface.ChatState`
- `org.freedesktop.Telepathy.Channel.Interface.Destroyable`
- `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.MediaSignalling.FUTURE`
- `org.freedesktop.Telepathy.Channel.Interface.Messages`
- `org.freedesktop.Telepathy.Channel.Interface.Tube`
- `org.freedesktop.Telepathy.Media.SessionHandler`
- `org.freedesktop.Telepathy.Media.StreamHandler`
- `org.freedesktop.Telepathy.Debug.DRAFT`
- `org.freedesktop.Telepathy.AccountManager`
- `org.freedesktop.Telepathy.Account`
- `org.freedesktop.Telepathy.Account.Interface.Avatar`
- `org.freedesktop.Telepathy.ChannelDispatcher`
- `org.freedesktop.Telepathy.ChannelDispatcher.Interface.OperationList`
- `org.freedesktop.Telepathy.ChannelDispatchOperation`
- `org.freedesktop.Telepathy.ChannelRequest`
- `org.freedesktop.Telepathy.Client`
- `org.freedesktop.Telepathy.Client.Observer`
- `org.freedesktop.Telepathy.Client.Approver`
- `org.freedesktop.Telepathy.Client.Handler`
- `org.freedesktop.Telepathy.Client.Interface.Requests`
- `org.freedesktop.Telepathy.ChannelHandler`
- `org.freedesktop.Telepathy.Properties`

# 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
- `dbus-property`, corresponding to Conn_Mgr_Param_Flag_DBus_Property

The group may also contain a key `default-p` whose value is a string form of the default value for the parameter. If this key exists, it sets the default, and also sets the flag Conn_Mgr_Param_Flag_Has_Default. The default value is formatted according to the D-Bus signature as follows:

s (string)
  The UTF-8 string, with the standard backslash escape sequences supported by the Desktop Entry Specification (the "localestring" type from the Desktop Entry Specification)
o (object path)
  The object path as an ASCII string
b (boolean)
  "true" (case-insensitively) or "1" means True, "false" (case-insensitively) or "0" means False
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
as (array of string)
  A sequence of UTF-8 strings each followed by a semicolon, with any semicolons they contain escaped with a backslash (the "localestrings" type from the Desktop Entry Specification)

Currently, no other D-Bus signatures are allowed to have default values, but clients parsing the .manager file MUST ignore defaults that they cannot parse, and treat them as if the `default-p` key was not present at all.

It is not required that a connection manager be able to support multiple protocols, or even multiple connections. When a connection is made, a service name where the connection object can be found is returned. A manager which can only make one connection may then remove itself from its well-known bus name, causing a new connection manager to be activated when somebody attempts to make a new connection.

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

Changed in version 0.17.16: Prior to version 0.17.16 the serialization of string arrays (signature 'as') was not defined

## Methods:

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

Get a list of the parameters which must or may be provided to the RequestConnection method when connecting to the given protocol, or registering (the boolean "register" parameter is available, and set to true).

#### Parameters

`Protocol` − `s` (Protocol)
  The required protocol name

#### Returns

`Parameters` − `a(susv)` (Param_Spec[])
  An array of structs representing possible parameters.

#### Possible errors

`org.freedesktop.Telepathy.Error.NotImplemented`
  Raised when the requested method, channel, etc is not available on this connection. (generic description)

### ListProtocols ( ) → as

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

#### Returns

`Protocols` − `as` (Protocol[])
  A array of string protocol identifiers supported by this manager

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

Request a Connection object representing a given account on a given protocol with the given parameters. The method returns the bus name and the object path where the new Connection object can be found, which should have the status of Connection_Status_Disconnected, to allow signal handlers to be attached before connecting is started with the Connect method.

The parameters which must and may be provided in the parameters dictionary can be discovered with the GetParameters method. These parameters, their types, and their default values may be cached in files so that all available connection managers do not need to be started to discover which protocols are available.

To request values for these parameters from the user, a client must have prior knowledge of the meaning of the parameter names, so the following well-known names and types should be used where appropriate:

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

Every successful RequestConnection call will cause the emission of a NewConnection signal for the same newly created connection. The requester can use the returned object path and service name independently of the emission of that signal. In that case this signal emission is most useful for, e.g. other processes that are monitoring the creation of new connections.

#### Parameters

`Protocol` − `s` (Protocol)
  The protocol identifier
`Parameters` − `a{sv}` (String_Variant_Map)
  A dictionary mapping parameter names to values of the appropriate type, as indicated by GetParameters and the above well-known list.

#### Returns

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

#### Possible errors

`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.NotImplemented`
  Raised when the requested method, channel, etc is not available on this connection. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  Raised when one of the provided arguments is invalid. (generic description)

## Signals:

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

Emitted when a new Connection object is created.

#### Parameters

`Bus_Name` − `s` (DBus_Bus_Name)
  The D-Bus service where the connection object can be found
`Object_Path` − `o`
  The object path of the Connection object on this service
`Protocol` − `s` (Protocol)
  The identifier for the protocol this connection uses

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

### Connection_Manager_Name − s

The name of a connection manager, found in its well-known bus name and object path. This must be a non-empty string of ASCII letters, digits and underscores, starting with a letter. This is typically the name of the executable with any "telepathy-" prefix removed, and any hyphen/minus signs replaced by underscores.

Connection manager names SHOULD NOT be the same as the name of the protocol they implement.

This is likely to lead to conflicts between different implementations of the same protocol (or indeed inability to distinguish between the different implementations!). The Telepathy project traditionally uses some sort of pun (Haze is based on libpurple, Salut implements a protocol often called Bonjour, and Wilde implements the OSCAR protocol).

Connection manager names SHOULD NOT be the same as the name of a library on which they are based.

We often abbreviate, for instance, telepathy-haze as "Haze", but abbreviating telepathy-sofiasip to "Sofia-SIP" would cause confusion between the connection manager and the library it uses. Please don't repeat that mistake.

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

### Protocol − s

An instant messaging protocol. It must consist only of ASCII letters, digits and hyphen/minus signs (U+002D "-"), and must start with a letter. Where possible, this SHOULD be chosen from the following well-known values:

- aim - AOL Instant Messenger (OSCAR or TOC)
- gadugadu - Gadu-Gadu
- groupwise - Novell Groupwise
- icq - ICQ (OSCAR)
- irc - Internet Relay Chat (RFC 1459, 2810-2813)
- jabber - XMPP (RFC 3920, 3921) or Jabber
- local-xmpp - Link-local XMPP (XEP-0174) (Bonjour, Salut)
- msn - MSNP (Windows Live Messenger)
- myspace - MySpaceIM
- napster - Napster
- qq - Tencent QQ
- sametime - IBM Lotus Sametime
- silc - SILC
- sip - Session Initiation Protocol (SIP)
- trepia - Trepia
- yahoo - YMSG (Yahoo! Messenger)
- zephyr - Zephyr

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

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

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

  Added in version 0.17.16.

## Structure types

### Param_Spec − ( s: Name, u: Flags, s: Signature, v: Default_Value )

A struct representing an allowed parameter, as returned by GetParameters on the ConnectionManager interface.

In bindings that need a separate name, arrays of Param_Spec should be called Param_Spec_List.

#### Members

`Name` − `s`
  A string parameter name
`Flags` − `u` (Conn_Mgr_Param_Flags)
  A bitwise OR of the parameter flags
`Signature` − `s` (DBus_Signature)
  A string containing the D-Bus type signature for this parameter
`Default_Value` − `v`
  The default value (if the Has_Default flag is not present, there is no default and this takes some dummy value, which SHOULD be of the appropriate D-Bus type)

# org.freedesktop.Telepathy.Connection

Implementations of this interface must also implement:

- `org.freedesktop.Telepathy.Connection.Interface.Requests`
- `org.freedesktop.Telepathy.Connection.Interface.Contacts`

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.

In order to allow Connection objects to be discovered by new clients, the object path and well-known bus name MUST be of the form `/org/freedesktop/Telepathy/Connection/cmname/proto/account` and `org.freedesktop.Telepathy.Connection.cmname.proto.account` where:

- cmname is the same Connection_Manager_Name that appears in the connection manager's object path and well-known bus name
- proto is the Protocol name as seen in ListProtocols, but with "-" replaced with "_" to get a valid object path/bus name
- account is some non-empty sequence of ASCII letters, digits and underscores not starting with a digit

account SHOULD be formed such that any valid distinct connection instance on this protocol has a distinct name. This might be formed by including the server name followed by the user name (escaped via some suitable mechanism like telepathy-glib's tp_escape_as_identifier() function to preserve uniqueness); on protocols where connecting multiple times is permissable, a per-connection identifier might be necessary to ensure uniqueness.

Clients MAY parse the object path to determine the connection manager name and the protocol, but MUST NOT attempt to parse the account part. Connection managers MAY use any unique string for this part.

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

Changed in version 0.17.10: Previously, the account part of Connection bus names/object paths was allowed to have more than one component (i.e. contain dots or slashes), resulting in Connection bus names and object paths with more than 7 components. We now restrict Connection bus names/object paths to have exactly 7 components.

Changed in version 0.17.23: The Requests and Contacts interfaces are now mandatory. Their functionality will be merged into the main Connection interface at some point in future.

## Methods:

### Connect ( ) → nothing

Request that the connection be established. This will be done asynchronously and errors will be returned by emitting StatusChanged signals.

Calling this method on a Connection that is already connecting or connected is allowed, and has no effect.

### Disconnect ( ) → nothing

Request that the connection be closed. This closes the connection if it's not already in DISCONNECTED state, and destroys the connection object.

### GetInterfaces ( ) → as

Get the optional interfaces supported by this connection. Before the connection status changes to CONNECTED, the return from this method may change at any time, but it is guaranteed that interfaces will only be added, not removed. After the connection status changes to CONNECTED, the return from this method cannot change further.

There is no explicit change notification; reasonable behaviour for a client would be to retrieve the interfaces list once initially, and once more when it becomes CONNECTED.

In some connection managers, certain capabilities of a connection are known to be implemented for all connections (e.g. support for SimplePresence), and some interfaces (like SimplePresence) can even be used before connecting. Other capabilities may or may not exist, depending on server functionality; by the time the connection goes CONNECTED, the connection manager is expected to have evaluated the server's functionality and enabled any extra interfaces for the remainder of the Connection's lifetime.

#### Returns

`Interfaces` − `as` (DBus_Interface[])
  An array of D-Bus interface names

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  Before version 0.17.8 calling GetInterfaces while on a connection that is not yet CONNECTED wasn't allowed. If a CM returns this error, its list of interfaces should be regarded as empty until it becomes CONNECTED.

### GetProtocol ( ) → s

Get the protocol this connection is using.

#### Returns

`Protocol` − `s` (Protocol)
  A string identifier for the protocol

### GetSelfHandle ( ) → u

Returns the value of the SelfHandle property. Change notification is via the SelfHandleChanged signal.

Deprecated since version 0.17.10. Use GetAll to get the SelfHandle property (and all other Connection properties) instead.

#### Returns

`Self_Handle` − `u` (Contact_Handle)
  The value of the SelfHandle property

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)

### GetStatus ( ) → u

Get the current status as defined in the StatusChanged signal.

#### Returns

`Status` − `u` (Connection_Status)
  An integer representing the current status

### HoldHandles ( u: Handle_Type, au: Handles ) → nothing

Notify the connection manger that your client is holding a copy of handles which may not be in use in any existing channel or list, and were not obtained by using the RequestHandles method. For example, a handle observed in an emitted signal, or displayed somewhere in the UI that is not associated with a channel. The connection manager must not deallocate a handle where any clients have used this method to indicate it is in use until the ReleaseHandles method is called, or the clients disappear from the bus.

Note that HoldHandles is idempotent - calling it multiple times is equivalent to calling it once. If a handle is "referenced" by several components which share a D-Bus unique name, the client should perform reference counting internally, and only call ReleaseHandles when none of the cooperating components need the handle any longer.

#### Parameters

`Handle_Type` − `u` (Handle_Type)
  The type of handle to be held
`Handles` − `au` (Handle[])
  A array of integer handles to hold

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  Raised when one of the provided arguments is invalid. (generic description)
`org.freedesktop.Telepathy.Error.InvalidHandle`
  The contact name specified is unknown on this channel or connection. (generic description)

### InspectHandles ( u: Handle_Type, au: Handles ) → as

Return a string representation for a number of handles of a given type.

#### Parameters

`Handle_Type` − `u` (Handle_Type)
  The type of handle to be inspected
`Handles` − `au` (Handle[])
  An array of integer handles of this type

#### Returns

`Identifiers` − `as`
  An array of handle names in the same order as the given numbers

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  Raised when one of the provided arguments is invalid. (generic description)
`org.freedesktop.Telepathy.Error.InvalidHandle`
  The contact name specified is unknown on this channel or connection. (generic description)

### ListChannels ( ) → a(osuu)

List all the channels which currently exist on this connection.

Deprecated since version 0.17.23. Use the Requests.Channels property instead.

#### Returns

`Channel_Info` − `a(osuu)` (Channel_Info[])
  An array of structs representing channels.

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)

### ReleaseHandles ( u: Handle_Type, au: Handles ) → nothing

Explicitly notify the connection manager that your client is no longer holding any references to the given handles, and that they may be deallocated if they are not held by any other clients or referenced by any existing channels. See HoldHandles for notes.

#### Parameters

`Handle_Type` − `u` (Handle_Type)
  An integer handle type (as defined in RequestHandle)
`Handles` − `au` (Handle[])
  An array of integer handles being held by the client

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  The handle type is invalid
`org.freedesktop.Telepathy.Error.InvalidHandle`
  One of the given handles is not valid
`org.freedesktop.Telepathy.Error.NotAvailable`
  One of the given handles is not held by this client

### RequestChannel ( s: Type, u: Handle_Type, u: Handle, b: Suppress_Handler ) → o

Request a channel satisfying the specified type and communicating with the contact, room, list etc. indicated by the given handle_type and handle. The handle_type and handle may both be zero to request the creation of a new, empty channel, which may or may not be possible, depending on the protocol and channel type.

On success, the returned channel will always be of the requested type (i.e. implement the requested channel-type interface).

If a new, empty channel is requested, on success the returned channel will always be an "anonymous" channel for which the type and handle are both zero.

If a channel to a contact, room etc. is requested, on success, the returned channel may either be a new or existing channel to the requested entity (i.e. its TargetHandleType and TargetHandle properties are the requested handle type and handle), or a newly created "anonymous" channel associated with the requested handle in some implementation-specific way.

For example, for a contact handle, the returned channel might be "anonymous", but implement the groups interface and have the requested contact already present among the members.

If the request cannot be satisfied, an error is raised and no channel is created.

Deprecated since version 0.17.23. Use Requests.CreateChannel or Requests.EnsureChannel instead. Connection managers MAY implement RequestChannel by raising NotImplemented, or implement fewer types of channel via this API.

#### Parameters

`Type` − `s` (DBus_Interface)
  A D-Bus interface name representing base channel type
`Handle_Type` − `u` (Handle_Type)
  An integer representing the handle type, or Handle_Type_None if no handle is specified
`Handle` − `u` (Handle)
  A nonzero integer handle representing a contact, room, list etc. according to handle_type, or zero if the handle_type is Handle_Type_None
`Suppress_Handler` − `b`
  Clients SHOULD always set this to true.
  The historical meaning was that clients that did not intend to take responsibility for displaying the channel to the user could set this to FALSE, in which case the channel dispatcher would launch an appropriate channel handler. However, clients whose functionality relies on having a working channel dispatcher should obtain that functionality by calling methods on the channel dispatcher, so that they will get an appropriate error if the channel dispatcher is missing or not working. The channel dispatcher itself should set this to true too, so that it will ignore the NewChannel signal that results from the creation of the channel. It can then dispatch the channel returned from this method to an appropriate handler. So, there is no sensible use-case for setting this to false, and setting it to false can result in unhandled channels (in the case where clients assume that a channel dispatcher is present, but it isn't).

#### Returns

`Object_Path` − `o`
  The D-Bus object path for the channel created or retrieved

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.NotImplemented`
  Unknown channel type
`org.freedesktop.Telepathy.Error.InvalidHandle`
  The given handle does not exist or cannot be created
`org.freedesktop.Telepathy.Error.NotAvailable`
  The requested channel type cannot be created with the given handle
`org.freedesktop.Telepathy.Error.NotCapable`
  The requested channel cannot be created because contact doesn't have the required capabilities.
`org.freedesktop.Telepathy.Error.Channel.Banned`
  You are banned from the channel. (generic description)
`org.freedesktop.Telepathy.Error.Channel.Full`
  The channel is full. (generic description)
`org.freedesktop.Telepathy.Error.Channel.InviteOnly`
  The requested channel is invite-only. (generic description)

### RequestHandles ( u: Handle_Type, as: Names ) → au

Request several handles from the connection manager which represent a number of contacts, rooms or server-stored lists on the service. The connection manager should record that these handles are in use by the client who invokes this method, and must not deallocate the handles until the client disconnects from the bus or calls the ReleaseHandles method. Where the name refers to an entity that already has a handle in this connection manager, this handle should be returned instead. The handle number 0 must not be returned by the connection manager.

#### Parameters

`Handle_Type` − `u` (Handle_Type)
  The type of handle required
`Names` − `as`
  An array of names of entities to request handles for

#### Returns

`Handles` − `au` (Handle[])
  An array of integer handle numbers in the same order as the given strings

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.InvalidHandle`
  The given name does not identify a valid entity of the given type.
  For instance, an XMPP connection would raise this error for identifiers with type Handle_Type_Room that do not contain exactly one '@' character, that contain spaces, and so on.
`org.freedesktop.Telepathy.Error.NotImplemented`
  The given handle type is not valid, or is not implemented on this connection.
  For instance, a connection to a protocol that doesn't have chat rooms would raise this error for room handles, and all CMs would raise this error for Handle_Type_None.

## Signals:

### SelfHandleChanged ( u: Self_Handle )

Emitted whenever the SelfHandle property changes. If the connection is not yet in the CONNECTED state, this signal is not guaranteed to be emitted.

Added in version 0.17.10. Clients MAY assume that if the SelfHandle property exists, this signal will be emitted when necessary.

#### Parameters

`Self_Handle` − `u` (Contact_Handle)
  The new value of the SelfHandle property.

### NewChannel ( o: Object_Path, s: Channel_Type, u: Handle_Type, u: Handle, b: Suppress_Handler )

Emitted when a new Channel object is created, either through user request or incoming information from the service.

Deprecated since version 0.17.23. Connection managers MUST still emit this signal, but clients SHOULD listen for the Requests.NewChannels signal instead.

#### Parameters

`Object_Path` − `o`
  A D-Bus object path for the channel object on this service
`Channel_Type` − `s` (DBus_Interface)
  A D-Bus interface name representing the channel type
`Handle_Type` − `u` (Handle_Type)
  An integer representing the type of handle this channel communicates with, or Handle_Type_None if no handle is specified
`Handle` − `u` (Handle)
  A handle indicating the specific contact, room or list this channel communicates with, or zero if no handle is specified
`Suppress_Handler` − `b`

  If true, the channel was requested by a client that intends to present it to the user itself (i.e. it passed suppress_handler=TRUE to the RequestChannel method), so no other handler should be launched. Clients MAY assume that channels where this is true were created by a user request.

  If false, either the channel was created due to incoming information from the service, or the channel was requested by a local client that does not intend to handle the channel itself (this usage is deprecated).

  Clients MUST NOT assume that only incoming channels will have this flag set to false.

### ConnectionError ( s: Error, a{sv}: Details )

Emitted when an error occurs that renders this connection unusable.

Whenever this signal is emitted, it MUST immediately be followed by a StatusChanged signal with status Connection_Status_Reason_Disconnected and an appropriate reason code.

Connection managers SHOULD emit this signal on disconnection, but need not do so. Clients MUST support connection managers that emit StatusChanged(Disconnected, ...) without first emitting ConnectionError.

This signal provides additional information about the reason for disconnection. The reason for connection is always straightforward - it was requested - so it does not need further explanation. However, on errors, it can be useful to provide additional information.

The Connection_Status_Reason is not given here, since it will be signalled in StatusChanged. A reasonable client implementation would be to store the information given by this signal until StatusChanged is received, at which point the information given by this signal can be used to supplement the StatusChanged signal.

#### Parameters

`Error` − `s` (DBus_Error_Name)
  The name of a D-Bus error describing the error that occurred, which may correspond to a Connection_Status_Reason or be a protocol-specific or connection-manager-specific error in a suitable namespace.
  For instance, a SIP connection manager could signal "402 Payment Required" as an error in a connection-manager-specific namespace, or a link-local XMPP implementation that used Avahi could provide the error given to it by the avahi-daemon.
`Details` − `a{sv}` (String_Variant_Map)

  Additional information about the error, which may include the following well-known keys:

  debug-message (s)
    Debugging information on the change, corresponding to the message part of a D-Bus error message, which SHOULD NOT be displayed to users under normal circumstances

  This argument allows for future extensions. For instance, if indicating DNS lookup failure, we could define a key that indicates the hostname that could not be found.

### StatusChanged ( u: Status, u: Reason )

Emitted when the status of the connection changes. All states and reasons have numerical values, as defined in ConnectionStatus and ConnectionStatusReason.

#### Parameters

`Status` − `u` (Connection_Status)
  An integer indicating the new status, as defined by ConnectionStatus
`Reason` − `u` (Connection_Status_Reason)
  An integer indicating the reason for the status change, as defined by ConnectionStatusReason

Interface has no Telepathy properties.

## D-Bus core Properties:

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

`SelfHandle` − `u` (Contact_Handle), read-only
  The handle which represents the user on this connection, which will remain valid for the lifetime of this connection, or until a change in the user's identifier is signalled by the SelfHandleChanged signal. If the connection is not yet in the CONNECTED state, the value of this property MAY be zero.

  Added in version 0.17.10. For compatibility with older versions, clients should fall back to calling the GetSelfHandle method.

## Simple types

### Handle − u

An unsigned 32-bit integer representing a handle

### Contact_Handle − u

An unsigned 32-bit integer representing a handle of type Handle_Type_Contact

### Room_Handle − u

An unsigned 32-bit integer representing a handle of type Handle_Type_Room

### List_Handle − u

An unsigned 32-bit integer representing a handle of type Handle_Type_List

### Group_Handle − u

An unsigned 32-bit integer representing a handle of type Handle_Type_Group

## 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

A reason why the status of the connection changed. Apart from Requested, the values of this enumeration only make sense as reasons why the status changed to Disconnected.

`Connection_Status_Reason_None_Specified = 0`

  There is no reason set for this state change. Unknown status reasons SHOULD be treated like this reason.

  When disconnected for this reason, the equivalent D-Bus error is `org.freedesktop.Telepathy.Error.Disconnected`.

`Connection_Status_Reason_Requested = 1`

  The change is in response to a user request. Changes to the Connecting or Connected status SHOULD always indicate this reason; changes to the Disconnected status SHOULD indicate this reason if and only if the disconnection was requested by the user.

  When disconnected for this reason, the equivalent D-Bus error is `org.freedesktop.Telepathy.Error.Cancelled`.

`Connection_Status_Reason_Network_Error = 2`

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

  When disconnected for this reason, the equivalent D-Bus error is `org.freedesktop.Telepathy.Error.NetworkError`.

`Connection_Status_Reason_Authentication_Failed = 3`

  The username or password was invalid.

  When disconnected for this reason, the equivalent D-Bus error is `org.freedesktop.Telepathy.Error.AuthenticationFailed`.

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

  When disconnected for this reason, the equivalent D-Bus error is `org.freedesktop.Telepathy.Error.EncryptionNotAvailable` if encryption was not available at all, or `org.freedesktop.Telepathy.Error.EncryptionError` if encryption failed.

`Connection_Status_Reason_Name_In_Use = 5`

  In general, this reason indicates that the requested account name or other identification could not be used due to conflict with another connection. It can be divided into three cases:

  - If the status change is from Connecting to Disconnected and the 'register' parameter to RequestConnection was present and true, the requested account could not be created on the server because it already exists.
  - If the status change is from Connecting to Disconnected but the 'register' parameter is absent or false, the connection manager could not connect to the specified account because a connection to that account already exists.
    In some protocols, like XMPP (when connecting with the same JID and resource as an existing connection), the existing connection "wins" and the new one fails to connect.
  - If the status change is from Connected to Disconnected, the existing connection was automatically disconnected because a new connection to the same account (perhaps from a different client or location) was established.
    In some protocols, like MSNP (when connecting twice with the same Passport), the new connection "wins" and the existing one is automatically disconnected.

  When disconnected for this reason, the equivalent D-Bus error is `org.freedesktop.Telepathy.Error.NotYours`.

  These three errors are distinct but very similar, and can be distinguished by other factors.
`Connection_Status_Reason_Cert_Not_Provided = 6`

  The server did not provide a SSL certificate.

  When disconnected for this reason, the equivalent D-Bus error is `org.freedesktop.Telepathy.Error.Cert.NotProvided`.

`Connection_Status_Reason_Cert_Untrusted = 7`

  The server's SSL certificate is signed by an untrusted certifying authority. This error SHOULD NOT be used to represent a self-signed certificate: use the more specific Cert_Self_Signed reason for that.

  When disconnected for this reason, the equivalent D-Bus error is `org.freedesktop.Telepathy.Error.Cert.Untrusted`.

`Connection_Status_Reason_Cert_Expired = 8`

  The server's SSL certificate has expired.

  When disconnected for this reason, the equivalent D-Bus error is `org.freedesktop.Telepathy.Error.Cert.Expired`.

`Connection_Status_Reason_Cert_Not_Activated = 9`

  The server's SSL certificate is not yet valid.

  When disconnected for this reason, the equivalent D-Bus error is `org.freedesktop.Telepathy.Error.Cert.NotActivated`.

`Connection_Status_Reason_Cert_Hostname_Mismatch = 10`

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

  When disconnected for this reason, the equivalent D-Bus error is `org.freedesktop.Telepathy.Error.Cert.HostnameMismatch`.

`Connection_Status_Reason_Cert_Fingerprint_Mismatch = 11`

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

  When disconnected for this reason, the equivalent D-Bus error is `org.freedesktop.Telepathy.Error.Cert.FingerprintMismatch`.

`Connection_Status_Reason_Cert_Self_Signed = 12`

  The server's SSL certificate is self-signed.

  When disconnected for this reason, the equivalent D-Bus error is `org.freedesktop.Telepathy.Error.Cert.HostnameMismatch`.

`Connection_Status_Reason_Cert_Other_Error = 13`

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

  When disconnected for this reason, the equivalent D-Bus error is `org.freedesktop.Telepathy.Error.Cert.Invalid`.

## Structure types

### Channel_Info − ( o: Channel, s: Channel_Type, u: Handle_Type, u: Handle )

A struct representing a channel, as returned by ListChannels on the Connection interface.

Deprecated since version 0.17.23.

In bindings that need a separate name, arrays of Channel_Info should be called Channel_Info_List.

#### Members

`Channel` − `o`
  The object path of the channel, which is on the same bus name as the connection
`Channel_Type` − `s` (DBus_Interface)
  The channel's type
`Handle_Type` − `u` (Handle_Type)
  The type of the handle that the channel communicates with, or Handle_Type_None if there is no associated handle
`Handle` − `u` (Handle)
  The handle that the channel communicates with, or 0 if there is no associated handle

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

### GetAliasFlags ( ) → u

Return a bitwise OR of flags detailing the behaviour of aliases on this connection.

#### Returns

`Alias_Flags` − `u` (Connection_Alias_Flags)
  An integer with a bitwise OR of flags from ConnectionAliasFlags

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)

### RequestAliases ( au: Contacts ) → as

Request the value of several contacts' aliases at once.

#### Parameters

`Contacts` − `au` (Contact_Handle[])
  An array of handles representing contacts

#### Returns

`Aliases` − `as`
  A list of aliases in the same order as the contact handles

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)
`org.freedesktop.Telepathy.Error.InvalidHandle`
  The contact name specified is unknown on this channel or connection. (generic description)

### GetAliases ( au: Contacts ) → a{us}

Request the value of several contacts' aliases at once. This SHOULD only return cached aliases, falling back on the handle name if none is present. Also if there was no cached alias, a request SHOULD be started of which the result is later signalled by AliasesChanged.

#### Parameters

`Contacts` − `au` (Contact_Handle[])
  An array of handles representing contacts

#### Returns

`Aliases` − `a{us}` (Alias_Map)
  A dictionary mapping contact handles to aliases

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.InvalidHandle`
  The contact name specified is unknown on this channel or connection. (generic description)

### SetAliases ( a{us}: Aliases ) → nothing

Request that the alias of the given contact be changed. Success will be indicated by emitting an AliasesChanged signal. On connections where the CONNECTION_ALIAS_FLAG_USER_SET flag is not set, this method will only ever succeed if the contact is the user's own handle (as returned by Connection.GetSelfHandle).

#### Parameters

`Aliases` − `a{us}` (Alias_Map)
  A dictionary mapping integer handles of contacts to strings of the new alias to set.

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  Raised when one of the provided arguments is invalid. (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)

## Signals:

### AliasesChanged ( a(us): Aliases )

Signal emitted when a contact's alias (or that of the user) is changed.

#### Parameters

`Aliases` − `a(us)` (Alias_Pair[])
  An array containing structs of:
  - the handle representing the contact
  - the new alias

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

### Alias_Pair − ( u: Handle, s: Alias )

A pair (contact handle, alias) as seen in the AliasesChanged signal.

In bindings that need a separate name, arrays of Alias_Pair should be called Alias_Pair_List.

#### Members

`Handle` − `u` (Contact_Handle)
  (undocumented)
`Alias` − `s`
  (undocumented)

## Mapping types

### Alias_Map − a{ u: Handle → s: Alias }

A dictionary whose keys are contact handles and whose values are aliases.

#### Members

`Handle` − `u` (Contact_Handle)
  (undocumented)
`Alias` − `s`
  (undocumented)

# 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 string, the Avatar_Token, which represents a particular avatar. Tokens MUST be chosen by the connection manager in such a way that the triple (Connection_Manager_Name, Protocol, Avatar_Token) uniquely identifies an avatar. 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 AvatarUpdated 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:

### GetAvatarRequirements ( ) → as, q, q, q, q, u

Get the required format of avatars on this connection.

Deprecated since version 0.17.22. Use GetAll to retrieve the D-Bus properties on this interface, falling back to this method on failure.

#### Returns

`MIME_Types` − `as`
  An array of supported MIME types (eg image/jpeg)
`Min_Width` − `q`
  The minimum image width in pixels
`Min_Height` − `q`
  The minimum image height in pixels
`Max_Width` − `q`
  The maximum image width in pixels, or 0 if there is no limit
`Max_Height` − `q`
  The maximum image height in pixels, or 0 if there is no limit
`Max_Bytes` − `u`
  The maximum image size in bytes, or 0 if there is no limit

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)

### GetAvatarTokens ( au: Contacts ) → as

Get the unique tokens for all of the given contacts' avatars. Using this method in new Telepathy clients is deprecated; use GetKnownAvatarTokens instead.

Deprecated since version 0.15.5. Use GetKnownAvatarTokens instead.

#### Parameters

`Contacts` − `au` (Contact_Handle[])
  An array of handles representing contacts

#### Returns

`Tokens` − `as` (Avatar_Token[])
  An array of avatar tokens or empty strings (if no avatar is set) in the same order as the given array of contact handles

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  Raised when one of the provided arguments is invalid. (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)

### GetKnownAvatarTokens ( au: Contacts ) → a{us}

Get the unique tokens for the given contacts' avatars. These tokens can be persisted across connections, and should be used by the client to check whether the avatars have been updated. For handles other than the self handle, only tokens that are already known are returned; an empty token means the given contact has no avatar. However, a CM must always have the tokens for the self handle if one is set (even if it is set to no avatar). On protocols where the avatar does not persist between connections, a CM should omit the self handle from the returned map until an avatar is explicitly set or cleared.

#### Parameters

`Contacts` − `au` (Contact_Handle[])
  An array of handles representing contacts

#### Returns

`Tokens` − `a{us}` (Avatar_Token_Map)
  A dictionary of handles mapped to avatar tokens, containing only the known avatar tokens.

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  Raised when one of the provided arguments is invalid. (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)

### RequestAvatar ( u: Contact ) → ay, s

Request the avatar for a given contact. Using this method in new Telepathy clients is deprecated; use RequestAvatars instead.

Deprecated since version 0.15.5. Use RequestAvatars instead.

#### Parameters

`Contact` − `u` (Contact_Handle)
  An integer handle for the contact to request the avatar for

#### Returns

`Data` − `ay`
  An array of bytes containing the image data
`MIME_Type` − `s`
  A string containing the image MIME type (eg image/jpeg), or empty if unknown

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.InvalidHandle`
  The contact name specified is unknown on this channel or connection. (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  The contact does not currently have an avatar.

### RequestAvatars ( au: Contacts ) → nothing

Request avatars for a number of contacts. The AvatarRetrieved signal is emitted for each avatar retrieved. If the handles are valid but retrieving an avatar fails (for any reason, including the contact not having an avatar) the AvatarRetrieved signal is not emitted for that contact.

#### Parameters

`Contacts` − `au` (Contact_Handle[])
  The contacts to retrieve avatars for

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.InvalidHandle`
  The contact name specified is unknown on this channel or connection. (generic description)

### SetAvatar ( ay: Avatar, s: MIME_Type ) → s

Set a new avatar image for this connection. The avatar image must respect the requirements obtained by GetAvatarRequirements.

#### Parameters

`Avatar` − `ay`
  An array of bytes representing the avatar image data
`MIME_Type` − `s`
  A string representing the image MIME type

#### Returns

`Token` − `s` (Avatar_Token)
  The string token of the new avatar

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  Raised when one of the provided arguments is invalid. (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)

### ClearAvatar ( ) → nothing

Remove the avatar image for this connection.

Added in version 0.15.0.

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)

## Signals:

### AvatarUpdated ( u: Contact, s: New_Avatar_Token )

Emitted when the avatar for a contact has been updated, or first discovered on this connection. If the token differs from the token associated with the client's cached avatar for this contact, the new avatar should be requested with RequestAvatars.

#### Parameters

`Contact` − `u` (Contact_Handle)
  An integer handle for the contact whose avatar has changed
`New_Avatar_Token` − `s` (Avatar_Token)
  Unique token for their new avatar

### AvatarRetrieved ( u: Contact, s: Token, ay: Avatar, s: Type )

Emitted when the avatar for a contact has been retrieved.

#### Parameters

`Contact` − `u` (Contact_Handle)
  The contact whose avatar has been retrieved
`Token` − `s` (Avatar_Token)
  The token corresponding to the avatar
`Avatar` − `ay`
  An array of bytes containing the image data
`Type` − `s`
  A string containing the image MIME type (eg image/jpeg), or empty if unknown

Interface has no Telepathy properties.

## D-Bus core Properties:

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

`SupportedAvatarMIMETypes` − `as`, read-only
  An array of supported MIME types (e.g. "image/jpeg"). Clients MAY assume that the first type in this array is preferred. This property cannot change after the Connection goes to the Connected state.

  Added in version 0.17.22. Fall back to calling GetAvatarRequirements if getting this property fails.

`MinimumAvatarHeight` − `u`, read-only
  The minimum height in pixels of an avatar on this protocol, which MAY be 0. This property cannot change after the Connection goes to the Connected state.

  Added in version 0.17.22. Fall back to calling GetAvatarRequirements if getting this property fails.

`MinimumAvatarWidth` − `u`, read-only
  The minimum width in pixels of an avatar on this protocol, which MAY be 0. This property cannot change after the Connection goes to the Connected state.

  Added in version 0.17.22. Fall back to calling GetAvatarRequirements if getting this property fails.

`RecommendedAvatarHeight` − `u`, read-only
  The recommended height in pixels of an avatar on this protocol, or 0 if there is no preferred height. This property cannot change after the Connection goes to the Connected state.
  In XMPP a recommended width is given by the protocol specification; in proprietary protocols, using the same avatar size as the proprietary client is likely to lead to the best display to other users.

  Added in version 0.17.22.

`RecommendedAvatarWidth` − `u`, read-only
  The recommended width in pixels of an avatar on this protocol, or 0 if there is no preferred width. This property cannot change after the Connection goes to the Connected state.
  The rationale is the same as for RecommendedAvatarHeight.

  Added in version 0.17.22.

`MaximumAvatarHeight` − `u`, read-only
  The maximum height in pixels of an avatar on this protocol, or 0 if there is no limit. This property cannot change after the Connection goes to the Connected state.

  Added in version 0.17.22. Fall back to calling GetAvatarRequirements if getting this property fails.

`MaximumAvatarWidth` − `u`, read-only
  The maximum width in pixels of an avatar on this protocol, or 0 if there is no limit. This property cannot change after the Connection goes to the Connected state.

  Added in version 0.17.22. Fall back to calling GetAvatarRequirements if getting this property fails.

`MaximumAvatarBytes` − `u`, read-only
  The maximum size in bytes of an avatar on this protocol, or 0 if there is no limit. This property cannot change after the Connection goes to the Connected state.

  Added in version 0.17.22. Fall back to calling GetAvatarRequirements if getting this property fails.

## Simple types

### Avatar_Token − s

An opaque token chosen by the connection manager, representing a particular avatar.

Because avatars can be relatively large images, most protocols provide a way to detect whether an old avatar is still valid, or whether an avatar has changed, without pushing the actual avatar data to all clients.

The connection manager MUST choose these tokens in a way that makes it highly unlikely that two different avatars with the same connection manager and protocol will have the same token.

This means that clients MAY use the triple (Connection_Manager_Name, Protocol, avatar token) as a key for their avatar cache. For instance, an avatar for a telepathy-gabble Jabber contact might be stored in a file .../gabble/jabber/4e199b4a1c40b497a95fcd1cd896351733849949.png.

For instance, some protocols (like XMPP) identify avatars by a hash of the avatar data; in this case, the hash can be used as the avatar token.

Some protocols identify avatars by the timestamp of the last change to the avatar; in these protocols it would be necessary for the connection manager to encode both the timestamp and the contact's identifier into the avatar token in order to ensure uniqueness.

This token SHOULD be kept short and reasonably suitable for use in a filename, but MAY contain any UTF-8 character (so clients using avatar tokens in filenames MUST be prepared to escape characters that are not valid in filenames). Connection managers for protocols where tokens would otherwise become inconveniently large or contain many unsuitable characters SHOULD hash the identifying data to generate the token.

Changed in version 0.17.16: strengthened uniqueness requirements so (CM name, protocol, token) is unique; previously only (our Account, remote contact identifier, token) was required to be unique

## Mapping types

### Avatar_Token_Map − a{ u: Handle → s: Token }

A dictionary whose keys are contact handles and whose values are avatar tokens.

#### Members

`Handle` − `u` (Contact_Handle)
  (undocumented)
`Token` − `s` (Avatar_Token)
  (undocumented)

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

### AdvertiseCapabilities ( a(su): Add, as: Remove ) → a(su)

Used by user interfaces to indicate which channel types they are able to handle on this connection. Because these may be provided by different client processes, this method accepts channel types to add and remove from the set already advertised on this connection. The type of advertised capabilities (create versus invite) is protocol-dependent and hence cannot be set by the this method. In the case of a client adding an already advertised channel type but with new channel type specific flags, the connection manager should simply add the new flags to the set of advertised capabilities.

Upon a successful invocation of this method, the CapabilitiesChanged signal will be emitted for the user's own handle ( Connection.GetSelfHandle) by the connection manager to indicate the changes that have been made. This signal should also be monitored to ensure that the set is kept accurate - for example, a client may remove capabilities or type specific capability flags when it exits which are still provided by another client.

#### Parameters

`Add` − `a(su)` (Capability_Pair[])
  An array of structures containing:
  - a string channel type
  - a bitwise OR of type specific capability flags
`Remove` − `as` (DBus_Interface[])
  An array of D-Bus interface names of channel types to remove

#### Returns

`Self_Capabilities` − `a(su)` (Capability_Pair[])
  An array of structures describing the current capabilities containing: a string channel type a bitwise OR of type specific capability flags

#### Possible errors

`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)

### GetCapabilities ( au: Handles ) → a(usuu)

Returns an array of capabilities for the given contact handles.

#### Parameters

`Handles` − `au` (Contact_Handle[])

  An array of contact handles for this connection.

  This may include zero, which originally meant a query for capabilities available on the connection itself. This usage is deprecated; clients SHOULD NOT do this, and connection managers SHOULD proceed as though zero had not been present in this list.

#### Returns

`Contact_Capabilities` − `a(usuu)` (Contact_Capability[])
  An array of structures containing:
  - an integer handle representing the contact
  - a string channel type
  - a bitwise OR of generic capability flags for the type
  - a bitwise OR of type specific capability flags for the type

#### Possible errors

`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.InvalidHandle`
  The handle does not represent a contact and is not zero
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)

## Signals:

### CapabilitiesChanged ( a(usuuuu): Caps )

Announce that there has been a change of capabilities on the given handle.

If the handle is zero, the capabilities refer to the connection itself, in some poorly defined way. This usage is deprecated and clients should ignore it.

#### Parameters

`Caps` − `a(usuuuu)` (Capability_Change[])
  An array of structures containing:
  - an integer handle representing the contact
  - a string channel type
  - a bitwise OR of the contact's old generic capability flags
  - a bitwise OR of the contact's new generic capability flags
  - a bitwise OR of the contact's old type specific capability flags
  - a bitwise OR of the contact's new type specific capability flags

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

### Capability_Pair − ( s: Channel_Type, u: Type_Specific_Flags )

A pair (channel type, type-specific flags) as passed to AdvertiseCapabilities on the Capabilities interface.

In bindings that need a separate name, arrays of Capability_Pair should be called Capability_Pair_List.

#### Members

`Channel_Type` − `s` (DBus_Interface)
  (undocumented)
`Type_Specific_Flags` − `u`
  (undocumented)

### Contact_Capability − ( u: Handle, s: Channel_Type, u: Generic_Flags, u: Type_Specific_Flags )

A struct (contact handle, channel type, generic flags, type-specific flags) representing a capability posessed by a contact, as returned by GetCapabilities on the Capabilities interface.

In bindings that need a separate name, arrays of Contact_Capability should be called Contact_Capability_List.

#### Members

`Handle` − `u` (Contact_Handle)
  (undocumented)
`Channel_Type` − `s` (DBus_Interface)
  (undocumented)
`Generic_Flags` − `u` (Connection_Capability_Flags)
  (undocumented)
`Type_Specific_Flags` − `u`
  (undocumented)

### Capability_Change − ( u: Handle, s: Channel_Type, u: Old_Generic_Flags, u: New_Generic_Flags, u: Old_Type_Specific_Flags, u: New_Type_Specific_Flags )

A struct (contact handle, channel type, old generic flags, new generic flags, old type-specific flags, new type-specific flags) representing a change to one of a contact's capabilities, as seen in the CapabilitiesChanged signal on the Capabilities interface.

In bindings that need a separate name, arrays of Capability_Change should be called Capability_Change_List.

#### Members

`Handle` − `u` (Contact_Handle)
  (undocumented)
`Channel_Type` − `s` (DBus_Interface)
  (undocumented)
`Old_Generic_Flags` − `u` (Connection_Capability_Flags)
  (undocumented)
`New_Generic_Flags` − `u` (Connection_Capability_Flags)
  (undocumented)
`Old_Type_Specific_Flags` − `u`
  (undocumented)
`New_Type_Specific_Flags` − `u`
  (undocumented)

# org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.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`

Contact capabilities describe the channel classes which may be created with a given contact in advance of attempting to create a channel. Each capability represents a commitment by the connection manager that it will ordinarily be able to create a channel with a contact when given a request with the properties defined by the channel class.

Capabilities pertain to particular contact handles, and represent activities such as having a text chat, a voice call with the user or a stream tube of a defined type.

This interface also enables user interfaces to notify the connection manager what capabilities to advertise for the user to other contacts. This is done by using the SetSelfCapabilities method, and deals with channel property values pertaining to them which are implemented by available client processes.

Added in version 0.17.16. (as a draft)

## Methods:

### SetSelfCapabilities ( aa{sv}: caps ) → nothing

Used by user interfaces to indicate which channel classes they are able to handle on this connection. It replaces the previous advertised channel classes by the set given as parameter.

If a channel class is unknown by the connection manager, it is just ignored. No error are returned in this case, and other known channel class are added.

Upon a successful invocation of this method, the ContactCapabilitiesChanged signal will only be emitted for the user's own handle (as returned by GetSelfHandle) by the connection manager if, in the given protocol, the given capabilities are distinct from the previous state.

The connection manager will essentially intersect the provided capabilities and the channel classes it implements. Therefore, certain properties which are never fixed for a channel class (such as the target handle, or the Parameters property of a tube channel) will almost certainly not be advertised.

#### Parameters

`caps` − `aa{sv}` (String_Variant_Map[])
  An array of channel classes to replace to the list of what the connection can handle. If you include optional properties, they may not get advertised. The given properties are matched to the mandatory properties.

#### Possible errors

`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)

### GetContactCapabilities ( au: handles ) → a{ua(a{sv}as)}

Returns an array of enhanced capabilities for the given contact handles.

#### Parameters

`handles` − `au` (Contact_Handle[])

  An array of contact handles for this connection.

  The handle zero MUST NOT be included in the request.

#### Returns

`Contact_Capabilities` − `a{ua(a{sv}as)}` (Contact_Capabilities_Map)
  An array of structures containing:
  - a dictionary mapping the channel properties to their values.
  - an array of additional allowed properties

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.InvalidHandle`
  The handle does not represent a contact. Zero is always invalid.

## Signals:

### ContactCapabilitiesChanged ( a{ua(a{sv}as)}: caps )

Announce that there has been a change of capabilities on the given handles. A single signal can be emitted for several contacts.

The underlying protocol can get several contacts' capabilities at the same time.

#### Parameters

`caps` − `a{ua(a{sv}as)}` (Contact_Capabilities_Map)
  All the capabilities of the contacts

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

## Mapping types

### Contact_Capabilities_Map − a{ u: Key → a(a{sv}as): Value }

A mapping from contact handle to their capabilities.

In bindings that need a separate name, arrays of Contact_Capabilities_Map should be called Contact_Capabilities_Map_List.

#### Members

`Key` − `u` (Contact_Handle)
  A contact handle.
`Value` − `a(a{sv}as)` (Requestable_Channel_Class[])
  The contact capabilities.

# org.freedesktop.Telepathy.Connection.Interface.ContactInfo.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 interface for requesting information about a contact on a given connection. Information is represented as a list of Contact_Info_Fields forming a structured representation of a vCard (as defined by RFC 2426), using field names and semantics defined therein.

Added in version 0.17.18. (as a draft)

## Methods:

### GetContactInfo ( au: Contacts ) → a{ua(sasas)}

Request information on several contacts at once. This SHOULD only return cached information, omitting handles for which no information is cached from the returned map. For contacts without cached information, the information SHOULD be requested from the network, with the result signalled later by ContactInfoChanged.

#### Parameters

`Contacts` − `au` (Contact_Handle[])
  An array of handles representing contacts.

#### Returns

`ContactInfo` − `a{ua(sasas)}` (Contact_Info_Map)
  A dictionary mapping contact handles to information, whose keys are the subset of the requested list of handles for which information was cached.

### RequestContactInfo ( u: Contact ) → a(sasas)

Retrieve information for a contact, requesting it from the network if it is not cached locally.

#### Parameters

`Contact` − `u` (Contact_Handle)
  An integer handle for a contact.

#### Returns

`Contact_Info` − `a(sasas)` (Contact_Info_Field[])
  Information about that contact.

#### Possible errors

`org.freedesktop.Telepathy.Error.NotAvailable`
  The contact's information could not be retrieved.

### SetContactInfo ( a(sasas): ContactInfo ) → nothing

Set new contact information for this connection, replacing existing information. This method is only suppported if ContactInfoFlags contains Can_Set, and may only be passed fields conforming to SupportedFields.

#### Parameters

`ContactInfo` − `a(sasas)` (Contact_Info_Field[])
  The new information to be set.

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)
`org.freedesktop.Telepathy.Error.NotImplemented`
  Setting your own information is not supported on this protocol.
`org.freedesktop.Telepathy.Error.InvalidArgument`
  The supplied fields do not match the restrictions specified by SupportedFields.

## Signals:

### ContactInfoChanged ( u: Contact, a(sasas): ContactInfo )

Emitted when a contact's information has changed or been received for the first time on this connection.

#### Parameters

`Contact` − `u` (Contact_Handle)
  An integer handle for the contact whose info has changed.
`ContactInfo` − `a(sasas)` (Contact_Info_Field[])
  An array of fields representing information about this contact.

Interface has no Telepathy properties.

## D-Bus core Properties:

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

`ContactInfoFlags` − `u` (Contact_Info_Flag), read-only
  An integer representing the bitwise-OR of flags on this connection. This property should be constant over the lifetime of a connection.
`SupportedFields` − `a(sasuu)` (Field_Spec[]), read-only

  A list of field specifications describing the kinds of fields which may be passed to SetContactInfo. The empty list indicates that arbitrary vCard fields are permitted. This property SHOULD be the empty list, and be ignored by clients, if ContactInfoFlags does not contain the Can_Set Contact_Info_Flag.

  For example, an implementation of XEP-0054, which defines a mapping of vCards to XML for use over XMPP, would set this property to the empty list. A protocol whose notion of contact information is one each of personal phone number, mobile phone number, location, email address and date of birth, with no attributes allowed on each piece of information, would set this property to (in Python-like syntax):

      [
        ('tel', ['home'], Parameters_Mandatory, 1),
        ('tel', ['cell'], Parameters_Mandatory, 1),
        ('adr', [], Parameters_Mandatory, 1),
        ('bday', [], Parameters_Mandatory, 1),
        ('email', ['internet'], Parameters_Mandatory, 1),
      ]

  A protocol which allows users to specify up to four phone numbers, which may be labelled as personal and/or mobile, would set this property to `[ ('tel', ['home', 'cell'], 0, 4), ]`.

  Studying existing IM protocols shows that in practice protocols allow either a very restricted set of fields (such as MSN, which seems to correspond roughly to the largest example above) or something mapping 1-1 to vCard (such as XMPP).

## Simple types

### VCard_Field − s

A string naming a field in a vCard, such as "fn" or "adr". Although these are case-insensitive in RFC 2425, in Telepathy they MUST be normalized to lower case. In the terminology of RFC 2425 this is called a "type name", and corresponds to the "name" production given in the ABNF.

### VCard_Type_Parameter − s

A type parameter as defined by RFC 2426, such as "type=cell" or "language=en".

## Enumerated types:

### Contact_Info_Flag

Flags defining the behaviour of contact information on this protocol. Some protocols provide no information on contacts without an explicit request; others always push information to the connection manager as and when it changes.

`Contact_Info_Flag_Can_Set = 1`
  Indicates that SetContactInfo is supported on this connection.
`Contact_Info_Flag_Push = 2`
  Indicates that the protocol pushes all contacts' information to the connection manager without prompting. If set, RequestContactInfo will not cause a network roundtrip and ContactInfoChanged will be emitted whenever contacts' information changes.

## Sets of flags:

### Contact_Info_Field_Flags

Flags describing the behaviour of a vCard field.

`Contact_Info_Field_Flag_Parameters_Mandatory = 1`

  If present, exactly the parameters indicated must be set on this field; in the case of an empty list of parameters, this implies that parameters may not be used.

  If absent, and the list of allowed parameters is non-empty, any (possibly empty) subset of that list may be used.

  If absent, and the list of allowed parameters is empty, any parameters may be used.

## Structure types

### Contact_Info_Field − ( s: Field_Name, as: Parameters, as: Field_Value )

Represents one piece of information about a contact, as modelled by a single vCard field. Of the fields defined in RFC 2426, common examples include:

fn
  The contact's full name, formatted to their liking
n
  The contact's full name, divided into five parts: family name, given name, additional names, honorific prefixes, and honorific suffixes
org
  The contact's organisation, divided into the organization's name possibly followed by one or more organizational unit names.
adr
  A street address for the contact, divided into seven components: post office box, extended address, street address, locality (e.g., city), region (e.g., state or province), the postal code, and the country name.
tel
  A telephone number for the contact.
email
  An email address for the contact.

For example, the following vCard:

       BEGIN:vCard
       VERSION:3.0
       FN:Wee Ninja
       N;LANGUAGE=ja:Ninja;Wee;;;-san
       ORG:Collabora, Ltd.;Human Resources\; Company Policy Enforcement
       ADR;TYPE=WORK,POSTAL,PARCEL:;;11 Kings Parade;Cambridge;Cambridgeshire
        ;CB2 1SJ;UK
       TEL;TYPE=VOICE,WORK:+44 1223 362967, +44 7700 900753
       EMAIL;TYPE=INTERNET,PREF:wee.ninja@collabora.co.uk
       EMAIL;TYPE=INTERNET:wee.ninja@example.com
       URL:http://www.thinkgeek.com/geektoys/plush/8823/
       NICKNAME:HR Ninja,Enforcement Ninja
       END:vCard

would be represented by (in Python-like syntax):

    [
      ('fn', [], ['Wee Ninja']),
      ('n', ['language=ja'], ['Ninja', 'Wee', '', '', '-san']),
      ('org', [], ['Collabora, Ltd.', 'Human Resources; Company Policy Enforcement']),
      ('adr', ['type=work','type=postal','type=parcel'],
       ['','','11 Kings Parade','Cambridge', 'Cambridgeshire','CB2 1SJ','UK']),
      ('tel', ['type=voice','type=work'], ['+44 1223 362967']),
      ('tel', ['type=voice','type=work'], ['+44 7700 900753']),
      ('email', ['type=internet','type=pref'], ['wee.ninja@collabora.co.uk']),
      ('email', ['type=internet'], ['wee.ninja@example.com']),
      ('url', [], ['http://www.thinkgeek.com/geektoys/plush/8823/']),
      ('nickname', [], ['HR Ninja']),
      ('nickname', [], ['Enforcement Ninja'])
    ]

In bindings that need a separate name, arrays of Contact_Info_Field should be called Contact_Info_Field_List.

#### Members

`Field_Name` − `s`
  The name of the field; this is the lowercased name of a vCard field. For example, a field representing a contact's address would be named "adr".
`Parameters` − `as`

  A list of vCard type parameters applicable to this field, with their values. The type parameter names, and any values that are case-insensitive in vCard, MUST be in lower case. For example, a contact's preferred home address would have parameters 'type=home' and 'type=pref'.

  The type parameter 'type' is likely to be the most common, but there can be others, such as 'language=en'.

  Characters which are required to be escaped in vCard type parameters should not be escaped in this list. For instance, a field "X-FOO;SEMICOLON=\;:bar" in a vCard would become ('x-foo', ['semicolon=;'], ['bar']) in this interface.

  This avoids Telepathy UIs having to understand the escaping and unescaping rules for vCards. The type parameter name is not allowed (by RFC 2425) to contain an '=' character, so no ambiguity is introduced.
`Field_Value` − `as`

  For unstructured vCard fields (such as 'fn', a formatted name field), a single-element array containing the field's value.

  For structured fields (such as 'adr', an address field), an array corresponding to the semicolon-separated elements of the field (with empty strings for empty elements).

  A vCard field with multiple comma-separated values, such as 'nickname', should be represented by several Contact_Info_Fields.

  Characters which are required to be escaped in vCard values, such as semi-colons and newlines, should not be escaped in this list (e.g. if a value contains a newline, the data passed over D-Bus should contain a literal newline character).

  An earlier draft of this interface split structured vCard fields into multiple Telepathy-level fields; for example, 'n' became 'family-name', 'given-name', etc. But under this representation, omitting empty components leads to difficulty identifying where one name ends and another begins. Consider the fields ['given-name', 'honorific-suffixes', 'family-name', 'honorific-prefixes']: does this represent two 'n' fields, or one with incorrect component ordering?

### Field_Spec − ( s: Name, as: Parameters, u: Flags, u: Max )

A struct describing a vCard field, with parameters, that may be passed to SetContactInfo on this Connection.

In bindings that need a separate name, arrays of Field_Spec should be called Field_Specs.

#### Members

`Name` − `s` (VCard_Field)
  A vCard field name, such as 'tel'.
`Parameters` − `as` (VCard_Type_Parameter[])
  The set of vCard type parameters which may be set on this field. If this list is empty and the Contact_Info_Field_Flag_Parameters_Mandatory flag is unset, any vCard type parameters may be used.
`Flags` − `u` (Contact_Info_Field_Flags)
  Flags describing the behaviour of this field.
`Max` − `u`
  Maximum number of instances of this field which may be set. MAXUINT32 is used to indicate that there is no limit.

## Mapping types

### Contact_Info_Map − a{ u: Handle → a(sasas): Contact_Info }

A dictionary whose keys are contact handles and whose values are contact information..

#### Members

`Handle` − `u` (Contact_Handle)
  (undocumented)
`Contact_Info` − `a(sasas)` (Contact_Info_Field[])
  (undocumented)

# 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, Avatar_Token)
  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.
org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT/caps (type a{ua(a{sv}as)}, Contact_Capabilities_Map)
  The same structs that would be returned by GetContactCapabilities 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.
org.freedesktop.Telepathy.Connection.Interface.Location.DRAFT/location (type a{sv}, Location)
  The same struct used by GetLocations Omitted from the result if the contact's location is not known.

Added in version 0.17.9.

## Methods:

### GetContactAttributes ( au: Handles, as: Interfaces, b: Hold ) → a{ua{sv}}

Return any number of contact attributes for the given handles.

#### Parameters

`Handles` − `au` (Contact_Handle[])
  An array of handles representing contacts.
`Interfaces` − `as` (DBus_Interface[])

  A list of strings indicating which D-Bus interfaces the calling process is interested in. All supported attributes from these interfaces, whose values can be obtained without additional network activity, will be in the reply.

  It is an error to request interfaces that are not supported by this Connection (i.e. mentioned in the ContactAttributeInterfaces property).

  This makes it possible to distinguish between interfaces for which the Connection has nothing to say (e.g. we don't know the avatar tokens of any of the contacts, so we omitted them all), and interfaces for which this API isn't supported.

  Attributes from the interface org.freedesktop.Telepathy.Connection are always returned, and need not be requested explicitly.

  As well as returning cached information immediately, the connection MAY start asynchronous requests to obtain better values for the contact attributes. If better values are later obtained by this process, they will be indicated with the usual signals (such as AliasesChanged).

  For instance, an XMPP connection manager could download vCards in response to a request for Aliasing attributes.
`Hold` − `b`
  If true, all handles in the result have been held on behalf of the calling process, as if by a call to Connection.HoldHandles.
  For further round-trip avoidance.

#### Returns

`Attributes` − `a{ua{sv}}` (Contact_Attributes_Map)

  A dictionary mapping the contact handles to contact attributes. If any of the requested handles are in fact invalid, they are simply omitted from this mapping. If contact attributes are not immediately known, the behaviour is defined by the interface; the attribute should either be omitted from the result or replaced with a default value.

  Each contact's attributes will always include at least the identifier that would be obtained by inspecting the handle (`org.freedesktop.Telepathy.Connection/contact-id`).

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  One of the requested interfaces is not supported (mentioned in ContactAttributeInterfaces).

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

### Contact_Attribute − s

A DBus_Interface, followed by a slash '/' character and an identifier for an attribute defined by that interface. The attribute identifier SHOULD be in lower case.
These aren't D-Bus core Properties, and we want them to look visibly different.

## Mapping types

### Single_Contact_Attributes_Map − a{ s: Attribute → v: Value }

Some of the attributes of a single contact.

#### Members

`Attribute` − `s` (Contact_Attribute)
  The name of the attribute
`Value` − `v`
  The value of the attribute

### Contact_Attributes_Map − a{ u: Contact → a{sv}: Attributes }

Mapping returned by GetContactAttributes, representing a collection of Contacts and their requested attributes.

#### Members

`Contact` − `u` (Contact_Handle)
  A contact
`Attributes` − `a{sv}` (Single_Contact_Attributes_Map)
  Attributes of that contact

# org.freedesktop.Telepathy.Connection.Interface.Location.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 interface on connections to support protocols which allow users to publish their current geographical location, and subscribe to the current location of their contacts.

This interface is geared strongly towards automatic propagation and use of this information, so focuses on latitude, longitude and altitude which can be determined by GPS, although provision is also included for an optional human-readable description of locations. All co-ordinate information is required to be relative to the WGS84 datum.

The information published through this interface is intended to have the same scope as presence information, so will normally be made available to those individuals on the user's "publish" contact list. Even so, user interfaces should not automatically publish location information without the consent of the user, and it is recommended that an option is made available to reduce the accuracy of the reported information to allow the user to maintain their privacy.

Location information is represented using the terminology of XMPP's XEP-0080 or the XEP-0080-derived Geoclue API where possible.

Added in version 0.17.18. (as a draft)

## Methods:

### GetLocations ( au: Contacts ) → a{ua{sv}}

Return the current locations of the given contacts, if they are already known. If any of the given contacts' locations are not known, request their current locations, but return immediately without waiting for a reply; if a reply with a non-empty location is later received for those contacts, the LocationUpdated signal will be emitted for them.
This method is appropriate for "lazy" location finding, for instance displaying the location (if available) of everyone in your contact list.

#### Parameters

`Contacts` − `au` (Contact_Handle[])
  The contacts whose locations should be returned or signalled.

#### Returns

`Locations` − `a{ua{sv}}` (Contact_Locations)
  The contacts' locations, if already known. Contacts whose locations are not already known are omitted from the mapping; contacts known to have no location information appear in the mapping with an empty Location dictionary.

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.InvalidHandle`
  The contact name specified is unknown on this channel or connection. (generic description)

### RequestLocation ( u: Contact ) → a{sv}

Return the current location of the given contact. If necessary, make a request to the server for up-to-date information, and wait for a reply.
This method is appropriate for use in a "Contact Information..." dialog; it can be used to show progress information (while waiting for the method to return), and can distinguish between various error conditions.

#### Parameters

`Contact` − `u` (Contact_Handle)
  The contact whose location should be returned.

#### Returns

`Location` − `a{sv}` (Location)
  The contact's location. It MAY be empty, indicating that no location information was found.

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.InvalidHandle`
  The contact name specified is unknown on this channel or connection. (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The requested contact does not allow the local user to see their location information.

### SetLocation ( a{sv}: Location ) → nothing

Set the local user's own location.

#### Parameters

`Location` − `a{sv}`
  The location to advertise. If the user wants to obscure their exact location by reducing the precision or accuracy, clients MUST do this themselves, rather than relying on the connection manager to do so. Clients that interact with more than one connection SHOULD advertise the same reduced-accuracy location to all of them, so that contacts cannot obtain an undesirably accurate location by assuming that random errors have been added and averaging the locations advertised on multiple connections.

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NotImplemented`
  Raised when the requested method, channel, etc is not available on this connection. (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)

## Signals:

### LocationUpdated ( u: Contact, a{sv}: Location )

Emitted when a contact's location changes or becomes known.

#### Parameters

`Contact` − `u` (Contact_Handle)
  The contact
`Location` − `a{sv}` (Location)
  The contact's location, or empty to indicate that nothing is known about the contact's location.

Interface has no Telepathy properties.

## D-Bus core Properties:

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

`LocationAccessControlTypes` − `au` (Rich_Presence_Access_Control_Type[]), read-only
  The types of access control that are supported by this connection.
`LocationAccessControl` − `(uv)` (Rich_Presence_Access_Control), read/write
  The current access control mechanism and settings for this connection. Before publishing location for the first time, if this has not been set by a client, implementations SHOULD set it to be as restrictive as possible (an empty whitelist, if supported).

## Enumerated types:

### Location_Accuracy_Level

A location accuracy level. This should be kept in sync with GeoclueAccuracyLevel in the Geoclue project.

`Location_Accuracy_Level_None = 0`
  The accuracy is unspecified.
`Location_Accuracy_Level_Country = 1`
  The location indicates the contact's country.
`Location_Accuracy_Level_Region = 2`
  The location indicates the contact's region within a country.
`Location_Accuracy_Level_Locality = 3`
  The location indicates the contact's locality within a region (e.g. the correct city).
`Location_Accuracy_Level_Postal_Code = 4`
  The location indicates the correct postal code.
`Location_Accuracy_Level_Street = 5`
  The location indicates the correct street.
`Location_Accuracy_Level_Detailed = 6`
  The location's accuracy is given by the error, horizontal-error-m and/or vertical-error-m keys.

## Mapping types

### Location − a{ s: Key → v: Value }

A user's location, represented as an extensible mapping.

#### Members

`Key` − `s`

  Civic addresses are represented by the following well-known keys (all of which have string values), which should be kept in sync with those used in XEP-0080 and in the Geoclue project:

  - countrycode - s: an ISO-3166-1 alpha-2 (two-letter) country code, e.g. "us", "gb", "fr"
  - country - s: a country name in unspecified locale, e.g. "USA"
  - region - s: an administrative region of the nation, such as a state or province
  - locality - s: a locality within the administrative region, such as a town or city
  - area - s: a named area such as a campus or neighborhood
  - postalcode - s: a code used for postal delivery
  - street - s: a thoroughfare within the locality, or a crossing of two thoroughfares

  The following address keys are defined in XEP-0080 but not by Geoclue, and are also allowed:

  - building - s: a specific building on a street or in an area
  - floor - s: a particular floor in a building
  - room - s: a particular room in a building
  - text - s: any more specific information, e.g. "Northwest corner of the lobby"
  - description - s: A natural-language name for or description of the location, e.g. "Bill's house"
  - uri - s: a URI representing the location or pointing to more information about it

  Positions are represented by the following well-known keys:

  - lat - d: latitude in decimal degrees north, -90 to +90, relative to the WGS-84 datum
    This is from XEP-0080; the XEP allows use of a different datum, but recommends this one. We enforce sanity by requiring a consistent datum: a minimal compliant implementation of this specification in terms of XEP-0080 would simply ignore the <lat> and <lon> elements if <datum> exists and has a value other than WGS-84, while an advanced implementation might correct for the different datum.
  - lon - d: Longitude in decimal degrees east, -180 to +180, relative to the WGS-84 datum
    Same rationale as 'lat'
  - alt - d: altitude in metres above sea level (negative if below sea level)
    This is from XEP-0080
  - accuracy-level - i (Location_Accuracy_Level): an indication of accuracy, which SHOULD be omitted if it would be Location_Accuracy_Level_None or Location_Accuracy_Level_Detailed
    This is a struct field in GeoClue; the name is new in this specification, and was chosen in an attempt to avoid clashing with any future XEP-0080 terminology.
  - error - d: horizontal position error in arc-minutes (1/60 degree) if known
    This is from XEP-0080
  - vertical-error-m - d: vertical position error in metres if known
    This exists as a struct field in GeoClue; the name is new in this specification.
  - horizontal-error-m - d: horizontal position error in metres if known
    This exists as a struct field in GeoClue; the name is new in this specification.

  Velocities are represented by the following well-known keys:

  - speed - d: speed in metres per second
    This is from XEP-0080
  - bearing - d: direction of movement in decimal degrees, where North is 0 and East is 90
    This is from XEP-0080, and is equivalent to the struct field called "direction" in GeoClue
  - climb - d: rate of change of 'alt' in metres per second
    This is a struct field in GeoClue; the name is new to this specification, but seems uncontroversial

  Other well-known keys:

  - timestamp - x (Unix_Timestamp64): the time that the contact was at this location, in seconds since 1970-01-01T00:00:00Z (i.e. the beginning of 1970 in UTC)
    XEP-0080 uses an ISO 8601 string for this, but a number of seconds since the epoch is probably easier to work with.
`Value` − `v`
  The value corresponding to the well-known key.

### Contact_Locations − a{ u: Contact → a{sv}: Location }

A map from contacts to their locations.

#### Members

`Contact` − `u` (Contact_Handle)
  A contact
`Location` − `a{sv}` (Location)
  The contact's location, which MAY be empty to indicate that the contact's location is unknown

# org.freedesktop.Telepathy.Connection.Interface.Presence

Implementations of this interface must also implement:

- `org.freedesktop.Telepathy.Connection`
- `org.freedesktop.Telepathy.Connection.Interface.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.

(The SimplePresence interface which replaces this one restricts presences to one status per contact, with an optional message, which is in practice all that was implemented on this interface.)

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 well-known values defined by the SimplePresence interface SHOULD be used where possible

As well as these well-known status identifiers, every status also has a numerical type value chosen from Connection_Presence_Type 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.

Changed in version 0.17.23: Connection managers implementing Presence MUST implement SimplePresence too.

Deprecated since version 0.17.21. Client implementations SHOULD use SimplePresence instead.

## Methods:

### AddStatus ( s: Status, a{sv}: Parameters ) → nothing

Request that a single presence status is published for the user, along with any desired parameters. Changes will be indicated by PresenceUpdate signals being emitted.

#### Parameters

`Status` − `s`
  The string identifier of the desired status
`Parameters` − `a{sv}` (String_Variant_Map)
  A dictionary of optional parameter names mapped to their variant-boxed values

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  Raised when one of the provided arguments is invalid. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)

### ClearStatus ( ) → nothing

Request that all of a user's presence statuses be removed. Be aware that this request may simply result in the statuses being replaced by a default available status. Changes will be indicated by PresenceUpdate signals being emitted.

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)

### GetPresence ( au: Contacts ) → a{u(ua{sa{sv}})}

Get presence previously emitted by PresenceUpdate for the given contacts. Data is returned in the same structure as the PresenceUpdate signal. Using this method in favour of RequestPresence has the advantage that it will not wake up each client connected to the PresenceUpdate signal.

#### Parameters

`Contacts` − `au` (Contact_Handle[])
  An array of the contacts whose presence should be obtained

#### Returns

`Presence` − `a{u(ua{sa{sv}})}` (Contact_Presences)
  Presence information in the same format as for the PresenceUpdate signal

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.InvalidHandle`
  The contact name specified is unknown on this channel or connection. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)

### GetStatuses ( ) → a{s(ubba{ss})}

Get a dictionary of the valid presence statuses for this connection. This is only available when online because only some statuses will be available on some servers.

#### Returns

`Available_Statuses` − `a{s(ubba{ss})}` (Status_Spec_Map)
  A dictionary of string identifiers mapped to a struct for each status, containing: a type value from one of the values above a boolean to indicate if this status may be set on yourself a boolean to indicate if this is an exclusive status which you may not set alongside any other a dictionary of valid optional string argument names mapped to their types

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)

### RemoveStatus ( s: Status ) → nothing

Request that the given presence status is no longer published for the user. Changes will be indicated by PresenceUpdate signals being emitted. As with ClearStatus, removing a status may actually result in it being replaced by a default available status.

#### Parameters

`Status` − `s`
  The string identifier of the status not to publish anymore for the user

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  The status requested is not currently set

### RequestPresence ( au: Contacts ) → nothing

Request the presence for contacts on this connection. A PresenceUpdate signal will be emitted when they are received. This is not the same as subscribing to the presence of a contact, which must be done using the 'subscription' ContactList, and on some protocols presence information may not be available unless a subscription exists.

#### Parameters

`Contacts` − `au` (Contact_Handle[])
  An array of the contacts whose presence should be obtained

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.InvalidHandle`
  The contact name specified is unknown on this channel or connection. (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  The presence of the requested contacts is not reported to this connection

### SetLastActivityTime ( u: Time ) → nothing

Request that the recorded last activity time for the user be updated on the server.

#### Parameters

`Time` − `u` (Unix_Timestamp)
  A UNIX timestamp of the user's last activity time (in UTC)

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.NotImplemented`
  This protocol has no concept of idle time

### SetStatus ( a{sa{sv}}: Statuses ) → nothing

Request that the user's presence be changed to the given statuses and desired parameters. Changes will be reflected by PresenceUpdate signals being emitted.

Statuses whose Connection_Presence_Type is Offline, Error or Unknown MUST NOT be passed to this function. Connection managers SHOULD reject these statuses.

The same rationale as for SimplePresence.SetPresence applies.

On certain protocols, this method may be called on a newly-created connection which is still in the DISCONNECTED state, and will sign on with the requested status. If the requested status is not available after signing on, NotAvailable will be returned and the connection will remain offline, or if the protocol does not support signing on with a certain status, Disconnected will be returned.

#### Parameters

`Statuses` − `a{sa{sv}}` (Multiple_Status_Map)
  A dictionary mapping status identifiers to dictionaries, which map optional parameter names to their variant-boxed values

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  Raised when one of the provided arguments is invalid. (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)

## Signals:

### PresenceUpdate ( a{u(ua{sa{sv}})}: Presence )

This signal should be emitted when your own presence has been changed, or the presence of the member of any of the connection's channels has been changed, or when the presence requested by RequestPresence is available.

#### Parameters

`Presence` − `a{u(ua{sa{sv}})}` (Contact_Presences)
  A dictionary of contact handles mapped to a struct containing a UNIX timestamp of the last activity time (in UTC), and a dictionary mapping the contact's current status identifiers to a dictionary of optional parameter names mapped to their variant-boxed values

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

## Structure types

### Last_Activity_And_Statuses − ( u: Last_Activity, a{sa{sv}}: Statuses )

Structure representing a contact's presence, containing a last-activity time (deprecated) and a Multiple_Status_Map.

Arrays of Last_Activity_And_Statuses don't generally make sense.

#### Members

`Last_Activity` − `u` (Unix_Timestamp)
  (undocumented)
`Statuses` − `a{sa{sv}}` (Multiple_Status_Map)
  (undocumented)

### Status_Spec − ( u: Type, b: May_Set_On_Self, b: Exclusive, a{ss}: Parameter_Types )

Arrays of Status_Spec don't generally make sense.

#### Members

`Type` − `u` (Connection_Presence_Type)
  (undocumented)
`May_Set_On_Self` − `b`
  (undocumented)
`Exclusive` − `b`
  (undocumented)
`Parameter_Types` − `a{ss}` (String_String_Map)
  (undocumented)

## Mapping types

### Multiple_Status_Map − a{ s: Status → a{sv}: Parameters }

Mapping used in Last_Activity_And_Statuses and passed to SetStatus, representing a collection of statuses. Use of this mapping with more than one member is deprecated.

#### Members

`Status` − `s`
  (undocumented)
`Parameters` − `a{sv}` (String_Variant_Map)
  (undocumented)

### Contact_Presences − a{ u: Contact → (ua{sa{sv}}): Presence }

Mapping returned by GetPresence and signalled by PresenceUpdate, where the keys are contacts and the values represent their presences.

#### Members

`Contact` − `u` (Contact_Handle)
  (undocumented)
`Presence` − `(ua{sa{sv}})` (Last_Activity_And_Statuses)
  (undocumented)

### Status_Spec_Map − a{ s: Identifier → (ubba{ss}): Spec }

#### Members

`Identifier` − `s`
  (undocumented)
`Spec` − `(ubba{ss})` (Status_Spec)
  (undocumented)

# 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`

An interface on connections to support protocols where the unique identifiers of contacts can change. Because handles are immutable, this is represented by a pair of handles, that representing the old name, and that representing the new one.

## Methods:

### RequestRename ( s: Name ) → nothing

Request that the user's own identifier is changed on the server. If successful, a Renamed signal will be emitted for the current "self handle" as returned by GetSelfHandle.

It is protocol-dependent how the identifier that's actually used will be derived from the supplied identifier; some sort of normalization might take place.

#### Parameters

`Name` − `s`
  The desired identifier

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  Raised when one of the provided arguments is invalid. (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)

## Signals:

### Renamed ( u: Original, u: New )

Emitted when the unique identifier of a contact on the server changes.

Any channels associated with the contact's original handle will continue to be to that handle, and so are no longer useful (unless the contact renames back, or another contact connects with that unique ID). Clients may open a similar channel associated with the new handle to continue communicating with the contact.

For example, if a GUI client associates text channels with chat windows, it should detach the old channel from the chat window, closing it, and associate a channel to the new handle with the same window.

If the contact's old handle is in any of the member lists of a channel which has the groups interface, it will be removed from the channel and the new handle will be added. The resulting MembersChanged signal must be emitted after the Renamed signal; the reason should be RENAMED.

The handles may be either general-purpose or channel-specific. If the original handle is general-purpose, the new handle must be general-purpose; if the original handle is channel-specific, the new handle must be channel-specific in the same channel.

#### Parameters

`Original` − `u` (Contact_Handle)
  The handle of the original identifier
`New` − `u` (Contact_Handle)
  The handle of the new identifier

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

# org.freedesktop.Telepathy.Connection.Interface.Requests

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.

If this interface is implemented on a connection, then NewChannels MUST be emitted for all new channels, even those created with RequestChannel.

Added in version 0.17.11. (as stable API)

## Methods:

### CreateChannel ( a{sv}: Request ) → o, a{sv}

Request that an entirely new channel is created.

There is deliberately no flag corresponding to the suppress_handler argument to Connection.RequestChannel, because passing a FALSE value for that argument is deprecated. Requests made using this interface always behave as though suppress_handler was TRUE.

Added in version 0.17.11. (as stable API)

Changed in version 0.17.14: It is now guaranteed that CreateChannel returns the channel before NewChannels announces it (the reverse was previously guaranteed).

#### Parameters

`Request` − `a{sv}` (Qualified_Property_Value_Map)

  A dictionary containing desirable properties, which MUST include ChannelType. Some properties are defined such that only an exact match makes sense, and connection managers MUST NOT satisfy a request with a channel where that property does not match; some properties are defined such that the connection manager MAY treat the request as merely a hint, and make a best-effort attempt to satisfy it. This is documented separately for each property.

  If this dictionary contains a property whose semantics are not known to the connection manager, this method MUST fail without side-effects (in particular it must not create a new channel).

  This is necessary if we want to be able to invent properties in future that, when used in a request, are hard requirements rather than just hints. A connection manager that did not know the semantics of those properties could incorrectly return a new channel that did not satisfy the requirements.

  The connection manager MUST NOT respond successfully, and SHOULD NOT create a new channel or cause any other side-effects, unless it can create a new channel that satisfies the client's requirements.

  Properties that will be set by this argument need not have write access after the channel has been created - indeed, it is expected that most will be read-only.

#### Returns

`Channel` − `o`

  The Channel object, which MUST NOT be signalled with NewChannels until after this method returns.

  This allows the requester to alter its handling of NewChannels by knowing whether one of the channels satisfied a request it made.

`Properties` − `a{sv}` (Qualified_Property_Value_Map)

  Properties of the channel that was produced, equivalent to the properties in Channel_Details. Connection managers MUST NOT include properties here whose values can change, for the same reasons as in Channel_Details.

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.NotImplemented`
  The channel request was one that can never succeed, such as requesting an unsupported channel type, or requesting a channel type which this connection manager does not support with the given target handle type.
`org.freedesktop.Telepathy.Error.InvalidHandle`
  An invalid handle was requested as the value of a property whose value is a handle (like Channel.TargetHandle), or a syntactically invalid identifier was requested as the value of a property whose value is the string corresponding to a handle (like Channel.TargetID).
`org.freedesktop.Telepathy.Error.InvalidArgument`
  The request matched the fixed properties of a Requestable_Channel_Class in RequestableChannelClasses, but the allowed arguments did not make sense; for example, a RoomList was requested, but the Server property provided was not a valid DNS name.
`org.freedesktop.Telepathy.Error.NotCapable`
  The requested channel cannot be created because the requested contact is using a client that lacks a particular feature.
`org.freedesktop.Telepathy.Error.Offline`
  The requested channel cannot be created because the target is offline.
`org.freedesktop.Telepathy.Error.NotAvailable`

  The requested channel cannot be created, but in principle, a similar request might succeed in future. For instance, this might be because:

  - a channel matching the request already exists and the protocol requires that only one such channel can exist at a time
  - a channel matching the request has already been requested (by a previous call to CreateChannel, EnsureChannel, Connection.RequestChannel or similar) and the protocol requires that only one such channel can exist at a time
`org.freedesktop.Telepathy.Error.Channel.Banned`
  You are banned from the channel. (generic description)
`org.freedesktop.Telepathy.Error.Channel.Full`
  The channel is full. (generic description)
`org.freedesktop.Telepathy.Error.Channel.InviteOnly`
  The requested channel is invite-only. (generic description)

### EnsureChannel ( a{sv}: Request ) → b, o, a{sv}

Request that channels are ensured to exist.

The connection manager is in the best position to determine which existing channels could satisfy which requests.

Added in version 0.17.12.

Changed in version 0.17.14: It is now guaranteed that if the channel was created by this call to EnsureChannel, it's returned before NewChannels announces it (the reverse was previously guaranteed).

#### Parameters

`Request` − `a{sv}` (Qualified_Property_Value_Map)

  A dictionary containing desirable properties, with the same semantics as the corresponding parameter to CreateChannel.

#### Returns

`Yours` − `b`

  If false, the caller of EnsureChannel MUST assume that some other process is handling this channel; if true, the caller of EnsureChannel SHOULD handle it themselves or delegate it to another client.

  If the creation of a channel makes several calls to EnsureChannel (and no other requests) successful, exactly one of those calls MUST return a true value for this argument.

  If the creation of a channel makes other requests successful, the value returned for this argument MUST be such that exactly one of the clients making requests ends up responsible for the channel. In particular, if CreateChannel returns a channel C, any EnsureChannel calls that also return C MUST return a false value for this argument.

`Channel` − `o`
  The Channel object. If it was created as a result of this method call, it MUST NOT be signalled by NewChannels until after this method returns.
  This allows the requester to alter its handling of NewChannels by knowing whether one of the channels satisfied a request it made.
`Properties` − `a{sv}` (Qualified_Property_Value_Map)

  Properties of the channel that was produced, equivalent to the properties in Channel_Details. Connection managers MUST NOT include properties here whose values can change, for the same reasons as in Channel_Details.

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.NotImplemented`
  The channel request was one that can never succeed, such as requesting an unsupported channel type, or requesting a channel type which this connection manager does not support with the given target handle type.
`org.freedesktop.Telepathy.Error.InvalidHandle`
  An invalid handle was requested as the value of a property whose value is a handle (like Channel.TargetHandle), or a syntactically invalid identifier was requested as the value of a property whose value is the string corresponding to a handle (like Channel.TargetID).
`org.freedesktop.Telepathy.Error.InvalidArgument`
  The request matched the fixed properties of a Requestable_Channel_Class in RequestableChannelClasses, but the allowed arguments did not make sense; for example, a RoomList was requested, but the Server property provided was not a valid DNS name.
`org.freedesktop.Telepathy.Error.NotCapable`
  The requested channel cannot be created because the requested contact is using a client that lacks a particular feature.
`org.freedesktop.Telepathy.Error.Offline`
  The requested channel cannot be created because the target is offline.
`org.freedesktop.Telepathy.Error.NotAvailable`
  The requested channel cannot be created, but in principle, a similar request might succeed in future.
`org.freedesktop.Telepathy.Error.Channel.Banned`
  You are banned from the channel. (generic description)
`org.freedesktop.Telepathy.Error.Channel.Full`
  The channel is full. (generic description)
`org.freedesktop.Telepathy.Error.Channel.InviteOnly`
  The requested channel is invite-only. (generic description)

## Signals:

### NewChannels ( a(oa{sv}): Channels )

New channels have been created. The connection manager SHOULD emit a single signal for any group of closely related channels that are created at the same time, so that the channel dispatcher can try to dispatch them to a handler as a unit.

In particular, if additional channels are created as a side-effect of a call to CreateChannel, these channels SHOULD appear in the same NewChannels signal as the channel that satisfies the request.

Joining a MUC Tube in XMPP requires joining the corresponding MUC (chatroom), so a Text channel can be created as a side-effect.

Every time NewChannels is emitted, it MUST be followed by a Connection.NewChannel signal for each channel.

The double signal emission is for the benefit of older Telepathy clients, which won't be listening for NewChannels.

The more informative NewChannels signal comes first so that clients that did not examine the connection to find out whether Requests is supported will see the more informative signal for each channel first, and then ignore the less informative signal because it announces a new channel of which they are already aware.

Added in version 0.17.11. (as stable API)

Changed in version 0.17.14: Added a guarantee of ordering relative to NewChannel

#### Parameters

`Channels` − `a(oa{sv})` (Channel_Details[])
  The channels and their details. All channels that are signalled together like this MUST have the same Bundle property, which may either refer to an existing bundle, or establish a new bundle.

### ChannelClosed ( o: Removed )

Emitted when a channel is closed and hence disappears from the Channels property.
This is redundant with the Closed signal on the channel itself, but it does provide full change notification for the Channels property.

Added in version 0.17.11. (as stable API)

#### Parameters

`Removed` − `o`
  The channel which has been removed from the Channels property

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.

  Added in version 0.17.11. (as stable API)

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

  Added in version 0.17.11. (as stable API)

## Structure types

### Channel_Details − ( o: Channel, a{sv}: Properties )

Enough details of a channel that clients can work out how to dispatch or handle it.

Added in version 0.17.11. (as stable API)

In bindings that need a separate name, arrays of Channel_Details should be called Channel_Details_List.

#### Members

`Channel` − `o`
  The object path of the channel.
`Properties` − `a{sv}` (Qualified_Property_Value_Map)

  Properties of the channel.

  Connection managers MUST NOT include properties in this mapping if their values can change. Clients MUST ignore properties that appear in this mapping if their values can change.

  If properties that could change were included, the following race condition would be likely to exist in some cases:

  - NewChannels or Get("Channels") includes a property P with value V1
  - Client creates a proxy object for the channel
  - The value of P changes to V2
  - Client connects to PChanged signal
  - Client should call Get("P") or GetAll here, to avoid the race, but client's author has forgotten to do so
  - Proxy object thinks P == V1, but actually P == V2

  We've taken the opportunity to make the API encourage the client author to get it right. Where possible, we intend that properties whose value will be used in channel dispatching or other "early" processing will be defined so that they are immutable (can never change).

  Each dictionary MUST contain the keys org.freedesktop.Telepathy.Channel.ChannelType, org.freedesktop.Telepathy.Channel.TargetHandleType, org.freedesktop.Telepathy.Channel.TargetHandle, org.freedesktop.Telepathy.Channel.TargetID and org.freedesktop.Telepathy.Channel.Requested.

  We expect these to be crucial to the channel-dispatching process.

### Requestable_Channel_Class − ( a{sv}: Fixed_Properties, as: Allowed_Properties )

Structure representing a class of channels that can be requested, identified by a set of properties that identify that class of channel.

This will often just be the channel type and the handle type, but can include other properties of the channel - for instance, encrypted channels might require properties that unencrypted channels do not, like an encryption key.

In some cases, these classes of channel may overlap, in the sense that one class fixes all the properties that another class does, plus some more properties.

For older clients to still be able to understand how to request channels in the presence of a hypothetical "encryption" interface, we'd need to represent it like this:

- class 1: ChannelType = Text, TargetHandleType = CONTACT
- class 2: Channel.ChannelType = Text, Channel.TargetHandleType = CONTACT, Encryption.Encrypted = TRUE

Added in version 0.17.11. (as stable API)

In bindings that need a separate name, arrays of Requestable_Channel_Class should be called Requestable_Channel_Class_List.

#### Members

`Fixed_Properties` − `a{sv}` (Channel_Class)

  The property values that identify this requestable channel class. These properties MUST be included in requests for a channel of this class, and MUST take these values.

  Clients that do not understand the semantics of all the Fixed_Properties MUST NOT request channels of this class, since they would be unable to avoid making an incorrect request.

  This implies that connection managers wishing to make channels available to old or minimal clients SHOULD have a channel class with the minimum number of Fixed_Properties, and MAY additionally have channel classes with extra Fixed_Properties.

`Allowed_Properties` − `as` (DBus_Qualified_Member[])

  Properties that MAY be set when requesting a channel of this channel type and handle type.

  This array MUST NOT include properties that are in the Fixed_Properties mapping.

  Properties in this array may either be required or optional, according to their documented semantics.

  For instance, if TargetHandleType takes a value that is not Handle_Type_None, one or the other of TargetHandle and TargetID is required. Clients are expected to understand the documented relationship between the properties, so we do not have separate arrays of required and optional properties.

  If this array contains the Bundle property, then this class of channel can be combined with other channels with that property in a request, or added to an existing bundle. If not, this signifies that the connection manager is unable to mark channels of this class as part of a bundle - this means that to the remote contact they are likely to be indistinguishable from channels requested separately.

## Mapping types

### Channel_Class − a{ s: Key → v: Value }

Mapping representing a class of channels that can be requested from a connection manager, can be handled by a user interface, are supported by a contact, etc.

Classes of channel are identified by the fixed values of a subset of their properties.

Channel classes SHOULD always include the keys org.freedesktop.Telepathy.Channel.ChannelType and org.freedesktop.Telepathy.Channel.TargetHandleType.

In bindings that need a separate name, arrays of Channel_Class should be called Channel_Class_List.

#### Members

`Key` − `s` (DBus_Qualified_Member)
  A D-Bus interface name, followed by a dot and a D-Bus property name.
`Value` − `v`
  The value of the property.

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

status identifier | Connection_Presence_Type | comments
--- | --- | ---
available | Connection_Presence_Type_Available |
away | Connection_Presence_Type_Away |
brb | Connection_Presence_Type_Away | Be Right Back (a more specific form of Away)
busy | Connection_Presence_Type_Busy |
dnd | Connection_Presence_Type_Busy | Do Not Disturb (a more specific form of Busy)
xa | Connection_Presence_Type_Extended_Away | Extended Away
hidden | Connection_Presence_Type_Hidden | Also known as "Invisible" or "Appear Offline"
offline | Connection_Presence_Type_Offline |
unknown | Connection_Presence_Type_Unknown | special, see below
error | Connection_Presence_Type_Error | special, see below

As well as these well-known status identifiers, every status also has a numerical type value chosen from Connection_Presence_Type 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:

### SetPresence ( s: Status, s: Status_Message ) → nothing

Request that the presence status and status message are published for the connection. Changes will be indicated by PresencesChanged signals being emitted.

This method may be called on a newly-created connection while it is still in the DISCONNECTED state, to request that when the connection connects, it will do so with the selected status.

In DISCONNECTED state the Statuses property will indicate which statuses are allowed to be set while DISCONNECTED (none, if the Connection Manager doesn't allow this). This value MUST NOT be cached, as the set of allowed presences might change upon connecting.

#### Parameters

`Status` − `s`

  The string identifier of the desired status. Possible status identifiers are defined in the Statuses property.

  Clients MUST NOT set a status whose string value they do not recognise, even if its presence type in Statuses matches what the user requested.

  Suppose a protocol has statuses that include 'phone' (of type BUSY) and 'in-a-meeting' (of type BUSY), but there is no generic 'busy' status.

  If the user requests "Busy" status from a menu, a client author might be tempted to pick an arbitrary status that has type BUSY. However, on this protocol, neither of the choices would be appropriate, and incorrect information about the user would be conveyed.

  Statuses whose Connection_Presence_Type is Offline, Error or Unknown MUST NOT be passed to this function. Connection managers SHOULD reject these statuses.

  To go offline, call Disconnect instead. The "error" and "unknown" statuses make no sense.

`Status_Message` − `s`
  The status message associated with the current status.

#### Possible errors

`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  Either the specified status is not supported, the specified status cannot be set on the user themselves, or a non-empty message was supplied for a status that does not accept a message.
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)

### GetPresences ( au: Contacts ) → a{u(uss)}

Get presence previously emitted by PresencesChanged for the given contacts. Data is returned in the same structure as the PresencesChanged signal; no additional network requests are made.

#### Parameters

`Contacts` − `au` (Contact_Handle[])
  An array of the contacts whose presence should be obtained.

#### Returns

`Presence` − `a{u(uss)}` (Simple_Contact_Presences)

  Presence information in the same format as for the PresencesChanged signal. The returned mapping MUST include an entry for each contact in the method's argument.

  The definition of the connection presence types Unknown and Offline means that if a connection manager will return Unknown for contacts not on the subscribe list, it MUST delay the reply to this method call until it has found out which contacts are, in fact, on the subscribe list.

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.InvalidHandle`
  The contact name specified is unknown on this channel or connection. (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  While discovering the subscribe list in order to distinguish between Unknown and Offline statuses, a network error occurred.
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)

## Signals:

### PresencesChanged ( a{u(uss)}: Presence )

This signal should be emitted when your own presence has been changed, or the presence of the member of any of the connection's channels has been changed.

#### Parameters

`Presence` − `a{u(uss)}` (Simple_Contact_Presences)
  A dictionary of contact handles mapped to the status, presence type and status message.

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 are available on 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.

## 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 Statuses property, or in the result of GetStatuses on the deprecated Presence 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.

### Rich_Presence_Access_Control_Type

A type of access control for Rich_Presence_Access_Control. For most types, the exact access control is given by an associated variant.
These are the access control types from XMPP publish/subscribe (XEP-0060).

`Rich_Presence_Access_Control_Type_Whitelist = 0`
  The associated variant is a list of contacts (signature 'au', Contact_Handle[]) who can see the extended presence information.
`Rich_Presence_Access_Control_Type_Publish_List = 1`
  All contacts in the user's 'publish' contact list can see the extended presence information. The associated variant is ignored.
`Rich_Presence_Access_Control_Type_Group = 2`
  The associated variant is a handle of type Group (signature 'u', Group_Handle) representing a group of contacts who can see the extended presence information.
`Rich_Presence_Access_Control_Type_Open = 3`
  Anyone with access to the service can see the extended presence information.

## Structure types

### Simple_Presence − ( u: Type, s: Status, s: Status_Message )

A struct representing the presence of a contact.

Arrays of Simple_Presence don't generally make sense.

#### Members

`Type` − `u` (Connection_Presence_Type)
  The presence type, e.g. Connection_Presence_Type_Away.
`Status` − `s`
  The string identifier of the status, e.g. "brb", as defined in the Statuses property.
`Status_Message` − `s`

  The user-defined status message, e.g. "Back soon!".

  Clients SHOULD set the status message for the local user to the empty string, unless the user has actually provided a specific message (i.e. one that conveys more information than the Status).

  User interfaces SHOULD regard an empty status message as unset, and MAY replace it with a localized string corresponding to the Status or Type.

  Use case: Daf sets his status in Empathy by choosing the Welsh translation of "Available" from a menu. It is more informative for his English-speaking colleagues to see the English translation of "Available" (as localized by their own clients) than to see "Ar Gael" (which they don't understand anyway).

### Simple_Status_Spec − ( u: Type, b: May_Set_On_Self, b: Can_Have_Message )

A struct containing information about a status.

Arrays of Simple_Status_Spec don't generally make sense.

#### Members

`Type` − `u` (Connection_Presence_Type)
  The type of a presence. This SHOULD NOT be used as a way to set statuses that the client does not recognise (as explained in SetPresence), but MAY be used to check that the client's assumptions about a particular status name match the connection manager's.
`May_Set_On_Self` − `b`
  If true, the user can set this status on themselves using SetPresence.
`Can_Have_Message` − `b`
  If true, a non-empty message can be set for this status. Otherwise, the empty string is the only acceptable message.
  On IRC you can be Away with a status message, but if you are available you cannot set a status message.

### Rich_Presence_Access_Control − ( u: Type, v: Detail )

An access control mode for extended presence items like geolocation. This type isn't actually used by the SimplePresence interface, but it's included here so it can be referenced by rich presence interfaces such as Location.DRAFT.

Arrays of Rich_Presence_Access_Control don't generally make sense.

#### Members

`Type` − `u` (Rich_Presence_Access_Control_Type)
  The type of access control to apply.
`Detail` − `v`
  Any additional information required by the Type. The required type and semantics are defined for each Rich_Presence_Access_Control_Type.

## Mapping types

### Simple_Contact_Presences − a{ u: Contact → (uss): Presence }

Mapping returned by GetPresences and signalled by PresencesChanged, indicating the presence of a number of contacts.

#### Members

`Contact` − `u` (Contact_Handle)
  A contact
`Presence` − `(uss)` (Simple_Presence)
  The contact's presence

### Simple_Status_Spec_Map − a{ s: Identifier → (ubb): Spec }

A mapping describing possible statuses.

#### Members

`Identifier` − `s`
  The string identifier of this status.
`Spec` − `(ubb)` (Simple_Status_Spec)
  Details of this status.

# 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's object path MUST start with the object path of its associated Connection, followed by '/'. There MAY be any number of additional object-path components, which clients MUST NOT attempt to parse.

This ensures that Channel object paths are unique, even between Connections and CMs, because Connection object paths are guaranteed-unique via their link to the well-known bus name.

If all connection managers in use are known to comply with at least spec version 0.17.10, then the Connection's object path can even be determined from the Channel's without any additional information, by taking the first 7 components.

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.

Changed in version 0.17.10: Previously we did not explicitly guarantee that Channels' object paths had the Connection's object path as a prefix.

## Methods:

### Close ( ) → nothing

Request that the channel be closed. This is not the case until the Closed signal has been emitted, and depending on the connection manager this may simply remove you from the channel on the server, rather than causing it to stop existing entirely. Some channels such as contact list channels may not be closed.

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.NotImplemented`
  This channel may never be closed, e.g. a contact list
`org.freedesktop.Telepathy.Error.NotAvailable`
  This channel is not currently in a state where it can be closed, e.g. a non-empty user-defined contact group

### GetChannelType ( ) → s

Returns the interface name for the type of this channel. Clients SHOULD use the ChannelType property instead, falling back to this method only if necessary.
The GetAll method lets clients retrieve all properties in one round-trip.

Deprecated since version 0.17.7. Use the ChannelType property if possible.

#### Returns

`Channel_Type` − `s` (DBus_Interface)
  The interface name

### GetHandle ( ) → u, u

Returns the handle type and number if this channel represents a communication with a particular contact, room or server-stored list, or zero if it is transient and defined only by its contents. Clients SHOULD use the TargetHandle and TargetHandleType properties instead, falling back to this method only if necessary.
The GetAll method lets clients retrieve all properties in one round-trip.

Deprecated since version 0.17.7. Use the TargetHandleType and TargetHandle properties if possible.

#### Returns

`Target_Handle_Type` − `u` (Handle_Type)
  The same as TargetHandleType.
`Target_Handle` − `u` (Handle)
  The same as TargetHandle.

### GetInterfaces ( ) → as

Get the optional interfaces implemented by the channel. Clients SHOULD use the Interfaces property instead, falling back to this method only if necessary.
The GetAll method lets clients retrieve all properties in one round-trip.

Deprecated since version 0.17.7. Use the Interfaces property if possible.

#### Returns

`Interfaces` − `as` (DBus_Interface[])
  An array of the D-Bus interface names

## Signals:

### Closed ( )

Emitted when the channel has been closed. Method calls on the channel are no longer valid after this signal has been emitted, and the connection manager may then remove the object from the bus at any point.

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.

`Requested` − `b`, read-only

  True if this channel was created in response to a local request, such as a call to Connection.RequestChannel or Connection.Interface.Requests.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.

  It does not make sense for this property to be in channel requests—it will always be true for channels returned by CreateChannel, and callers of EnsureChannel cannot control whether an existing channel was originally requested locally—so it MUST NOT be accepted.

  Added in version 0.17.13. (as stable API)

`InitiatorHandle` − `u` (Contact_Handle), read-only

  The contact who initiated the channel. For channels requested by the local user, this MUST be the value of Connection.SelfHandle at the time the channel was created (i.e. not a channel-specific handle).

  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.13. (as stable API)

`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.13. (as stable API)

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

If we add new functionality to the Channel interface, libraries that use generated code (notably telepathy-glib) will have it as part of their ABI forever, meaning we can't make incompatible changes. By using this interface as a staging area for future Channel functionality, we can try out new properties, signals and methods as application-specific extensions, then merge them into the core Channel interface when we have enough implementation experience to declare them to be stable.

The name is by analogy to Python's `__future__` pseudo-module.

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.

`Bundle` − `o`, read-only

  The ChannelBundle.DRAFT 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 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
- stored - on protocols where the user's contacts are stored, this contact list contains all stored contacts regardless of subscription status.

A contact can be in several server-defined lists. All lists are optional to implement. If RequestHandles or RequestChannel for a particular contact list raises an error, this indicates that the connection manager makes no particular statement about the list's contents; clients MUST NOT consider this to be fatal.

If a client wants to list all of a user's contacts, it is appropriate to use the union of the subscribe, publish and stored lists, including the local and remote pending members.

For example in XMPP, contacts who have the subscription type "none", "from", "to" and "both" can be respectively in the lists:

- "none": stored
- "from": stored and publish
- "to": stored and subscribe
- "both": stored, publish and subscribe

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 calling Close on 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.

To make a media call to a contact, clients should call CreateChannel with ChannelType = StreamedMedia, TargetHandleType = Contact, and one of TargetHandle or TargetID (which should yield a channel with the local user in Members, and the remote contact as TargetHandle but not in any group members list), then call RequestStreams to initiate the call (at which point the contact should appear in the channel's RemotePendingMembers).

In the past, several other patterns have been used to place outgoing calls; see 'Requesting StreamedMedia Channels' on the Telepathy wiki for the details.

Incoming calls should be signalled as TargetHandleType = Contact, TargetHandle set to the remote contact, with the local user in LocalPendingMembers; to accept the call, AddMembers can be used to move the local user to the group's members.

When the local user accepts an incoming call, the connection manager SHOULD change the direction of any streams with pending local send to be sending, without altering whether those streams are receiving.

This matches existing practice, and means that a client can answer incoming calls and get an unmuted microphone/activated webcam without having to take additional action to accept the stream directions.

It does, however, introduce a race condition: a client believing that it is accepting an audio-only call by calling AddMembers can inadvertantly accept an audio + video call (and hence activate sending from a webcam without the user's permission) if a video stream is added just before AddMembers is processed. This race should be removed when this specification is revised.

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:

### ListStreams ( ) → a(uuuuuu)

Returns an array of structs representing the streams currently active within this channel. Each stream is identified by an unsigned integer which is unique for each stream within the channel.

#### Returns

`Streams` − `a(uuuuuu)` (Media_Stream_Info[])
  An array of structs containing:
  - the stream identifier
  - the contact handle who the stream is with (or 0 if the stream represents more than a single member)
  - the type of the stream
  - the current stream state
  - the current direction of the stream
  - the current pending send flags

### RemoveStreams ( au: Streams ) → nothing

Request that the given streams are removed. If all streams are removed, the channel MAY close.

Clients SHOULD NOT attempt to terminate calls by removing all the streams; instead, clients SHOULD terminate calls by removing the Group.SelfHandle from the channel, using either RemoveMembers or RemoveMembersWithReason.

#### Parameters

`Streams` − `au` (Stream_ID[])
  An array of stream identifiers (as defined in ListStreams)

#### Possible errors

`org.freedesktop.Telepathy.Error.InvalidArgument`
  Raised when one of the provided arguments is invalid. (generic description)

### RequestStreamDirection ( u: Stream_ID, u: Stream_Direction ) → nothing

Request a change in the direction of an existing stream. In particular, this might be useful to stop sending media of a particular type, or inform the peer that you are no longer using media that is being sent to you.

Depending on the protocol, streams which are no longer sending in either direction should be removed and a StreamRemoved signal emitted. Some direction changes can be enforced locally (for example, BIDIRECTIONAL -> RECEIVE can be achieved by merely stopping sending), others may not be possible on some protocols, and some need agreement from the remote end. In this case, the MEDIA_STREAM_PENDING_REMOTE_SEND flag will be set in the StreamDirectionChanged signal, and the signal emitted again without the flag to indicate the resulting direction when the remote end has accepted or rejected the change.

#### Parameters

`Stream_ID` − `u`
  The stream identifier (as defined in ListStreams)
`Stream_Direction` − `u` (Media_Stream_Direction)
  The desired stream direction (a value of MediaStreamDirection)

#### Possible errors

`org.freedesktop.Telepathy.Error.InvalidArgument`
  Raised when one of the provided arguments is invalid. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)

### RequestStreams ( u: Contact_Handle, au: Types ) → a(uuuuuu)

Request that streams be established to exchange the given types of media with the given member. In general this will try and establish a bidirectional stream, but on some protocols it may not be possible to indicate to the peer that you would like to receive media, so a send-only stream will be created initially. In the cases where the stream requires remote agreement (eg you wish to receive media from them), the StreamDirectionChanged signal will be emitted with the MEDIA_STREAM_PENDING_REMOTE_SEND flag set, and the signal emitted again with the flag cleared when the remote end has replied.

If streams of the requested types already exist, calling this method results in the creation of additional streams. Accordingly, clients wishing to have exactly one audio stream or exactly one video stream SHOULD check for the current streams using ListStreams before calling this method.

Changed in version 0.17.2: It is valid to use a handle which is neither a current nor pending member in this channel's Group interface. If so, that handle will be added to the remote-pending set only when an attempt has actually been made to contact them. For further call-state notification, use the CallState interface, if supported. This usage was not allowed in spec versions below 0.17.2.

#### Parameters

`Contact_Handle` − `u` (Contact_Handle)
  A contact handle with whom to establish the streams
`Types` − `au` (Media_Stream_Type[])
  An array of stream types (values of MediaStreamType)

#### Returns

`Streams` − `a(uuuuuu)` (Media_Stream_Info[])
  An array of structs (in the same order as the given stream types) containing:
  - the stream identifier
  - the contact handle who the stream is with (or 0 if the stream represents more than a single member)
  - the type of the stream
  - the current stream state
  - the current direction of the stream
  - the current pending send flags

#### Possible errors

`org.freedesktop.Telepathy.Error.InvalidHandle`
  The contact name specified is unknown on this channel or connection. (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  A stream type given is invalid.
`org.freedesktop.Telepathy.Error.NotImplemented`
  A stream type given is not implemented by the connection manager. Since 0.17.23, connection managers SHOULD raise this error in preference to InvalidArgument.
  Connection managers can't know whether an unknown number is a valid stream type that was introduced in a later spec version.
`org.freedesktop.Telepathy.Error.NotAvailable`
  That contact's client does not implement one of the given stream types. For this method, clients SHOULD consider this error and NotCapable to be equivalent.
`org.freedesktop.Telepathy.Error.NotCapable`
  That contact's client does not implement one of the given stream types. Since 0.17.23, connection managers SHOULD raise this in preference to NotAvailable.

## Signals:

### StreamAdded ( u: Stream_ID, u: Contact_Handle, u: Stream_Type )

Emitted when a new stream has been added to this channel. Clients SHOULD assume that the stream's Media_Stream_State is initially Disconnected.

If a connection manager needs to represent the addition of a stream whose state is already Connecting or Connected, it MUST do this by emitting StreamAdded, closely followed by StreamStateChanged indicating a change to the appropriate state.

Historically, it was not clear from the StreamAdded signal what the state of the stream was. telepathy-spec 0.17.22 clarified this.

Similarly, clients SHOULD assume that the initial Media_Stream_Direction of a newly added stream is Receive, and that the initial Media_Stream_Pending_Send is Pending_Local_Send.

If a connection manager needs to represent the addition of a stream whose direction or pending-send differs from those initial values, it MUST do so by emitting StreamAdded, closely followed by StreamDirectionChanged indicating a change to the appropriate direction and pending-send state.

StreamAdded doesn't itself indicate the stream's direction; this is unfortunate, but is preserved for compatibility.

This is the appropriate direction for streams added by a remote contact on existing connection managers, and does not violate user privacy by automatically sending audio or video (audio streams start off muted, video streams start off not sending). For streams added by the local user using the client receiving the signal, the true direction can also be determined from the return value of the RequestStreams method.

Existing clients typically operate by maintaining a separate idea of the directions that they would like the streams to have, and enforcing these intended directions by calling RequestStreamDirection whenever needed.

#### Parameters

`Stream_ID` − `u`
  The stream identifier (as defined in ListStreams)
`Contact_Handle` − `u` (Contact_Handle)
  The contact handle who the stream is with (or 0 if it represents more than a single member)
`Stream_Type` − `u` (Media_Stream_Type)
  The stream type (a value from MediaStreamType)

### StreamDirectionChanged ( u: Stream_ID, u: Stream_Direction, u: Pending_Flags )

Emitted when the direction or pending flags of a stream are changed.

If the MEDIA_STREAM_PENDING_LOCAL_SEND flag is set, the remote user has requested that we begin sending on this stream. RequestStreamDirection should be called to indicate whether or not this change is acceptable.

This allows for a MSN-style user interface, "Fred has asked you to enable your webcam. (Accept | Reject)", if desired.

#### Parameters

`Stream_ID` − `u`
  The stream identifier (as defined in ListStreams)
`Stream_Direction` − `u` (Media_Stream_Direction)
  The new stream direction (as defined in ListStreams)
`Pending_Flags` − `u` (Media_Stream_Pending_Send)
  The new pending send flags (as defined in ListStreams)

### StreamError ( u: Stream_ID, u: Error_Code, s: Message )

Emitted when a stream encounters an error.

#### Parameters

`Stream_ID` − `u`
  The stream identifier (as defined in ListStreams)
`Error_Code` − `u` (Media_Stream_Error)
  A stream error number, one of the values of MediaStreamError
`Message` − `s`
  A string describing the error (for debugging purposes only)

### StreamRemoved ( u: Stream_ID )

Emitted when a stream has been removed from this channel.

#### Parameters

`Stream_ID` − `u`
  stream_id - the stream identifier (as defined in ListStreams)

### StreamStateChanged ( u: Stream_ID, u: Stream_State )

Emitted when a member's stream's state changes.

#### Parameters

`Stream_ID` − `u`
  The stream identifier (as defined in ListStreams)
`Stream_State` − `u` (Media_Stream_State)
  The new stream state (as defined in ListStreams)

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

## Simple types

### Stream_ID − u

An unsigned integer identifying a stream within a channel.

## 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

The channel-type-specific capability flags used for Channel.Type.StreamedMedia in the Connection.Interface.Capabilities interface. See the FUTURE.InitialAudio property for details of the mechanisms that will replace this.

`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.
`Channel_Media_Capability_NAT_Traversal_ICE_UDP = 16`
  The handle is capable of establishing ICE UDP peer-to-peer connections (as defined by the IETF MMUSIC working group) to traverse NATs.

## Structure types

### Media_Stream_Info − ( u: Identifier, u: Contact, u: Type, u: State, u: Direction, u: Pending_Send_Flags )

In bindings that need a separate name, arrays of Media_Stream_Info should be called Media_Stream_Info_List.

#### Members

`Identifier` − `u` (Stream_ID)
  (undocumented)
`Contact` − `u` (Contact_Handle)
  (undocumented)
`Type` − `u` (Media_Stream_Type)
  (undocumented)
`State` − `u` (Media_Stream_State)
  (undocumented)
`Direction` − `u` (Media_Stream_Direction)
  (undocumented)
`Pending_Send_Flags` − `u` (Media_Stream_Pending_Send)
  (undocumented)

# org.freedesktop.Telepathy.Channel.Type.StreamedMedia.FUTURE

Implementations of this interface must also implement:

- `org.freedesktop.Telepathy.Channel`
- `org.freedesktop.Telepathy.Channel.Type.StreamedMedia`

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

The rationale is the same as for Channel.FUTURE.

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.

`InitialAudio` − `b`, read-only

  If set to true in a channel request that will create a new channel, the connection manager should immediately attempt to establish an audio stream to the remote contact, making it unnecessary for the client to call RequestStreams.

  If this property, or InitialVideo, is passed to EnsureChannel (as opposed to CreateChannel), the connection manager SHOULD ignore these properties when checking whether it can return an existing channel as suitable; these properties only become significant when the connection manager has decided to create a new channel.

  If true on a requested channel, this indicates that the audio stream has already been requested and the client does not need to call RequestStreams, although it MAY still do so.

  If true on an unrequested (incoming) channel, this indicates that the remote contact initially requested an audio stream; this does not imply that that audio stream is still active (as indicated by ListStreams).

  This property is immutable (cannot change), and therefore SHOULD appear wherever immutable properties are reported, e.g. NewChannels signals.

  This reduces D-Bus round trips.

  Connection managers capable of signalling audio calls to contacts SHOULD include a channel class in RequestableChannelClasses with ChannelType = StreamedMedia and TargetHandleType = Contact in the fixed properties dictionary, and InitialAudio (and also InitialVideo, if applicable) in the allowed properties list. Clients wishing to discover whether a connection manager can signal audio and/or video calls SHOULD use this information.

  Not all protocols support signalling video calls, and it would be possible (although unlikely) to have a protocol where only video, and not audio, could be signalled.

  Connection managers that support the ContactCapabilities.DRAFT interface SHOULD represent the capabilities of receiving audio and/or video calls by including a channel class in a contact's capabilities with ChannelType = StreamedMedia in the fixed properties dictionary, and InitialAudio and/or InitialVideo in the allowed properties list. Clients wishing to discover whether a particular contact is likely to be able to receive audio and/or video calls SHOULD use this information.

  Not all clients support video calls, and it would also be possible (although unlikely) to have a client which could only stream video, not audio.

  Clients that are willing to receive audio and/or video calls SHOULD include the following filters if calling SetSelfCapabilities (clients of a ChannelDispatcher SHOULD instead arrange for the ChannelDispatcher to do this, by including the filters in their HandlerChannelFilter properties):

  - { ChannelType = StreamedMedia }
  - { ChannelType = StreamedMedia, InitialAudio = true } if receiving calls with audio is supported
  - { ChannelType = StreamedMedia, InitialVideo = true } if receiving calls with video is supported

  Connection managers for protocols with capability discovery, like XMPP, need this information to advertise the appropriate capabilities for their protocol.

`InitialVideo` − `b`, read-only

  The same as InitialAudio, but for a video stream. This property is immutable (cannot change).

  In particular, note that if this property is false, this does not imply that an active video stream has not been added, only that no video stream was active at the time the channel appeared.

  This property is the correct way to discover whether connection managers, contacts etc. support video calls; it appears in capabilities structures in the same way as InitialAudio.

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

### GetListingRooms ( ) → b

Check to see if there is already a room list request in progress on this channel.

#### Returns

`In_Progress` − `b`
  A boolean indicating if room listing is in progress

### ListRooms ( ) → nothing

Request the list of rooms from the server. The ListingRooms (True) signal should be emitted when this request is being processed, GotRooms when any room information is received, and ListingRooms (False) when the request is complete.

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)

### StopListing ( ) → nothing

Stop the room listing if it's in progress, but don't close the channel. The ListingRooms (False) signal should be emitted when the listing stops.

## Signals:

### GotRooms ( a(usa{sv}): Rooms )

Emitted when information about rooms on the server becomes available. The array contains the room handle (as can be passed to the RequestChannel method with HANDLE_TYPE_ROOM), the channel type, and a dictionary containing further information about the room as available. The following well-known keys and types are recommended for use where appropriate:

handle-name (s)
  The string name of the room handle (as would be returned by InspectHandles)
name (s)
  The human-readable name of the room if different from the handle
description (s)
  A description of the room's overall purpose
subject (s)
  The current subject of conversation in the room
members (u)
  The number of members in the room
password (b)
  True if the room requires a password to enter
invite-only (b)
  True if you cannot join the room, but must be invited

#### Parameters

`Rooms` − `a(usa{sv})` (Room_Info[])
  An array of structs containing:
  - an integer room handle
  - a string representing the D-Bus interface name of the channel type
  - a dictionary mapping string keys to variant boxed information

### ListingRooms ( b: Listing )

Emitted to indicate whether or not room listing request is currently in progress.

#### Parameters

`Listing` − `b`
  A boolean indicating if room listing is in progress

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

### Room_Info − ( u: Handle, s: Channel_Type, a{sv}: Info )

In bindings that need a separate name, arrays of Room_Info should be called Room_Info_List.

#### Members

`Handle` − `u` (Room_Handle)
  (undocumented)
`Channel_Type` − `s` (DBus_Interface)
  (undocumented)
`Info` − `a{sv}` (String_Variant_Map)
  (undocumented)

# 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 AcknowledgePendingMessages 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 Channel_Text_Message_Type.

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

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.

If a channel of type Text is closed while it has pending messages, the connection manager MUST allow this, but SHOULD open a new, identical channel to deliver those messages, signalling it as a new channel with the NewChannel signal (with the suppress_handler parameter set to FALSE).

If messages were sent on the old channel but the Sentsignal has not yet been emitted for those messages, the new channel SHOULD emit Sent for those messages when appropriate - it behaves like a continuation of the old channel.

In effect, this turns this situation, in which a client is likely to lose messages:

- UI window is closed
- message arrives
- text channel emits Received
- UI calls Close on text channel before it has seen the Received signal
- text channel emits Closed and closes

into something nearly equivalent to this situation, which is fine:

- UI window is closed
- UI calls Close on text channel
- text channel emits Closed and closes
- message arrives
- new text channel is created, connection emits NewChannel
- (the same or a different) UI handles it

suppress_handler must be set to FALSE so the replacement channel will be handled by something.

As a result, Text channels SHOULD implement Channel.Interface.Destroyable.

This "respawning" behaviour becomes problematic if there is no suitable handler for Text channels, or if a particular message repeatedly crashes the Text channel handler; a channel dispatcher can't just Close() the channel in these situations, because it will come back.

In these situations, the channel dispatcher needs a last-resort way to destroy the channel and stop it respawning. It could either acknowledge the messages itself, or use the Destroyable interface; the Destroyable interface has the advantage that it's not channel-type-dependent, so the channel dispatcher only has to understand one extra interface, however many channel types eventually need a distinction between Close and Destroy.

## Methods:

### AcknowledgePendingMessages ( au: IDs ) → nothing

Inform the channel that you have handled messages by displaying them to the user (or equivalent), so they can be removed from the pending queue.

#### Parameters

`IDs` − `au` (Message_ID[])
  The IDs of the messages to acknowledge

#### Possible errors

`org.freedesktop.Telepathy.Error.InvalidArgument`
  A given message ID was not found, so no action was taken

### GetMessageTypes ( ) → au

Return an array indicating which types of message may be sent on this channel.

#### Returns

`Available_Types` − `au` (Channel_Text_Message_Type[])
  An array of integer message types (ChannelTextMessageType)

### ListPendingMessages ( b: Clear ) → a(uuuuus)

List the messages currently in the pending queue, and optionally remove then all.

#### Parameters

`Clear` − `b`
  If true, behave as if AcknowledgePendingMessages had also been called.

#### Returns

`Pending_Messages` − `a(uuuuus)` (Pending_Text_Message[])
  An array of structs representing the pending queue. Each contains:
  - a numeric identifier
  - a Unix timestamp indicating when the message was received
  - the contact handle for the contact who sent the message
  - the message type, taken from ChannelTextMessageType
  - the bitwise-OR of the message flags from ChannelTextMessageFlags
  - the text of the message

### Send ( u: Type, s: Text ) → nothing

Request that a message be sent on this channel. When the message has been submitted for delivery, this method will return and the Sent signal will be emitted. If the message cannot be submitted for delivery, the method returns an error and no signal is emitted.

This method SHOULD return before the Sent signal is emitted.

When a Text channel implements the Messages interface, that "SHOULD" becomes a "MUST".

#### Parameters

`Type` − `u` (Channel_Text_Message_Type)
  An integer indicating the type of the message
`Text` − `s`
  The message to send

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  Raised when one of the provided arguments is invalid. (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)

## Signals:

### LostMessage ( )

This signal is emitted to indicate that an incoming message was not able to be stored and forwarded by the connection manager due to lack of memory.

### Received ( u: ID, u: Timestamp, u: Sender, u: Type, u: Flags, s: Text )

Signals that a message with the given id, timestamp, sender, type and text has been received on this channel. Applications that catch this signal and reliably inform the user of the message should acknowledge that they have dealt with the message with the AcknowledgePendingMessages method.

#### Parameters

`ID` − `u`
  A numeric identifier for acknowledging the message
`Timestamp` − `u` (Unix_Timestamp)
  A Unix timestamp indicating when the message was received
`Sender` − `u` (Contact_Handle)
  The handle of the contact who sent the message
`Type` − `u` (Channel_Text_Message_Type)
  The type of the message (normal, action, notice, etc.)
`Flags` − `u` (Channel_Text_Message_Flags)
  A bitwise OR of the message flags
`Text` − `s`
  The text of the message

### SendError ( u: Error, u: Timestamp, u: Type, s: Text )

Signals that an outgoing message has failed to send. The error will be one of the values from ChannelTextSendError.

This signal should only be emitted for messages for which Sent has already been emitted and Send has already returned success.

Changed in version 0.17.3: older spec versions claimed that SendError was emitted instead of Sent, rather than in addition to Sent. However, the 0.17.3+ semantics were what we'd always actually implemented.

#### Parameters

`Error` − `u` (Channel_Text_Send_Error)
  The error that occurred
`Timestamp` − `u` (Unix_Timestamp)
  The Unix timestamp indicating when the message was sent
`Type` − `u` (Channel_Text_Message_Type)
  The message type
`Text` − `s`
  The text of the message

### Sent ( u: Timestamp, u: Type, s: Text )

Signals that a message has been submitted for sending.

#### Parameters

`Timestamp` − `u` (Unix_Timestamp)
  Unix timestamp indicating when the message was sent
`Type` − `u` (Channel_Text_Message_Type)
  The message type (normal, action, notice, etc) from ChannelTextMessageType
`Text` − `s`
  The text of the message. If the message was, or will be, altered during transmission, this argument SHOULD reflect what other contacts will receive rather than being a copy of the argument to Send.

## 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

### Message_ID − u

A unique-per-channel identifier for an incoming message. These SHOULD be allocated in a way that minimizes collisions (in particular, message IDs SHOULD NOT be re-used until all of the 32-bit integer space has already been used).

## 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

The type of message.

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

`Channel_Text_Message_Flag_Scrollback = 4`

  The incoming message was part of a replay of message history.

  In XMPP multi-user chat, a few past messages are replayed when you join a chatroom. A sufficiently capable IRC connection manager could also set this flag on historical messages when connected to a proxy like bip or irssi-proxy. The existence of this flag allows loggers and UIs to use better heuristics when eliminating duplicates (a simple implementation made possible by this flag would be to avoid logging scrollback at all).

`Channel_Text_Message_Flag_Rescued = 8`

  The incoming message has been seen in a previous channel during the lifetime of the Connection, but had not been acknowledged when that channel closed, causing an identical channel (the channel in which the message now appears) to open.

  This means that a logger (which should already have seen the message in the previous channel) is able to recognise and ignore these replayed messages.

## Structure types

### Pending_Text_Message − ( u: Identifier, u: Unix_Timestamp, u: Sender, u: Message_Type, u: Flags, s: Text )

A struct (message ID, timestamp in seconds since 1970-01-01 00:00 UTC, sender's handle, message type, flags, text) representing a pending text message, as returned by ListPendingMessages. The arguments of the Received signal also match this struct's signature.

In bindings that need a separate name, arrays of Pending_Text_Message should be called Pending_Text_Message_List.

#### Members

`Identifier` − `u` (Message_ID)
  (undocumented)
`Unix_Timestamp` − `u` (Unix_Timestamp)
  (undocumented)
`Sender` − `u` (Contact_Handle)
  (undocumented)
`Message_Type` − `u` (Channel_Text_Message_Type)
  (undocumented)
`Flags` − `u` (Channel_Text_Message_Flags)
  (undocumented)
`Text` − `s`
  (undocumented)

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

Deprecated since version 0.17.25. Client implementations SHOULD use StreamTube and DBusTube instead.

## Methods:

### GetAvailableStreamTubeTypes ( ) → a{uau}

List the available address types and access-control types for stream tubes.

#### Returns

`Available_Stream_Tube_Types` − `a{uau}` (Supported_Socket_Map)

  A mapping from address types (members of Socket_Address_Type) to arrays of access-control type (members of Socket_Access_Control) that the connection manager supports for stream tubes with that address type. For simplicity, if a CM supports offering a particular type of tube, it is assumed to support accepting it.

  A typical value for a host without IPv6 support:

                  {
                    Socket_Address_Type_IPv4:
                      [Socket_Access_Control_Localhost, Socket_Access_Control_Port,
                       Socket_Access_Control_Netmask],
                    Socket_Address_Type_Unix:
                      [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
                  }

  If stream tubes are not supported, this will be an empty dictionary.

### GetAvailableTubeTypes ( ) → au

#### Returns

`Available_Tube_Types` − `au` (Tube_Type[])
  An array of the available tube types, as defined by the Tube_Type enum.

### ListTubes ( ) → a(uuusa{sv}u)

#### Returns

`Tubes` − `a(uuusa{sv}u)` (Tube_Info[])
  Return an array of tuples, each representing a tube, with the following members: the tube's ID the tube's initiator the tube's type the tube's service the tube's parameters the tube's state

### OfferDBusTube ( s: Service, a{sv}: Parameters ) → u

Offers a D-Bus tube providing the service specified.

#### Parameters

`Service` − `s`
  A string representing the service name that will be used over the tube. It should be a well-known D-Bus service name, of the form com.example.ServiceName.
`Parameters` − `a{sv}` (String_Variant_Map)
  A dictionary of properties for the new tube; the allowable keys, types and values are defined by the service. Connection managers must support the value being any primitive (non-container) D-Bus type, or a byte array 'ay'.

#### Returns

`Tube_ID` − `u` (Tube_ID)
  The ID of the new tube.

#### Possible errors

`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  The contact associated with this channel doesn't have tubes capabilities.
`org.freedesktop.Telepathy.Error.NotImplemented`
  The connection manager doesn't support D-Bus tubes.

### OfferStreamTube ( s: Service, a{sv}: Parameters, u: Address_Type, v: Address, u: Access_Control, v: Access_Control_Param ) → u

Offer a stream tube exporting the local socket specified.

#### Parameters

`Service` − `s`
  A string representing the service name that will be used over the tube. It should be a well-known TCP service name as defined by http://www.iana.org/assignments/port-numbers or http://www.dns-sd.org/ServiceTypes.html, for instance "rsync" or "daap".
`Parameters` − `a{sv}` (String_Variant_Map)

  A dictionary of properties for the new tube; the allowable keys, types and values are defined by the service. Connection managers must support the value being any primitive (non-container) D-Bus type, or a byte array 'ay'.

  These should usually be the same key-value pairs specified for use in the DNS-SD TXT record for that service.

`Address_Type` − `u` (Socket_Address_Type)
  The type of the listening address of the local service, as a member of Socket_Address_Type.
`Address` − `v`
  The listening address of the local service, as indicated by the address_type.
`Access_Control` − `u` (Socket_Access_Control)
  The access control the local service applies to the local socket, specified so the connection manager can behave appropriately when it connects.
`Access_Control_Param` − `v`
  A parameter for the access control type, to be interpreted as specified in the documentation for the Socket_Access_Control enum.

#### Returns

`Tube_ID` − `u` (Tube_ID)
  The ID of the new tube.

#### Possible errors

`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  The contact associated with this channel doesn't have tube capabilities.
`org.freedesktop.Telepathy.Error.NotImplemented`
  The connection manager doesn't support stream tubes, or does not support the given address type or access-control type.

### AcceptDBusTube ( u: ID ) → s

Accept a D-Bus tube that's in the "local pending" state. The connection manager will attempt to open the tube. The tube remains in the "local pending" state until the TubeStateChanged signal is emitted.

#### Parameters

`ID` − `u` (Tube_ID)
  The ID of the tube to accept.

#### Returns

`Address` − `s`
  The string describing the address of the private bus. The client should not attempt to connect to the address until the tube is open.

#### Possible errors

`org.freedesktop.Telepathy.Error.InvalidArgument`
  The given tube ID is invalid or does not refer to a D-Bus tube.

### AcceptStreamTube ( u: ID, u: Address_Type, u: Access_Control, v: Access_Control_Param ) → v

Accept a stream tube that's in the "local pending" state. The connection manager will attempt to open the tube. The tube remains in the "local pending" state until the TubeStateChanged signal is emitted.

#### Parameters

`ID` − `u` (Tube_ID)
  The ID of the tube to accept.
`Address_Type` − `u` (Socket_Address_Type)
  The type of address the connection manager should listen on.
`Access_Control` − `u` (Socket_Access_Control)
  The type of access control the connection manager should apply to the socket.
`Access_Control_Param` − `v`
  A parameter for the access control type, to be interpreted as specified in the documentation for the Socket_Access_Control enum.

#### Returns

`Address` − `v`
  The address on which the connection manager will listen for connections to this tube. The client should not attempt to connect to the address until the tube is open.

#### Possible errors

`org.freedesktop.Telepathy.Error.InvalidArgument`
  The given tube ID is invalid or does not refer to a stream tube.
`org.freedesktop.Telepathy.Error.NotImplemented`
  The given address type or access-control mechanism is not supported.

### CloseTube ( u: ID ) → nothing

Close a tube.

#### Parameters

`ID` − `u` (Tube_ID)
  The ID of the tube to close.

#### Possible errors

`org.freedesktop.Telepathy.Error.InvalidArgument`
  Raised when one of the provided arguments is invalid. (generic description)

### GetDBusTubeAddress ( u: ID ) → s

For a D-Bus tube, return a string describing the address of the private bus.

#### Parameters

`ID` − `u` (Tube_ID)
  The ID of the tube to get an address for.

#### Returns

`Address` − `s`
  The bus address.

#### Possible errors

`org.freedesktop.Telepathy.Error.InvalidArgument`
  The tube is not a D-Bus tube.
`org.freedesktop.Telepathy.Error.NotAvailable`
  This tube is not in the "open" state.

### GetDBusNames ( u: ID ) → a(us)

For a multi-user (i.e. Handle_Type_Room) D-Bus tube, obtain a mapping between contact handles and their unique bus names on this tube.

#### Parameters

`ID` − `u` (Tube_ID)
  The ID of the tube to get names for.

#### Returns

`DBus_Names` − `a(us)` (DBus_Tube_Member[])
  An array of structures, each containing a contact handle and a D-Bus bus name.

#### Possible errors

`org.freedesktop.Telepathy.Error.InvalidArgument`
  The tube is not a multi-user D-Bus tube.
`org.freedesktop.Telepathy.Error.NotAvailable`
  This tube is not in the "open" state.

### GetStreamTubeSocketAddress ( u: ID ) → u, v

For a stream tube, obtain the address of the socket used to communicate over this tube.

#### Parameters

`ID` − `u` (Tube_ID)
  The ID of the stream tube to get the socket for.

#### Returns

`Address_Type` − `u` (Socket_Address_Type)
  The type of the listening address of the socket, as a member of Socket_Address_Type.
`Address` − `v`
  The listening address of the socket, as indicated by the address_type.

#### Possible errors

`org.freedesktop.Telepathy.Error.InvalidArgument`
  The tube is not a stream tube.
`org.freedesktop.Telepathy.Error.NotAvailable`
  This tube is not in the "open" state.

## Signals:

### NewTube ( u: ID, u: Initiator, u: Type, s: Service, a{sv}: Parameters, u: State )

Emitted when a tube is created.

#### Parameters

`ID` − `u` (Tube_ID)
  The ID of the new tube.
`Initiator` − `u` (Contact_Handle)
  The handle of the contact who initiated the tube.
`Type` − `u` (Tube_Type)
  The tube type, as defined by the Tube_Type enum.
`Service` − `s`
  A string representing the service that will be used over the tube.
`Parameters` − `a{sv}` (String_Variant_Map)
  The new tube's properties.
`State` − `u` (Tube_State)
  The new tube's state.

### TubeStateChanged ( u: ID, u: State )

Emitted when the state of a tube changes.

#### Parameters

`ID` − `u` (Tube_ID)
  The ID of the tube that changed state.
`State` − `u` (Tube_State)
  The new state of the tube; see the Tube_State enumeration.

### TubeClosed ( u: ID )

Emitted when a tube has been closed. The ID of a closed tube is no longer valid. The ID may later be reused for a new tube.

#### Parameters

`ID` − `u` (Tube_ID)
  The ID of the tube that was closed.

### DBusNamesChanged ( u: ID, a(us): Added, au: Removed )

Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a participant opens or closes the tube.

#### Parameters

`ID` − `u` (Tube_ID)
  The ID of the tube whose names have changed.
`Added` − `a(us)` (DBus_Tube_Member[])
  Array of handles and D-Bus names of new participants.
`Removed` − `au` (Contact_Handle[])
  Array of handles of former participants.

### StreamTubeNewConnection ( u: ID, u: Handle )

Emitted on a stream tube when a participant opens a new connection to its socket.

#### Parameters

`ID` − `u` (Tube_ID)
  The ID of the tube
`Handle` − `u` (Contact_Handle)
  The handle of the participant who opened the new connection

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

## Simple types

### Tube_ID − u

An identifier for a tube. These are local to a Tubes channel, and may not be assumed to be the same as the other participants' idea of the tube identifier.

## Enumerated types:

### Tube_Type

`Tube_Type_DBus = 0`

  The tube is D-Bus tube as described by the org.freedesktop.Telepathy.Channel.Type.DBusTube interface.

`Tube_Type_Stream = 1`

  The tube is stream tube as described by the org.freedesktop.Telepathy.Channel.Type.StreamTube interface.

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

## Structure types

### Tube_Info − ( u: Identifier, u: Initiator, u: Type, s: Service, a{sv}: Parameters, u: State )

A struct (tube ID, initiator handle, tube type, service name, parameters, state) representing a tube, as returned by ListTubes on the Tubes channel type.

In bindings that need a separate name, arrays of Tube_Info should be called Tube_Info_List.

#### Members

`Identifier` − `u` (Tube_ID)
  (undocumented)
`Initiator` − `u` (Contact_Handle)
  (undocumented)
`Type` − `u` (Tube_Type)
  (undocumented)
`Service` − `s`
  (undocumented)
`Parameters` − `a{sv}` (String_Variant_Map)
  (undocumented)
`State` − `u` (Tube_State)
  (undocumented)

### DBus_Tube_Member − ( u: Handle, s: Unique_Name )

Represents a participant in a multi-user D-Bus tube, as returned by GetDBusNames and seen in the DBusNamesChanged signal.

In bindings that need a separate name, arrays of DBus_Tube_Member should be called DBus_Tube_Member_List.

#### Members

`Handle` − `u` (Contact_Handle)
  The handle of a participant in this D-Bus tube.
`Unique_Name` − `s` (DBus_Unique_Name)
  That participant's unique name.

## Mapping types

### Supported_Socket_Map − a{ u: Address_Type → au: Access_Control }

The supported socket address and access-control types for tubes. See GetAvailableStreamTubeTypes.

#### Members

`Address_Type` − `u` (Socket_Address_Type)
  (undocumented)
`Access_Control` − `au` (Socket_Access_Control[])
  (undocumented)

# org.freedesktop.Telepathy.Channel.Type.StreamTube

Implementations of this interface must also implement:

- `org.freedesktop.Telepathy.Channel`
- `org.freedesktop.Telepathy.Channel.Interface.Tube`

A stream tube is a transport for ordered, reliable data transfer, similar to SOCK_STREAM sockets.

When offering a stream tube, the initiating client creates a local listening socket and offers it to the recipient client using the Offer method. When a recipient accepts a stream tube using the Accept method, the recipient's connection manager creates a new local listening socket. Each time the recipient's client connects to this socket, the initiator's connection manager proxies this connection to the originally offered socket.

## Methods:

### Offer ( u: address_type, v: address, u: access_control, a{sv}: parameters ) → nothing

Offer a stream tube exporting the local socket specified.

#### Parameters

`address_type` − `u` (Socket_Address_Type)
  The type of the listening address of the local service, as a member of Socket_Address_Type.
`address` − `v`
  The listening address of the local service, as indicated by the address_type.
`access_control` − `u` (Socket_Access_Control)
  The access control the local service applies to the local socket, specified so the connection manager can behave appropriately when it connects.
`parameters` − `a{sv}` (String_Variant_Map)
  The dictionary of arbitrary Parameters to send with the tube offer.

#### Possible errors

`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  The contact associated with this channel doesn't have tube capabilities.
`org.freedesktop.Telepathy.Error.NotImplemented`
  The connection manager doesn't support the given address type or access-control type.

### Accept ( u: address_type, u: access_control, v: access_control_param ) → v

Accept a stream tube that's in the "local pending" state. The connection manager will attempt to open the tube. The tube remains in the "local pending" state until the TubeChannelStateChanged signal is emitted.

#### Parameters

`address_type` − `u` (Socket_Address_Type)
  The type of address the connection manager should listen on.
`access_control` − `u` (Socket_Access_Control)

  The type of access control the connection manager should apply to the socket.

  Note that if you plan to establish more than one connection through the tube, the Socket_Access_Control_Port access control can't be used as you can't connect more than once from the same port.

`access_control_param` − `v`
  A parameter for the access control type, to be interpreted as specified in the documentation for the Socket_Access_Control enum.

#### Returns

`address` − `v`
  The address on which the connection manager will listen for connections to this tube. The client should not attempt to connect to the address until the tube is open.

#### Possible errors

`org.freedesktop.Telepathy.Error.InvalidArgument`
  The access_control_param is invalid with the given access_control.
`org.freedesktop.Telepathy.Error.NotImplemented`
  The given address type or access-control mechanism is not supported.

## Signals:

### NewRemoteConnection ( u: Handle, v: Connection_Param, u: Connection_ID )

Emitted each time a participant opens a new connection to its socket.

This signal is only fired on the offering side.

#### Parameters

`Handle` − `u` (Contact_Handle)
  The handle of the participant who opened the new connection
`Connection_Param` − `v`

  A parameter which can be used by the listening process to identify the connection. Note that this parameter has a meaningful value only in the Socket_Access_Control_Port and Socket_Access_Control_Credentials cases. If a different Socket_Access_Control has been chosen when offering the tube, this parameter should be ignored.

  In the Socket_Access_Control_Port case, the variant contains a struct Socket_Address_IPv4 (or Socket_Address_IPv6) containing the address from which the CM is connected to the client application.

  In the Socket_Access_Control_Credentials case, the variant contains the byte (D-Bus signature 'y') that has been sent with the credentials.

`Connection_ID` − `u` (Stream_Tube_Connection_ID)
  The unique ID associated with this connection. This ID will be used to identifiy the connection when reporting errors with ConnectionClosed.

### NewLocalConnection ( u: Connection_ID )

Emitted when the tube application connects to the CM's socket.

This signal is only fired on the accepting side.

#### Parameters

`Connection_ID` − `u` (Stream_Tube_Connection_ID)
  The unique ID associated with this connection. This ID will be used to identifiy the connection when reporting errors with ConnectionClosed.

### ConnectionClosed ( u: Connection_ID, s: Error, s: Message )

Emitted when a connection has been closed.

#### Parameters

`Connection_ID` − `u` (Stream_Tube_Connection_ID)
  The ID of the connection.
`Error` − `s` (DBus_Error_Name)

  The name of a D-Bus error describing the error that occurred.

  The following errors can be used:

  - `org.freedesktop.Telepathy.Error.Cancelled`: user closed the socket or the tube.
  - `org.freedesktop.Telepathy.Error.ConnectionLost`: the bytestream relaying connection's data has been broken.
  - `org.freedesktop.Telepathy.Error.ConnectionRefused`: the tube offer refused the connection.
`Message` − `s`
  A debug message.

Interface has no Telepathy properties.

## D-Bus core Properties:

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

`Service` − `s`, read-only

  A string representing the service name that will be used over the tube. It should be a well-known TCP service name as defined by http://www.iana.org/assignments/port-numbers or http://www.dns-sd.org/ServiceTypes.html, for instance "rsync" or "daap".

  When the tube is offered, the service name is transmitted to the other end.

  When requesting a channel with Connection.Interface.Requests.CreateChannel, this property MUST be included in the request.

`SupportedSocketTypes` − `a{uau}` (Supported_Socket_Map), read-only

  A mapping from address types (members of Socket_Address_Type) to arrays of access-control type (members of Socket_Access_Control) that the connection manager supports for stream tubes with that address type. For simplicity, if a CM supports offering a particular type of tube, it is assumed to support accepting it.

  A typical value for a host without IPv6 support:

                {
                  Socket_Address_Type_IPv4:
                    [Socket_Access_Control_Localhost, Socket_Access_Control_Port,
                     Socket_Access_Control_Netmask],
                  Socket_Address_Type_Unix:
                    [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
                }

  Connection Managers MUST support at least IPv4 with the localhost access control.

  When requesting a channel with Connection.Interface.Requests.CreateChannel, this property MUST NOT be included in the request.

## Simple types

### Stream_Tube_Connection_ID − u

An identifier for a stream tube connection. These are defined with the NewLocalConnection or NewRemoteConnection signals and are used by ConnectionClosed to identify the closed connection.

# org.freedesktop.Telepathy.Channel.Type.DBusTube

Implementations of this interface must also implement:

- `org.freedesktop.Telepathy.Channel`
- `org.freedesktop.Telepathy.Channel.Interface.Tube`

A D-Bus tube is 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.

## Methods:

### Offer ( a{sv}: parameters, u: access_control ) → s

Offers a D-Bus tube providing the service specified.

#### Parameters

`parameters` − `a{sv}` (String_Variant_Map)
  The dictionary of arbitrary Parameters to send with the tube offer.
`access_control` − `u` (Socket_Access_Control)
  The access control the connection manager applies to the D-Bus socket.

#### Returns

`address` − `s`
  The string describing the address of the private bus. The client SHOULD NOT attempt to connect to the address until the tube is open.

#### Possible errors

`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  The contact associated with this channel doesn't have tubes capabilities.

### Accept ( u: access_control ) → s

Accept a D-Bus tube that's in the "local pending" state. The connection manager will attempt to open the tube. The tube remains in the "local pending" state until the TubeChannelStateChanged signal is emitted.

#### Parameters

`access_control` − `u` (Socket_Access_Control)
  The access control the connection manager applies to the D-Bus socket.

#### Returns

`address` − `s`
  The string describing the address of the private bus. The client SHOULD NOT attempt to connect to the address until the tube is open.

## Signals:

### DBusNamesChanged ( a{us}: Added, au: Removed )

Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a participant opens or closes the tube. This provides change notification for the DBusNames property.

#### Parameters

`Added` − `a{us}` (DBus_Tube_Participants)
  Array of handles and D-Bus names of new participants.
`Removed` − `au` (Contact_Handle[])
  Array of handles of former participants.

Interface has no Telepathy properties.

## D-Bus core Properties:

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

`ServiceName` − `s`, read-only

  A string representing the service name that will be used over the tube. It SHOULD be a well-known D-Bus service name, of the form `com.example.ServiceName`.

  When the tube is offered, the service name is transmitted to the other end.

  When requesting a channel with CreateChannel, this property MUST be included in the request.

`DBusNames` − `a{us}` (DBus_Tube_Participants), read-only
  For a multi-user (i.e. Handle_Type_Room) D-Bus tube, a mapping between contact handles and their unique bus names on this tube. For a peer-to-peer (i.e. Handle_Type_Contact) D-Bus tube, the empty dictionary. Change notification is via DBusNamesChanged.
`SupportedAccessControls` − `au` (Socket_Access_Control[]), read-only

  A list of the access control types that are supported with this channel. Note that only Socket_Access_Control_Localhost and Socket_Access_Control_Credentials can be used with D-Bus tubes.

  When requesting a channel with Connection.Interface.Requests.CreateChannel, this property MUST NOT be included in the request.

## Mapping types

### DBus_Tube_Participants − a{ u: Handle → s: Unique_Name }

Represents the participants in a multi-user D-Bus tube, as used by the DBusNames property and the DBusNamesChanged signal.

#### Members

`Handle` − `u` (Contact_Handle)
  The handle of a participant in this D-Bus tube.
`Unique_Name` − `s` (DBus_Unique_Name)
  That participant's unique name.

# org.freedesktop.Telepathy.Channel.Type.FileTransfer

Implementations of this interface must also implement:

- `org.freedesktop.Telepathy.Channel`

A channel type for transferring files. The transmission of data between contacts is achieved by reading from or writing to a socket. The type of the socket (local Unix, IPv4, etc.) is decided on when the file transfer is offered or accepted.

A socket approach is used to make the transfer less dependent on both client and connection manager knowing the same protocols. As an example, when browsing an SMB share in a file manager, one selects "Send file" and chooses a contact. Instead of passing a URL which would then require the connection manager to connect to the SMB share itself, the client passes a stream from which the connection manager reads, requiring no further connection to the share. It also allows connection managers to be more restricted in their access to the system, allowing tighter security policies with eg SELinux, or more flexible deployments which cross user or system boundaries.

The Telepathy client should connect to the socket or address that the connection manager has set up and provided back to the clients through the two methods.

- In order to send a file, one should request a FileTransfer channel for a contact, including at least the mandatory properties (Filename, Size and ContentType). Then, one should call ProvideFile to configure the socket that will be used to transfer the file.
- In order to receive an incoming file transfer, one should call AcceptFile and then wait until the state changes to Open. When the receiver wants to resume a transfer, the Offset argument should be should be set to a non-zero value when calling AcceptFile.
- Once the offset has been negotiated, the InitialOffsetDefined signal is emitted and the InitialOffset property is defined. The InitialOffsetDefined signal is emitted before channel becomes Open. The receiver MUST check the value of InitialOffset for a difference in offset from the requested value in AcceptFile.
- When the state changes to Open, Clients can start the transfer of the file using the offset previously announced.

If something goes wrong with the transfer, Channel.Close should be called on the channel.

The File channel type may be requested for handles of type HANDLE_TYPE_CONTACT. If the channel is requested for any other handle type then the behaviour is undefined.

Connection managers SHOULD NOT advertise support for file transfer to other contacts unless it has been indicated by a call to SetSelfCapabilities.

People would send us files, and it would always fail. That would be silly.

Added in version 0.17.18. (as stable API)

## Methods:

### AcceptFile ( u: Address_Type, u: Access_Control, v: Access_Control_Param, t: Offset ) → v

Accept a file transfer that's in the Pending state. The file transfer's state becomes Accepted after this method is called. At this point the client can connect to the socket. CM MUST emit InitialOffsetDefined and change the state to Open before writing to the socket. Then InitialOffset should be respected in case its value differs from the offset that was specified as an argument to AcceptFile.

#### Parameters

`Address_Type` − `u` (Socket_Address_Type)
  The type of address the connection manager should listen on.
`Access_Control` − `u` (Socket_Access_Control)
  The type of access control the connection manager should apply to the socket.
`Access_Control_Param` − `v`
  A parameter for the access control type, to be interpreted as specified in the documentation for the Socket_Access_Control enum.
`Offset` − `t`
  The desired offset in bytes where the file transfer should start. The offset is taken from the beginning of the file. Specifying an offset of zero will start the transfer from the beginning of the file. The offset that is actually given in the InitialOffset property can differ from this argument where the requested offset is not supported. (For example, some protocols do not support offsets at all so the InitialOffset property will always be 0.)

#### Returns

`Address` − `v`
  The address on which the connection manager will listen for connections for this file transfer.

#### Possible errors

`org.freedesktop.Telepathy.Error.NotImplemented`
  The given address type or access-control mechanism is not supported.
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  Raised when one of the provided arguments is invalid. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  The file transfer is not in the Pending state, there isn't or there is a local error with acquiring a socket.

### ProvideFile ( u: Address_Type, u: Access_Control, v: Access_Control_Param ) → v

Provide the file for an outgoing file transfer which has been offered. Opens a socket that the client can use to provide a file to the connection manager. The channel MUST have been requested, and will change state to Open when this method is called if its state was Accepted.

#### Parameters

`Address_Type` − `u` (Socket_Address_Type)
  The type of address the connection manager should listen on.
`Access_Control` − `u` (Socket_Access_Control)
  The type of access control the connection manager should apply to the socket.
`Access_Control_Param` − `v`
  A parameter for the access control type, to be interpreted as specified in the documentation for the Socket_Access_Control enum.

#### Returns

`Address` − `v`
  The address on which the connection manager will listen for connections for this file transfer.

#### Possible errors

`org.freedesktop.Telepathy.Error.NotImplemented`
  The given address type or access-control mechanism is not supported.
`org.freedesktop.Telepathy.Error.InvalidArgument`
  Raised when one of the provided arguments is invalid. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  Channel is not an outgoing transfer, ProvideFile has already been called, or there was a local error acquiring the socket.

## Signals:

### FileTransferStateChanged ( u: State, u: Reason )

Emitted when the state of a file transfer changes.

#### Parameters

`State` − `u` (File_Transfer_State)
  The new state of the file transfer; see the File_Transfer_State enumeration.
`Reason` − `u` (File_Transfer_State_Change_Reason)
  The reason for the state change; see the File_Transfer_State_Change_Reason enumeration. The value will always be File_Transfer_State_Change_Reason_None, except when changing state to cancelled.

### TransferredBytesChanged ( t: Count )

Emitted when the number of transferred bytes changes. This will not be signalled with every single byte change. Instead, the most frequent this signal will be emitted is once a second. This should be sufficient, and the TransferredBytes property SHOULD NOT be polled.

#### Parameters

`Count` − `t`
  The number of already transferred bytes.

### InitialOffsetDefined ( t: InitialOffset )

Emitted when the value of the InitialOffset property has been negotiated. This signal MUST be emitted before the channel becomes Open and clients have to use this offset when transferring the file.

#### Parameters

`InitialOffset` − `t`
  The value of the InitialOffset property.

Interface has no Telepathy properties.

## D-Bus core Properties:

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

`State` − `u` (File_Transfer_State), read-only

  The state of the file transfer as described by the File_Transfer_State enum.

`ContentType` − `s`, read-only

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

  This property is mandatory when requesting the channel with the Connection.Interface.Requests.CreateChannel method. Protocols which do not have a content-type property with file transfers should set this value to application/octet-stream.

`Filename` − `s`, read-only

  The name of the file on the sender's side. This is therefore given as a suggested filename for the receiver. This cannot change once the channel has been created.

  This property should be the basename of the file being sent. For example, if the sender sends the file /home/user/monkey.pdf then this property should be set to monkey.pdf.

  This property is mandatory when requesting the channel with the Connection.Interface.Requests.CreateChannel method. This property cannot be empty and MUST be set to a sensible value.

`Size` − `t`, read-only

  The size of the file. If this property is set, then the file transfer is guaranteed to be this size. This cannot change once the channel has been created.

  When you are creating a channel with this property, its value MUST be accurate and in bytes. However, when receiving a file, this property still MUST be in bytes but might not be entirely accurate to the byte.

  This property is mandatory when requesting the channel with the Connection.Interface.Requests.CreateChannel method. If this information isn't provided in the protocol, connection managers MUST set it to UINT64_MAX.

`ContentHashType` − `u` (File_Hash_Type), read-only

  The type of the ContentHash property.

  This property is optional when requesting the channel with the Connection.Interface.Requests.CreateChannel method. However, if you wish to include the ContentHash property you MUST also include this property. If you omit this property from a Connection.Interface.Requests.CreateChannel method call then its value will be assumed to be File_Hash_Type_None.

  For each supported hash type, implementations SHOULD include an entry in RequestableChannelClasses with this property fixed to that hash type. If the protocol supports offering a file without a content hash, implementations SHOULD list this property in Allowed in a requestable channel class, mapping hash types they don't understand to None.

`ContentHash` − `s`, read-only

  Hash of the contents of the file transfer, of type described in the value of the ContentHashType property.

  This property is optional when requesting the channel with the Connection.Interface.Requests.CreateChannel method. Its value MUST correspond to the appropriate type of the ContentHashType property. If the ContentHashType property is not set, or set to File_Hash_Type_None, then this property will not even be looked at.

`Description` − `s`, read-only

  Description of the file transfer. This cannot change once the channel has been created.

  This property is optional when requesting the channel with the Connection.Interface.Requests.CreateChannel method. If this property was not provided by the remote party, connection managers MUST set it to the empty string.

`Date` − `x` (Unix_Timestamp64), read-only

  The last modification time of the file being transferred. This cannot change once the channel has been created

  This property is optional when requesting the channel with the Connection.Interface.Requests.CreateChannel method.

`AvailableSocketTypes` − `a{uau}` (Supported_Socket_Map), read-only

  A mapping from address types (members of Socket_Address_Type) to arrays of access-control type (members of Socket_Access_Control) that the connection manager supports for sockets with that address type. For simplicity, if a CM supports offering a particular type of file transfer, it is assumed to support accepting it. Connection Managers MUST support at least Socket_Address_Type_IPv4.

  A typical value for a host without IPv6 support:

                {
                  Socket_Address_Type_IPv4:
                    [Socket_Access_Control_Localhost, Socket_Access_Control_Port,
                     Socket_Access_Control_Netmask],
                  Socket_Address_Type_Unix:
                    [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
                }

`TransferredBytes` − `t`, read-only

  The number of bytes that have been transferred at the time of requesting the property. This will be updated as the file transfer continues.

`InitialOffset` − `t`, read-only

  The offset in bytes from where the file should be sent. This MUST be respected by both the receiver and the sender after the state becomes Open, but before any data is sent or received. Until the InitialOffsetDefined signal is emitted, this property is undefined.

  Before setting the State property to Open, the connection manager MUST set the InitialOffset property, possibly to 0.

  This property MUST NOT change after the state of the transfer has changed to Open.

## Enumerated types:

### File_Transfer_State

`File_Transfer_State_None = 0`
  An invalid state type used as a null value. This value MUST NOT appear in the State property.
`File_Transfer_State_Pending = 1`
  The file transfer is waiting to be accepted/closed by the receiver. The receiver has to call AcceptFile, then wait for the state to change to Open and check the offset value.
`File_Transfer_State_Accepted = 2`
  The receiver has accepted the transfer. The sender now has to call ProvideFile to actually start the transfer. The receiver should now wait for the state to change to Open and check the offset value.
`File_Transfer_State_Open = 3`
  The file transfer is open for traffic.
`File_Transfer_State_Completed = 4`
  The file transfer has been completed successfully.
`File_Transfer_State_Cancelled = 5`
  The file transfer has been cancelled.

### File_Transfer_State_Change_Reason

`File_Transfer_State_Change_Reason_None = 0`
  No reason was specified.
`File_Transfer_State_Change_Reason_Requested = 1`
  The change in state was requested.
`File_Transfer_State_Change_Reason_Local_Stopped = 2`
  The file transfer was cancelled by the local user.
`File_Transfer_State_Change_Reason_Remote_Stopped = 3`
  The file transfer was cancelled by the remote user.
`File_Transfer_State_Change_Reason_Local_Error = 4`
  The file transfer was cancelled because of a local error.
`File_Transfer_State_Change_Reason_Remote_Error = 5`
  The file transfer was cancelled because of a remote error.

### File_Hash_Type

`File_Hash_Type_None = 0`
  No hash.
`File_Hash_Type_MD5 = 1`
  MD5 digest as a string of 32 ASCII hex digits.
`File_Hash_Type_SHA1 = 2`
  SHA1 digest as a string of ASCII hex digits.
`File_Hash_Type_SHA256 = 3`
  SHA256 digest as a string of ASCII hex digits.

# org.freedesktop.Telepathy.Channel.Type.ContactSearch.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`

A channel type for searching server-stored user directories. A new channel should be requested by a client for each search attempt, and closed when the search is completed or the required result has been found in order to free unused handles.

Before searching, the AvailableSearchKeys property should be inspected to determine the valid search keys which can be provided to the Search method. A search request is then started by providing some of these terms to the Search method, and the SearchState will change from `Not_Started` to `In_Progress`. As results are returned by the server, the SearchResultReceived signal is emitted for each contact found; when the search is complete, the search state will be set to `Completed`. If the search fails after Search has been called, the state will change to `Failed`. A running search can be cancelled by calling Stop.

If the protocol supports limiting the number of results returned by a search and subsequently requesting more results, after Limit results have been received the search state will be set to `More_Available`. Clients may call More to request another Limit results. If allowed by the connection manager, clients may specify the "page size" by specifying Limit when calling CreateChannel.

The client should call the channel's Close method when it is finished with the channel, so that any handles held only by the channel can be released.

Each channel can only be used for a single search; a new channel should be requested for each subsequent search. Connection managers MUST support multiple ContactSearch channels being open at once (even to the same server, if applicable).

It does not make sense to request this channel type using EnsureChannel; clients SHOULD request channels of this type using CreateChannel instead.

A contact search channel that is already in use for a different search isn't useful.

## Methods:

### Search ( a{ss}: Terms ) → nothing

Send a request to start a search for contacts on this connection. This may only be called while the SearchState is Not_Started; a valid search request will cause the SearchStateChanged signal to be emitted with the state In_Progress.

#### Parameters

`Terms` − `a{ss}` (Contact_Search_Map)
  A dictionary mapping search key names to the desired values

#### Possible errors

`org.freedesktop.Telepathy.Error.NotAvailable`
  The SearchState is no longer Not_Started, so this method is no longer available.
`org.freedesktop.Telepathy.Error.InvalidArgument`
  The search terms included something this connection manager cannot search for.
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)

### More ( ) → nothing

Request that a search in SearchState `More_Available` move back to state `In_Progress` and continue listing up to Limit more results.

#### Possible errors

`org.freedesktop.Telepathy.Error.NotAvailable`
  The SearchState is not More_Available.

### Stop ( ) → nothing

Stop the current search. This may not be called while the SearchState is Not_Started. If called while the SearchState is In_Progress, SearchStateChanged will be emitted, with the state Failed and the error `org.freedesktop.Telepathy.Errors.Cancelled`.

Calling this method on a search in state Completed or Failed succeeds, but has no effect.

Specifying Stop to succeed when the search has finished means that clients who call Stop just before receiving SearchStateChanged don't have to handle a useless error.

Depending on the protocol, the connection manager may not be able to prevent the server from sending further results after this method returns; if this is the case, it MUST ignore any further results.

#### Possible errors

`org.freedesktop.Telepathy.Error.NotAvailable`
  The SearchState is Not_Started, so this method is not yet available.

## Signals:

### SearchStateChanged ( u: State, s: Error, a{sv}: Details )

Emitted when the SearchState property changes. The implementation MUST NOT make transitions other than the following:

- `Not_Started` → `In_Progress`
- `In_Progress` → `More_Available`
- `More_Available` → `In_Progress`
- `In_Progress` → `Completed`
- `In_Progress` → `Failed`

#### Parameters

`State` − `u` (Channel_Contact_Search_State)
  The new search state
`Error` − `s` (DBus_Error_Name)
  If the new state is `Failed`, the name of a D-Bus error describing what went wrong. Otherwise, the empty string.
`Details` − `a{sv}` (String_Variant_Map)

  Additional information about the state transition, which may include the following well-known keys:

  debug-message (s)
    Debugging information on the change, corresponding to the message part of a D-Bus error message, which SHOULD NOT be displayed to users under normal circumstances

  This argument allows for future extensions. For instance, if moving to state `Failed` because the server rejected one of our search terms, we could define a key that indicates which terms were invalid.

### SearchResultReceived ( u: Contact, a(sasas): Info )

Emitted when a search result is received from the server.

#### Parameters

`Contact` − `u` (Contact_Handle)
  An integer handle for the contact, which will remain valid at least until this Channel closes
`Info` − `a(sasas)` (Contact_Info_Field[])

  An array of fields representing information about this contact, in the same format used in the ContactInfo.DRAFT interface. It is possible that a separate call to RequestContactInfo would return more information than this signal provides.

  This array SHOULD include the `x-telepathy-identifier` field, whose values matches the result of calling InspectHandles on the Contact handle.

  UIs will most likely want to show the identifier to the user; while they could do this by inspecting the signalled handle, including it in this signal is cheap and removes a roundtrip to look it up.

Interface has no Telepathy properties.

## D-Bus core Properties:

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

`SearchState` − `u` (Channel_Contact_Search_State), read-only
  The current state of this search channel object. Change notification is via SearchStateChanged.
`Limit` − `u`, read-only

  If supported by the protocol, the maximum number of results that should be returned, where `0` represents no limit. If the protocol does not support limiting results, this should be `0`.

  For example, if the terms passed to Search match Antonius, Bridget and Charles and this property is `2`, the search service SHOULD only return Antonius and Bridget.

  This property cannot change during the lifetime of the channel. This property SHOULD be in the Allowed_Properties of a Requestable_Channel_Class if and only if the protocol supports specifying a limit; implementations SHOULD use `0` as the default if possible, or a protocol-specific sensible default otherwise.

`AvailableSearchKeys` − `as`, read-only
  The set of search keys supported by this channel. Example values include [""] (for protocols where several address fields are implicitly searched) or ["x-n-given", "x-n-family", "nickname", "email"] (for XMPP XEP-0055, without extensibility via Data Forms). This property cannot change during the lifetime of a channel.
  It can be in the NewChannels signal for round-trip reduction.
`Server` − `s`, read-only
  For protocols which support searching for contacts on multiple servers with different DNS names (like XMPP), the DNS name of the server being searched by this channel, e.g. "characters.shakespeare.lit". Otherwise, the empty string.
  XEP 0055 defines a mechanism for XMPP clients to search services of their choice for contacts, such as users.jabber.org (the "Jabber User Directory").
  This property cannot change during the lifetime of the channel. This property SHOULD be in the Allowed_Properties of a Requestable_Channel_Class if and only if the protocol supports querying multiple different servers; implementations SHOULD use a sensible default if possible if this property is not specified in a channel request.
  This allows a client to perform searches on a protocol it knows nothing about without requiring the user to guess a valid server's hostname.

## Simple types

### Contact_Search_Key − s

Any of the following search keys, with the indicated result for the search:

The empty string
  Search for the search term in some implementation-dependent set of fields, using an implementation-dependent algorithm (e.g. searching for each word mentioned)
  The "one big search box" approach to searching, as is familiar from Google. The Sametime plugin to Pidgin appears to search in this way.
A VCard_Field
  Search for the search term in fields matching that name (for instance, `nickname` would search nicknames, and `tel` would search any available phone number, regardless of its work/home/mobile/... status).
A VCard_Field followed by "`;`" and a VCard_Type_Parameter of the form "`type=...`"
  Search for the search term in fields of that name and type only (for instance, `tel;type=mobile`).
`x-telepathy-identifier`
  Search for contacts whose identifier in the IM protocol matches the search term (e.g. contains it as a substring)
  Otherwise, starting a search by identifier would require the UI to know the vCard field name corresponding to identifiers in this protocol, which might be non-standard (like `x-jabber`) or not exist at all.
`x-gender`
  For the search term "male" or "female", search only for contacts listed as male or female, respectively. The results for other search terms are undefined; it is likely that contacts with unspecified gender will only be matched if this search key is omitted from the request.
  Examples in XEP-0055 suggest this usage, and at least Gadu-Gadu also supports limiting search results by gender.
`x-n-family`
  Search for the search term in contacts' family names (the first component of the vCard field `n`).
  Gadu-Gadu and TOC seem to support this mode of searching.
`x-n-given`
  Search for the search term in contacts' given names (the second component of the vCard field `n`).
  As for `x-n-family`.
`x-online`
  For the search term "yes", search only for contacts who are currently online. The results for other search terms are undefined.
  Gadu-Gadu appears to support this.
`x-adr-locality`
  Search for the search term as a locality or city (the fourth component of the vCard field `adr`).
  Gadu-Gadu and TOC appear to support this.

## Enumerated types:

### Channel_Contact_Search_State

`Channel_Contact_Search_State_Not_Started = 0`
  The search has not started
`Channel_Contact_Search_State_In_Progress = 1`
  The search is in progress
`Channel_Contact_Search_State_More_Available = 2`
  The search has paused, but more results can be retrieved by calling More.
`Channel_Contact_Search_State_Completed = 3`
  The search has been completed
`Channel_Contact_Search_State_Failed = 4`
  The search has failed

## Mapping types

### Contact_Search_Map − a{ s: Key → s: Term }

A map from search keys to search terms.

#### Members

`Key` − `s` (Contact_Search_Key)
  The search key to match against
`Term` − `s`
  The term or terms to be searched for in the search key; depending on the protocol and the server implementation, this may be matched by exact or approximate equality, substring matching, word matching or any other matching algorithm

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

### Merge ( o: Other ) → nothing

Request that the given channel be merged into this one. This means that the other channel is closed, and all its participants are added to the channel on which this method was called.

#### Parameters

`Other` − `o`
  The other channel to merge into this one

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  Raised when one of the provided arguments is invalid. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)

### Split ( u: Contact ) → o

Request that the given contact is removed from this channel, and a new channel is created to communicate with them privately instead. This is the inverse of Merge.

#### Parameters

`Contact` − `u` (Contact_Handle)
  The handle of the contact to split off a conversation with, who must be a member in the channel's Group interface

#### Returns

`Channel` − `o`
  The new channel

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.InvalidHandle`
  The contact name specified is unknown on this channel or connection. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)

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`

An interface for streamed media channels that can indicate call progress or call states. The presence of this interface is no guarantee that call states will actually be signalled (for instance, SIP implementations are not guaranteed to generate status 180 Ringing, so a call can be accepted without the Ringing flag ever having been set).

To notify the other participant in the call that they are on hold, see Hold.

Added in version 0.17.2.

## Methods:

### GetCallStates ( ) → a{uu}

Get the current call states for all contacts involved in this call.

#### Returns

`States` − `a{uu}` (Channel_Call_State_Map)
  The current call states. Participants where the call state flags would be 0 (all unset) may be omitted from this mapping.

## Signals:

### CallStateChanged ( u: Contact, u: State )

Emitted when the state of a member of the channel has changed.

#### Parameters

`Contact` − `u` (Contact_Handle)
  An integer handle for the contact.
`State` − `u` (Channel_Call_State_Flags)
  The new state for this contact.

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

## Sets of flags:

### Channel_Call_State_Flags

A set of flags representing call states.

`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.
`Channel_Call_State_Forwarded = 8`
  The initiator of the call originally called a contact other than the current recipient of the call, but the call was then forwarded or diverted.

## Mapping types

### Channel_Call_State_Map − a{ u: Contact → u: State }

A map from contacts to call states.

#### Members

`Contact` − `u` (Contact_Handle)
  A contact involved in this call.
`State` − `u` (Channel_Call_State_Flags)
  State flags for the given contact.

# org.freedesktop.Telepathy.Channel.Interface.ChatState

Implementations of this interface must also implement:

- `org.freedesktop.Telepathy.Channel`

An interface for channels for receiving notifications of remote contacts' state, and for notifying remote contacts of the local state.

Clients should assume that a contact's state is Channel_Chat_State_Inactive unless they receive a notification otherwise.

The Channel_Chat_State_Gone state is treated differently to other states:

- It may not be used for multi-user chats
- It may not be explicitly sent
- It should be automatically sent when the channel is closed
- It must not be sent to the peer if a channel is closed without being used
- Receiving it must not cause a new channel to be opened

The different states are defined by XEP-0085, but may be applied to any suitable protocol.

## Methods:

### SetChatState ( u: State ) → nothing

Set the local state and notify other members of the channel that it has changed.

#### Parameters

`State` − `u` (Channel_Chat_State)
  The new state.

#### Possible errors

`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  Raised when one of the provided arguments is invalid. (generic description)

## Signals:

### ChatStateChanged ( u: Contact, u: State )

Emitted when the state of a member of the channel has changed. This includes local state.

#### Parameters

`Contact` − `u` (Contact_Handle)
  An integer handle for the contact.
`State` − `u` (Channel_Chat_State)
  The new state of this contact.

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

Implementations of this interface must also implement:

- `org.freedesktop.Telepathy.Channel`

This interface exists to support channels where Channel.Close is insufficiently destructive. At the moment this means Channel.Type.Text, but the existence of this interface means that unsupported channels can be terminated in a non-channel-type-specific way.

Added in version 0.17.14. (as stable API)

## Methods:

### Destroy ( ) → nothing

Close the channel abruptly, possibly with loss of data. The connection manager MUST NOT re-create the channel unless/until more events occur.

The main motivating situation for this method is that when a Text channel with pending messages is closed with Close, it comes back as an incoming channel (to avoid a race between Close and an incoming message). If Destroy is called on a Text channel, the CM should delete all pending messages and close the channel, and the channel shouldn't be re-created until/unless another message arrives.

Most clients SHOULD call Channel.Close instead. However, if a client explicitly intends to destroy the channel with possible loss of data, it SHOULD call this method if this interface is supported (according to the Channel.Interfaces property), falling back to Close if not.

In particular, channel dispatchers SHOULD use this method if available when terminating channels that cannot be handled correctly (for instance, if no handler has been installed for a channel type, or if the handler crashes repeatedly).

Connection managers do not need to implement this interface on channels where Close and Destroy would be equivalent.

Callers need to be able to fall back to Close in any case.

Interface has no signals.

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

# org.freedesktop.Telepathy.Channel.Interface.DTMF

Implementations of this interface must also implement:

- `org.freedesktop.Telepathy.Channel.Type.StreamedMedia`

An interface that gives a Channel the ability to send DTMF events over audio streams which have been established using the StreamedMedia channel type. The event codes used are in common with those defined in RFC4733, and are listed in the DTMF_Event enumeration.

## Methods:

### StartTone ( u: Stream_ID, y: Event ) → nothing

Start sending a DTMF tone on this stream. Where possible, the tone will continue until StopTone is called. On certain protocols, it may only be possible to send events with a predetermined length. In this case, the implementation may emit a fixed-length tone, and the StopTone method call should return NotAvailable.

#### Parameters

`Stream_ID` − `u` (Stream_ID)
  A stream ID as defined in the StreamedMedia channel type.
`Event` − `y` (DTMF_Event)
  A numeric event code from the DTMF_Event enum.

#### Possible errors

`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  The given stream ID was invalid.
`org.freedesktop.Telepathy.Error.NotAvailable`
  The requested event is not available on this stream.

### StopTone ( u: Stream_ID ) → nothing

Stop sending any DTMF tone which has been started using the StartTone method. If there is no current tone, this method will do nothing.

#### Parameters

`Stream_ID` − `u` (Stream_ID)
  A stream ID as defined in the StreamedMedia channel type.

#### Possible errors

`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  The given stream ID was invalid.
`org.freedesktop.Telepathy.Error.NotAvailable`
  Continuous tones are not supported by this stream.

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 (Members), and two lists of local pending and remote pending members (LocalPendingMembers and RemotePendingMembers, respectively). 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 (and, if the channel's GroupFlags contains Members_Changed_Detailed, the MembersChangedDetailed signal) should be emitted when information is retrieved from the server, or changes occur.

If the MembersChanged or MembersChangedDetailed signal indicates that the SelfHandle has been removed from the channel, and the channel subsequently emits Closed, clients SHOULD consider the details given in the MembersChanged or MembersChangedDetailed signal to be the reason why the channel closed.

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:

### AddMembers ( au: Contacts, s: Message ) → nothing

Invite all the given contacts into the channel, or accept requests for channel membership for contacts on the pending local list.

A message may be provided along with the request, which will be sent to the server if supported. See the CHANNEL_GROUP_FLAG_MESSAGE_ADD and CHANNEL_GROUP_FLAG_MESSAGE_ACCEPT GroupFlags to see in which cases this message should be provided.

Attempting to add contacts who are already members is allowed; connection managers must silently accept this, without error.

#### Parameters

`Contacts` − `au` (Contact_Handle[])
  An array of contact handles to invite to the channel
`Message` − `s`
  A string message, which can be blank if desired

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)
`org.freedesktop.Telepathy.Error.NotCapable`
  Raised when requested functionality is unavailable due to contact not having required capabilities. (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)
`org.freedesktop.Telepathy.Error.InvalidHandle`
  The contact name specified is unknown on this channel or connection. (generic description)
`org.freedesktop.Telepathy.Error.Channel.Full`
  The channel is full. (generic description)
`org.freedesktop.Telepathy.Error.Channel.InviteOnly`
  The requested channel is invite-only. (generic description)
`org.freedesktop.Telepathy.Error.Channel.Banned`
  You are banned from the channel. (generic description)

### GetAllMembers ( ) → au, au, au

Returns arrays of all current, local and remote pending channel members.

Deprecated since version 0.17.6. Use GetAll on the D-Bus Properties D-Bus interface to get properties including Members, RemotePendingMembers and LocalPendingMembers instead, falling back to this method and GetLocalPendingMembersWithInfo if necessary.

#### Returns

`Members` − `au` (Contact_Handle[])
  array of handles of current members
`Local_Pending` − `au` (Contact_Handle[])
  array of handles of local pending members
`Remote_Pending` − `au` (Contact_Handle[])
  array of handles of remote pending members

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)

### GetGroupFlags ( ) → u

Returns the value of the GroupFlags property.

Deprecated since version 0.17.6. Use GetAll on the D-Bus Properties D-Bus interface to get properties including GroupFlags instead, falling back to this method if necessary.

#### Returns

`Group_Flags` − `u` (Channel_Group_Flags)
  The value of the GroupFlags property

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)

### GetHandleOwners ( au: Handles ) → au

If the CHANNEL_GROUP_FLAG_CHANNEL_SPECIFIC_HANDLES flag is set on the channel, then the handles of the group members are specific to this channel, and are not meaningful in a connection-wide context such as contact lists. This method allows you to find the owner of the handle if it can be discovered in this channel, or 0 if the owner is not available.

Deprecated since version 0.17.6. Clients should use the HandleOwners property and HandleOwnersChanged signal if Channel_Group_Flag_Properties is present.

#### Parameters

`Handles` − `au` (Contact_Handle[])
  A list of integer handles representing members of the channel

#### Returns

`Owners` − `au` (Contact_Handle[])
  An array of integer handles representing the owner handles of the given room members, in the same order, or 0 if the owner is not available

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.InvalidHandle`
  The contact name specified is unknown on this channel or connection. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  This channel doesn't have the CHANNEL_SPECIFIC_HANDLES flag, so handles in this channel are globally meaningful and calling this method is not necessary
`org.freedesktop.Telepathy.Error.InvalidArgument`
  One of the given handles is not a member

### GetLocalPendingMembers ( ) → au

Returns the To_Be_Added handle (only) for each structure in the LocalPendingMembers property.

Deprecated since version 0.17.6. Use the LocalPendingMembers property, if Channel_Group_Flag_Properties is present.

#### Returns

`Handles` − `au` (Contact_Handle[])

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)

### GetLocalPendingMembersWithInfo ( ) → a(uuus)

Returns the LocalPendingMembers property.

Added in version 0.15.0.

Deprecated since version 0.17.6. Use the LocalPendingMembers property, if Channel_Group_Flag_Properties is present.

#### Returns

`Info` − `a(uuus)` (Local_Pending_Info[])
  An array of structs containing: A handle representing the contact requesting channel membership A handle representing the contact making the request, or 0 if unknown The reason for the request: one of the values of Channel_Group_Change_Reason A string message containing the reason for the request if any (or blank if none)

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)

### GetMembers ( ) → au

Returns the Members property.

Deprecated since version 0.17.6. Use the Members property, if Channel_Group_Flag_Properties is present.

#### Returns

`Handles` − `au` (Contact_Handle[])

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)

### GetRemotePendingMembers ( ) → au

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

Deprecated since version 0.17.6. Use the RemotePendingMembers property, if Channel_Group_Flag_Properties is present.

#### Returns

`Handles` − `au` (Contact_Handle[])

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)

### GetSelfHandle ( ) → u

Returns the value of the SelfHandle property.

Deprecated since version 0.17.6. Clients should retrieve the SelfHandle property using GetAll instead, if Channel_Group_Flag_Properties is present.

#### Returns

`Self_Handle` − `u` (Contact_Handle)

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)

### RemoveMembers ( au: Contacts, s: Message ) → nothing

Requests the removal of contacts from a channel, reject their request for channel membership on the pending local list, or rescind their invitation on the pending remote list.

If the SelfHandle is in a Group, it can be removed via this method, in order to leave the group gracefully. This is the recommended way to leave a chatroom, close or reject a StreamedMedia call, and so on.

Accordingly, connection managers SHOULD support doing this, regardless of the value of GroupFlags. If doing so fails with PermissionDenied, this is considered to a bug in the connection manager, but clients MUST recover by falling back to closing the channel with the Close method.

Removing any contact from the local pending list is always allowed. Removing contacts other than the SelfHandle from the channel's members is allowed if and only if Channel_Group_Flag_Can_Remove is in the GroupFlags, while removing contacts other than the SelfHandle from the remote pending list is allowed if and only if Channel_Group_Flag_Can_Rescind is in the GroupFlags.

A message may be provided along with the request, which will be sent to the server if supported. See the Channel_Group_Flag_Message_Remove, Channel_Group_Flag_Message_Depart, Channel_Group_Flag_Message_Reject and Channel_Group_Flag_Message_Rescind GroupFlags to see in which cases this message should be provided.

#### Parameters

`Contacts` − `au` (Contact_Handle[])
  An array of contact handles to remove from the channel
`Message` − `s`
  A string message, which can be blank if desired

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)
`org.freedesktop.Telepathy.Error.InvalidHandle`
  The contact name specified is unknown on this channel or connection. (generic description)

### RemoveMembersWithReason ( au: Contacts, s: Message, u: Reason ) → nothing

As RemoveMembers, but a reason code may be provided where appropriate. The reason code may be ignored if the underlying protocol is unable to represent the given reason.

#### Parameters

`Contacts` − `au` (Contact_Handle[])
  An array of contact handles to remove from the channel
`Message` − `s`
  A string message, which can be blank if desired
`Reason` − `u` (Channel_Group_Change_Reason)
  A reason for the change

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)
`org.freedesktop.Telepathy.Error.InvalidHandle`
  The contact name specified is unknown on this channel or connection. (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  The provided reason code was invalid.

## Signals:

### HandleOwnersChanged ( a{uu}: Added, au: Removed )

Emitted whenever the HandleOwners property changes.

Added in version 0.17.6. This signal should not be relied on unless Channel_Group_Flag_Properties is present.

#### Parameters

`Added` − `a{uu}` (Handle_Owner_Map)
  A map from channel-specific handles to their owners, in which the keys include all the handles that were added to the keys of the HandleOwners property, and all the handles in that property whose owner has changed
`Removed` − `au` (Contact_Handle[])
  The channel-specific handles that were removed from the keys of the HandleOwners property, as a result of the contact leaving this group in a previous MembersChanged signal

### SelfHandleChanged ( u: Self_Handle )

Emitted whenever the SelfHandle property changes.

Added in version 0.17.6. This signal should not be relied on unless Channel_Group_Flag_Properties is present.

#### Parameters

`Self_Handle` − `u` (Contact_Handle)
  The new value of the SelfHandle property.

### GroupFlagsChanged ( u: Added, u: Removed )

Emitted when the flags as returned by GetGroupFlags are changed. The user interface should be updated as appropriate.

#### Parameters

`Added` − `u` (Channel_Group_Flags)
  A bitwise OR of the flags which have been set
`Removed` − `u` (Channel_Group_Flags)
  A bitwise OR of the flags which have been cleared

### MembersChanged ( s: Message, au: Added, au: Removed, au: Local_Pending, au: Remote_Pending, u: Actor, u: Reason )

Emitted when contacts join any of the three lists (members, local pending or remote pending) or when they leave any of the three lists. There may also be a message from the server regarding this change, which may be displayed to the user if desired.

All channel-specific handles that are mentioned in this signal MUST be represented in the value of the HandleOwners property. In practice, this will mean that HandleOwnersChanged is emitted before emitting a MembersChanged signal in which channel-specific handles are added, but that it is emitted after emitting a MembersChanged signal in which channel-specific handles are removed.

#### Parameters

`Message` − `s`
  A string message from the server, or blank if not
`Added` − `au` (Contact_Handle[])
  A list of members added to the channel
`Removed` − `au` (Contact_Handle[])
  A list of members removed from the channel
`Local_Pending` − `au` (Contact_Handle[])
  A list of members who are pending local approval
`Remote_Pending` − `au` (Contact_Handle[])
  A list of members who are pending remote approval
`Actor` − `u` (Contact_Handle)
  The contact handle of the person who made the change, or 0 if not known
`Reason` − `u` (Channel_Group_Change_Reason)
  A reason for the change

### MembersChangedDetailed ( au: Added, au: Removed, au: Local_Pending, au: Remote_Pending, a{sv}: Details )

Emitted when contacts join any of the three lists (members, local pending or remote pending) or when they leave any of the three lists. This signal provides a superset of the information provided by MembersChanged; if the channel's GroupFlags contains Members_Changed_Detailed, then clients may listen exclusively to this signal in preference to that signal.

All channel-specific handles that are mentioned in this signal MUST be represented in the value of the HandleOwners property. In practice, this will mean that HandleOwnersChanged is emitted before emitting a MembersChangedDetailed signal in which channel-specific handles are added, but that it is emitted after emitting a MembersChangedDetailed signal in which channel-specific handles are removed.

Added in version 0.17.16.

#### Parameters

`Added` − `au` (Contact_Handle[])
  A list of members added to the channel
`Removed` − `au` (Contact_Handle[])
  A list of members removed from the channel
`Local_Pending` − `au` (Contact_Handle[])
  A list of members who are pending local approval
`Remote_Pending` − `au` (Contact_Handle[])
  A list of members who are pending remote approval
`Details` − `a{sv}` (String_Variant_Map)

  Information about the change, which may include the following well-known keys:

  actor (u — Contact_Handle)
    The contact handle of the person who made the change; 0 or omitted if unknown or not applicable.
  change-reason (u — Channel_Group_Change_Reason)
    A reason for the change.
  contact-ids (a{us} — Handle_Identifier_Map)

    The string identifiers for handles mentioned in this signal, to give clients the minimal information necessary to react to the event without waiting for round-trips. Connection managers SHOULD include the identifiers for members added to the group and for the actor (if any); they MAY omit the identifiers for handles which have been removed from the group.

    On IRC, an event such as a netsplit could cause the vast majority of a channel to leave. Given that clients should already know the identifiers of a channel's members, including potentially hundreds of strings in the netsplit signal is unnecessary.

    Clients MUST NOT assume that the presence or absence of a handle in this mapping is meaningful. This mapping is merely an optimization for round-trip reduction, and connection managers MAY add additional handles, omit some handles, or omit the mapping completely.

  message (s)
    A string message from the server regarding the change
  error (s — DBus_Error_Name)
    A (possibly implementation-specific) DBus error describing the change, providing more specific information than the Channel_Group_Change_Reason enum allows. This MUST only be present if it is strictly more informative than 'change-reason'; if present, 'change-reason' MUST be set to the closest available reason.
    A SIP connection manager might want to signal "402 Payment required" as something more specific than Error or Permission_Denied so that a SIP-aware UI could handle it specially; including a namespaced error permits this to be done without Channel_Group_Change_Reason being extended to encompass every error any CM ever wants to report.
  debug-message (s)
    Debugging information on the change. SHOULD NOT be shown to users in normal circumstances.

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 result of 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.

  In particular, this reason SHOULD be used when representing users joining a named chatroom in the usual way, users leaving a chatroom by their own request, and normal termination of a StreamedMedia call by the remote user.

  If the SelfHandle is removed from a group for this reason and the actor is not the SelfHandle, the equivalent D-Bus error is `org.freedesktop.Telepathy.Error.Terminated`.

  If the SelfHandle is removed from a group for this reason and the actor is also the SelfHandle, the equivalent D-Bus error is `org.freedesktop.Telepathy.Error.Cancelled`.

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

  If a one-to-one StreamedMedia call fails because the contact being called is offline, the connection manager SHOULD indicate this by removing both the SelfHandle and the other contact's handle from the Group interface with reason Offline.

  For 1-1 calls, the call terminates as a result of removing the remote contact, so the SelfHandle should be removed at the same time as the remote contact and for the same reason.

  If a handle is removed from a group for this reason, the equivalent D-Bus error is `org.freedesktop.Telepathy.Error.Offline`.

`Channel_Group_Change_Reason_Kicked = 2`

  The change is due to a kick operation.

  If the SelfHandle is removed from a group for this reason, the equivalent D-Bus error is `org.freedesktop.Telepathy.Error.Channel.Kicked`.

`Channel_Group_Change_Reason_Busy = 3`

  The change is due to a busy indication.

  If a one-to-one StreamedMedia call fails because the contact being called is busy, the connection manager SHOULD indicate this by removing both the SelfHandle and the other contact's handle from the Group interface with reason Busy.

  For 1-1 calls, the call terminates as a result of removing the remote contact, so the SelfHandle should be removed at the same time as the remote contact and for the same reason.

  If the SelfHandle is removed from a group for this reason, the equivalent D-Bus error is `org.freedesktop.Telepathy.Error.Busy`.

`Channel_Group_Change_Reason_Invited = 4`
  The change is due to an invitation. This reason SHOULD only be used when contacts are added to the remote-pending set (to indicate that the contact has been invited) or to the members (to indicate that the contact has accepted the invitation).
  Otherwise, what would it mean?
`Channel_Group_Change_Reason_Banned = 5`

  The change is due to a kick+ban operation.

  If the SelfHandle is removed from a group for this reason, the equivalent D-Bus error is `org.freedesktop.Telepathy.Error.Channel.Banned`.

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

  For instance, if the user invites a nonexistent contact to a chatroom or attempts to call a nonexistent contact, this could be indicated by the CM adding that contact's handle to remote-pending for reason None or Invited, then removing it for reason Invalid_Contact. In the case of a 1-1 StreamedMedia call, the CM SHOULD remove the self handle from the Group in the same signal.

  For 1-1 calls, the call terminates as a result of removing the remote contact, so the SelfHandle should be removed at the same time as the remote contact and for the same reason.

  If a contact is removed from a group for this reason, the equivalent D-Bus error is `org.freedesktop.Telepathy.Error.DoesNotExist`.

`Channel_Group_Change_Reason_No_Answer = 8`

  The change is because the requested contact did not respond.

  If a one-to-one StreamedMedia call fails because the contact being called did not respond, the connection manager SHOULD indicate this by removing both the SelfHandle and the other contact's handle from the Group interface with reason No_Answer.

  Documenting existing practice.

  If a contact is removed from a group for this reason, the equivalent D-Bus error is `org.freedesktop.Telepathy.Error.NoAnswer`.

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

  If a contact is removed from a group for this reason, the equivalent D-Bus error is `org.freedesktop.Telepathy.Error.PermissionDenied`.

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

  The SelfHandle SHOULD NOT be removed from channels with this reason.

## 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 check the HandleOwners property or call GetHandleOwners to find the owners of these handles, which should be done if you wish to (e.g.) 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 HandleOwners property and HandleOwnersChanged signal.
`Channel_Group_Flag_Properties = 2048`
  This flag indicates that all the properties introduced in specification 0.17.6 are fully supported.
`Channel_Group_Flag_Members_Changed_Detailed = 4096`
  Indicates that MembersChangedDetailed will be emitted for changes to this group's members in addition to MembersChanged. Clients can then connect to the former and ignore emission of the latter. This flag's state MUST NOT change over the lifetime of a channel.
  If it were allowed to change, client bindings would have to always connect to MembersChanged just in case the flag ever went away (and generally be unnecessarily complicated), which would mostly negate the point of having this flag in the first place.
`Channel_Group_Flag_Message_Depart = 8192`
  A message may be sent to the server when calling RemoveMembers on the SelfHandle.
  This would be set for XMPP Multi-User Chat or IRC channels, but not for a typical implementation of streamed media calls.

  Added in version 0.17.21.

## Structure types

### Local_Pending_Info − ( u: To_Be_Added, u: Actor, u: Reason, s: Message )

A structure representing a contact whose attempt to join a group is to be confirmed by the local user using AddMembers.

In bindings that need a separate name, arrays of Local_Pending_Info should be called Local_Pending_Info_List.

#### Members

`To_Be_Added` − `u` (Contact_Handle)
  The contact to be added to the group
`Actor` − `u` (Contact_Handle)
  The contact requesting or causing the change
`Reason` − `u` (Channel_Group_Change_Reason)
  The reason for the change
`Message` − `s`
  A human-readable message from the Actor, or an empty string if there is no message

## Mapping types

### Handle_Owner_Map − a{ u: Channel_Specific_Handle → u: Global_Handle }

A map from channel-specific handles to their owners.

#### Members

`Channel_Specific_Handle` − `u` (Contact_Handle)
  A nonzero channel-specific handle
`Global_Handle` − `u` (Contact_Handle)
  The global handle that owns the corresponding channel-specific handle, or 0 if this could not be determined

### Handle_Identifier_Map − a{ u: Handle → s: Identifier }

A map from handles to the corresponding normalized string identifier.

#### Members

`Handle` − `u` (Contact_Handle)
  A nonzero handle
`Identifier` − `s`
  The same string that would be returned by InspectHandles for this handle.

# 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. (To see whether the other participant has put you on hold, see CallState.)

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:

### GetHoldState ( ) → u, u

Return whether the local user has placed the channel on hold.

#### Returns

`HoldState` − `u` (Local_Hold_State)
  The state of the channel
`Reason` − `u` (Local_Hold_State_Reason)
  The reason why the channel is in that state

### RequestHold ( b: Hold ) → nothing

Request that the channel be put on hold (be instructed not to send any media streams to you) or be taken off hold.

If the connection manager can immediately tell that the requested state change could not possibly succeed, this method SHOULD return the NotAvailable error. If the requested state is the same as the current state, this method SHOULD return successfully without doing anything.

Otherwise, this method SHOULD immediately set the hold state to Local_Hold_State_Pending_Hold or Local_Hold_State_Pending_Unhold (as appropriate), emitting HoldStateChanged if this is a change, and return successfully.

The eventual success or failure of the request is indicated by a subsequent HoldStateChanged signal, changing the hold state to Local_Hold_State_Held or Local_Hold_State_Unheld.

If the channel has multiple streams, and the connection manager succeeds in changing the hold state of one stream but fails to change the hold state of another, it SHOULD attempt to revert all streams to their previous hold states.

The following state transitions SHOULD be used, where appropriate:

- Successful hold: (Unheld, any reason) → (Pending_Hold, Requested) → (Held, Requested)
- Successful unhold: (Held, any reason) → (Pending_Unhold, Requested) → (Unheld, Requested)
- Attempting to unhold fails at the first attempt to acquire a resource: (Held, any reason) → (Pending_Unhold, Requested) → (Held, Resource_Not_Available)
- Attempting to unhold acquires one resource, but fails to acquire a second, and takes time to release the first: (Held, any reason) → (Pending_Unhold, Requested) → (Pending_Hold, Resource_Not_Available) → (Held, Resource_Not_Available)

#### Parameters

`Hold` − `b`
  A boolean indicating whether or not the channel should be on hold

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  The requested hold state cannot be achieved; for example, if only a limited number of channels can be in the "not on hold" state, attempts to exceed this number will raise NotAvailable.

## Signals:

### HoldStateChanged ( u: HoldState, u: Reason )

Emitted to indicate that the hold state has changed for this channel. This may occur as a consequence of you requesting a change with RequestHold, or the state changing as a result of a request from another process.

#### Parameters

`HoldState` − `u` (Local_Hold_State)
  The state of the channel
`Reason` − `u` (Local_Hold_State_Reason)
  The reason for the state change

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

## Enumerated types:

### Local_Hold_State

The hold state of a channel.

`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

The reason for a change to the Local_Hold_State. Clients MUST treat unknown values as equivalent to Local_Hold_State_Reason_None.

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

XMPP supports all of XHTML-IM, and SIP (at least theoretically) supports all of XHTML. However, many protocols are more limited - for instance, in MSN you can only set font properties for a whole message at a time. We should not mislead users into thinking they can send MSN messages where individual words are emphasized.

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.

Connection managers are the components in Telepathy that are most likely to be exploitable by a remote attacker to run malicious code (since they are network-facing), so any filtering that the CM does might be subverted.

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.

Connection managers should be lenient in what they receive.

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:

### GetPasswordFlags ( ) → u

Returns the bitwise-OR of the flags relevant to the password on this channel. The user interface can use this to present information about which operations are currently valid.

#### Returns

`Password_Flags` − `u` (Channel_Password_Flags)
  An integer with the logical OR of all the flags set (values of ChannelPasswordFlags)

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)

### ProvidePassword ( s: Password ) → b

Provide the password so that the channel can be joined. Must be called with the correct password in order for channel joining to proceed if the 'provide' password flag is set.

#### Parameters

`Password` − `s`
  The password

#### Returns

`Correct` − `b`

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  Raised when one of the provided arguments is invalid. (generic description)

## Signals:

### PasswordFlagsChanged ( u: Added, u: Removed )

Emitted when the flags as returned by GetPasswordFlags are changed. The user interface should be updated as appropriate.

#### Parameters

`Added` − `u` (Channel_Password_Flags)
  A bitwise OR of the flags which have been set
`Removed` − `u` (Channel_Password_Flags)
  A bitwise OR of the flags which have been cleared

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`

An interface for signalling a channel containing synchronised media sessions which can contain an arbitrary number of streams. The presence of this interface on a Channel indicates that the connection manager will not carry out the actual streaming for this channel, and that the client handling the channel is responsible for doing so; in most cases we recommend doing this by using the telepathy-farsight library.

Streaming audio and (particularly) video requires a high level of integration with the UI, and having the connection manager act as a proxy would be likely to introduce unacceptable latency. As a result, audio/video streaming is offloaded into the client where possible, as an exception to the general design of Telepathy.

The negotiation interface is based on the API of the Farsight library. This, in turn, is based upon the IETF MMusic ICE drafts, where connections are established by signalling potential connection candidates to the peer until a usable connection is found, and codecs are negotiated with an SDP-style offer and answer. However, the principles should be applicable to other media streaming methods and the API re-used without difficulty.

Note that the naming conventions used in the MediaStreamHandler and MediaSessionHandler interfaces are rather confusing; methods have signal-like names and signals have method-like names, due to the API being based rather too closely on that of Farsight. This is for historical reasons and will be fixed in a future release of the Telepathy specification.

## Methods:

### GetSessionHandlers ( ) → a(os)

Returns all currently active session handlers on this channel as a list of (session_handler_path, type).

#### Returns

`Session_Handlers` − `a(os)` (Media_Session_Handler_Info[])

## Signals:

### NewSessionHandler ( o: Session_Handler, s: Session_Type )

Signal that a session handler object has been created. The client should create a session object and create streams for the streams within.

#### Parameters

`Session_Handler` − `o`
  Object path of the new Media.SessionHandler object
`Session_Type` − `s` (Media_Session_Type)
  String indicating type of session, eg "rtp"

## 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 if they do not have a NATTraversal property. The possible values are the same as for the NATTraversal property on the streams.

  Deprecated since version 0.17.22. Use the NATTraversal property on the Media.StreamHandler, if available; use this as a fallback.

`stun-server` − `s`
  The IP address or hostname of the STUN server to use for NAT traversal if the individual streams do not specify one.

  Deprecated since version 0.17.22. Use the STUNServers property on the Media.StreamHandler, if available; use this as a fallback.

`stun-port` − `q`
  The UDP port number to use on the provided STUN server.

  Deprecated since version 0.17.22. Use the STUNServers property on the Media.StreamHandler, if available; use this as a fallback.

`gtalk-p2p-relay-token` − `s`
  The authentication token for use with the Google Talk peer-to-peer relay server.

  Deprecated since version 0.17.22. XMPP connection managers supporting the Google Talk relay server SHOULD make the necessary HTTP requests to find a username and password, and use those to populate the RelayInfo property on the Media.StreamHandler.

Interface has no D-Bus core properties.

## Simple types

### Media_Session_Type − s

The type of a media session. Currently, the only supported value is "rtp".

## Structure types

### Media_Session_Handler_Info − ( o: Session_Handler, s: Media_Session_Type )

A struct representing a active session handler.

In bindings that need a separate name, arrays of Media_Session_Handler_Info should be called Media_Session_Handler_Info_List.

#### Members

`Session_Handler` − `o`
  The object path of the session handler, which is on the same bus name as the channel.
`Media_Session_Type` − `s` (Media_Session_Type)
  The media session's type

# org.freedesktop.Telepathy.Channel.Interface.MediaSignalling.FUTURE

Implementations of this interface must also implement:

- `org.freedesktop.Telepathy.Channel`
- `org.freedesktop.Telepathy.Channel.Type.StreamedMedia`
- `org.freedesktop.Telepathy.Channel.Interface.MediaSignalling`

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

The rationale is the same as for Channel.FUTURE.

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.

`ICETransportAvailable` − `b`, read-only

  True if this channel supports the use of the ICE-UDP transport (XEP-0176, ICE RFC draft). Various other transports have boolean properties that work in the same way as this one, so this description covers all such transports.

  This property is immutable (cannot change), and therefore SHOULD appear wherever immutable properties are reported, e.g. NewChannels signals.

  Connection managers capable of signalling streamed media calls to contacts SHOULD include the properties representing all supported transports in the allowed properties list of the channel class in RequestableChannelClasses that advertises support for streamed media channels.

  Similarly, connection managers that support the ContactCapabilities.DRAFT interface SHOULD include all supported transports in the allowed properties list of the channel class that advertises a contact's ability to receive streamed media calls.

  Clients SHOULD NOT pass ICETransportAvailable and similar properties to EnsureChannel or similar functions. If they do, the connection manager MUST accept and ignore any such property that is in the allowed properties list.

  There is currently no way for clients to influence the choice of transport: in general, a client making a call can't know the capabilities of the streaming implementation, or even which streaming implementation will be used (channels will often be requested by an address book or similar application that will not handle the channel itself).

  If a mechanism for transport negotiation is added, it should be something that happens after the request, but before calling Media.SessionHandler.Ready, so that it is the streaming implementation that chooses the transport, rather than the requesting client.

  Clients that are able to receive calls with particular transports MUST include the following filters if calling SetSelfCapabilities (clients of a ChannelDispatcher SHOULD instead arrange for the ChannelDispatcher to do this, by including the filters in their HandlerChannelFilter properties):

  - { ChannelType = StreamedMedia, ICETransportAvailable = true } if the ICE transport is supported
  - { ChannelType = StreamedMedia, RawUDPTransportAvailable = true } if the raw UDP transport is supported
  - ... and so on, one filter per available transport.

  Connection managers MAY use this information to adjust the transports for which they advertise support to other contacts.

  In particular, in XMPP, the connection manager will not be callable unless a client has told it to advertise support for at least one transport.

`RawUDPTransportAvailable` − `b`, read-only

  The same as ICETransportAvailable, but for raw UDP streaming as described by XEP-0177.

`GTalkP2PTransportAvailable` − `b`, read-only

  The same as ICETransportAvailable, but for the variant of ICE used by the Google Talk peer-to-peer connectivity establishment mechanism (as implemented in libjingle 0.3).

`WLM85TransportAvailable` − `b`, read-only

  The same as ICETransportAvailable, but for the transport implemented by Windows Live Messenger 8.5 or later (which resembles ICE draft 6).

`WLM2009TransportAvailable` − `b`, read-only

  The same as ICETransportAvailable, but for the transport implemented by Windows Live Messenger 2009 or later (which resembles ICE draft 19).

# org.freedesktop.Telepathy.Channel.Interface.Messages

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

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.

We intend to expose all rich-text messages as XHTML-IM, but on some protocols, formatting is an extremely limited subset of that format (e.g. there are protocols where foreground/background colours, font and size can be set, but only for entire messages). Until we can tell UIs what controls to offer to the user, it's unfriendly to offer the user controls that may have no effect.

This interface also replaces Text.SendError, adding support for protocols where the message content is not echoed back to the sender on failure, adding support for receiving positive acknowledgements, and using 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 is present, clients that support it SHOULD listen for the MessageSent and MessageReceived signals, and ignore the Sent, SendError and Received signals on the Text interface (which are guaranteed to duplicate signals from this interface).

Added in version 0.17.16. (as stable API)

## Methods:

### SendMessage ( aa{sv}: Message, u: Flags ) → s

Submit a message to the server for sending. If this method returns successfully, the message has been submitted to the server and the MessageSent signal is emitted. A corresponding Sent signal on the Text interface MUST also be emitted.

This method MUST return before the MessageSent signal is emitted.

This means that the process sending the message is the first to see the Sent_Message_Token, and can relate the message to the corresponding MessageSent signal by comparing message tokens (if supported by the protocol).

If this method fails, message submission to the server has failed and no signal on this interface (or the Text interface) is emitted.

#### Parameters

`Message` − `aa{sv}` (Message_Part[])
  The message content, including any attachments or alternatives
`Flags` − `u` (Message_Sending_Flags)
  Flags affecting how the message is sent.

#### Returns

`Token` − `s` (Sent_Message_Token)
  An opaque token used to match any incoming delivery or failure reports against this message, or an empty string if the message is not readily identifiable.

#### Possible errors

`org.freedesktop.Telepathy.Error.InvalidArgument`
  The requested message is malformed and cannot be sent.
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)

### GetPendingMessageContent ( u: Message_ID, au: Parts ) → a{uv}

Retrieve the content of one or more parts of a pending message. Note that this function may take a considerable amount of time to return if the part's 'needs-retrieval' flag is true; consider extending the default D-Bus method call timeout. Additional API is likely to be added in future, to stream large message parts.

#### Parameters

`Message_ID` − `u` (Message_ID)
  The ID of a pending message
`Parts` − `au` (Message_Part_Index[])
  The desired entries in the array of message parts, identified by their position. The "headers" part (which is not a valid argument to this method) is considered to be part 0, so the valid part numbers start at 1 (for the second Message_Part).

#### Returns

`Content` − `a{uv}` (Message_Part_Content_Map)

  The content of the requested parts. The keys in this mapping are positions in the array of message parts; the values are either of type 's' or 'ay' (UTF-8 text string, or byte array), following the same rules as for the value of the 'content' key in the Message_Part mappings.

  If the one of the requested part numbers was greater than zero but referred to a part that had no content (i.e. it had no 'content-type' key or no 'content' key), it is simply omitted from this mapping; this is not considered to be an error condition.

#### Possible errors

`org.freedesktop.Telepathy.Error.InvalidArgument`
  Either there is no pending message with the given message ID, or one of the part numbers given was 0 or too large.
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)

## Signals:

### MessageSent ( aa{sv}: Content, u: Flags, s: Message_Token )

Signals that a message has been submitted for sending. This MUST be emitted exactly once per emission of the Sent signal on the Text interface.

This signal allows a process that is not the caller of SendMessage to log sent messages. The double signal-emission provides compatibility with older clients. Clients supporting Messages should listen for Messages.MessageSent only (if the channel has the Messages interface) or Text.Sent only (otherwise).

#### Parameters

`Content` − `aa{sv}` (Message_Part[])

  The message content (see Message_Part for full details). If the message that was passed to SendMessage has a formatted text part that the connection manager recognises, but no text/plain alternative, the CM MUST use the formatted text part to generate a text/plain alternative which is also included in this signal argument.

  If the connection manager can predict that the message will be altered during transmission, this argument SHOULD reflect what other contacts will receive, rather than being a copy of the argument to SendMessage (if the message is truncated, formatting or alternatives are dropped, etc., then the edited version SHOULD appear in this signal).

`Flags` − `u` (Message_Sending_Flags)
  Flags affecting how the message was sent. The flags might be a subset of those passed to SendMessage if the caller requested unsupported flags.
`Message_Token` − `s` (Sent_Message_Token)
  An opaque token used to match any incoming delivery or failure reports against this message, or an empty string if the message is not readily identifiable.

### PendingMessagesRemoved ( au: Message_IDs )

The messages with the given IDs have been removed from the PendingMessages list. Clients SHOULD NOT attempt to acknowledge those messages.
This completes change notification for the PendingMessages property (previously, there was change notification when pending messages were added, but not when they were removed).

#### Parameters

`Message_IDs` − `au` (Message_ID[])
  The messages that have been removed from the pending message list.

### MessageReceived ( aa{sv}: Message )

Signals that a message has been received and added to the pending messages queue. This MUST be emitted exactly once per emission of the Received signal on the Text interface.
The double signal-emission provides compatibility with older clients. Clients supporting Messages should listen for Messages.MessageReceived only (if the channel has the Messages interface) or Text.Received only (otherwise).

#### Parameters

`Message` − `aa{sv}` (Message_Part[])
  The message content, including any attachments or alternatives

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. This list MUST NOT be empty, since all Messages implementations MUST accept messages containing a single "text/plain" part.

  Some examples of how this property interacts with the MessagePartSupportFlags:

  A simple IM implementation: only plain text messages are allowed
    SupportedContentTypes = ['text/plain'], MessagePartSupportFlags = 0
  Formatted text with a plain text alternative is allowed (see the HTML interface draft)
    SupportedContentTypes = ['text/html', 'text/plain'], MessagePartSupportFlags = 0
  JPEG or PNG images may be sent, but without any attached text
    SupportedContentTypes = ['text/plain', 'image/jpeg', 'image/png'], MessagePartSupportFlags = 0
  Unformatted text to which an optional JPEG or PNG image may be attached
    SupportedContentTypes = ['text/plain', 'image/jpeg', 'image/png'], MessagePartSupportFlags = One_Attachment
  Formatted text to which arbitrarily many images may be attached
    SupportedContentTypes = ['text/html', 'text/plain', 'image/jpeg', 'image/png', 'image/x-ms-bmp'], MessagePartSupportFlags = One_Attachment | Multiple_Attachments
  A full SIP implementation: arbitrary MIME messages are allowed
    SupportedContentTypes = ['*/*'], MessagePartSupportFlags = One_Attachment | Multiple_Attachments
`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 more detailed version of the one returned by Text.ListPendingMessages, and contains the same messages, uniquely identified by the same pending message IDs. Its items can be removed using Text.AcknowledgePendingMessages.
`DeliveryReportingSupport` − `u` (Delivery_Reporting_Support_Flags), read-only
  A bitfield indicating features supported by this channel.

## Simple types

### Message_Part_Index − u

The index of a message part within a message.

Added in version 0.17.17.

### Sent_Message_Token − s

An opaque token used to identify sent messages. As a special case, the empty string indicates that there is no particular identification for a message.

CM implementations SHOULD use an identifier expected to be unique, such as a UUID, if possible.

Some protocols can only track a limited number of sent messages in a small message-ID space. As a result, clients MUST NOT assume that message tokens will not be re-used, and SHOULD use some reasonable heuristic to assign delivery reports to messages, such as matching on message content or timestamp (if available), or assuming that the delivery report refers to the most recent message with that ID.

## Enumerated types:

### Delivery_Status

The status of a message as indicated by a delivery report. If this enum is extended in future specifications, this should only be to add new, non-overlapping conditions (i.e. all failures should still be signalled as either Temporarily_Failed or Permanently_Failed). If additional detail is required (e.g. distinguishing between the various types of permanent failure) this will be done using additional keys in the Message_Part.

`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.
`Delivery_Status_Accepted = 4`
  An intermediate server has accepted the message but the message has not been yet delivered to the ultimate recipient. The connection manager might send a Failed report or Delivered report later.
  Similar to "202 Accepted" success code in SIP; analogous to 251 and 252 responses in SMTP.

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

If no flags are set, this indicates that messages may contain a single message part whose content-type is any of the types from SupportedContentTypes, possibly with some alternatives.

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.

Each of the flags so far implies the previous flag, so we could have used a simple enumeration here; however, we've defined the message-part support indicator as a flag set for future expansion.

See SupportedContentTypes for some examples.

`Message_Part_Support_Flag_One_Attachment = 1`
  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 = 2`
  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

Flags altering the way a message is sent. The "most usual" action should always be to have these flags unset.

`Message_Sending_Flag_Report_Delivery = 1`

  Provide a successful delivery report 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 positive delivery notifications.

  Delivery failure reports SHOULD always be sent, but if this flag is present, the connection manager MAY also try harder to obtain failed delivery reports or allow them to be matched to outgoing messages.

### Delivery_Reporting_Support_Flags

Flags indicating the level of support for delivery reporting on this channel. Any future flags added to this set will conform to the convention that the presence of an extra flag implies that more operations will succeed.

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

## Mapping types

### Message_Part − a{ s: Key → v: Value }

Part of a message's content. In practice, this mapping never appears in isolation - messages are represented by a list of Message_Part mappings.

An example of how a message might look, in a Python-like syntax:

    [
      {
        'message-token': '9de9546a-3400-4419-a505-3ea270cb834c',
        'message-sender': 42,
        'message-sent': 1210067943,
        'message-received': 1210067947,
        'message-type': 0,              # = Channel_Text_Message_Type_Normal
        'pending-message-id': 437,
      },
      { 'alternative': 'main',
        'content-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',
        'content-type': 'text/plain',
        'content': 'Here is a photo of my cat:\n[IMG: lol!]\nIsn't it cute?',
      },
      { 'identifier': 'catphoto',
        'content-type': 'image/jpeg',
        'size': 101000,
        'needs-retrieval': True,
      },
    ]

The first part of the message contains "headers" which refer to the entire message.

It is an error for a connection manager to put keys referring to the message as a whole in the second or subsequent Message_Part, but clients MUST recover from this error by ignoring these keys in the second and subsequent parts.

Instead of representing messages as aa{sv} where the first dictionary is special (a dictionary of headers), we could have used a signature like (a{sv}aa{sv}) to separate out the headers and the body parts.

However, this would make access to the messages more awkward. In Python, the syntax for access to a header field would remain `message[0]['message-type']`, but access to a body field in the second body part would change from message[2]['content'] to message[1][1]['content']. In GLib, the message would change from being a GPtrArray(GHashTable) to being a GValueArray(GHashTable, GPtrArray(GHashTable)) which is rather inconvenient to dereference.

Well-known keys for the message as a whole, and the corresponding value types, include:

message-token (s)
  An opaque, globally-unique identifier for the entire message. This MAY be treated as if it were a MIME Message-ID, e.g. for the mid: and cid: URI schemes. If omitted, there is no suitable token.
message-sent (x - Unix_Timestamp64)
  The time the message was sent (if unavailable, the time it arrived at a central server MAY be used). Omitted if no reasonable approximation is available; SHOULD always be present on outgoing messages.
message-received (x - Unix_Timestamp64)
  The time the message was received locally. SHOULD always be present.
message-sender (u - Contact_Handle)
  The contact who sent the message. If 0 or omitted, the contact who sent the message could not be determined.
message-type (u - Channel_Text_Message_Type)
  The type of message; if omitted, Channel_Text_Message_Type_Normal MUST be assumed. MAY be omitted for normal chat messages.
pending-message-id (u - Message_ID)
  The incoming message ID. This MUST NOT be present on outgoing messages. Clients SHOULD NOT store this key - it is only valid for as long as the message remains unacknowledged.
interface (s - DBus_Interface)
  This message is specific to the given interface, which is neither Text nor Messages. It SHOULD be ignored if that interface is not supported. (Note that an 'interface' key can also appear on the second and subsequent parts, where it indicates that that part (only) should be ignored if unsupported.)
scrollback (b)
  If present and true, the incoming message was part of a replay of message history (this matches the Scrollback flag in Channel_Text_Message_Flags). This flag does not make sense on outgoing messages and SHOULD NOT appear there.
rescued (b)
  If present and true, the incoming message has been seen in a previous channel during the lifetime of the Connection, but had not been acknowledged when that channel closed, causing an identical channel (in which the message now appears) to open. This matches the Rescued flag in Channel_Text_Message_Flags; it does not make sense on outgoing messages, and SHOULD NOT appear there.

The second and subsequent parts contain the message's content, including plain text, formatted text and/or attached files.

It is an error for a connection manager to put keys referring to the message body in the first Message_Part; clients MUST recover from this error by ignoring these keys in first part.

In any group of parts with the same non-empty value for the "alternative" key (which represent alternative versions of the same content), more faithful versions of the intended message MUST come before less faithful versions (note that this order is the opposite of MIME "multipart/alternative" parts). Clients SHOULD display the first alternative that they understand.

Specifying the preference order means that if the underlying protocol doesn't support alternatives, the CM can safely delete everything apart from the first supported alternative when sending messages.

The order is the reverse of MIME because MIME's rationale for placing the "plainest" part first (legibility in pre-MIME UAs) does not apply to us, and placing the most preferred part first simplifies display (a client can iterate the message in order, display the first alternative that it understands, and skip displaying all subsequent parts with the same "alternative" key).

Clients SHOULD present all parts that are not redundant alternatives in the order they appear in this array, possibly excluding parts that are referenced by another displayed part. It is implementation-specific how the parts are presented to the user.

This allows CMs to assume that all parts are actually shown to the user, even if they are not explicitly referenced - we do not yet recommend formatted text, and there is no way for plain text to reference an attachment since it has no concept of markup or references. This also forces clients to do something sensible with messages that consist entirely of "attachments", with no "body" at all.

For instance, when displaying the above example, a client that understands the HTML part should display the JPEG image once, between the two lines "Here is a photo of my cat:" and "Isn't it cute?"; it may additionally present the image in some way for a second time, after "Isn't it cute?", or may choose not to.

A client that does not understand HTML, displaying the same message, should display the plain-text part, followed by the JPEG image.

Well-known keys for the second and subsequent parts, and the corresponding value types, include:

identifier (s)
  An opaque identifier for this part. Parts of a message MAY reference other parts by treating this identifier as if it were a MIME Content-ID and using the cid: URI scheme.
alternative (s)

  If present, this part of the message is an alternative for all other parts with the same value for "alternative". Clients SHOULD only display one of them (this is expected to be used for XHTML messages in a future version of this specification).

  If omitted, this part is not an alternative for any other part.

  Parts of a message MAY reference the group of alternatives as a whole (i.e. a reference to whichever of them is chosen) by treating this identifier as if it were the MIME Content-ID of a multipart/alternative part, and using the cid: URI scheme.

content-type (s)

  The MIME type of this part. See the documentation for ReceivedMessage for notes on the special status of "text/plain" parts.

  Connection managers MUST NOT signal parts without a 'content-type' key; if a protocol provides no way to determine the MIME type, the connection manager is responsible for guessing it, but MAY fall back to "text/plain" for text and "application/octet-stream" for non-text.

  Clients MUST ignore parts without a 'content-type' key, which are reserved for future expansion.

lang (s)
  The natural language of this part, identified by a RFC 3066 language tag.
  XMPP allows alternative-selection by language as well as by content-type.
size (u)
  The size in bytes (if needs-retrieval is true, this MAY be an estimated or approximate size). SHOULD be omitted if 'content' is provided.
  There's no point in providing the size if you're already providing all the content.
needs-retrieval (b)
  If false or omitted, the connection manager already holds this part in memory. If present and true, this part will be retrieved on demand (like MIME's message/external-body), so clients should expect retrieval to take time; if this specification is later extended to provide a streaming version of GetPendingMessageContent, clients should use it for parts with this flag.
truncated (b)
  The content available via the 'content' key or GetPendingMessageContent has been truncated by the server or connection manager (equivalent to Channel_Text_Message_Flag_Truncated in the Text interface).
content (s or ay)
  The part's content, if it is available and sufficiently small to include here (implies that 'needs-retrieval' is false or omitted). Otherwise, omitted. If the part is human-readable text or HTML, the value for this key MUST be a UTF-8 string (D-Bus signature 's'). If the part is not text, the value MUST be a byte-array (D-Bus signature 'ay'). If the part is a text-based format that is not the main body of the message (e.g. an iCalendar or an attached XML document), the value SHOULD be a UTF-8 string, transcoding from another charset to UTF-8 if necessary, but MAY be a byte-array (of unspecified character set) if transcoding fails or the source charset is not known.
interface (s - DBus_Interface)
  This part is specific to the given interface, which is neither Text nor Messages. It SHOULD be ignored if that interface is not supported. (Note that an 'interface' key can also appear on the first part, where it indicates that the entire message should be ignored if unsupported.)

Delivery reports are also represented as messages, of type Channel_Text_Message_Type_Delivery_Report, with the Non_Text_Content flag in the Text interface.

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.

message-sender (u - Contact_Handle as defined above)
  MUST be the intended recipient of the original message, if available (zero or omitted if the intended recipient is unavailable or is not a contact, e.g. a chatroom), even if the delivery report actually came from an intermediate server.
message-type (u - Channel_Text_Message_Type as defined above)
  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. 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-dbus-error (s - DBus_Error_Name)
  The reason for the failure, specified as a (possibly implementation-specific) D-Bus error. MUST be omitted if this was a successful delivery. If set, the 'delivery-error' key SHOULD be set to the closest available value.
delivery-error-message (s)
  Debugging information on why the message could not be delivered. MUST be omitted if this was a successful delivery; MAY always be omitted.
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.

Clients MUST NOT attempt to send delivery reports using the SendMessage method in the Messages API, and connection managers MUST NOT allow this to be done. If support for sending delivery reports is later added, it will be part of this 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
      '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
      '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
          'content-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
      '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
          'content-type': 'text/plain',
          'content': 'Hello, world!',
          }]
        ],
      },
      { # message from server (alternative in English)
      'alternative': '404',
      'content-type': 'text/plain',
      'lang': 'en',
      'content': 'I have no contact with that name',
      },
      { # message from server (alternative in German)
      'alternative': '404'.
      'content-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
      '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
      ]

In bindings that need a separate name, arrays of Message_Part should be called Message_Part_List.

#### Members

`Key` − `s`
  A key, which SHOULD be one of the well-known keys specified, if possible.
`Value` − `v`
  The value corresponding to the given key, which must be of one of the types indicated.

### Message_Part_Content_Map − a{ u: Part → v: Content }

A mapping from message part indexes to their content, as returned by GetPendingMessageContent.

#### Members

`Part` − `u` (Message_Part_Index)
  Indexes into the array of Message_Parts that represents a message. The "headers" part (which is not a valid argument to GetPendingMessageContent) is considered to be part 0, so the valid part numbers start at 1 (for the second message part).
`Content` − `v`
  The message part's content. The variant MUST contain either type 's' or 'ay' (UTF-8 text string, or byte array), following the same rules as for the value of the 'content' key in the Message_Part mappings.

# org.freedesktop.Telepathy.Channel.Interface.Tube

Implementations of this interface must also implement:

- `org.freedesktop.Telepathy.Channel`

A tube is a mechanism for arbitrary data transfer between two or more IM users, used to allow applications on the users' systems to communicate without having to establish network connections themselves. Currently, two types of tube exist: Channel.Type.DBusTube and Channel.Type.StreamTube. This interface contains the properties, signals and methods common to both types of tube; you can only create channels of a specific tube type, not of this type. A tube channel contains exactly one tube; if you need several tubes, you have to create several tube channels.

Tube channels can be requested for Handle_Type Contact (for 1-1 communication) or Room (to communicate with others in the room simultaneously).

As an exception to the usual handling of capabilities, connection managers for protocols with capability discovery (such as XMPP) SHOULD advertise the capability representing each Tube type that they support (Channel.Type.DBusTube and/or Channel.Type.StreamTube) even if no client has indicated via SetSelfCapabilities that such a tube is supported. They SHOULD also allow clients to offer tubes with any Service or ServiceName to any contact which supports the corresponding tube capability.

This lowers the barrier to entry for those writing new tube applications, and preserves interoperability with older versions of the Telepathy stack which did not support rich capabilities.

Interface has no methods.

## Signals:

### TubeChannelStateChanged ( u: State )

Emitted when the state of the tube channel changes. Valid state transitions are documented with Tube_Channel_State.

#### Parameters

`State` − `u` (Tube_Channel_State)
  The new state of the tube.

Interface has no Telepathy properties.

## D-Bus core Properties:

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

`Parameters` − `a{sv}` (String_Variant_Map), read-only

  Each tube has a dictionary of arbitrary parameters. Parameters are commonly used to bootstrap legacy protocols where you can't negotiate parameters in-band. The allowable keys, types and values are defined by the service, but connection managers must support the value being a string (D-Bus type `'s'`), array of bytes (D-Bus type `'ay'`), unsigned integer (D-Bus type `'u'`), integer (D-Bus type `'i'`) and boolean (D-Bus type `'b'`).

  When the tube is offered, the parameters are transmitted with the offer and appear as a property of the incoming tube for other participants.

  For example, a stream tube for Service `"smb"` (Server Message Block over TCP/IP) might use the following properties, as defined in DNS SRV (RFC 2782) Service Types:

      { 'u': 'some-username',
        'p': 'top-secret-password',
        'path': '/etc/passwd',
      }

  When requesting a tube with CreateChannel, this property MUST NOT be included in the request; instead, it is set when StreamTube.Offer or DBusTube.Offer (as appropriate) is called. Its value is undefined until the tube is offered; once set, its value MUST NOT change.

  When receiving an incoming tube, this property is immutable and so advertised in the NewChannels signal.

`State` − `u` (Tube_Channel_State), read-only

  State of the tube in this channel.

  When requesting a tube with CreateChannel, this property MUST NOT be included in the request.

## Enumerated types:

### Tube_Channel_State

`Tube_Channel_State_Local_Pending = 0`
  The initiator offered the tube. The tube is waiting to be accepted/closed locally. If the client accepts the tube, the tube's state will be Open.
`Tube_Channel_State_Remote_Pending = 1`
  The tube is waiting to be accepted/closed remotely. If the recipient accepts the tube, the tube's state will be Open.
`Tube_Channel_State_Open = 2`
  The initiator offered the tube and the recipient accepted it. The tube is open for traffic. The tube's state stays in this state until it is closed.
`Tube_Channel_State_Not_Offered = 3`
  The tube channel has been requested but the tube is not yet offered. The client should offer the tube to the recipient and the tube's state will be Remote_Pending. The method used to offer the tube depends on the tube type.

### Socket_Address_Type

`Socket_Address_Type_Unix = 0`
  A Unix socket. The address variant contains a byte-array, signature 'ay', containing the path of the socket.
`Socket_Address_Type_Abstract_Unix = 1`
  An abstract Unix socket. The address 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 address 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 address 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.

  Deprecated since version 0.17.25. This has never been implemented. If you want to share a service to your whole LAN, Telepathy is not the way to do it.

`Socket_Access_Control_Credentials = 3`

  May only be used on UNIX sockets. The connecting process must send a 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.

# org.freedesktop.Telepathy.Media.SessionHandler

An media session handler is an object that handles a number of synchronised media streams.

## Methods:

### Error ( u: Error_Code, s: Message ) → nothing

Informs the connection manager that an error occured in this session. If used, the connection manager must terminate the session and all of the streams within it, and may also emit a StreamError signal on the channel for each stream within the session.

Deprecated since version 0.13.4. Use StreamHandler.Error on each StreamHandler object instead.

#### Parameters

`Error_Code` − `u` (Media_Stream_Error)
`Message` − `s`

### Ready ( ) → nothing

Inform the connection manager that a client is ready to handle this session handler (i.e. that it has connected to the NewStreamHandler signal and done any other necessary setup).

## Signals:

### NewStreamHandler ( o: Stream_Handler, u: ID, u: Media_Type, u: Direction )

Emitted when a new stream handler has been created for this session.

#### Parameters

`Stream_Handler` − `o`
  The path of a new object implementing the StreamHandler interface.
`ID` − `u`
  The unique ID of the new stream
`Media_Type` − `u` (Media_Stream_Type)
  Type of media that this stream should handle
`Direction` − `u` (Media_Stream_Direction)
  Direction of this stream

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

# org.freedesktop.Telepathy.Media.StreamHandler

Handles signalling the information pertaining to a specific media stream. A client should provide information to this handler as and when it is available.

## Methods:

### CodecChoice ( u: Codec_ID ) → nothing

Inform the connection manager of codec used to receive data.

#### Parameters

`Codec_ID` − `u`

### Error ( u: Error_Code, s: Message ) → nothing

Inform the connection manager that an error occured in this stream. The connection manager should emit the StreamError signal for the stream on the relevant channel, and remove the stream from the session.

#### Parameters

`Error_Code` − `u` (Media_Stream_Error)
  ID of error, from the MediaStreamError enumeration
`Message` − `s`
  String describing the error

### NativeCandidatesPrepared ( ) → nothing

Informs the connection manager that all possible native candisates have been discovered for the moment.

### NewActiveCandidatePair ( s: Native_Candidate_ID, s: Remote_Candidate_ID ) → nothing

Informs the connection manager that a valid candidate pair has been discovered and streaming is in progress.

#### Parameters

`Native_Candidate_ID` − `s`
`Remote_Candidate_ID` − `s`

### NewNativeCandidate ( s: Candidate_ID, a(usuussduss): Transports ) → nothing

Inform this MediaStreamHandler that a new native transport candidate has been ascertained.

#### Parameters

`Candidate_ID` − `s`
  String identifier for this candidate
`Transports` − `a(usuussduss)` (Media_Stream_Handler_Transport[])
  Array of transports for this candidate, with fields:
  - component number
  - IP address (as a string)
  - port
  - base network protocol (one of the values of MediaStreamBaseProto)
  - proto subtype (e.g. RTP)
  - proto profile (e.g. AVP)
  - our preference value of this transport (double in range 0.0-1.0 inclusive); 1 signals the most preferred transport
  - transport type, one of the values of MediaStreamTransportType
  - username if authentication is required
  - password if authentication is required

### Ready ( a(usuuua{ss}): Codecs ) → nothing

Inform the connection manager that a client is ready to handle this StreamHandler. Also provide it with info about all supported codecs.

#### Parameters

`Codecs` − `a(usuuua{ss})` (Media_Stream_Handler_Codec[])
  Locally-supported codecs.

### SetLocalCodecs ( a(usuuua{ss}): Codecs ) → nothing

Used to provide codecs after Ready(), so the media client can go ready for an incoming call and exchange candidates/codecs before knowing what local codecs are available.

This is useful for gatewaying calls between two connection managers. Given an incoming call, you need to call Ready to get the remote codecs before you can use them as the "local" codecs to place the outgoing call, and hence receive the outgoing call's remote codecs to use as the incoming call's "local" codecs.

In this situation, you would pass an empty list of codecs to the incoming call's Ready method, then later call SetLocalCodecs on the incoming call in order to respond to the offer.

#### Parameters

`Codecs` − `a(usuuua{ss})` (Media_Stream_Handler_Codec[])
  Locally-supported codecs

### StreamState ( u: State ) → nothing

Informs the connection manager of the stream's current state, as as specified in Channel.Type.StreamedMedia::ListStreams.

#### Parameters

`State` − `u` (Media_Stream_State)

### SupportedCodecs ( a(usuuua{ss}): Codecs ) → nothing

Inform the connection manager of the supported codecs for this session. This is called after the connection manager has emitted SetRemoteCodecs to notify what codecs are supported by the peer, and will thus be an intersection of all locally supported codecs (passed to Ready) and those supported by the peer.

#### Parameters

`Codecs` − `a(usuuua{ss})` (Media_Stream_Handler_Codec[])
  Locally supported codecs.

### CodecsUpdated ( a(usuuua{ss}): Codecs ) → nothing

Inform the connection manager that the parameters of the supported codecs for this session have changed. The connection manager should send the new parameters to the remote contact.
This is required for H.264 and Theora, for example.

#### Parameters

`Codecs` − `a(usuuua{ss})` (Media_Stream_Handler_Codec[])
  Locally supported codecs, which SHOULD be the same as were previously in effect, but possibly with different parameters.

### HoldState ( b: Held ) → nothing

Notify the connection manager that the stream's hold state has been changed successfully in response to SetStreamHeld.

Added in version 0.17.3.

#### Parameters

`Held` − `b`
  If true, the stream is now on hold.

### UnholdFailure ( ) → nothing

Notify the connection manager that an attempt to reacquire the necessary hardware or software resources to unhold the stream, in response to SetStreamHeld, has failed.

Added in version 0.17.3.

## Signals:

### AddRemoteCandidate ( s: Candidate_ID, a(usuussduss): Transports )

Signal emitted when the connection manager wishes to inform the client of a new remote candidate.

#### Parameters

`Candidate_ID` − `s`
  String identifier for this candidate
`Transports` − `a(usuussduss)` (Media_Stream_Handler_Transport[])
  Array of transports for this candidate with fields, as defined in NewNativeCandidate

### Close ( )

Signal emitted when the connection manager wishes the stream to be closed.

### RemoveRemoteCandidate ( s: Candidate_ID )

Signal emitted when the connection manager wishes to inform the client that the remote end has removed a previously usable candidate.
It seemed like a good idea at the time, but wasn't.

Deprecated since version 0.17.18. There is no case where you want to release candidates (except for an ICE reset, and there you'd want to replace then all, using SetRemoteCandidateList).

#### Parameters

`Candidate_ID` − `s`
  String identifier for remote candidate to drop

### SetActiveCandidatePair ( s: Native_Candidate_ID, s: Remote_Candidate_ID )

Emitted by the connection manager to inform the client that a valid candidate pair has been discovered by the remote end and streaming is in progress.

#### Parameters

`Native_Candidate_ID` − `s`
`Remote_Candidate_ID` − `s`

### SetRemoteCandidateList ( a(sa(usuussduss)): Remote_Candidates )

Signal emitted when the connection manager wishes to inform the client of all the available remote candidates at once.

#### Parameters

`Remote_Candidates` − `a(sa(usuussduss))` (Media_Stream_Handler_Candidate[])
  A list of candidate id and a list of transports as defined in NewNativeCandidate

### SetRemoteCodecs ( a(usuuua{ss}): Codecs )

Signal emitted when the connection manager wishes to inform the client of the codecs supported by the remote end. If these codecs are compatible with the remote codecs, then the client must call SupportedCodecs, otherwise call Error.

#### Parameters

`Codecs` − `a(usuuua{ss})` (Media_Stream_Handler_Codec[])
  Codecs supported by the remote peer.

### SetStreamPlaying ( b: Playing )

If emitted with argument TRUE, this means that the connection manager wishes to set the stream playing; this means that the streaming implementation should expect to receive data. If emitted with argument FALSE this signal is basically meaningless and should be ignored.
We're very sorry.

#### Parameters

`Playing` − `b`

### SetStreamSending ( b: Sending )

Signal emitted when the connection manager wishes to set whether or not the stream sends to the remote end.

#### Parameters

`Sending` − `b`

### StartTelephonyEvent ( y: Event )

Request that a telephony event (as defined by RFC 4733) is transmitted over this stream until StopTelephonyEvent is called.

#### Parameters

`Event` − `y`
  A telephony event code as defined by RFC 4733.

### StopTelephonyEvent ( )

Request that any ongoing telephony events (as defined by RFC 4733) being transmitted over this stream are stopped.

### SetStreamHeld ( b: Held )

Emitted when the connection manager wishes to place the stream on hold (so the streaming client should free hardware or software resources) or take the stream off hold (so the streaming client should reacquire the necessary resources).

When placing a channel's streams on hold, the connection manager SHOULD notify the remote contact that this will be done (if appropriate in the protocol) before it emits this signal.

It is assumed that relinquishing a resource will not fail. If it does, the call is probably doomed anyway.

When unholding a channel's streams, the connection manager SHOULD emit this signal and wait for success to be indicated via HoldState before it notifies the remote contact that the channel has been taken off hold.

This means that if a resource is unavailable, the remote contact will never even be told that we tried to acquire it.

Added in version 0.17.3.

#### Parameters

`Held` − `b`
  If true, the stream is to be placed on hold.

Interface has no Telepathy properties.

## D-Bus core Properties:

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

`STUNServers` − `a(sq)` (Socket_Address_IP[]), read-only
  The IP addresses of possible STUN servers to use for NAT traversal, as dotted-quad IPv4 address literals or RFC2373 IPv6 address literals. This property cannot change once the stream has been created, so there is no change notification. The IP addresses MUST NOT be given as DNS hostnames.
  High-quality connection managers already need an asynchronous DNS resolver, so they might as well resolve this name to an IP to make life easier for streaming implementations.

  Added in version 0.17.22.

`CreatedLocally` − `b`, read-only
  True if we were the creator of this stream, false otherwise.
  This information is needed for some nat traversal mechanisms, such as ICE-UDP, where the creator gets the role of the controlling agent.

  Added in version 0.17.22.

`NATTraversal` − `s`, read-only

  The transport (NAT traversal technique) to be used for this stream. Well-known values include:

  none
    Raw UDP, with or without STUN, should be used. If the STUNServers property is non-empty, STUN SHOULD be used.
  stun
    A deprecated synonym for 'none'.
  gtalk-p2p
    Google Talk peer-to-peer connectivity establishment should be used, as implemented in libjingle 0.3.
  ice-udp
    Interactive Connectivity Establishment should be used, as defined by the IETF MMUSIC working group.
  wlm-8.5
    The transport used by Windows Live Messenger 8.5 or later, which resembles ICE draft 6, should be used.
  wlm-2009
    The transport used by Windows Live Messenger 2009 or later, which resembles ICE draft 19, should be used.

  This property cannot change once the stream has been created, so there is no change notification.

  Added in version 0.17.22.

`RelayInfo` − `aa{sv}` (String_Variant_Map[]), read-only

  A list of mappings describing TURN or Google relay servers available for the client to use in its candidate gathering, as determined from the protocol. Map keys are:

  `ip` - s
    The IP address of the relay server as a dotted-quad IPv4 address literal or an RFC2373 IPv6 address literal. This MUST NOT be a DNS hostname.
    High-quality connection managers already need an asynchronous DNS resolver, so they might as well resolve this name to an IP and make life easier for streaming implementations.
  `type` - s

    Either `udp` for UDP (UDP MUST be assumed if this key is omitted), `tcp` for TCP, or `tls`.

    The precise meaning of this key depends on the NATTraversal property: if NATTraversal is `ice-udp`, `tls` means TLS over TCP as referenced by ICE draft 19, and if NATTraversal is `gtalk-p2p`, `tls` means a fake SSL session over TCP as implemented by libjingle.

  `port` - q
    The UDP or TCP port of the relay server as an ASCII unsigned integer
  `username` - s
    The username to use
  `password` - s
    The password to use
  `component` - u
    The component number to use this relay server for, as an ASCII unsigned integer; if not included, this relay server may be used for any or all components.
    In ICE draft 6, as used by Google Talk, credentials are only valid once, so each component needs relaying separately.

  An equivalent of the gtalk-p2p-relay-token property on MediaSignalling channels is not included here. The connection manager should be responsible for making the necessary HTTP requests to turn the token into a username and password.

  The type of relay server that this represents depends on the value of the NATTraversal property. If NATTraversal is ice-udp, this is a TURN server; if NATTraversal is gtalk-p2p, this is a Google relay server; otherwise, the meaning of RelayInfo is undefined.

  If relaying is not possible for this stream, the list is empty.

  This property cannot change once the stream has been created, so there is no change notification.

## 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

### Media_Stream_Handler_Candidate − ( s: Name, a(usuussduss): Transports )

In bindings that need a separate name, arrays of Media_Stream_Handler_Candidate should be called Media_Stream_Handler_Candidate_List.

#### Members

`Name` − `s`
  (undocumented)
`Transports` − `a(usuussduss)` (Media_Stream_Handler_Transport[])
  (undocumented)

### Media_Stream_Handler_Transport − ( u: Component_Number, s: IP_Address, u: Port, u: Protocol, s: Subtype, s: Profile, d: Preference_Value, u: Transport_Type, s: Username, s: Password )

In bindings that need a separate name, arrays of Media_Stream_Handler_Transport should be called Media_Stream_Handler_Transport_List.

#### Members

`Component_Number` − `u`
  (undocumented)
`IP_Address` − `s`
  (undocumented)
`Port` − `u`
  (undocumented)
`Protocol` − `u` (Media_Stream_Base_Proto)
  (undocumented)
`Subtype` − `s`
  (undocumented)
`Profile` − `s`
  (undocumented)
`Preference_Value` − `d`
  (undocumented)
`Transport_Type` − `u` (Media_Stream_Transport_Type)
  (undocumented)
`Username` − `s`
  (undocumented)
`Password` − `s`
  (undocumented)

### Media_Stream_Handler_Codec − ( u: Codec_ID, s: Name, u: Media_Type, u: Clock_Rate, u: Number_Of_Channels, a{ss}: Parameters )

Information about a codec supported by a client or a peer's client.

In bindings that need a separate name, arrays of Media_Stream_Handler_Codec should be called Media_Stream_Handler_Codec_List.

#### Members

`Codec_ID` − `u`
  The codec's payload identifier, as per RFC 3551 (static or dynamic)
`Name` − `s`
  The codec's name
`Media_Type` − `u` (Media_Stream_Type)
  Type of stream this codec supports
`Clock_Rate` − `u`
  Sampling frequency in Hertz
`Number_Of_Channels` − `u`
  Number of supported channels
`Parameters` − `a{ss}` (String_String_Map)
  Codec-specific optional parameters

# org.freedesktop.Telepathy.Debug.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.

An interface for providing debug messages.

This interface is primarily provided by one object per service, at the path `/org/freedesktop/Telepathy/debug`.

Added in version 0.17.24.

## Methods:

### GetMessages ( ) → a(dsus)

Retrieve buffered debug messages. An implementation could have a limit on how many message it keeps and so the array returned from this method should not be assumed to be all of the messages in the lifetime of the service.

#### Returns

`Messages` − `a(dsus)` (Debug_Message[])
  A list of debug messages.

## Signals:

### NewDebugMessage ( d: time, s: domain, u: level, s: message )

Emitted when a debug messages is generated if the Enabled property is set to TRUE.

#### Parameters

`time` − `d`
  Timestamp of the debug message.
`domain` − `s`
  Domain of the debug message, as described in the Debug_Message struct.
`level` − `u` (Debug_Level)
  Level of the debug message.
`message` − `s`
  The text of the debug message.

Interface has no Telepathy properties.

## D-Bus core Properties:

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

`Enabled` − `b`, read/write
  TRUE if the NewDebugMessage signal should be emitted when a new debug message is generated.

## Enumerated types:

### Debug_Level

`Debug_Level_Error = 0`
  Log level for errors. Error messages are always fatal, resulting in the service terminating after something completely unexpected occurred.
`Debug_Level_Critical = 1`
  Log level for critical messages. Critical messages are messages that the service might predict and it is up to the service itself to decide whether to terminate following a critical message.
`Debug_Level_Warning = 2`
  Log level for warnings.
`Debug_Level_Message = 3`
  Log level for messages.
`Debug_Level_Info = 4`
  Log level for information messages.
`Debug_Level_Debug = 5`
  Log level for debug messages.

## Structure types

### Debug_Message − ( d: Timestamp, s: Domain, u: Level, s: Message )

A struct representing a debug message, as returned by GetMessages.

In bindings that need a separate name, arrays of Debug_Message should be called Debug_Message_List.

#### Members

`Timestamp` − `d`
  Timestamp of the debug message. This is a double to allow more accuracy in the time the message was logged.
`Domain` − `s`

  Domain of the debug message. This is used to identify the source of debug messages. For example, debug messages from a connection manager could have this Domain struct member be the name of the connection manager, and logs from any helper library could have the name of the helper library.

  The domain could also contain a category as to where the log message originated separated by a forward-slash. For example, if a debug message was output in a connection manager called "dummy", in the file-transfer code, this Domain struct member might be `dummy/file-transfer`.

`Level` − `u` (Debug_Level)
  Level of the debug message. This states the severity of the debug message.
`Message` − `s`
  The text of the debug message.

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

Until a mechanism exists for making a reasonable automatic choice of AccountManager implementation, implementations SHOULD NOT register as an activatable service for the AccountManager's well-known bus name. Instead, it is RECOMMENDED that some component of the user's session will select and activate a particular implementation, and that other Telepathy-enabled programs can detect whether Telepathy is in use by checking whether the AccountManager's well-known name is in use at runtime.

Added in version 0.17.2.

## Methods:

### CreateAccount ( s: Connection_Manager, s: Protocol, s: Display_Name, a{sv}: Parameters, a{sv}: Properties ) → o

Request the creation of a new Account. The account manager SHOULD NOT allow invalid accounts to be created.

Changed in version 0.17.24: added the Properties argument

#### Parameters

`Connection_Manager` − `s` (Connection_Manager_Name)
  The name of the connection manager, e.g. "salut".
`Protocol` − `s` (Protocol)
  The protocol, e.g. "local-xmpp".
`Display_Name` − `s`
  The initial value of the new account's DisplayName property. The account manager SHOULD modify this to make it unique if an Account already exists with the same display name, for instance by appending a number or the 'account' parameter. Account manager implementations SHOULD accept an empty string, but account editing user interfaces should avoid passing an empty string for this parameter.
  The account creation UI may ask the user for a name for the new account. If the author of the UI chooses not to do this, the account creation UI is better able to suggest a default display name because it has protocol-specific knowledge which the account manager does not. The account manager always knows the complete list of accounts so it can easily tell whether it should append something to the display name to avoid presenting two identically-named accounts to the user.
`Parameters` − `a{sv}`
  Initial parameter values, as would be passed to RequestConnection.
`Properties` − `a{sv}` (Qualified_Property_Value_Map)

  The values of any other properties to be set immediately on the new Account.

  Only the properties mentioned in SupportedAccountProperties are acceptable here. In particular, the DisplayName and Parameters properties are never allowed here, since they are set using the other arguments to this method.

  Account manager implementations SHOULD support creating accounts with an empty value for this argument.

#### Returns

`Account` − `o`
  The new Account.

#### Possible errors

`org.freedesktop.Telepathy.Error.NotImplemented`

  The Connection_Manager is not installed or does not implement the given Protocol, or one of the properties in the Properties argument is unsupported.

`org.freedesktop.Telepathy.Error.InvalidArgument`

  The Parameters provided omit a required parameter or provide unsupported parameter, or the type of one of the Parameters or Properties is inappropriate.

## Signals:

### AccountRemoved ( o: Account )

The given account has been removed.
This is effectively change notification for the valid and invalid accounts lists. On emission of this signal, the Account indicated will no longer be present in either of the lists.

#### Parameters

`Account` − `o`
  An Account, which must not be used any more.

### AccountValidityChanged ( o: Account, b: Valid )

The validity of the given account has changed. New accounts are also indicated by this signal, as an account validity change (usually to True) on an account that did not previously exist.
This is effectively change notification for the valid and invalid accounts lists.

#### Parameters

`Account` − `o`
  An Account.
`Valid` − `b`
  True if the account is now valid.

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 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.
`SupportedAccountProperties` − `as` (DBus_Qualified_Member[]), read-only

  A list of the fully qualified names of properties that can be set via the Properties argument to CreateAccount when an account is created.

  Examples of good properties to support here include Icon, Enabled, Nickname, AutomaticPresence, ConnectAutomatically, RequestedPresence and Avatar.

  Examples of properties that would make no sense here include Valid, Connection, ConnectionStatus, ConnectionStatusReason, CurrentPresence and NormalizedName.

  This property MUST NOT include include the DisplayName and Parameters properties, which are set using separate arguments.

  This property MAY include the names of properties that, after account creation, will be read-only: this indicates that the property can be set at account creation but not changed later.

  For example, an account manager might support migration tools that use this to preserve the HasBeenOnline property, even though that property is usually read-only.

  Added in version 0.17.24.

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

This API avoids specifying the "profiles" used in Mission Control 4.x or the "presets" that have been proposed to replace them. An optional interface will be provided for AM implementations that want to provide presets.

There is deliberately no functionality here for opening channels; we intend to provide that in the channel dispatcher.

Other missing features which would be better in their own interfaces:

- dynamic parameter-providing (aka provisioning)
- saved server capabilities
- account conditions
- account grouping

Added in version 0.17.2.

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

## Methods:

### Remove ( ) → nothing

Delete the account.

#### Possible errors

`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)

### UpdateParameters ( a{sv}: Set, as: Unset ) → as

Change the value of the Parameters property.

If any of the changed parameters' Conn_Mgr_Param_Flags include `DBus_Property`, the change will be applied to the corresponding D-Bus Property on the active Connection, if there is one. Changes to other parameters will not take effect until the next time the account is disconnected and reconnected.

In general, reconnecting is a destructive operation that shouldn't happen as a side-effect. In particular, migration tools that twiddle the settings of all accounts shouldn't cause an automatic disconnect and reconnect.

Changed in version 0.17.16: parameters which are also D-Bus properties can and should be updated on existing Connections

Changed in version 0.17.24: return an array of the parameters that won't change until the account is reconnected

#### Parameters

`Set` − `a{sv}`
  A mapping from parameter names to their values. These parameters should be stored for future use.
`Unset` − `as`
  A list of the names of parameters to be removed from the set of stored values, allowing the default values to be used. If the given parameters were not, in fact, stored, or even if they do not exist at all, the account manager MUST accept this without error.

#### Returns

`Reconnect_Required` − `as`
  A list of the names of parameters with changes that will not take effect until the account is reconnected (this may be empty, e.g. if all the parameters are D-Bus properties or parameters for which the account manager has specific support). User interfaces that require "instant apply" semantics MAY call Reconnect in response to receiving a non-empty list.

#### Possible errors

`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  Raised when one of the provided arguments is invalid. (generic description)

### Reconnect ( ) → nothing

Re-connect this account. If the account is currently disconnected and the requested presence is offline, or if the account is not Enabled or not Valid, this does nothing.

If the account is disconnected and the requested presence is not offline, this forces an attempt to connect with the requested presence immediately.

If the account is connecting or connected, this is equivalent to remembering the current value of RequestedPresence, setting its value to (OFFLINE, "offline", ""), waiting for the change to take effect, then setting its value to the value that was previously remembered.

Clients desiring "instant apply" semantics for CM parameters MAY call this method to achieve that.

In particular, if the account's Connection is in the Connecting state, calling this method causes the attempt to connect to be aborted and re-tried.

This is necessary to ensure that the new parameters are picked up.

Added in version 0.17.24.

## Signals:

### Removed ( )

This account has been removed.
This is redundant with AccountRemoved, but it's still worth having, to avoid having to bind to AccountManager.AccountRemoved to tell you whether your Account is valid — ideally, an account-editing UI should only care about a single Account.

### AccountPropertyChanged ( a{sv}: Properties )

The values of one or more properties on this interface (that do not specify that this signal does not apply to them) may have changed. This does not cover properties of other interfaces, which must provide their own change notification if appropriate.

#### Parameters

`Properties` − `a{sv}`
  A map from property names in this namespace (e.g. Nickname) to values. Properties whose values have not changed SHOULD be omitted, but this need not be done.

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 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` − `s`, 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` − `o`, read-only

  Either the object path of the Connection to this account, or the special value `'/'` if there is no connection.

  If this object path is not '/', the Connection's well-known bus name can be derived from this object path by removing the first '/' and replacing subsequent '/' characters with '.'.

  Object paths aren't nullable, so we can't use an empty string.
`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 SimplePresence 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 InspectHandles 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.

`HasBeenOnline` − `b`, read-only
  If true, this account has successfully been put online at some point in the past.
  UIs could apply a policy that the 'account' parameter can only be edited in accounts that have never been online, or that ConnectAutomatically cannot be set on such accounts. The account manager should not enforce such policies, but it can expose enough information to UIs that the UI can decide what to do.

# org.freedesktop.Telepathy.Account.Interface.Avatar

Implementations of this interface must also implement:

- `org.freedesktop.Telepathy.Account`

This interface extends the core Account interface to provide a user-settable avatar image.

The avatar could have been a property on the core Account interface, but was moved to a separate interface because it is likely to be large. This means that clients can safely use GetAll to get properties on the core Account interface without flooding the session bus with large images.

Added in version 0.17.6.

Interface has no methods.

## Signals:

### AvatarChanged ( )

Emitted when the Avatar property changes.
The avatar itself is deliberately not included in this signal, to reduce bus traffic in the (likely common) case where no running application cares about the user's own avatar.

Interface has no Telepathy properties.

## D-Bus core Properties:

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

`Avatar` − `(ays)` (Avatar), read/write
  The avatar to set on this account for display to other contacts, represented as a structure containing the bytes of the avatar, and the MIME type as a string; may be set to an empty byte-array and an empty string to indicate no avatar. When the account becomes connected, the account manager SHOULD set this avatar using SetAvatar if appropriate.
  This corresponds to NMC 4.x mc_account_get_avatar.

## Structure types

### Avatar − ( ay: Avatar_Data, s: MIME_Type )

A struct containing avatar data marked with its MIME type.

Arrays of Avatar don't generally make sense.

#### Members

`Avatar_Data` − `ay`
  (undocumented)
`MIME_Type` − `s`
  (undocumented)

# org.freedesktop.Telepathy.ChannelDispatcher

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

The channel dispatcher is responsible for responding to new channels and launching client processes to handle them. It also provides functionality for client processes to request that new channels are created.

If a channel dispatcher is running, it is responsible for dispatching new channels on all Connections created by the AccountManager. Connections not created by the AccountManager are outside the scope of the channel dispatcher.

Connections created by standalone Telepathy clients that do not intend to interact with the channel dispatcher should be ignored - otherwise, the channel dispatcher would try to launch handlers for channels that the standalone client was already handling internally.

The current channel dispatcher is defined to be the process that owns the well-known bus name `org.freedesktop.Telepathy.ChannelDispatcher` on the session bus. This process MUST export an object with this interface at the object path `/org/freedesktop/Telepathy/ChannelDispatcher`.

Until a mechanism exists for making a reasonable automatic choice of ChannelDispatcher implementation, implementations SHOULD NOT register as an activatable service for the ChannelDispatcher's well-known bus name. Instead, it is RECOMMENDED that some component of the user's session will select and activate a particular implementation, and that other Telepathy-enabled programs can detect whether channel request/dispatch functionality is available by checking whether the ChannelDispatcher's well-known name is in use at runtime.

There are three categories of client process defined by this specification:

Observer

  Observers monitor the creation of new channels. This functionality can be used for things like message logging. All observers are notified simultaneously.

Approver
p

  Approvers notify the user that new channels have been created, and also select which channel handler will be used for the channel, either by asking the user or by choosing the most appropriate channel handler.

Handler

  Each new channel or set of channels is passed to exactly one handler as its final destination. A typical channel handler is a user interface process handling channels of a particular type.

## Methods:

### CreateChannel ( o: Account, a{sv}: Requested_Properties, x: User_Action_Time, s: Preferred_Handler ) → o

Start a request to create a channel. This initially just creates a ChannelRequest object, which can be used to continue the request and track its success or failure.

The request can take a long time - in the worst case, the channel dispatcher has to ask the account manager to put the account online, the account manager has to ask the operating system to obtain an Internet connection, and the operating system has to ask the user whether to activate an Internet connection using an on-demand mechanism like dialup.

This means that using a single D-Bus method call and response to represent the whole request will tend to lead to that call timing out, which is not the behaviour we want.

If this method is called for an Account that is disabled, invalid or otherwise unusable, no error is signalled until ChannelRequest.Proceed is called, at which point ChannelRequest.Failed is emitted with an appropriate error.

This means there's only one code path for errors, apart from InvalidArgument for "that request makes no sense".

It also means that the request will proceed if the account is enabled after calling CreateChannel, but before calling Proceed.

#### Parameters

`Account` − `o`
  The Account for which the new channel is to be created.
`Requested_Properties` − `a{sv}` (Qualified_Property_Value_Map)

  A dictionary containing desirable properties. This has the same semantics as the corresponding parameter to Connection.Interface.Requests.CreateChannel.

  Certain properties will not necessarily make sense in this dictionary: for instance, TargetHandle can only be given if the requester is able to interact with a Connection to the desired account.

`User_Action_Time` − `x` (Unix_Timestamp64)

  The time at which user action occurred, or 0 if this channel request is for some reason not involving user action. The UserActionTime property will be set to this value, and it will eventually be passed as the `User_Action_Time` parameter of HandleChannels.

`Preferred_Handler` − `s` (DBus_Well_Known_Name)

  Either the well-known bus name (starting with `org.freedesktop.Telepathy.Client.`) of the preferred handler for this channel, or an empty string to indicate that any handler would be acceptable. The channel dispatcher SHOULD dispatch as many as possible of the resulting channels (ideally, all of them) to that handler, and SHOULD remember the preferred handler so it can try to dispatch subsequent channels in the same bundle to the same handler.

  This must be the well-known bus name, not the unique name, to ensure that all handlers do indeed have the Client API, and the Client object on the handler can be located easily.

  This is partly so the channel dispatcher can call HandleChannels on it, and partly so the channel dispatcher can recover state if it crashes and is restarted.

  If this is a well-known bus name and the handler has the Requests interface, the channel dispatcher SHOULD call AddRequest on that Handler after this method has returned.

  This ordering allows a Handler which calls CreateChannel with itself as the preferred handler to associate the call to AddRequest with that call.

  This is copied to the ChannelRequest that is returned, as the PreferredHandler property.

#### Returns

`Request` − `o`
  A ChannelRequest object.

#### Possible errors

`org.freedesktop.Telepathy.Error.InvalidArgument`
  The Preferred_Handler is syntactically invalid or does not start with org.freedesktop.Telepathy.Client., the Account does not exist, or one of the Requested_Properties is invalid

### EnsureChannel ( o: Account, a{sv}: Requested_Properties, x: User_Action_Time, s: Preferred_Handler ) → o

Start a request to ensure that a channel exists, creating it if necessary. This initially just creates a ChannelRequest object, which can be used to continue the request and track its success or failure.

If this method is called for an Account that is disabled, invalid or otherwise unusable, no error is signalled until ChannelRequest.Proceed is called, at which point ChannelRequest.Failed is emitted with an appropriate error.

The rationale is as for CreateChannel.

#### Parameters

`Account` − `o`
  The Account for which the new channel is to be created.
`Requested_Properties` − `a{sv}` (Qualified_Property_Value_Map)

  A dictionary containing desirable properties. This has the same semantics as the corresponding parameter to Connection.Interface.Requests.EnsureChannel.

  Certain properties will not necessarily make sense in this dictionary: for instance, TargetHandle can only be given if the requester is able to interact with a Connection to the desired account.

`User_Action_Time` − `x` (Unix_Timestamp64)

  The time at which user action occurred, or 0 if this channel request is for some reason not involving user action.

  This parameter is used in the same way as the corresponding parameter to CreateChannel.

`Preferred_Handler` − `s` (DBus_Well_Known_Name)

  Either the well-known bus name (starting with `org.freedesktop.Telepathy.Client.`) of the preferred handler for this channel, or an empty string to indicate that any handler would be acceptable. The behaviour and rationale are the same as for the corresponding parameter to CreateChannel, except as noted here.

  If any new channels are created in response to this request, the channel dispatcher SHOULD dispatch as many as possible of the resulting channels (ideally, all of them) to that handler, and SHOULD remember the preferred handler so it can try to dispatch subsequent channels in the same bundle to the same handler. If the requested channel already exists (that is, Connection.Interface.Requests.EnsureChannel returns `Yours=False`) then the channel dispatcher SHOULD re-dispatch the channel to its existing handler, and MUST NOT dispatch it to this client (unless it is the existing handler); the request is still deemed to have succeeded in this case.

  An address book application, for example, might call EnsureChannel to ensure that a text channel with a particular contact is displayed to the user; it does not care whether a new channel was made. An IM client might call EnsureChannel in response to the user double-clicking an entry in the contact list, with itself as the `Preferred_Handler`; if the user already has a conversation with that contact in another application, they would expect the existing window to be presented, rather than their double-click leading to an error message. So the request should succeed, even if its `Preferred_Handler` is not used.

#### Returns

`Request` − `o`
  A ChannelRequest object.

#### Possible errors

`org.freedesktop.Telepathy.Error.InvalidArgument`
  The Preferred_Handler is syntactically invalid or does not start with org.freedesktop.Telepathy.Client., the Account does not exist, or one of the Requested_Properties is invalid

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

# org.freedesktop.Telepathy.ChannelDispatcher.Interface.OperationList

This interface is not yet final 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.ChannelDispatcher`

This interface allows users of the ChannelDispatcher to enumerate all the pending dispatch operations, with change notification.

The existence of the DispatchOperations property allows a newly started approver to pick up existing dispatch operations.

This is on a separate interface so clients that aren't interested in doing this aren't woken up by its signals.

Interface has no methods.

## Signals:

### NewDispatchOperation ( o: Dispatch_Operation, a{sv}: Properties )

Emitted when a dispatch operation is added to DispatchOperations.

#### Parameters

`Dispatch_Operation` − `o`
  The dispatch operation that was created.
`Properties` − `a{sv}` (Qualified_Property_Value_Map)
  The same properties that would appear in the Properties member of Dispatch_Operation_Details.

### DispatchOperationFinished ( o: Dispatch_Operation )

Emitted when a dispatch operation finishes (i.e. exactly once per emission of ChannelDispatchOperation.Finished).
Strictly speaking this is redundant with ChannelDispatchOperation.Finished, but it provides full change-notification for the DispatchOperations property.

#### Parameters

`Dispatch_Operation` − `o`
  The dispatch operation that was closed.

Interface has no Telepathy properties.

## D-Bus core Properties:

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

`DispatchOperations` − `a(oa{sv})` (Dispatch_Operation_Details[]), read-only

  The list of ChannelDispatchOperation objects currently being processed. Change notification is via the NewDispatchOperation and DispatchOperationFinished signals.

## Structure types

### Dispatch_Operation_Details − ( o: Channel_Dispatch_Operation, a{sv}: Properties )

Details of a channel dispatch operation.

In bindings that need a separate name, arrays of Dispatch_Operation_Details should be called Dispatch_Operation_Details_List.

#### Members

`Channel_Dispatch_Operation` − `o`
  The object path of the ChannelDispatchOperation.
`Properties` − `a{sv}` (Qualified_Property_Value_Map)

  Properties of the channel dispatch operation.

  Connection managers MUST NOT include properties in this mapping if their values can change. Clients MUST ignore properties that appear in this mapping if their values can change.

  The rationale is the same as for Channel_Details.

  Each dictionary MUST contain at least the following keys:

  - org.freedesktop.Telepathy.ChannelDispatchOperation.Interfaces
  - org.freedesktop.Telepathy.ChannelDispatchOperation.Connection
  - org.freedesktop.Telepathy.ChannelDispatchOperation.Account
  - org.freedesktop.Telepathy.ChannelDispatchOperation.PossibleHandlers

# org.freedesktop.Telepathy.ChannelDispatchOperation

This interface is not yet final 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 channel dispatch operation is an object in the ChannelDispatcher representing a batch of unrequested channels being announced to client Approver processes.

These objects can result from new incoming channels or channels which are automatically created for some reason, but cannot result from outgoing requests for channels.

More specifically, whenever the Connection.Interface.Requests.NewChannels signal contains channels whose Requested property is false, or whenever the Connection.NewChannel signal contains a channel with suppress_handler false, one or more ChannelDispatchOperation objects are created for those channels.

(If some channels in a NewChannels signal are in different bundles, this is an error. The channel dispatcher SHOULD recover by treating the NewChannels signal as if it had been several NewChannels signals each containing one channel.)

First, the channel dispatcher SHOULD construct a list of all the Handlers that could handle all the channels (based on their HandlerChannelFilter property), ordered by priority in some implementation-dependent way. If there are handlers which could handle all the channels, one channel dispatch operation SHOULD be created for all the channels. If there are not, one channel dispatch operation SHOULD be created for each channel, each with a list of channel handlers that could handle that channel.

If no handler at all can handle a channel, the channel dispatcher SHOULD terminate that channel instead of creating a channel dispatcher for it. It is RECOMMENDED that the channel dispatcher closes the channels using Channel.Interface.Destroyable.Destroy if supported, or Channel.Close otherwise. As a special case, the channel dispatcher SHOULD NOT close ContactList channels, and if Close fails, the channel dispatcher SHOULD ignore that channel.

ContactList channels are strange. We hope to replace them with something better, such as an interface on the Connection, in a future version of this specification.

When listing channel handlers, priority SHOULD be given to channel handlers that are already handling channels from the same bundle.

If a handler with BypassApproval `= True` could handle all of the channels in the dispatch operation, then the channel dispatcher SHOULD call HandleChannels on that handler, and (assuming the call succeeds) emit Finished and stop processing those channels without involving any approvers.

Some channel types can be picked up "quietly" by an existing channel handler. If a Text channel is added to an existing bundle containing a StreamedMedia channel, there shouldn't be any approvers, flashing icons or notification bubbles, if the the UI for the StreamedMedia channel can just add a text box and display the message.

Otherwise, the channel dispatcher SHOULD send the channel dispatch operation to all relevant approvers (in parallel) and wait for an approver to claim the channels or request that they are handled. See AddDispatchOperation for more details on this.

Finally, if the approver requested it, the channel dispatcher SHOULD send the channels to a handler.

## Methods:

### HandleWith ( s: Handler ) → nothing

Called by an approver to accept a channel bundle and request that the given handler be used to handle it.

If successful, this method will cause the ChannelDispatchOperation object to disappear, emitting Finished.

However, this method may fail because the dispatch has already been completed and the object has already gone. If this occurs, it indicates that another approver has asked for the bundle to be handled by a particular handler. The approver MUST NOT attempt to interact with the channels further in this case, unless it is separately invoked as the handler.

Approvers which are also channel handlers SHOULD use Claim instead of HandleWith to request that they can handle a channel bundle themselves.

(FIXME: list some possible errors)

If the channel handler raises an error from HandleChannels, this method MAY respond by raising that same error, even if it is not specifically documented here.

#### Parameters

`Handler` − `s` (DBus_Bus_Name)

  The well-known bus name (starting with `org.freedesktop.Telepathy.Client.`) of the channel handler that should handle the channel, or the empty string if the client has no preferred channel handler.

#### Possible errors

`org.freedesktop.Telepathy.Error.InvalidArgument`
  The selected handler is non-empty, but is not a syntactically correct DBus_Bus_Name or does not start with "`org.freedesktop.Telepathy.Client.`".
`org.freedesktop.Telepathy.Error.NotAvailable`
  The selected handler is temporarily unable to handle these channels.
`org.freedesktop.Telepathy.Error.NotImplemented`
  The selected handler is syntactically correct, but will never be able to handle these channels (for instance because the channels do not match its HandlerChannelFilter, or because HandleChannels raised NotImplemented).
`org.freedesktop.Telepathy.Error.NotYours`
  At the time that HandleWith was called, this dispatch operation was processing an earlier call to HandleWith. The earlier call has now succeeded, so some Handler nominated by another approver is now responsible for the channels. In this situation, the second call to HandleWith MUST NOT return until the first one has returned successfully or unsuccessfully, and if the first call to HandleChannels fails, the channel dispatcher SHOULD try to obey the choice of Handler made by the second call to HandleWith.

### Claim ( ) → nothing

Called by an approver to claim channels for handling internally. If this method is called successfully, the process calling this method becomes the handler for the channel, but does not have the HandleChannels method called on it.

Clients that call Claim on channels but do not immediately close them SHOULD implement the Handler interface and its HandledChannels property.

Approvers wishing to reject channels MUST call this method to claim ownership of them, and MUST NOT call Close on the channels unless/until this method returns successfully.

The channel dispatcher can't know how best to close arbitrary channel types, so it leaves it up to the approver to do so. For instance, for Text channels it is necessary to acknowledge any messages that have already been displayed to the user first - ideally, the approver would display and then acknowledge the messages - or to call Channel.Interface.Destroyable.Destroy if the destructive behaviour of that method is desired.

Similarly, an Approver for StreamedMedia channels can close the channel with a reason (e.g. "busy") if desired. The channel dispatcher, which is designed to have no specific knowledge of particular channel types, can't do that.

If successful, this method will cause the ChannelDispatchOperation object to disappear, emitting Finished, in the same way as for HandleWith.

This method may fail because the dispatch operation has already been completed. Again, see HandleWith for more details. The approver MUST NOT attempt to interact with the channels further in this case.

(FIXME: list some other possible errors)

#### Possible errors

`org.freedesktop.Telepathy.Error.NotYours`
  At the time that Claim was called, this dispatch operation was processing a call to HandleWith which has now succeeded, so some Handler nominated by another approver is now responsible for the channel.

## Signals:

### ChannelLost ( o: Channel, s: Error, s: Message )

A channel has closed before it could be claimed or handled. If this is emitted for the last remaining channel in a channel dispatch operation, it MUST immediately be followed by Finished.

This signal MUST NOT be emitted until all Approvers that were invoked have returned (successfully or with an error) from their AddDispatchOperation method.

This means that Approvers can connect to the ChannelLost signal in a race-free way. Non-approver processes that discover a channel dispatch operation in some way (such as observers) will have to follow the usual "connect to signals then recover state" model - first connect to ChannelLost and Finished, then download Channels (and on error, perhaps assume that the operation has already Finished).

#### Parameters

`Channel` − `o`
  The Channel that closed.
`Error` − `s` (DBus_Error_Name)

  The name of a D-Bus error indicating why the channel closed. If no better reason can be found, `org.freedesktop.Telepathy.Error.NotAvailable` MAY be used as a fallback; this means that this error SHOULD NOT be given any more specific meaning.

`Message` − `s`
  A string associated with the D-Bus error.

### Finished ( )

Emitted when this dispatch operation finishes. The dispatch operation is no longer present and further methods must not be called on it.

Approvers that have a user interface SHOULD stop notifying the user about the channels in response to this signal; they MAY assume that on errors, they would have received ChannelLost first.

Its object path SHOULD NOT be reused for a subsequent dispatch operation; the ChannelDispatcher MUST choose object paths in a way that avoids immediate re-use.

Otherwise, clients might accidentally call HandleWith or Claim on a new dispatch operation instead of the one they intended to handle.

This signal MUST NOT be emitted until all Approvers that were invoked have returned (successfully or with an error) from their AddDispatchOperation method.

This means that Approvers can connect to the ChannelLost signal in a race-free way. Non-approver processes that discover a channel dispatch operation in some way (such as observers) will have to follow the usual "connect to signals then recover state" model - first connect to ChannelLost and Finished, then download Channels (and on error, perhaps assume that the operation has already Finished).

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 dispatch operation. This property cannot change.
`Connection` − `o`, read-only
  The Connection with which the Channels are associated. The well-known bus name to use can be derived from this object path by removing the leading '/' and replacing all subsequent '/' by '.'. This property cannot change.
`Account` − `o`, read-only
  The Account with which the Connection and Channels are associated. This property cannot change.
`Channels` − `a(oa{sv})` (Channel_Details[]), read-only
  The Channels to be dispatched, and their properties. Change notification is via the ChannelLost signal (channels cannot be added to this property, only removed).
`PossibleHandlers` − `as` (DBus_Well_Known_Name[]), read-only
  The well known bus names (starting with org.freedesktop.Telepathy.Client.) of the possible Handlers for these channels. The channel dispatcher MUST place the most preferred handlers first, according to some reasonable heuristic. As a result, approvers SHOULD use the first handler by default. The heuristic used to prioritize handlers SHOULD give a higher priority to handlers that are already running.
  If, for instance, Empathy and Kopete have similar functionality, and Empathy is running, we should prefer to send channels to it rather than launching Kopete via service activation.

# org.freedesktop.Telepathy.ChannelRequest

This interface is not yet final 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 channel request is an object in the ChannelDispatcher representing an ongoing request for some channels to be created or found. There can be any number of ChannelRequest objects at the same time.

Its well-known bus name is the same as that of the ChannelDispatcher, "org.freedesktop.Telepathy.ChannelDispatcher".

See ChannelDispatcher.CreateChannel for rationale for ChannelRequest being a separate object.

A channel request can be cancelled by any client (not just the one that requested it). This means that the ChannelDispatcher will Close the resulting channel, or refrain from requesting it at all, rather than dispatching it to a handler.

## Methods:

### Proceed ( ) → nothing

Proceed with the channel request.

The client that created this object calls this method when it has connected signal handlers for Succeeded and Failed.

Clients other than the client which created the ChannelRequest MUST NOT call this method.

This method SHOULD return immediately; on success, the request might still fail, but this will be indicated asynchronously by the Failed signal.

Proceed cannot fail, unless clients have got the life-cycle of a ChannelRequest seriously wrong (e.g. a client calls this method twice, or a client that did not create the ChannelRequest calls this method). If it fails, clients SHOULD assume that the whole ChannelRequest has become useless.

#### Possible errors

`org.freedesktop.Telepathy.Error.NotAvailable`
  This method has already been called, so it is no longer available. Stop calling it.

### Cancel ( ) → nothing

Cancel the channel request. The precise effect depends on the current progress of the request.

If the connection manager has not already been asked to create a channel, then Failed is emitted immediately, and the channel request is removed.

If the connection manager has already been asked to create a channel but has not produced one yet (e.g. if Connection.Interface.Requests.CreateChannel has been called, but has not yet returned), then the ChannelDispatcher will remember that the request has been cancelled. When the channel appears, it will be closed (if it was newly created and can be closed), and will not be dispatched to a handler.

If the connection manager has already returned a channel, but the channel has not yet been dispatched to a handler then the channel dispatcher will not dispatch that channel to a handler. If the channel was newly created for this request, the channel dispatcher will close it with Close; otherwise, the channel dispatcher will ignore it. In either case, Failed will be emitted when processing has been completed.

If Failed is emitted in response to this method, the error SHOULD be `org.freedesktop.Telepathy.Error.Cancelled`.

If the channel has already been dispatched to a handler, then it's too late to call this method, and the channel request will no longer exist.

## Signals:

### Failed ( s: Error, s: Message )

The channel request has failed. It is no longer present, and further methods must not be called on it.

#### Parameters

`Error` − `s` (DBus_Error_Name)

  The name of a D-Bus error. This can come from various sources, including the error raised by CreateChannel, or an error generated to represent failure to establish the Connection.

`Message` − `s`
  If the first argument of the D-Bus error message was a string, that string. Otherwise, an empty string.

### Succeeded ( )

The channel request has succeeded. It is no longer present, and further methods must not be called on it.

Interface has no Telepathy properties.

## D-Bus core Properties:

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

`Account` − `o`, read-only
  The Account on which this request was made. This property cannot change.
`UserActionTime` − `x` (Unix_Timestamp64), read-only

  The time at which user action occurred, or 0 if this channel request is for some reason not involving user action.

  This corresponds to the _NET_WM_USER_TIME property in EWMH.

  This property is set when the channel request is created, and can never change.

`PreferredHandler` − `s` (DBus_Well_Known_Name), read-only

  Either the well-known bus name (starting with `org.freedesktop.Telepathy.Client.`) of the preferred handler for this channel, or an empty string to indicate that any handler would be acceptable.

  This property is set when the channel request is created, and can never change.

`Requests` − `aa{sv}` (Qualified_Property_Value_Map[]), read-only

  An array of dictionaries containing desirable properties for the channel or channels to be created.

  This is an array so that we could add a CreateChannels method in future without redefining the API of ChannelRequest.

  This property is set when the channel request is created, and can never change.

`Interfaces` − `as` (DBus_Interface[]), read-only
  A list of the extra interfaces provided by this channel request. This property cannot change.

# org.freedesktop.Telepathy.Client

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

Telepathy clients use connection managers, the channel dispatcher and optionally the account manager to provide useful functionality.

User interface processes are the obvious example of Telepathy clients, but they can provide other functionality, such as address-book synchronization.

Every running or activatable process with a well-known name of the form org.freedesktop.Telepathy.Client.clientname should be probed by the channel dispatcher to discover its capabilities. Each client is either an observer, an approver, a channel handler, or some combination of these.

Activatable services (those with a D-Bus `.service` file) must be supported so that we can run clients in response to channel creation.

Non-activatable services (those that do not register a D-Bus `.service` file for their well-known name, but do request it at runtime) must be supported so that we can have programs that process channels, but only if they are already running - for instance, a full-screen media centre application might do this.

The client name, clientname, MUST be a non-empty string of ASCII digits, letters, dots and/or underscores, starting with a letter, and without sets of two consecutive dots or a dot followed by a digit. For non-activatable services, it MAY contain a part that is generated per instance at runtime.

If each of a client Foo's instances should be able to manipulate channels separately, the instance with unique name `:1.25` might request a well-known name like `org.freedesktop.Telepathy.Client.Foo._1._25`.

(Note that well-known bus-name components may not start with a digit, so o.f.T.Client.Foo.1.25 would not be acceptable.)

Each Client MUST export an object whose object path may be determined by replacing '.' with '/' in the well-known name and prepending '/'. This object represents its API as a Telepathy client; the channel dispatcher will call its methods and read its properties when appropriate.

As an optimization, activatable clients SHOULD install a file `$XDG_DATA_DIRS/telepathy/clients/clientname.client` containing a cached version of its immutable properties, so that for most clients, the channel dispatcher can just read a file to discover capabilities, instead of having to service-activate the client immediately in order to fetch its read-only properties. However, the D-Bus API is canonical, and the channel dispatcher MUST support clients without such a file.

Non-activatable clients MAY install a `.client` file, but there's not much point in them doing so.

The .client files MUST contain UTF-8 text with the same syntax as Desktop Entry files (although the allowed groups, keys and values differ). Every `.client` file MUST contain a group whose name is the name of this interface.

The groups, keys and values in the `.client` file are defined by individual interfaces. Each interface that can usefully cache information in the `.client` file SHOULD correspond to a group with the same name.

Added in version 0.17.12. (as a draft)

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 client. This SHOULD include at least one of Client.Observer, Client.Approver or Client.Handler.

  In the `.client` file, this is represented by key "`Interfaces`" in the group named after this interface. The value of the key is a list of interface names each followed by a semicolon (so it always ends with a semicolon unless it is empty), i.e. a key of type "strings" as described in the Desktop Entry specification.

# org.freedesktop.Telepathy.Client.Observer

This interface is not yet final 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.Client`

Observers monitor the creation of new channels. This functionality can be used for things like message logging. All observers are notified simultaneously.

Observers SHOULD NOT modify the state of a channel except via user interaction.

We want Observer UIs for file transfer channels (a progress bar for the transfer) to be able to have a Cancel button.

Observers MUST NOT carry out actions that exactly one process must take responsibility for (e.g. acknowledging Text messages, or carrying out the actual transfer in a file transfer channel).

Since arbitrarily many observers can be activated for each channel, it would not make sense for observers to do things that can only be done by one process (acknowledging Text messages, carrying out streaming for StreamedMedia channels, doing the actual data transfer for file transfers, setting up the out-of-band connection for Tubes). The Handler is responsible for such tasks.

Handlers MAY, of course, delegate responsibility for these tasks to other processes (including those run as observers), but this MUST be done explicitly via a request from the Handler to the Observer.

Whenever a collection of new channels is signalled, the channel dispatcher will notify all running or activatable observers whose ObserverChannelFilter property (possibly as cached in the .client file) indicates that they are interested in some of the channels.

Observers are activated for all channels in which they have registered an interest - incoming, outgoing or automatically created - although of course the ObserverChannelFilter property can be set to filter on the Requested property.

Because it might take time for an observer to become ready (for instance, a Text logger needs to wait until pending messages have been downloaded), the channel dispatcher must wait (up to some timeout) for all observers to return from ObserveChannels before letting anything destructive happen. Destructive things (e.g. acknowledging messages) are defined to be done by handlers, therefore HandleWith and Claim aren't allowed to succeed until all observers are ready.

Added in version 0.17.12. (as a draft)

## Methods:

### ObserveChannels ( o: Account, o: Connection, a(oa{sv}): Channels, o: Dispatch_Operation, ao: Requests_Satisfied, a{sv}: Observer_Info ) → nothing

Called by the channel dispatcher when channels in which the observer has registered an interest are announced in a NewChannels signal.

If the same NewChannels signal announces some channels that match the filter, and some that do not, then only a subset of the channels (those that do match the filter) are passed to this method.

If the channel dispatcher will split up the channels from a single NewChannels signal and dispatch them separately (for instance because no installed Handler can handle all of them), it will call ObserveChannels several times.

The observer MUST NOT return from this method call until it is ready for a handler for the channel to run (which may change the channel's state).

The channel dispatcher must wait for observers to start up, to avoid the following race: text channel logger (observer) gets ObserveChannels, text channel handler gets HandleChannels channel handler starts up faster and acknowledges messages, logger never sees those messages.

The channel dispatcher SHOULD NOT change its behaviour based on whether this method succeeds or fails: there are no defined D-Bus errors for this method, and if it fails, this only indicates that an Observer is somehow broken.

The expected error response in the channel dispatcher is to log a warning, and otherwise continue as though this method had succeeded.

#### Parameters

`Account` − `o`
  The Account with which the channels are associated. The well-known bus name to use is that of the AccountManager.
`Connection` − `o`
  The Connection with which the channels are associated. The well-known bus name to use can be derived from this object path by removing the leading '/' and replacing all subsequent '/' by '.'.
`Channels` − `a(oa{sv})` (Channel_Details[])
  The Channels and their properties. Their well-known bus names are all the same as that of the Connection.
`Dispatch_Operation` − `o`

  The path to the ChannelDispatchOperation for these channels, or the special value '/' if there is no ChannelDispatchOperation (because the channels were requested, not incoming).

  If the Observer calls Claim or HandleWith on the dispatch operation, it MUST be careful to avoid deadlock, since these methods cannot return until the Observer has returned from ObserveChannels.

  This allows an Observer to Claim a set of channels without having to match up calls to this method with calls to AddDispatchOperation.

`Requests_Satisfied` − `ao`
  The requests satisfied by these channels.
  If the same process is an Observer and a Handler, it can be useful to be given this information as soon as possible (it will also be passed to Handler.HandleChannels).
`Observer_Info` − `a{sv}`

  Additional information about these channels. No keys are currently defined.

  If keys are defined for this dictionary, all will be optional; observers MAY safely ignore any entry in this dictionary.

Interface has no signals.

Interface has no Telepathy properties.

## D-Bus core Properties:

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

`ObserverChannelFilter` − `aa{sv}` (Channel_Class[]), read-only

  A specification of the channels in which this observer is interested. The ObserveChannels method should be called by the channel dispatcher whenever any of the new channels in a NewChannels signal match this description.

  Only certain D-Bus types have useful semantics for matching like this, so only certain types are allowed:

  Integers of all sizes, including byte (y, n, q, i, u, x, t)
    Matched by numeric value, regardless of type (e.g. 42 as a 16-bit signed integer 'n' is considered equal to 42 as a 32-bit unsigned integer 'u')
  Booleans (b)
    Matched by equality in the obvious way; not considered equal to any other type
  Strings (s)
    Matched by equality in the obvious way; not considered equal to any other type
  Object paths (o)
    Matched by equality in the obvious way; not considered equal to any other type

  This property never changes while the observer process owns its Client bus name. For activatable processes, the filter can change due to an upgrade - the channel dispatcher SHOULD observe changes to .client files using a mechanism like inotify.

  Not allowing this property to change is a simplification, particularly for activatable processes (we reject the possibility that a process with a .client file, when activated, has a filter that differs from what its .client file said).

  If an Observer wants to add extra channels to its list of interests at runtime, it can register an additional Client bus name (for instance, the org.freedesktop.Telepathy.Client.Empathy process with unique name :1.42 could additionally register org.freedesktop.Telepathy.Client.Empathy._1_42) with additional filters. To remove those filters, it can release the bus name; it could even re-claim the bus name immediately, with different filters.

  The same principle is applied to Approvers and Handlers.

  For observers that have a .client file, the channel dispatcher may discover this property from keys of the form `propertyname/type`, in groups in the .client file whose name is the name of this interface followed by `.ObserverChannelFilter`, a space and an ASCII decimal number starting from 0.

  Integers in the .client file are encoded in ASCII decimal, booleans are encoded as "true" or "false", and strings are encoded in the usual way for desktop files (including the C-style backslash escapes documented in the Desktop Entry specification).

  For instance, a .client file for an observer that is only interested in Text channels, with CONTACT or ROOM handles, that were requested by a local client:

      [org.freedesktop.Telepathy.Client]
      Interfaces=org.freedesktop.Telepathy.Client.Observer;

      [org.freedesktop.Telepathy.Client.Observer.ObserverChannelFilter 0]
      org.freedesktop.Telepathy.Channel.Type s=org.freedesktop.Telepathy.Channel.Type.Text
      org.freedesktop.Telepathy.Channel.TargetHandleType u=1
      org.freedesktop.Telepathy.Channel.Requested b=true

      [org.freedesktop.Telepathy.Client.Observer.ObserverChannelFilter 1]
      org.freedesktop.Telepathy.Channel.Type s=org.freedesktop.Telepathy.Channel.Type.Text
      org.freedesktop.Telepathy.Channel.TargetHandleType u=2
      org.freedesktop.Telepathy.Channel.Requested b=true

# org.freedesktop.Telepathy.Client.Approver

This interface is not yet final 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.Client`

Approvers are clients that notify the user that new channels have been created by a contact, and allow the user to accept or reject those channels. The new channels are represented by a ChannelDispatchOperation object, which is passed to the AddDispatchOperation method.

For instance, Empathy's tray icon, or the answer/reject window seen when a Maemo device receives a VoIP call, should be Approvers.

Approvers can also select which channel handler will be used for the channel, for instance by offering the user a list of possible handlers rather than just an accept/reject choice. However, the Channel Dispatcher must be able to prioritize possible handlers on its own using some reasonable heuristic, probably based on user configuration.

It is possible (and useful) to have an approver and a channel handler in the same process; this is particularly useful if a channel handler wants to claim responsibility for particular channels itself.

All approvers are notified simultaneously. For instance, in a desktop system, there might be one approver that displays a notification-area icon, one that is part of a contact list window and highlights contacts there, and one that is part of a full-screen media player.

Any approver can approve the handling of a channel dispatch operation with a particular channel handler by calling the HandleWith method. Approvers can also attempt to Claim channels; if this succeeds, the approver may handle the channels itself (if it is also a Handler), or close the channels in order to reject them.

At the D-Bus level, there is no "reject" operation: approvers wishing to reject channels SHOULD call the Claim method, then (if it succeeds) close the channels in any way they see fit.

The first approver to reply gets its decision acted on; any other approvers that reply at approximately the same time will get a D-Bus error, indicating that the channel has already been dealt with.

Approvers should usually prompt the user and ask for confirmation, rather than dispatching the channel to a handler straight away.

Added in version 0.17.12. (as a draft)

## Methods:

### AddDispatchOperation ( a(oa{sv}): Channels, o: DispatchOperation, a{sv}: Properties ) → nothing

Called by the channel dispatcher when a ChannelDispatchOperation in which the approver has registered an interest is created, or when the approver starts up while such channel dispatch operations already exist.

The channel dispatcher SHOULD call this method on all approvers at the same time. If an approver returns an error from this method, the approver is assumed to be faulty.

If no approvers return from this method successfully (including situations where there are no matching approvers at all), the channel dispatcher SHOULD consider this to be an error, and recover by dispatching the channel to the most preferred handler.

Processes that aren't approvers (or don't at least ensure that there is some approver) probably shouldn't be making connections anyway, so there should always be at least one approver running.

#### Parameters

`Channels` − `a(oa{sv})` (Channel_Details[])

  The initial value of the ChannelDispatchOperation.Channels property, containing the Channels to be dispatched and their properties.

  This can't be signalled to the approver through the Properties parameter of this method, because Channels is not an immutable property.

  This argument always contains all of the channels in the channel dispatch operation, even if not all of them actually match the ApproverChannelFilter.

  This seems the least bad way to handle such a situation; see the discussion on bug #21090.

  The actual channels to be dispatched may reduce as channels are closed: this is signalled by ChannelDispatchOperation.ChannelLost.

  Approvers SHOULD connect to ChannelLost and ChannelDispatchOperation.Finished. (if desired) before returning from AddDispatchOperation, since those signals are guaranteed not to be emitted until after all AddDispatchOperation calls have returned (with success or failure) or timed out.

`DispatchOperation` − `o`

  The ChannelDispatchOperation to be processed.

`Properties` − `a{sv}` (Qualified_Property_Value_Map)
  Properties of the channel dispatch operation. This MUST NOT include properties that could change, SHOULD include as many properties as possible given that constraint, and MUST include at least the Account, Connection and PossibleHandlers properties.

Interface has no signals.

Interface has no Telepathy properties.

## D-Bus core Properties:

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

`ApproverChannelFilter` − `aa{sv}` (Channel_Class[]), read-only

  A specification of the channels in which this approver is interested. The AddDispatchOperation method should be called by the channel dispatcher whenever at least one of the channels in a channel dispatch operation matches this description.

  This property works in exactly the same way as the Client.Observer.ObserverChannelFilter property. In particular, it cannot change while the approver process continues to own the corresponding Client bus name.

  In the .client file, it is represented in the same way as ObserverChannelFilter, but the group has the same name as this interface and the keys start with ApproverChannelFilter instead of ObserverChannelFilter.

# org.freedesktop.Telepathy.Client.Handler

This interface is not yet final 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.Client`

Handlers are the user interface for a channel. They turn an abstract Telepathy channel into something the user wants to see, like a text message stream or an audio and/or video call.

For its entire lifetime, each channel on a connection known to the channel dispatcher is either being processed by the channel dispatcher, or being handled by precisely one Handler.

Because each channel is only handled by one Handler, handlers may perform actions that only make sense to do once, such as acknowledging Text messages, doing the actual streaming for StreamedMedia channels with the MediaSignalling interface, or transferring the file in FileTransfer channels.

When a new incoming channel (one with Requested = FALSE) is offered to Approvers by the channel dispatcher, it also offers the Approvers a list of all the running or activatable handlers whose HandlerChannelFilter property (possibly as cached in the .client file) indicates that they are able to handle the channel. The Approvers can choose one of those channel handlers to handle the channel.

When a new outgoing channel (one with Requested = TRUE) appears, the channel dispatcher passes it to an appropriate channel handler automatically.

Added in version 0.17.12. (as a draft)

## Methods:

### HandleChannels ( o: Account, o: Connection, a(oa{sv}): Channels, ao: Requests_Satisfied, t: User_Action_Time, a{sv}: Handler_Info ) → nothing

Called by the channel dispatcher when this client should handle these channels, or when this client should present channels that it is already handling to the user (e.g. bring them into the foreground).

Clients are expected to know what channels they're already handling, and which channel object path corresponds to which window or tab. This can easily be done using a hash table keyed by channels' object paths.

This method can raise any D-Bus error. If it does, the handler is assumed to have failed or crashed, and the channel dispatcher MUST recover in an implementation-specific way; it MAY attempt to dispatch the channels to another handler, or close the channels.

If closing the channels, it is RECOMMENDED that the channel dispatcher attempts to close the channels using Channel.Close, but resorts to calling Channel.Interface.Destroyable.Destroy (if available) or ignoring the channel (if not) if the same handler repeatedly fails to handle channels.

After HandleChannels returns successfully, the client process is considered to be responsible for the channel until it its unique name disappears from the bus.

If a process has multiple Client bus names - some temporary and some long-lived - and drops one of the temporary bus names in order to reduce the set of channels that it will handle, any channels that it is already handling should remain unaffected.

#### Parameters

`Account` − `o`
  The Account with which the channels are associated. The well-known bus name to use is that of the AccountManager.
`Connection` − `o`
  The Connection with which the channels are associated. The well-known bus name to use can be derived from this object path by removing the leading '/' and replacing all subsequent '/' by '.'.
`Channels` − `a(oa{sv})` (Channel_Details[])
  The channels and their immutable properties. Their well-known bus name is the same as that of the Connection.
`Requests_Satisfied` − `ao`

  The requests satisfied by these channels.

  If the handler implements Requests, this tells it that these channels match previous AddRequest calls that it may have received.

  There can be more than one, if they were EnsureChannel requests.

`User_Action_Time` − `t`
  The time at which user action occurred, or 0 if this channel is to be handled for some reason not involving user action. Handlers SHOULD use this for focus-stealing prevention, if applicable.
`Handler_Info` − `a{sv}`

  Additional information about these channels. No keys are currently defined.

  If keys are defined for this dictionary, all will be optional; handlers MAY safely ignore any entry in this dictionary.

Interface has no signals.

Interface has no Telepathy properties.

## D-Bus core Properties:

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

`HandlerChannelFilter` − `aa{sv}` (Channel_Class[]), read-only

  A specification of the channels that this channel handler can deal with. It will be offered to approvers as a potential channel handler for bundles that contain only suitable channels, or for suitable channels that must be handled separately.

  This property works in exactly the same way as the Client.Observer.ObserverChannelFilter property. In particular, it cannot change while the handler process continues to own the corresponding Client bus name.

  In the .client file, it is represented in the same way as ObserverChannelFilter, but the group has the same name as this interface and the keys start with HandlerChannelFilter instead of ObserverChannelFilter.

`BypassApproval` − `b`, read-only

  If true, channels destined for this handler are automatically handled, without invoking approvers.

  The intended usage is to allow a client handling one channel to pick up closely related channels. Suppose a client capable of handling both Text and StreamedMedia, `org.freedesktop.Telepathy.Client.Empathy`, is handling a StreamedMedia channel. That client can take a second well-known bus name, say `org.freedesktop.Telepathy.Client.Empathy._1._42.Bundle1`, and configure an object at `/org/freedesktop/Telepathy/Client/Empathy/_1/_42/Bundle1` with BypassApproval = TRUE, whose HandlerChannelFilter matches closely related Text channels by their Bundle property. (This is use-case dis5)

`HandledChannels` − `ao`, read-only

  A list of the channels that this process is currently handling.

  There is no change notification.

  This property exists for state recovery - it makes it possible for channel handling to survive a ChannelDispatcher crash.

  If the channel dispatcher is automatically replaced, the replacement can discover all Handlers by looking for the Client well-known bus names, and discover which channels they are currently handling. Once this has been done, all unhandled channels can be re-dispatched, and the only issue visible to the user is that unhandled channels that they have already approved might be sent back to Approvers.

  The value of this property SHOULD be the same for all Client instances that share a unique bus name, and SHOULD include all channels that are being handled, even if they were conceptually handled by a different Client instance.

  Otherwise, when a process released a temporary Client name, channels that it handled because of that Client name would no longer be state-recoverable.

# org.freedesktop.Telepathy.Client.Interface.Requests

This interface is not yet final 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.Client`
- `org.freedesktop.Telepathy.Client.Handler`

This interface can be implemented by a Handler to be notified about requests for channels that it is likely to be asked to handle.

Added in version 0.17.23. (as a draft; functionality moved from Handler)

## Methods:

### AddRequest ( o: Request, a{sv}: Properties ) → nothing

Called by the ChannelDispatcher to indicate that channels have been requested, and that if the request is successful, they will probably be handled by this Handler. The ChannelDispatcher SHOULD only call this method on one handler per request.

This allows the UI to start preparing to handle the channels in advance (e.g. render a window with an "in progress" message), improving perceived responsiveness.

The use of "probably" is because you can't necessarily tell from a channel request which handler will handle particular channels. A reasonable heuristic would be to match the request against the HandlerChannelFilter, and respect the preferred handler (if any).

If the request succeeds and is given to the expected Handler, the Requests_Satisfied parameter to HandleChannels can be used to match the channel to a previous AddRequest call.

This lets the UI direct the channels to the window that it already opened.

If the request fails, the expected handler is notified by the channel dispatcher calling its RemoveRequest method.

This lets the UI close the window or display the error.

The channel dispatcher SHOULD remember which handler was notified, and if the channel request succeeds, it SHOULD dispatch the channels to the expected handler, unless the channels do not match that handler's HandlerChannelFilter. If the channels are not dispatched to the expected handler, the handler that was expected is notified by the channel dispatcher calling its RemoveRequest method with the NotYours error.

Expected handling is for the UI to close the window it previously opened.

Handlers SHOULD NOT return an error from this method; errors returned from this method SHOULD NOT alter the channel dispatcher's behaviour.

Calls to this method are merely a notification.

#### Parameters

`Request` − `o`
  The ChannelRequest object, which MUST have been returned by CreateChannel or EnsureChannel before this method is called.
  See those methods for the rationale of this ordering.
`Properties` − `a{sv}` (Qualified_Property_Value_Map)
  Some of the properties of the ChannelRequest. To avoid race conditions, this dictionary MUST NOT include properties whose values could subsequently change. It SHOULD include as many properties as possible, given that constraint. In particular, the properties Requests and UserActionTime MUST be included.

### RemoveRequest ( o: Request, s: Error, s: Message ) → nothing

Called by the ChannelDispatcher to indicate that a request previously passed to AddRequest has failed and should be disregarded.

Handlers SHOULD NOT return an error from this method; errors returned from this method SHOULD NOT alter the channel dispatcher's behaviour.

Calls to this method are merely a notification.

#### Parameters

`Request` − `o`
  The request that failed.
`Error` − `s` (DBus_Error_Name)

  The name of the D-Bus error with which the request failed.

  If this is `org.freedesktop.Telepathy.Error.NotYours`, this indicates that the request succeeded, but all the resulting channels were given to some other handler.

`Message` − `s`
  Any message supplied with the D-Bus error.

Interface has no signals.

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

# org.freedesktop.Telepathy.ChannelHandler

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

Added in version 0.17.0.

Deprecated since version 0.17.23. Clients should implement Client.Handler instead.

## Methods:

### HandleChannel ( s: Bus_Name, o: Connection, s: Channel_Type, o: Channel, u: Handle_Type, u: Handle ) → nothing

Called when a channel handler should handle a new channel.

Added in version 0.17.0.

#### Parameters

`Bus_Name` − `s` (DBus_Bus_Name)
  The bus name of the connection and channel
`Connection` − `o`
  The object-path of the connection that owns the channel
`Channel_Type` − `s` (DBus_Interface)
  The channel type
`Channel` − `o`
  The object-path of the channel
`Handle_Type` − `u` (Handle_Type)
  The type of the handle that the channel communicates with, or 0 if there is no associated handle
`Handle` − `u` (Handle)
  The handle that the channel communicates with, or 0 if there is no associated handle

Interface has no signals.

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

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

### GetProperties ( au: Properties ) → a(uv)

Returns an array of (identifier, value) pairs containing the current values of the given properties.

#### Parameters

`Properties` − `au` (Property_ID[])
  An array of property identifiers

#### Returns

`Values` − `a(uv)` (Property_Value[])

  An array of structs containing:

  - integer identifiers
  - variant boxed values

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  Some property identifier requested is invalid
`org.freedesktop.Telepathy.Error.PermissionDenied`
  Some property requested does not have the PROPERTY_FLAG_READ flag

### ListProperties ( ) → a(ussu)

Returns a dictionary of the properties available on this channel.

#### Returns

`Available_Properties` − `a(ussu)` (Property_Spec[])
  An array of structs containing: an integer identifier a string property name a string representing the D-Bus signature of this property a bitwise OR of the flags applicable to this property

### SetProperties ( a(uv): Properties ) → nothing

Takes an array of (identifier, value) pairs containing desired values to set the given properties. In the case of any errors, no properties will be changed. When the changes have been acknowledged by the server, the PropertiesChanged signal will be emitted.

All properties given must have the PROPERTY_FLAG_WRITE flag, or PermissionDenied will be returned. If any variants are of the wrong type, NotAvailable will be returned. If any given property identifiers are invalid, InvalidArgument will be returned.

#### Parameters

`Properties` − `a(uv)` (Property_Value[])
  An array mapping integer property identifiers to boxed values

#### Possible errors

`org.freedesktop.Telepathy.Error.Disconnected`
  The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
  The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  (generic description)
`org.freedesktop.Telepathy.Error.InvalidArgument`
  Raised when one of the provided arguments is invalid. (generic description)
`org.freedesktop.Telepathy.Error.NotAvailable`
  Raised when the requested functionality is temporarily unavailable. (generic description)
`org.freedesktop.Telepathy.Error.PermissionDenied`
  The user is not permitted to perform the requested operation. (generic description)
`org.freedesktop.Telepathy.Error.NetworkError`
  Raised when there is an error reading from or writing to the network. (generic description)

## Signals:

### PropertiesChanged ( a(uv): Properties )

Emitted when the value of readable properties has changed.

#### Parameters

`Properties` − `a(uv)` (Property_Value[])

  An array of structs containing:

  - integer identifiers
  - variant boxed values

  The array should contain only properties whose values have actually changed.

### PropertyFlagsChanged ( a(uu): Properties )

Emitted when the flags of some room properties have changed.

#### Parameters

`Properties` − `a(uu)` (Property_Flags_Change[])

  An array of structs containing:

  - integer identifiers
  - a bitwise OR of the current flags

  The array should contain only properties whose flags have actually changed.

Interface has no Telepathy properties.

Interface has no D-Bus core properties.

## Simple types

### Property_ID − u

An unsigned integer used to represent a Telepathy property.

## 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

### Property_Spec − ( u: Property_ID, s: Name, s: Signature, u: Flags )

A struct (property ID, property name, D-Bus signature, flags) representing a property, as returned by ListProperties on the Properties interface.

In bindings that need a separate name, arrays of Property_Spec should be called Property_Spec_List.

#### Members

`Property_ID` − `u`
  (undocumented)
`Name` − `s`
  (undocumented)
`Signature` − `s` (DBus_Signature)
  (undocumented)
`Flags` − `u` (Property_Flags)
  (undocumented)

### Property_Flags_Change − ( u: Property_ID, u: New_Flags )

A struct (property ID, flags) representing a change to a property's flags, as seen in the PropertyFlagsChanged signal on the Properties interface.

In bindings that need a separate name, arrays of Property_Flags_Change should be called Property_Flags_Change_List.

#### Members

`Property_ID` − `u`
  (undocumented)
`New_Flags` − `u`
  (undocumented)

### Property_Value − ( u: Identifier, v: Value )

A struct (property ID, value) representing a property's value, as seen in the PropertiesChanged signal on the Properties interface, returned by the GetProperties method and passed to the SetProperties method.

In bindings that need a separate name, arrays of Property_Value should be called Property_Value_List.

#### Members

`Identifier` − `u` (Property_ID)
  (undocumented)
`Value` − `v`
  (undocumented)

# Generic types

## Simple types

### Unix_Timestamp − u

An unsigned 32-bit integer representing time as the number of seconds elapsed since the Unix epoch (1970-01-01T00:00:00Z)

### Unix_Timestamp64 − x

An signed 64-bit integer representing time as the number of seconds elapsed since the Unix epoch (1970-01-01T00:00:00Z); negative for times before the epoch

### DBus_Bus_Name − s

A string representing a D-Bus bus name - either a well-known name like "org.freedesktop.Telepathy.MissionControl" or a unique name like ":1.123"

### DBus_Well_Known_Name − s

A string representing a D-Bus well-known name like "org.freedesktop.Telepathy.MissionControl".

### DBus_Unique_Name − s

A string representing a D-Bus unique name, such as ":1.123"

### DBus_Interface − s

An ASCII string representing a D-Bus interface - two or more elements separated by dots, where each element is a non-empty string of ASCII letters, digits and underscores, not starting with a digit. The maximum total length is 255 characters. For example, "org.freedesktop.DBus.Peer".

### DBus_Error_Name − s

An ASCII string representing a D-Bus error. This is syntactically the same as a DBus_Interface, but the meaning is different.

### DBus_Signature − s

A string representing a D-Bus signature (the 'g' type isn't used because of poor interoperability, particularly with dbus-glib)

### DBus_Member − s

An ASCII string representing a D-Bus method, signal or property name - a non-empty string of ASCII letters, digits and underscores, not starting with a digit, with a maximum length of 255 characters. For example, "Ping".

### DBus_Qualified_Member − s

A string representing the full name of a D-Bus method, signal or property, consisting of a DBus_Interface, followed by a dot, followed by a DBus_Member. For example, "org.freedesktop.DBus.Peer.Ping".

## Structure types

### Socket_Address_IP − ( s: Address, q: Port )

An IP address and port.

In bindings that need a separate name, arrays of Socket_Address_IP should be called Socket_Address_IP_List.

#### Members

`Address` − `s`
  Either a dotted-quad IPv4 address literal as for Socket_Address_IPv4, or an RFC2373 IPv6 address as for Socket_Address_IPv6.
`Port` − `q`
  The TCP or UDP port number.

### Socket_Address_IPv4 − ( s: Address, q: Port )

An IPv4 address and port.

Arrays of Socket_Address_IPv4 don't generally make sense.

#### Members

`Address` − `s`
  A dotted-quad IPv4 address literal: four ASCII decimal numbers, each between 0 and 255 inclusive, e.g. "192.168.0.1".
`Port` − `q`
  The TCP or UDP port number.

### Socket_Address_IPv6 − ( s: Address, q: Port )

An IPv6 address and port.

Arrays of Socket_Address_IPv6 don't generally make sense.

#### Members

`Address` − `s`
  An IPv6 address literal as specified by RFC2373 section 2.2, e.g. "2001:DB8::8:800:200C:4171".
`Port` − `q`
  The TCP or UDP port number.

### Socket_Netmask_IPv4 − ( s: Address, y: Prefix_Length )

An IPv4 network or subnet.

Arrays of Socket_Netmask_IPv4 don't generally make sense.

#### Members

`Address` − `s`
  A dotted-quad IPv4 address literal: four ASCII decimal numbers, each between 0 and 255 inclusive, e.g. "192.168.0.1".
`Prefix_Length` − `y`
  The number of leading bits of the address that must match, for this netmask to be considered to match an address.

### Socket_Netmask_IPv6 − ( s: Address, y: Prefix_Length )

An IPv6 network or subnet.

Arrays of Socket_Netmask_IPv6 don't generally make sense.

#### Members

`Address` − `s`
  An IPv6 address literal as specified by RFC2373 section 2.2, e.g. "2001:DB8::8:800:200C:4171".
`Prefix_Length` − `y`
  The number of leading bits of the address that must match, for this netmask to be considered to match an address.

## Mapping types

### Qualified_Property_Value_Map − a{ s: Key → v: Value }

A mapping from strings representing D-Bus properties (by their namespaced names) to their values.

In bindings that need a separate name, arrays of Qualified_Property_Value_Map should be called Qualified_Property_Value_Map_List.

#### Members

`Key` − `s` (DBus_Qualified_Member)
  A D-Bus interface name, followed by a dot and a D-Bus property name.
`Value` − `v`
  The value of the property.

### String_Variant_Map − a{ s: Key → v: Value }

A mapping from strings to variants representing extra key-value pairs.

In bindings that need a separate name, arrays of String_Variant_Map should be called String_Variant_Map_List.

#### Members

`Key` − `s`
  (undocumented)
`Value` − `v`
  (undocumented)

### String_String_Map − a{ s: Key → s: Value }

A mapping from strings to strings representing extra key-value pairs.

In bindings that need a separate name, arrays of String_String_Map should be called String_String_Map_List.

#### Members

`Key` − `s`
  (undocumented)
`Value` − `s`
  (undocumented)

# Errors

## org.freedesktop.Telepathy.Error.NetworkError

Raised when there is an error reading from or writing to the network.

## org.freedesktop.Telepathy.Error.NotImplemented

Raised when the requested method, channel, etc is not available on this connection.

## org.freedesktop.Telepathy.Error.InvalidArgument

Raised when one of the provided arguments is invalid.

## org.freedesktop.Telepathy.Error.NotAvailable

Raised when the requested functionality is temporarily unavailable.

## org.freedesktop.Telepathy.Error.PermissionDenied

The user is not permitted to perform the requested operation.

## org.freedesktop.Telepathy.Error.Disconnected

The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.

## org.freedesktop.Telepathy.Error.InvalidHandle

The contact name specified is unknown on this channel or connection.

## org.freedesktop.Telepathy.Error.Channel.Banned

You are banned from the channel.

## org.freedesktop.Telepathy.Error.Channel.Full

The channel is full.

## org.freedesktop.Telepathy.Error.Channel.InviteOnly

The requested channel is invite-only.

## org.freedesktop.Telepathy.Error.NotYours

The requested channel or other resource already exists, and another client is responsible for it

## org.freedesktop.Telepathy.Error.Cancelled

Raised by an ongoing request if it is cancelled by user request before it has completed, or when operations are performed on an object which the user has asked to close (for instance, a Connection where the user has called Disconnect, or a Channel where the user has called Close).
The second form can be used to correspond to the Requested member in the Connection_Status_Reason enum, or to to represent the situation where disconnecting a Connection, closing a Channel, etc. has been requested by the user but this request has not yet been acted on, for instance because the service will only act on the request when it has finished processing an event queue.

## org.freedesktop.Telepathy.Error.AuthenticationFailed

Raised when authentication with a service was unsuccessful.
This corresponds to Authentication_Failed in the Connection_Status_Reason enum.

## org.freedesktop.Telepathy.Error.EncryptionNotAvailable

Raised if a user request insisted that encryption should be used, but encryption was not actually available.
This corresponds to part of Encryption_Error in the Connection_Status_Reason enum. It's been separated into a distinct error here because the two concepts that were part of EncryptionError seem to be things that could reasonably appear differently in the UI.

## org.freedesktop.Telepathy.Error.EncryptionError

Raised if encryption appears to be available, but could not actually be used (for instance if SSL/TLS negotiation fails).
This corresponds to part of Encryption_Error in the Connection_Status_Reason enum.

## org.freedesktop.Telepathy.Error.Cert.NotProvided

Raised if the server did not provide a SSL/TLS certificate. This error MUST NOT be used to represent the absence of a client certificate provided by the Telepathy connection manager.
This corresponds to Cert_Not_Provided in the Connection_Status_Reason enum. That error explicitly applied only to server SSL certificates, so this one is similarly limited; having the CM present a client certificate is a possible future feature, but it should have its own error handling.

## org.freedesktop.Telepathy.Error.Cert.Untrusted

Raised if the server provided a SSL/TLS certificate signed by an untrusted certifying authority. This error SHOULD NOT be used to represent a self-signed certificate: see the Self Signed error for that.
This corresponds to Cert_Untrusted in the Connection_Status_Reason enum, with a clarification to avoid ambiguity.

## org.freedesktop.Telepathy.Error.Cert.Expired

Raised if the server provided an expired SSL/TLS certificate.
This corresponds to Cert_Expired in the Connection_Status_Reason enum.

## org.freedesktop.Telepathy.Error.Cert.NotActivated

Raised if the server provided an SSL/TLS certificate that will become valid at some point in the future.
This corresponds to Cert_Not_Activated in the Connection_Status_Reason enum.

## org.freedesktop.Telepathy.Error.Cert.FingerprintMismatch

Raised if the server provided an SSL/TLS certificate that did not have the expected fingerprint.
This corresponds to Cert_Fingerprint_Mismatch in the Connection_Status_Reason enum.

## org.freedesktop.Telepathy.Error.Cert.HostnameMismatch

Raised if the server provided an SSL/TLS certificate that did not match its hostname.
This corresponds to Cert_Hostname_Mismatch in the Connection_Status_Reason enum.

## org.freedesktop.Telepathy.Error.Cert.SelfSigned

Raised if the server provided an SSL/TLS certificate that is self-signed and untrusted.
This corresponds to Cert_Hostname_Mismatch in the Connection_Status_Reason enum.

## org.freedesktop.Telepathy.Error.Cert.Invalid

Raised if the server provided an SSL/TLS certificate that is unacceptable in some way that does not have a more specific error.
This corresponds to Cert_Other_Error in the Connection_Status_Reason enum.

## org.freedesktop.Telepathy.Error.NotCapable

Raised when requested functionality is unavailable due to contact not having required capabilities.

## org.freedesktop.Telepathy.Error.Offline

Raised when requested functionality is unavailable because a contact is offline.
This corresponds to Offline in the Channel_Group_Change_Reason enum.

## org.freedesktop.Telepathy.Error.Channel.Kicked

Used to represent a user being ejected from a channel by another user, for instance being kicked from a chatroom.
This corresponds to Kicked in the Channel_Group_Change_Reason enum.

## org.freedesktop.Telepathy.Error.Busy

Used to represent a user being removed from a channel because of a "busy" indication.
This corresponds to Busy in the Channel_Group_Change_Reason enum.

## org.freedesktop.Telepathy.Error.NoAnswer

Used to represent a user being removed from a channel because they did not respond, e.g. to a StreamedMedia call.
This corresponds to No_Answer in the Channel_Group_Change_Reason enum.

## org.freedesktop.Telepathy.Error.DoesNotExist

Raised when the requested user does not, in fact, exist.
This corresponds to Invalid_Contact in the Channel_Group_Change_Reason enum, but can also be used to represent other things not existing (like chatrooms, perhaps).

## org.freedesktop.Telepathy.Error.Terminated

Raised when a channel is terminated for an unspecified reason. In particular, this error SHOULD be used whenever normal termination of a 1-1 StreamedMedia call by the remote user is represented as a D-Bus error name.
This corresponds to None in the Channel_Group_Change_Reason enum.

## org.freedesktop.Telepathy.Error.ConnectionRefused

Raised when a connection is refused.

## org.freedesktop.Telepathy.Error.ConnectionFailed

Raised when a connection can't be established.

## org.freedesktop.Telepathy.Error.ConnectionLost

Raised when a connection is broken.

# 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.ContactCapabilities.DRAFT`
- `org.freedesktop.Telepathy.Connection.Interface.ContactInfo.DRAFT`
- `org.freedesktop.Telepathy.Connection.Interface.Contacts`
- `org.freedesktop.Telepathy.Connection.Interface.Location.DRAFT`
- `org.freedesktop.Telepathy.Connection.Interface.Presence`
- `org.freedesktop.Telepathy.Connection.Interface.Renaming`
- `org.freedesktop.Telepathy.Connection.Interface.Requests`
- `org.freedesktop.Telepathy.Connection.Interface.SimplePresence`
- `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.StreamedMedia.FUTURE`
- `org.freedesktop.Telepathy.Channel.Type.RoomList`
- `org.freedesktop.Telepathy.Channel.Type.Text`
- `org.freedesktop.Telepathy.Channel.Type.Tubes`
- `org.freedesktop.Telepathy.Channel.Type.StreamTube`
- `org.freedesktop.Telepathy.Channel.Type.DBusTube`
- `org.freedesktop.Telepathy.Channel.Type.FileTransfer`
- `org.freedesktop.Telepathy.Channel.Type.ContactSearch.DRAFT`
- `org.freedesktop.Telepathy.Channel.Interface.CallMerging`
- `org.freedesktop.Telepathy.Channel.Interface.CallState`
- `org.freedesktop.Telepathy.Channel.Interface.ChatState`
- `org.freedesktop.Telepathy.Channel.Interface.Destroyable`
- `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.MediaSignalling.FUTURE`
- `org.freedesktop.Telepathy.Channel.Interface.Messages`
- `org.freedesktop.Telepathy.Channel.Interface.Tube`
- `org.freedesktop.Telepathy.Media.SessionHandler`
- `org.freedesktop.Telepathy.Media.StreamHandler`
- `org.freedesktop.Telepathy.Debug.DRAFT`
- `org.freedesktop.Telepathy.AccountManager`
- `org.freedesktop.Telepathy.Account`
- `org.freedesktop.Telepathy.Account.Interface.Avatar`
- `org.freedesktop.Telepathy.ChannelDispatcher`
- `org.freedesktop.Telepathy.ChannelDispatcher.Interface.OperationList`
- `org.freedesktop.Telepathy.ChannelDispatchOperation`
- `org.freedesktop.Telepathy.ChannelRequest`
- `org.freedesktop.Telepathy.Client`
- `org.freedesktop.Telepathy.Client.Observer`
- `org.freedesktop.Telepathy.Client.Approver`
- `org.freedesktop.Telepathy.Client.Handler`
- `org.freedesktop.Telepathy.Client.Interface.Requests`
- `org.freedesktop.Telepathy.ChannelHandler`
- `org.freedesktop.Telepathy.Properties`

## Index of types

- `Alias_Map` − a{ u → s }
- `Alias_Pair` − ( u, s )
- `Avatar` − ( ay, s )
- `Avatar_Token` − 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_Contact_Search_State` − u
- `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_Capabilities_Map` − a{ u → a(a{sv}as) }
- `Contact_Capability` − ( u, s, u, u )
- `Contact_Handle` − u
- `Contact_Info_Field` − ( s, as, as )
- `Contact_Info_Field_Flags` − u
- `Contact_Info_Flag` − u
- `Contact_Info_Map` − a{ u → a(sasas) }
- `Contact_Locations` − a{ u → a{sv} }
- `Contact_Presences` − a{ u → (ua{sa{sv}}) }
- `Contact_Search_Key` − s
- `Contact_Search_Map` − a{ s → s }
- `DBus_Bus_Name` − s
- `DBus_Error_Name` − s
- `DBus_Interface` − s
- `DBus_Member` − s
- `DBus_Qualified_Member` − s
- `DBus_Signature` − s
- `DBus_Tube_Member` − ( u, s )
- `DBus_Tube_Participants` − a{ u → s }
- `DBus_Unique_Name` − s
- `DBus_Well_Known_Name` − s
- `DTMF_Event` − y
- `Debug_Level` − u
- `Debug_Message` − ( d, s, u, s )
- `Delivery_Reporting_Support_Flags` − u
- `Delivery_Status` − u
- `Dispatch_Operation_Details` − ( o, a{sv} )
- `Field_Spec` − ( s, as, u, u )
- `File_Hash_Type` − u
- `File_Transfer_State` − u
- `File_Transfer_State_Change_Reason` − u
- `Group_Handle` − u
- `Handle` − u
- `Handle_Identifier_Map` − a{ u → s }
- `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 )
- `Location` − a{ s → v }
- `Location_Accuracy_Level` − i
- `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_Content_Map` − a{ u → v }
- `Message_Part_Index` − u
- `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 )
- `Rich_Presence_Access_Control` − ( u, v )
- `Rich_Presence_Access_Control_Type` − u
- `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_IP` − ( s, q )
- `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
- `Stream_Tube_Connection_ID` − u
- `String_String_Map` − a{ s → s }
- `String_Variant_Map` − a{ s → v }
- `Supported_Socket_Map` − a{ u → au }
- `Tube_Channel_State` − u
- `Tube_ID` − u
- `Tube_Info` − ( u, u, u, s, a{sv}, u )
- `Tube_State` − u
- `Tube_Type` − u
- `Unix_Timestamp` − u
- `Unix_Timestamp64` − x
- `VCard_Field` − s
- `VCard_Type_Parameter` − s