Telepathy D-Bus Interface Specification

Version 0.16.0

Copyright (C) 2005, 2006, 2007 Collabora Limited
Copyright (C) 2005, 2006, 2007 Nokia Corporation
Copyright (C) 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 Library 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. The names of these services, the protocols they support, and the parameters understood by that protocol are intended to be discovered by reading files on disk which are provided along with the connection manager. These are documented elsewhere.

Once a connection manager service has been activated, the object path of the manager object implementing this interface is always /org/freedesktop/Telepathy/ConnectionManager/name Where name is the identifier for the connection manager.

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.

Methods:

GetParameters ( s: proto ) → 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

proto - s
The required protocol name

Returns

a(susv)
An array of structs containing:
  • a string parameter name
  • a bitwise OR of the parameter flags (as defined above)
  • a string D-Bus type signature
  • a variant boxed default value (if the HAS_DEFAULT flag is not present, there is no default and this takes some dummy value)

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. The following well-known values should be used when applicable:

Returns

as
A array of string protocol identifiers supported by this manager

RequestConnection ( s: proto, 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.

In order to allow Connection objects to be discovered by new clients, the object path and bus name must be of the form:

/org/freedesktop/Telepathy/Connection/manager/proto/account

And:

org.freedesktop.Telepathy.Connection.manager.proto.account

Where manager and proto are the identifiers for this manager and this protocol, and account is a series of elements 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, or on protocols where connecting multiple times is permissable, a per-connection identifier is also necessary to ensure uniqueness.

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:

s:account
The identifier for the user's account on the server
s:server
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.
q:port
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.
s:password
A password associated with the account.
b:require-encryption
Require encryption for this connection. A connection should fail to connect if require-encryption is set and an encrypted connection is not possible.
b:register
This account should be created on the server if it does not already exist.
s:ident
The local username to report to the server if necessary, such as in IRC.
s:fullname
The user's full name if the service requires this when authenticating or registering.
s:stun-server
The IP address or FQDN of a STUN server to use for NAT traversal, without any ":port" suffix.
q:stun-port
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

proto - s
The protocol identifier
parameters - a{sv}
A dictionary mapping parameter name to the variant boxed value

Returns

s
A D-Bus service name where the new Connection object can be found
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: proto )

Emitted when a new Connection object is created.

Parameters

bus_name - s
The D-Bus service where the connection object can be found
object_path - o
The object path of the Connection object on this service
proto - s
The identifier for the protocol this connection uses

Interface has no properties.

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.

org.freedesktop.Telepathy.Connection

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

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

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

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

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

Methods:

Connect ( ) → nothing

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

Possible errors

org.freedesktop.Telepathy.Error.NotAvailable
Raised when the requested functionality is temporarily unavailable. (generic description)

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.

Returns

as
An array of D-Bus interface names

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (generic description)

GetProtocol ( ) → s

Get the protocol this connection is using.

Returns

s
A string identifier for the protocol

GetSelfHandle ( ) → u

Get 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 Renamed signal on the Renaming interface (if present). This is always a CONTACT type handle.

Returns

u
An integer handle representing the user

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (generic description)

GetStatus ( ) → u

Get the current status as defined in the StatusChanged signal.

Returns

u
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 ReleaseHandle 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
An integer handle type (as defined in HandleType)
handles - au
A array of integer handles to hold

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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
An integer handle type (as defined in HandleType)
handles - au
An array of integer handles of this type

Returns

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

Returns

a(osuu)

An array of structs containing:

  • a D-Bus object path for the channel object on this service
  • a D-Bus interface name representing the channel type
  • an integer representing the handle type this channel communicates with, or zero
  • an integer handle representing the contact, room or list this channel communicates with, or zero

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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
An integer handle type (as defined in RequestHandle)
handles - au
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. (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)
org.freedesktop.Telepathy.Error.NotAvailable
Raised when the requested functionality is temporarily unavailable. (generic description)

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 GetHandle() returns 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.

Parameters

type - s
A D-Bus interface name representing base channel type
handle_type - u
An integer representing the handle type, or zero if no handle is being specified
handle - u
A nonzero integer handle representing a contact, room, list etc. according to handle_type, or zero if the handle_type is zero
suppress_handler - b
If true, the requesting client intends to take responsibility for displaying the channel to the user, so no other handler needs to be launched

Returns

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. (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.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 ReleaseHandle 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
An integer handle type (as defined in HandleType)
names - as
An array of names of entities to request handles for

Returns

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

Signals:

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. The suppress_handler boolean indicates if the channel was requested by an existing client, or is an incoming communication and needs to have a handler launched.

Parameters

object_path - o
A D-Bus object path for the channel object on this service
channel_type - s
A D-Bus interface name representing the channel type
handle_type - u
An integer representing the type of handle this channel communicates with, which is zero if no handle is specified
handle - u
A handle indicating the specific contact, room or list this channel communicates with, or zero if it is an anonymous channel
suppress_handler - b
A boolean indicating that the channel was requested by a client that intends to display it to the user, so no handler needs to be launched

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
An integer indicating the new status, as defined by ConnectionStatus
reason - u
An integer indicating the reason for the status change, as defined by ConnectionStatusReason

Interface has no properties.

Enumerated types:

Handle_Type

Handle_Type_None = 0
A "null" handle type used to indicate the absence of a handle. When a handle type and a handle appear as a pair, if the handle type is zero, the handle must also be zero.
Handle_Type_Contact = 1
A contact
Handle_Type_Room = 2
A chat room
Handle_Type_List = 3
A server-generated contact list (see Channel.Interface.Group)
Handle_Type_Group = 4
A user-defined contact list (see Channel.Interface.Group)

Connection_Status

Connection_Status_Connected = 0
The connection is alive and all methods are available.
Connection_Status_Connecting = 1
The connection has not yet been established, or has been severed and reconnection is being attempted. Some methods may fail until the connection has been established.
Connection_Status_Disconnected = 2
The connection has been severed and no method calls are valid. The object may be removed from the bus at any time.

Connection_Status_Reason

Connection_Status_Reason_None_Specified = 0
There is no reason set for this state change.
Connection_Status_Reason_Requested = 1
The change is in response to a user request.
Connection_Status_Reason_Network_Error = 2
There was an error sending or receiving on the network socket.
Connection_Status_Reason_Authentication_Failed = 3
The username or password was invalid.
Connection_Status_Reason_Encryption_Error = 4
There was an error negotiating SSL on this connection, or encryption was unavailable and require-encryption was set when the connection was created.
Connection_Status_Reason_Name_In_Use = 5
Someone is already connected to the server using the name you are trying to connect with.
Connection_Status_Reason_Cert_Not_Provided = 6
The server did not provide a SSL certificate.
Connection_Status_Reason_Cert_Untrusted = 7
The server's SSL certificate could not be trusted.
Connection_Status_Reason_Cert_Expired = 8
The server's SSL certificate has expired.
Connection_Status_Reason_Cert_Not_Activated = 9
The server's SSL certificate is not yet valid.
Connection_Status_Reason_Cert_Hostname_Mismatch = 10
The server's SSL certificate did not match its hostname.
Connection_Status_Reason_Cert_Fingerprint_Mismatch = 11
The server's SSL certificate does not have the expected fingerprint.
Connection_Status_Reason_Cert_Self_Signed = 12
The server's SSL certificate is self-signed.
Connection_Status_Reason_Cert_Other_Error = 13
There was some other error validating the server's SSL certificate.

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

u
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. (generic description)

RequestAliases ( au: contacts ) → as

Request the value of several contacts' aliases at once.

Parameters

contacts - au
An array of handles representing contacts

Returns

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

SetAliases ( a{us}: aliases ) → nothing

Request that the alias of the given contact be changed. Success will be indicated by emitting an AliasUpdate 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 GetSelfHandle on the Connection interface).

Parameters

aliases - a{us}
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. (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.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)

Signals:

AliasesChanged ( a(us): aliases )

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

Parameters

aliases - a(us)
An array containing structs of:
  • the handle representing the contact
  • the new alias

Interface has no 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.

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

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

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

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

Methods:

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

Get the required format of avatars on this connection.

Returns

as
An array of supported MIME types (eg image/jpeg)
q
The minimum image width in pixels
q
The minimum image height in pixels
q
The maximum image width in pixels, or 0 if there is no limit
q
The maximum image height in pixels, or 0 if there is no limit
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. (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.

Parameters

contacts - au
An array of handles representing contacts

Returns

as
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. (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. A empty token means that no avatar is set for the given contact.

Parameters

contacts - au
An array of handles representing contacts

Returns

a{us}
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. (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.

Parameters

contact - u
An integer handle for the contact to request the avatar for

Returns

ay
An array of bytes containing the image data
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. (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
The contacts to retrieve avatars for

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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

s
The string token of the new avatar

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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.

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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 RequestAvatar.

Parameters

contact - u
An integer handle for the contact whose avatar has changed
new_avatar_token - s
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
The contact whose avatar has been retrieved
token - s
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 properties.

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

The generic capability flags are defined by ConnectionCapabilityFlag.

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

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

Methods:

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 (as returned by GetSelfHandle) the 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)
An array of structures containing:
  • a string channel type
  • a bitwise OR of type specific capability flags
remove - as
An array of D-Bus interface names of channel types to remove

Returns

a(su)
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. (generic description)

GetCapabilities ( au: handles ) → a(usuu)

Returns an array of capabilities for the given contact handles, or the connection itself (where handle is zero).

Parameters

handles - au
An array of contact handles for this connection, or zero to query capabilities available on the connection itself

Returns

a(usuu)
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. (generic description)
org.freedesktop.Telepathy.Error.InvalidHandle
The handle does not represent a contact
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, or on the connection itself if the handle is zero.

Parameters

caps - a(usuuuu)
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 properties.

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.

org.freedesktop.Telepathy.Connection.Interface.ContactInfo

Implementations of this interface must also implement:

THIS INTERFACE IS DEPRECATED AND SHOULD NOT BE USED. A new version will be proposed in the 0.13 specification branch.

An interface for requesting information about a contact on a given connection. Information is returned as a vCard represented as an XML string, in the format defined by JEP-0054: vcard-temp specifiation from the Jabber Software Foundation (this is derived from the aborted IETF draft draft-dawson-vcard-xml-dtd-01).

Implementations using PHOTO or SOUND elements should use the URI encoding where possible, and not provide base64 encoded data to avoid unnecessary bus traffic. Clients should not implement support for these encoded forms. A separate interface will be provided for transferring user avatars.

The following extended element names are also added to represent information from other systems which are not based around vCards:

USERNAME
the username of the contact on their local system (used on IRC for example)
HOSTNAME
the fully qualified hostname, or IPv4 or IPv6 address of the contact in dotted quad or colon-separated form

Methods:

RequestContactInfo ( u: contact ) → nothing

Request information for a given contact. The function will return after a GotContactInfo signal has been emitted for the contact, or an error returned.

Parameters

contact - u
An integer handle for the contact to request info for

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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
Raised when the requested functionality is temporarily unavailable. (generic description)

Signals:

GotContactInfo ( u: contact, s: vcard )

Emitted when information has been received from the server with the details of a particular contact.

Parameters

contact - u
An integer handle of the contact ID on the server
vcard - s
The XML string containing their vcard information

Interface has no properties.

org.freedesktop.Telepathy.Connection.Interface.Forwarding

Implementations of this interface must also implement:

A connection interface for services which can signal to contacts that they should instead contact a different user ID, effectively forwarding all incoming communication channels to another contact on the service.

Methods:

GetForwardingHandle ( ) → u

Returns the current forwarding contact handle, or zero if none is set.

Returns

u
An integer contact handle to whom incoming communication is forwarded

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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)

SetForwardingHandle ( u: forward_to ) → nothing

Set a contact handle to forward incoming communications to. A zero handle disables forwarding.

Parameters

forward_to - u
An integer contact handle to forward incoming communications to

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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)

Signals:

ForwardingChanged ( u: forward_to )

Emitted when the forwarding contact handle for this connection has been changed. An zero handle indicates forwarding is disabled.

Parameters

forward_to - u
An integer contact handle to forward communication to

Interface has no properties.

org.freedesktop.Telepathy.Connection.Interface.Presence

Implementations of this interface must also implement:

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

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

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

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

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

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

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

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

Methods:

AddStatus ( s: status, a{sv}: parms ) → 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
parms - a{sv}
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. (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. (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
An array of the contacts whose presence should be obtained

Returns

presence - a{u(ua{sa{sv}})}
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. (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

a{s(ubba{ss})}
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. (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. (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' Channel.Type.ContactList, and on some protocols presence information may not be available unless a subscription exists.

Parameters

contacts - au
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. (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
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. (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. 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}}
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. (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}})}
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 properties.

Enumerated types:

Connection_Presence_Type

Connection_Presence_Type_Unset = 0
An invalid presence type used as a null value
Connection_Presence_Type_Offline = 1
Offline
Connection_Presence_Type_Available = 2
Available
Connection_Presence_Type_Away = 3
Away
Connection_Presence_Type_Extended_Away = 4
Away for an extended time
Connection_Presence_Type_Hidden = 5
Hidden (invisible)

org.freedesktop.Telepathy.Connection.Interface.Privacy

Implementations of this interface must also implement:

An interface to support getting and setting privacy modes to configure situations such as not being contactable by people who are not on your subscribe list. If this interface is not implemented, the default can be presumed to be allow-all (as defined in GetPrivacyModes).

Methods:

GetPrivacyMode ( ) → s

Return the current privacy mode, which must be one of the values returned by GetPrivacyModes.

Returns

s
A string representing the current privacy mode

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (generic description)
org.freedesktop.Telepathy.Error.NetworkError
Raised when there is an error reading from or writing to the network. (generic description)

GetPrivacyModes ( ) → as

Returns the privacy modes available on this connection. The following well-known names should be used where appropriate:
allow-all
any contact may initiate communication
allow-specified
only contacts on your 'allow' list may initiate communication
allow-subscribed
only contacts on your subscription list may initiate communication

Returns

as
An array of valid privacy modes for this connection

SetPrivacyMode ( s: mode ) → nothing

Request that the privacy mode be changed to the given value, which must be one of the values returned by GetPrivacyModes. Success is indicated by the method returning and the PrivacyModeChanged signal being emitted.

Parameters

mode - s
The desired privacy mode

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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
Raised when one of the provided arguments is invalid. (generic description)

Signals:

PrivacyModeChanged ( s: mode )

Emitted when the privacy mode is changed or the value has been initially received from the server.

Parameters

mode - s
The current privacy mode

Interface has no properties.

org.freedesktop.Telepathy.Connection.Interface.Renaming

Implementations of this interface must also implement:

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. (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
The handle of the original identifier
new - u
The handle of the new identifier

Interface has no properties.

org.freedesktop.Telepathy.Channel

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

Each channel may have an immutable handle associated with it, which may be any handle type, such as a contact, room or list handle, indicating that the channel is for communicating with that handle. There can be at most one channel for each combination of (channel type, handle type, handle) with nonzero handle type.

If a channel does not have a handle (an "anonymous channel"), 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. There can be any number of anonymous channels of the same channel type.

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.

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

Returns

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

Returns

u
The handle type, or zero if this channel does not correspond to any particular handle
u
The handle, or zero if this channel does not correspond to any particular handle

GetInterfaces ( ) → as

Get the optional interfaces implemented by the channel.

Returns

as
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 properties.

org.freedesktop.Telepathy.Channel.Type.ContactList

Implementations of this interface must also implement:

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 RequestHandle with a handle type of HANDLE_TYPE_LIST and one of the following identifiers:

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 RequestHandle with a handle type of HANDLE_TYPE_GROUP and with the name set to the human-readable UTF-8 name of the group.

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

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

Interface has no methods.

Interface has no signals.

Interface has no properties.

org.freedesktop.Telepathy.Channel.Type.ContactSearch

Implementations of this interface must also implement:

A channel type for searching server-stored user directories. A new channel should be requested by a client for each search attempt, and it should be closed when the search is completed or the required result has been found in order to free unused handles. The search can be cancelled at any time by calling the channel Close method, although depending upon the protocol the connection manager may not be able to prevent the server from sending further results.

Before searching, the GetSearchKeys method should be used to discover any instructions sent by the server, and 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 search status will be set to CHANNEL_CONTACT_SEARCH_STATE_DURING. When results are returned by the server, the SearchResultReceived signal is emitted for each contact found, and when the search is complete, the search status will be set to CHANNEL_SEARCH_STATE_AFTER.

Methods:

GetSearchKeys ( ) → s, a{s(bg)}

Returns any instructions from the server along with a dictionary of search key names to their types, and a boolean indicating if the key is mandatory. The following well-known search key names should be used where appropriate:

s:first
The desired contact's given name
s:last
The desired contact's family name
s:nick
The desired contact's nickname
s:email
The e-mail address of the desired contact

Returns

s
A string with any instructions from the server
a{s(bg)}
A dictionary mapping string search key names to an array of:
  • booleans indicating if the search key is mandatory
  • type signature of the value for this search key

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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)

GetSearchState ( ) → u

Returns the current state of this search channel object.

Returns

u
The search state represented as one of the values of ChannelContactSearchState

Search ( a{sv}: terms ) → nothing

Send a request to start a search for contacts on this connection. A valid search request will cause the SearchStateChanged signal to be emitted with the status CHANNEL_CONTACT_SEARCH_STATE_DURING.

Parameters

terms - a{sv}
A dictionary mapping search key names to the desired values

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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:

SearchResultReceived ( u: contact, a{sv}: values )

Emitted when a search result is received from the server.

Parameters

contact - u
An integer handle for the contact
values - a{sv}
A dictionary mapping search key names to values for this contact

SearchStateChanged ( u: state )

Emitted when the search state (as returned by the GetSearchState method) changes.

Parameters

state - u
An integer representing the new search state

Interface has no properties.

Enumerated types:

Channel_Contact_Search_State

Channel_Contact_Search_State_Before = 0
The search has not started
Channel_Contact_Search_State_During = 1
The search is in progress
Channel_Contact_Search_State_After = 2
The search has been completed

org.freedesktop.Telepathy.Channel.Type.StreamedMedia

Implementations of this interface must also implement:

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

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

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

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

Methods:

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

a(uuuuuu)
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.

Parameters

streams - au
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
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.

Parameters

contact_handle - u
A contact handle with whom to establish the streams
types - au
An array of stream types (values of MediaStreamType)

Returns

a(uuuuuu)
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
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)

Signals:

StreamAdded ( u: stream_id, u: contact_handle, u: stream_type )

Emitted when a new stream has been added to this channel.

Parameters

stream_id - u
The stream identifier (as defined in ListStreams)
contact_handle - u
The contact handle who the stream is with (or 0 if it represents more than a single member)
stream_type - u
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.

Parameters

stream_id - u
The stream identifier (as defined in ListStreams)
stream_direction - u
The new stream direction (as defined in ListStreams)
pending_flags - u
The new pending send flags (as defined in ListStreams)

StreamError ( u: stream_id, u: errno, s: message )

Emitted when a stream encounters an error.

Parameters

stream_id - u
The stream identifier (as defined in ListStreams)
errno - u
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
The new stream state (as defined in ListStreams)

Interface has no properties.

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

org.freedesktop.Telepathy.Channel.Type.RoomList

Implementations of this interface must also implement:

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

b
A boolean indicating if room listing is in progress

ListRooms ( ) → nothing

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

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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 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:

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

Parameters

rooms - a(usa{sv})
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 properties.

org.freedesktop.Telepathy.Channel.Type.Text

Implementations of this interface must also implement:

A channel type for sending and receiving messages in plain text, with no formatting.

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

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

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

Sending messages can be requested using the Send method, which will return and cause the Sent signal to be emitted when the message has been delivered to the server, or SendError if there is a failure.

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

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

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

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

Methods:

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
The IDs of the messages to acknowledge

Possible errors

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

GetMessageTypes ( ) → au

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

Returns

au
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, remove all messages from the queue

Returns

a(uuuuus)
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. The Sent signal will be emitted when the message has been sent, and this method will return.

Parameters

type - u
An integer indicating the type of the message, from ChannelTextMessageType
text - s
The message to send

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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 AcknowledgePendingMessage method.

Parameters

id - u
A numeric identifier for acknowledging the message
timestamp - u
A Unix timestamp indicating when the message was received
sender - u
The handle of the contact who sent the message
type - u
The type of the message (normal, action, notice, etc), from ChannelTextMessageType
flags - u
A bitwise OR of the message flags as defined by ChannelTextMessageFlags
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.

Parameters

error - u
One of the values of ChannelTextSendError
timestamp - u
The Unix timestamp indicating when the message was sent
type - u
The message type from ChannelTextMessageType
text - s
The text of the message

Sent ( u: timestamp, u: type, s: text )

Signals that a message has been sent on this channel.

Parameters

timestamp - u
Unix timestamp indicating when the message was sent
type - u
The message type (normal, action, notice, etc) from ChannelTextMessageType
text - s
The text of the message

Properties:

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.

Enumerated types:

Channel_Text_Send_Error

Channel_Text_Send_Error_Unknown = 0
An unknown error occurred
Channel_Text_Send_Error_Offline = 1
The requested contact was offline
Channel_Text_Send_Error_Invalid_Contact = 2
The requested contact is not valid
Channel_Text_Send_Error_Permission_Denied = 3
The user does not have permission to speak on this channel
Channel_Text_Send_Error_Too_Long = 4
The outgoing message was too long and was rejected by the server
Channel_Text_Send_Error_Not_Implemented = 5
The channel doesn't support sending text messages to the requested contact

Channel_Text_Message_Type

Channel_Text_Message_Type_Normal = 0
A standard message
Channel_Text_Message_Type_Action = 1
An action which might be presented to the user as "* <sender> <action>"
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

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.

org.freedesktop.Telepathy.Channel.Type.Tubes

Implementations of this interface must also implement:

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

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

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

Methods:

GetAvailableStreamTubeTypes ( ) → a{uau}

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

Returns

a{uau}

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

au
An array of the available tube types, as defined by the Tube_Type enum.

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

Returns

a(uuusa{sv}u)
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}
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

u
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.dns-sd.org/ServiceTypes.html, for instance "rsync" or "daap".
parameters - a{sv}

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

u
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
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
The ID of the tube to accept.
address_type - u
The type of address the connection manager should listen on.
access_control - u
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
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
The ID of the tube to get an address for.

Returns

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
The ID of the tube to get names for.

Returns

a(us)
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
The ID of the stream tube to get the socket for.

Returns

address_type - u
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
The ID of the new tube.
initiator - u
The handle of the contact who initiated the tube.
type - u
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}
The new tube's properties.
state - u
The new tube's state.

TubeStateChanged ( u: id, u: state )

Emitted when the state of a tube changes.

Parameters

id - u
The ID of the tube that changed state.
state - u
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
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
The ID of the tube whose names have changed.
added - a(us)
Array of handles and D-Bus names of new participants.
removed - au
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
The ID of the tube
handle - u
The handle of the participant who opened the new connection

Interface has no properties.

Enumerated types:

Tube_Type

Tube_Type_DBus = 0

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

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

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

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

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

Tube_Type_Stream = 1

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

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

Tube_State

Tube_State_Local_Pending = 0
The tube is waiting to be accepted/closed locally.
Tube_State_Remote_Pending = 1
The tube is waiting to be accepted/closed remotely.
Tube_State_Open = 2
The tube is open for traffic.

Socket_Address_Type

Socket_Address_Type_Unix = 0
A Unix socket. The variant contains a byte-array, signature 'ay', containing the path of the socket.
Socket_Address_Type_Abstract_Unix = 1
An abstract Unix socket. The variant contains a byte-array, signature 'ay', containing the path of the socket including the leading null byte.
Socket_Address_Type_IPv4 = 2
An IPv4 socket. The variant contains a struct with signature (sq) in which the string is an IPv4 dotted-quad address literal (and must not be a DNS name), while the 16-bit unsigned integer is the port number.
Socket_Address_Type_IPv6 = 3
An IPv6 socket. The variant contains a struct 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 with signature (sq) 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 with signature (sy) containing the string form of an IP address of the appropriate version, and a prefix length "n". The socket can only be accessed if the first n bits of the connecting address match the first n bits of the given address.
Socket_Access_Control_Credentials = 3

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

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

The associated variant must be ignored.

org.freedesktop.Telepathy.Channel.Interface.ChatState

Implementations of this interface must also implement:

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:

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
The new state: one of the values of ChannelChatState.

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
An integer handle for the contact.
state - u
The new state of this contact: one of the values of ChannelChatState.

Interface has no 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.DTMF

Implementations of this interface must also implement:

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
A stream ID as defined in the StreamedMedia channel type.
event - y
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
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 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:

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

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

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

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

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

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

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

Methods:

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 flags to see in which cases this message should be provided.

Parameters

contacts - au
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. (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.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.

Returns

au
array of handles of current members
au
array of handles of local pending members
au
array of handles of remote pending members

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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 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.

Returns

u
The bitwise OR of zero or more values from ChannelGroupFlags

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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.

Parameters

handles - au
A list of integer handles representing members of the channel

Returns

au
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. (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 an array of handles representing contacts requesting channel membership and awaiting local approval with AddMembers.

Returns

au

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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 an array of structs containing handles representing contacts requesting channel membership and awaiting local approval with AddMembers.

Returns

a(uuus)
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 ChannelGroupChangeReason
  • 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. (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 an array of handles for the members of this channel.

Returns

au

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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.

Returns

au

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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 handle for the user on this channel (which can also be a local or remote pending member) or 0 if the user not a member at all (which is likely to be the case, for instance, on Type.ContactList channels). Note that this is different from the connection GetSelfHandle on some protocols, so the value of this handle should always be used with the methods of this interface.

Returns

u

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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. 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_REJECT and CHANNEL_GROUP_FLAG_MESSAGE_RESCIND flags to see in which cases this message should be provided.

Parameters

contacts - au
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. (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
An array of contact handles to remove from the channel
message - s
A string message, which can be blank if desired
reason - u
A reason for the change: one of the values of ChannelGroupChangeReason

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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:

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
A bitwise OR of the flags which have been set
removed - u
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). Contacts are listed in the removed list 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.

Parameters

message - s
A string message from the server, or blank if not
added - au
A list of members added to the channel
removed - au
A list of members removed from the channel
local_pending - au
A list of members who are pending local approval
remote_pending - au
A list of members who are pending remote approval
actor - u
The contact handle of the person who made the change, or 0 if not known
reason - u
A reason for the change: one of the values of ChannelGroupChangeReason

Interface has no properties.

Enumerated types:

Channel_Group_Change_Reason

Channel_Group_Change_Reason_None = 0
No reason was provided for this change.
Channel_Group_Change_Reason_Offline = 1
The change is due to a user going offline. Also used when user is already offline, but this wasn't known previously.
Channel_Group_Change_Reason_Kicked = 2
The change is due to a kick operation.
Channel_Group_Change_Reason_Busy = 3
The change is due to a busy indication.
Channel_Group_Change_Reason_Invited = 4
The change is due to an invitation.
Channel_Group_Change_Reason_Banned = 5
The change is due to a kick+ban operation.
Channel_Group_Change_Reason_Error = 6
The change is due to an error occurring.
Channel_Group_Change_Reason_Invalid_Contact = 7
The change is because the requested contact does not exist.
Channel_Group_Change_Reason_No_Answer = 8
The change is because the requested contact did not respond.
Channel_Group_Change_Reason_Renamed = 9
The change is because a contact's unique identifier changed. There must be exactly one handle in the removed set and exactly one handle in one of the added sets. The Renamed signal on the Renaming interface will have been emitted for the same handles, shortly before this MembersChanged signal is emitted.
Channel_Group_Change_Reason_Permission_Denied = 10
The change is because there was no permission to contact the requested handle.
Channel_Group_Change_Reason_Separated = 11

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

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

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

Sets of flags:

Channel_Group_Flags

Channel_Group_Flag_Can_Add = 1
The AddMembers method can be used to add or invite members who are not already in the local pending list (which is always valid).
Channel_Group_Flag_Can_Remove = 2
The RemoveMembers method can be used to remove channel members (removing those on the pending local list is always valid).
Channel_Group_Flag_Can_Rescind = 4
The RemoveMembers method can be used on people on the remote pending list.
Channel_Group_Flag_Message_Add = 8
A message may be sent to the server when calling AddMembers on contacts who are not currently pending members.
Channel_Group_Flag_Message_Remove = 16
A message may be sent to the server when calling RemoveMembers on contacts who are currently channel members.
Channel_Group_Flag_Message_Accept = 32
A message may be sent to the server when calling AddMembers on contacts who are locally pending.
Channel_Group_Flag_Message_Reject = 64
A message may be sent to the server when calling RemoveMembers on contacts who are locally pending.
Channel_Group_Flag_Message_Rescind = 128
A message may be sent to the server when calling RemoveMembers on contacts who are remote pending.
Channel_Group_Flag_Channel_Specific_Handles = 256

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

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

Channel_Group_Flag_Only_One_Group = 512
Placing a contact in multiple groups of this type is not allowed and will raise NotAvailable (on services where contacts may only be in one user-defined group, user-defined groups will have this flag).
Channel_Group_Flag_Handle_Owners_Not_Available = 1024
In rooms with channel specific handles (ie Channel_Specific_Handles flag is set), this flag indicates that none of the handle owners are available, and that GetHandleOwners method will always return 0 for channel members other than the self handle.

Channel_Hold_State

Channel_Hold_State_None = 0
Neither the local user and the remote member are on hold, and media is being sent bidirectionally.
Channel_Hold_State_Send_Only = 1
The local user has put the remote member on hold, so is sending media but has arranged not to receive any media streams.
Channel_Hold_State_Recv_Only = 2
The user has been put on hold by the remote member, so is receiving media but has arranged not to send any media streams.
Channel_Hold_State_Both = 3
Both the local user and the remote member have agreed not to send any media streams to each other.

org.freedesktop.Telepathy.Channel.Interface.Hold

Implementations of this interface must also implement:

THIS INTERFACE IS DEPRECATED AND SHOULD NOT BE USED. Hold functionality should be added to the StreamedMedia channel in due course.

Interface for channels where members may put you on hold, or you may put members on hold. This usually only makes sense for channels where you are streaming media to or from the members. Hold is defined as requesting that you are not sent any media streams by another, so these states indicate whether or not you are sending and receiving media streams to each member of the channel.

Methods:

GetHoldState ( u: member ) → u

Given a member of the channel, return their current hold state.

Parameters

member - u
The contact handle for a member of the channel

Returns

u
The member's current hold state as one of the values of ChannelHoldState

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (generic description)
org.freedesktop.Telepathy.Error.InvalidHandle
The contact name specified is unknown on this channel or connection. (generic description)

RequestHold ( u: member, b: hold ) → nothing

Request that a certain member be put on hold (be instructed not to send any media streams to you) or be taken off hold. Success is indicated by the HoldStateChanged signal being emitted.

Parameters

member - u
The contact handle for a member of the channel
hold - b
A boolean indicating whether or not the user should be on hold

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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)

Signals:

HoldStateChanged ( u: member, u: state )

Emitted to indicate that the hold state (as defined in GetHoldState above) has changed for a member of 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 the remote member or another process.

Parameters

member - u
The integer handle of a member of the channel
state - u
An integer representing the new hold state

Interface has no properties.

org.freedesktop.Telepathy.Channel.Interface.Password

Implementations of this interface must also implement:

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

u
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. (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

b

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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
A bitwise OR of the flags which have been set
removed - u
A bitwise OR of the flags which have been cleared

Interface has no 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.Transfer

Implementations of this interface must also implement:

An interface for channels where you may request that one of the members connects to somewhere else instead.

Methods:

Transfer ( u: member, u: destination ) → nothing

Request that the given channel member instead connects to a different contact ID.

Parameters

member - u
The handle of the member to transfer
destination - u
The handle of the destination contact

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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)
org.freedesktop.Telepathy.Error.PermissionDenied
The user is not permitted to perform the requested operation. (generic description)

Interface has no signals.

Interface has no properties.

org.freedesktop.Telepathy.Channel.Interface.MediaSignalling

Implementations of this interface must also implement:

An interface for signalling a channel containing synchronised media sessions which can contain an arbitrary number of streams. The negotiation interface is based closely around the API of the Farsight library (http://farsight.sourceforge.net/). 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.

Methods:

GetSessionHandlers ( ) → a(os)

Returns all currently active session handlers on this channel as a list of (session_handler_path, type).

Returns

a(os)

Signals:

NewSessionHandler ( o: session_handler, s: 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 MediaSessionHandler object
type - s
String indicating type of session, eg "rtp"

Properties:

nat-traversal - s

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

none
No attempt should be made at NAT traversal.
stun
If appropriate, a STUN request should be made to the given server to open a UDP port mapping and determine the external IP.
gtalk-p2p
Google Talk peer-to-peer connectivity establishment should be used, as implemented in libjingle 0.3.
stun-server - s
The IP address or hostname of the STUN server to use for NAT traversal.
stun-port - q
The UDP port number to use on the provided STUN server.
gtalk-p2p-relay-token - s
The authentication token for use with the Google Talk peer-to-peer relay server.

org.freedesktop.Telepathy.Media.SessionHandler

An media session handler is an object that handles a number of synchronised media streams.

Methods:

Error ( u: errno, s: message ) → nothing

THIS METHOD IS DEPRECATED AND SHOULD NOT BE USED. Instead the Error function should be used on the relevant MediaStreamHandler objects. 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.

Parameters

errno - u
message - s

Ready ( ) → nothing

Inform the connection manager that a client is ready to handle this session handler.

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
An object path to a new MediaStreamHandler
id - u
The unique ID of the new stream
media_type - u
Enum for type of media that this stream should handle (a value from MediaStreamType)
direction - u
Enum for direction of this stream (a value from MediaStreamDirection)

Interface has no 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 the current codec choice.

Parameters

codec_id - u

Error ( u: errno, 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

errno - u
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)
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})
As for SupportedCodecs.

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.

Parameters

codecs - a(usuuua{ss})
Codecs in the same format as for SupportedCodecs, which have the same semantics as the local codecs passed to Ready

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

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})
List of codec info structures, each containing:
  • ID of codec
  • Codec name
  • Media type
  • Clock rate of codec
  • Number of supported channels
  • String key-value pairs for supported optional parameters

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

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

Parameters

codecs - a(usuuua{ss})
As for SupportedCodecs

SetStreamPlaying ( b: playing )

Signal emitted when the connection manager wishes to set the stream playing or stopped.

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.

Interface has no properties.

Enumerated types:

Media_Stream_Error

Media_Stream_Error_Unknown = 0
An unknown error occured.
Media_Stream_Error_EOS = 1
The end of the stream was reached.

Media_Stream_Base_Proto

Media_Stream_Base_Proto_UDP = 0
UDP (User Datagram Protocol)
Media_Stream_Base_Proto_TCP = 1
TCP (Transmission Control Protocol)

Media_Stream_Transport_Type

Media_Stream_Transport_Type_Local = 0
A local address
Media_Stream_Transport_Type_Derived = 1
An external address derived by a method such as STUN
Media_Stream_Transport_Type_Relay = 2
An external stream relay

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
An array of property identifiers

Returns

a(uv)

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

a(ussu)
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)
A dictionary mapping integer identifiers to boxed values

Possible errors

org.freedesktop.Telepathy.Error.Disconnected
The connection is not currently connected and cannot be used. (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)

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)

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

Sets of flags:

Property_Flags

Property_Flag_Read = 1
The property can be read
Property_Flag_Write = 2
The property can be written

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.

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.