Telepathy D-Bus Interface Specification

Version 0.17.26

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

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:

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:

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:

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:

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:

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:

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:

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:

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 exp