This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
org.freedesktop.Telepathy.ConnectionManagerorg.freedesktop.Telepathy.Connectionorg.freedesktop.Telepathy.Connection.Interface.Aliasingorg.freedesktop.Telepathy.Connection.Interface.Avatarsorg.freedesktop.Telepathy.Connection.Interface.Capabilitiesorg.freedesktop.Telepathy.Connection.Interface.Presenceorg.freedesktop.Telepathy.Connection.Interface.Renamingorg.freedesktop.Telepathy.Channelorg.freedesktop.Telepathy.Channel.FUTUREorg.freedesktop.Telepathy.Channel.Type.ContactListorg.freedesktop.Telepathy.Channel.Type.StreamedMediaorg.freedesktop.Telepathy.Channel.Type.RoomListorg.freedesktop.Telepathy.Channel.Type.Textorg.freedesktop.Telepathy.Channel.Type.Tubesorg.freedesktop.Telepathy.Channel.Interface.CallMergingorg.freedesktop.Telepathy.Channel.Interface.CallStateorg.freedesktop.Telepathy.Channel.Interface.ChatStateorg.freedesktop.Telepathy.Channel.Interface.DeliveryReporting.DRAFTorg.freedesktop.Telepathy.Channel.Interface.DTMForg.freedesktop.Telepathy.Channel.Interface.Grouporg.freedesktop.Telepathy.Channel.Interface.Holdorg.freedesktop.Telepathy.Channel.Interface.HTML.DRAFTorg.freedesktop.Telepathy.Channel.Interface.Passwordorg.freedesktop.Telepathy.Channel.Interface.MediaSignallingorg.freedesktop.Telepathy.Channel.Interface.Messages.DRAFTorg.freedesktop.Telepathy.Media.SessionHandlerorg.freedesktop.Telepathy.Media.StreamHandlerorg.freedesktop.Telepathy.Propertiesorg.freedesktop.Telepathy.AccountManagerorg.freedesktop.Telepathy.Accountorg.freedesktop.Telepathy.ChannelHandlerA D-Bus service which allows connections to be created. The manager processes are intended to be started by D-Bus service activation.
For service discovery, each Telepathy connection manager must have a connection manager name (see Connection_Manager_Name for syntax).
The connection manager must then provide a well-known bus name of
org.freedesktop.Telepathy.ConnectionManager.cmname
where cmname is its connection manager name. If it makes sense
to start the connection manager using D-Bus service activation, it
must register that well-known name for service activation by installing
a .service file.
Clients can list the running connection managers by calling the ListNames method on the D-Bus daemon's org.freedesktop.DBus interface and looking for names matching the above pattern; they can list the activatable connection managers by calling ListActivatableNames, and they should usually combine the two lists to get a complete list of running or activatable connection managers.
When the connection manager is running, it must have an object
implementing the ConnectionManager interface at the object path
/org/freedesktop/Telepathy/ConnectionManager/cmname.
Connection managers' capabilities can be determined dynamically by calling their ListProtocols method, then for each protocol of interest, calling GetParameters to discover the required and optional parameters. However, since it is inefficient to activate all possible connection managers on the system just to find out what they can do, there is a standard mechanism to store static information about CMs in ".manager files".
To look up a connection manager's supported protocols, clients
should search the data directories specified by
the
freedesktop.org XDG Base Directory Specification ($XDG_DATA_HOME,
defaulting to $HOME/.local/share if unset, followed by
colon-separated paths from $XDG_DATA_DIRS, defaulting to
/usr/local/share:/usr/share if unset) for the first file named
telepathy/managers/cmname.manager that can be
read without error. This file has the same syntax as a
freedesktop.org Desktop Entry file.
Clients must still support connection managers for which no
.manager file can be found, which they can do by activating
the connection manager and calling its methods; the
.manager file is merely an optimization. Connection managers
whose list of protocols can change at any time (for instance, via
a plugin architecture) should not install a .manager
file.
For each protocol name proto that would be returned by
ListProtocols, the .manager file contains a group
headed [Protocol proto]. For each parameter
p that would be returned by GetParameters(proto), the
.manager file contains a key param-p with a value
consisting of a D-Bus signature (a single complete type), optionally
followed by a space and a space-separated list of flags. The supported
flags are:
required, corresponding to
Conn_Mgr_Param_Flag_Requiredregister, corresponding
to Conn_Mgr_Param_Flag_Registersecret, corresponding
to Conn_Mgr_Param_Flag_SecretThe group may also contain a key default-p
whose value is a string form of the default value for the parameter.
If this key exists, it sets the default, and also sets the flag
Conn_Mgr_Param_Flag_Has_Default. The default value is formatted
according to the D-Bus signature as follows:
Currently, no other D-Bus signatures are allowed to have default values,
but clients parsing the .manager file MUST ignore defaults
that they cannot parse, and treat them as if the
default-p key was not present at all.
It is not required that a connection manager be able to support multiple protocols, or even multiple connections. When a connection is made, a service name where the connection object can be found is returned. A manager which can only make one connection may then remove itself from its well-known bus name, causing a new connection manager to be activated when somebody attempts to make a new connection.
Changed in version 0.17.2: Prior to version 0.17.2, support for CMs with no .manager file was not explicitly required.
proto -
s(Protocol)a(susv)(Param_Spec[])org.freedesktop.Telepathy.Error.NotImplementedas(Protocol[])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 well-known bus name must be of the form
/org/freedesktop/Telepathy/Connection/cmname/proto/account
and
org.freedesktop.Telepathy.Connection.cmname.proto.account
where:
Clients MUST NOT attempt to parse the account part of the bus name. Connection managers MAY use any unique string for this part.
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:
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.
proto -
s(Protocol)parameters -
a{sv}(String_Variant_Map)s(DBus_Bus_Name)oorg.freedesktop.Telepathy.Error.NetworkErrororg.freedesktop.Telepathy.Error.NotImplementedorg.freedesktop.Telepathy.Error.NotAvailableorg.freedesktop.Telepathy.Error.InvalidArgumentbus_name -
s(DBus_Bus_Name)object_path -
oproto -
s(Protocol)Interface has no Telepathy properties.
Interface has no D-Bus core properties.
Changed in version 0.17.1: Prior to version 0.17.1, the allowed characters were not specified
An instant messaging protocol. It must consist only of ASCII letters, digits and hyphen/minus signs (U+002D "-"), and must start with a letter. Where possible, this SHOULD be chosen from the following well-known values:
Changed in version 0.17.1: Prior to version 0.17.1, the allowed characters were not specified
Conn_Mgr_Param_Flag_Required = 1Conn_Mgr_Param_Flag_Register = 2Conn_Mgr_Param_Flag_Has_Default = 4Conn_Mgr_Param_Flag_Secret = 8This parameter should be considered private or secret; for instance, clients should store it in a "password safe" like gnome-keyring or kwallet, omit it from debug logs, and use a text input widget that hides the value of the parameter.
(Clients that support older connection managers may also treat any parameter whose name contains "password" as though it had this flag.)
Added in version 0.17.2.
In bindings that need a separate name, arrays of Param_Spec should be called Param_Spec_List.
Name -
sFlags -
u(Conn_Mgr_Param_Flags)Signature -
s(DBus_Signature)Default_Value -
vThis 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.
org.freedesktop.Telepathy.Error.NotAvailableas(DBus_Interface[])org.freedesktop.Telepathy.Error.Disconnecteds(Protocol)u(Contact_Handle)org.freedesktop.Telepathy.Error.Disconnectedu(Connection_Status)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.
handle_type -
u(Handle_Type)handles -
au(Handle[])org.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.InvalidArgumentorg.freedesktop.Telepathy.Error.InvalidHandlehandle_type -
u(Handle_Type)handles -
au(Handle[])asorg.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.InvalidArgumentorg.freedesktop.Telepathy.Error.InvalidHandlea(osuu)(Channel_Info[])org.freedesktop.Telepathy.Error.Disconnectedhandle_type -
u(Handle_Type)handles -
au(Handle[])org.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.InvalidArgumentorg.freedesktop.Telepathy.Error.InvalidHandleorg.freedesktop.Telepathy.Error.NotAvailableRequest 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.
type -
s(DBus_Interface)handle_type -
u(Handle_Type)handle -
u(Handle)suppress_handler -
boorg.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.NetworkErrororg.freedesktop.Telepathy.Error.NotImplementedorg.freedesktop.Telepathy.Error.InvalidHandleorg.freedesktop.Telepathy.Error.NotAvailableorg.freedesktop.Telepathy.Error.Channel.Bannedorg.freedesktop.Telepathy.Error.Channel.Fullorg.freedesktop.Telepathy.Error.Channel.InviteOnlyhandle_type -
u(Handle_Type)names -
asau(Handle[])org.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.InvalidArgumentorg.freedesktop.Telepathy.Error.NotAvailableobject_path -
ochannel_type -
s(DBus_Interface)handle_type -
u(Handle_Type)handle -
u(Handle)suppress_handler -
bIf true, the channel was requested by a client that intends to present it to the user itself (i.e. it passed suppress_handler=TRUE to the RequestChannel method), so no other handler should be launched.
If false, either the channel was created due to incoming information from the service, or the channel was requested by a local client that does not intend to handle the channel itself (a typical use-case is an address-book viewer that does not itself implement chat or VoIP functionality, starting a channel that will be handled by the same user interface that would handle incoming channels).
Clients MUST NOT assume that only incoming channels will have this flag set to false.
status -
u(Connection_Status)reason -
u(Connection_Status_Reason)Interface has no Telepathy properties.
Interface has no D-Bus core properties.
Handle_Type_None = 0Handle_Type_Contact = 1Handle_Type_Room = 2Handle_Type_List = 3Handle_Type_Group = 4Connection_Status_Connected = 0Connection_Status_Connecting = 1Connection_Status_Disconnected = 2Connection_Status_Reason_None_Specified = 0Connection_Status_Reason_Requested = 1Connection_Status_Reason_Network_Error = 2Connection_Status_Reason_Authentication_Failed = 3Connection_Status_Reason_Encryption_Error = 4Connection_Status_Reason_Name_In_Use = 5Connection_Status_Reason_Cert_Not_Provided = 6Connection_Status_Reason_Cert_Untrusted = 7Connection_Status_Reason_Cert_Expired = 8Connection_Status_Reason_Cert_Not_Activated = 9Connection_Status_Reason_Cert_Hostname_Mismatch = 10Connection_Status_Reason_Cert_Fingerprint_Mismatch = 11Connection_Status_Reason_Cert_Self_Signed = 12Connection_Status_Reason_Cert_Other_Error = 13In bindings that need a separate name, arrays of Channel_Info should be called Channel_Info_List.
Channel -
oChannel_Type -
s(DBus_Interface)Handle_Type -
u(Handle_Type)Handle -
u(Handle)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.
u(Connection_Alias_Flags)org.freedesktop.Telepathy.Error.Disconnectedcontacts -
au(Contact_Handle[])asorg.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.NetworkErrororg.freedesktop.Telepathy.Error.NotAvailableorg.freedesktop.Telepathy.Error.InvalidHandlealiases -
a{us}(Alias_Map)org.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.NetworkErrororg.freedesktop.Telepathy.Error.NotAvailableorg.freedesktop.Telepathy.Error.InvalidArgumentorg.freedesktop.Telepathy.Error.PermissionDeniedaliases -
a(us)(Alias_Pair[])Interface has no Telepathy properties.
Interface has no D-Bus core properties.
Connection_Alias_Flag_User_Set = 1The 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.
In bindings that need a separate name, arrays of Alias_Pair should be called Alias_Pair_List.
Handle -
u(Contact_Handle)Alias -
sHandle -
u(Contact_Handle)Alias -
sImplementations 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 GetKnownAvatarTokens to request the tokens for the avatars of all the contacts it is interested in when it connects. The avatars can then be requested using RequestAvatars for the contacts. Clients should bind to the AvatarChanged signal and request a new copy of the avatar when a contacts' avatar token changes. Clients should cache the token and data of each contact's avatar between connections, to avoid repeatedly retrieving the same avatar.
To publish an avatar, a client should use SetAvatar to provide an image which meets the requirements returned by the GetAvatarRequirements function. On some protocols the avatar is stored on the server, so setting the avatar is persistent, but on others it is transferred via a peer to peer mechanism, so needs to be set every connection. Hence, on every connection, clients should inspect the avatar token of the connection's self handle, and set the avatar if it is an empty string (and may optionally replace it if the token corresponds to a different avatar).
To remove the published avatar on protocols which have persistent avatars, a client should use the ClearAvatar method. This method can safely be used even if there is no avatar for this connection.
asqqqquorg.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.NetworkErrororg.freedesktop.Telepathy.Error.PermissionDeniedorg.freedesktop.Telepathy.Error.NotAvailablecontacts -
au(Contact_Handle[])asorg.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.NetworkErrororg.freedesktop.Telepathy.Error.InvalidArgumentorg.freedesktop.Telepathy.Error.PermissionDeniedorg.freedesktop.Telepathy.Error.NotAvailablecontacts -
au(Contact_Handle[])a{us}(Avatar_Token_Map)org.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.NetworkErrororg.freedesktop.Telepathy.Error.InvalidArgumentorg.freedesktop.Telepathy.Error.PermissionDeniedorg.freedesktop.Telepathy.Error.NotAvailablecontact -
u(Contact_Handle)aysorg.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.NetworkErrororg.freedesktop.Telepathy.Error.InvalidHandleorg.freedesktop.Telepathy.Error.PermissionDeniedorg.freedesktop.Telepathy.Error.NotAvailablecontacts -
au(Contact_Handle[])org.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.InvalidHandleavatar -
aymime_type -
ssorg.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.NetworkErrororg.freedesktop.Telepathy.Error.InvalidArgumentorg.freedesktop.Telepathy.Error.PermissionDeniedorg.freedesktop.Telepathy.Error.NotAvailableAdded in version 0.15.0.
org.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.NetworkErrorcontact -
u(Contact_Handle)new_avatar_token -
scontact -
u(Contact_Handle)token -
savatar -
aytype -
sInterface has no Telepathy properties.
Interface has no D-Bus core properties.
Handle -
u(Contact_Handle)Token -
sImplementations 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 Connection_Capability_Flags.
In addition, channel types may have type specific capability flags of their own, which are described in the documentation for each channel type.
This interface also provides for user interfaces notifying the connection manager of what capabilities to advertise for the user. This is done by using the AdvertiseCapabilities method, and deals with the interface names of channel types and the type specific flags pertaining to them which are implemented by available client processes.
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.
add -
a(su)(Capability_Pair[])remove -
as(DBus_Interface[])a(su)(Capability_Pair[])org.freedesktop.Telepathy.Error.NetworkErrororg.freedesktop.Telepathy.Error.Disconnectedhandles -
au(Contact_Handle[])a(usuu)(Contact_Capability[])org.freedesktop.Telepathy.Error.NetworkErrororg.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.InvalidHandleorg.freedesktop.Telepathy.Error.PermissionDeniedcaps -
a(usuuuu)(Capability_Change[])Interface has no Telepathy properties.
Interface has no D-Bus core properties.
Connection_Capability_Flag_Create = 1Connection_Capability_Flag_Invite = 2In bindings that need a separate name, arrays of Capability_Pair should be called Capability_Pair_List.
Channel_Type -
s(DBus_Interface)Type_Specific_Flags -
uIn bindings that need a separate name, arrays of Contact_Capability should be called Contact_Capability_List.
Handle -
u(Contact_Handle)Channel_Type -
s(DBus_Interface)Generic_Flags -
u(Connection_Capability_Flags)Type_Specific_Flags -
uIn bindings that need a separate name, arrays of Capability_Change should be called Capability_Change_List.
Handle -
u(Contact_Handle)Channel_Type -
s(DBus_Interface)Old_Generic_Flags -
u(Connection_Capability_Flags)New_Generic_Flags -
u(Connection_Capability_Flags)Old_Type_Specific_Flags -
uNew_Type_Specific_Flags -
uImplementations 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.
status -
sparms -
a{sv}(String_Variant_Map)org.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.NetworkErrororg.freedesktop.Telepathy.Error.InvalidArgumentorg.freedesktop.Telepathy.Error.NotAvailableorg.freedesktop.Telepathy.Error.PermissionDeniedorg.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.NetworkErrororg.freedesktop.Telepathy.Error.PermissionDeniedcontacts -
au(Contact_Handle[])presence -
a{u(ua{sa{sv}})}(Contact_Presences)org.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.InvalidHandleorg.freedesktop.Telepathy.Error.NotAvailablea{s(ubba{ss})}(Status_Spec_Map)org.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.NetworkErrorstatus -
sorg.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.NetworkErrororg.freedesktop.Telepathy.Error.PermissionDeniedorg.freedesktop.Telepathy.Error.InvalidArgumentcontacts -
au(Contact_Handle[])org.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.NetworkErrororg.freedesktop.Telepathy.Error.InvalidHandleorg.freedesktop.Telepathy.Error.PermissionDeniedorg.freedesktop.Telepathy.Error.NotAvailabletime -
u(Unix_Timestamp)org.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.NetworkErrororg.freedesktop.Telepathy.Error.NotImplementedstatuses -
a{sa{sv}}(Multiple_Status_Map)org.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.NetworkErrororg.freedesktop.Telepathy.Error.NotAvailableorg.freedesktop.Telepathy.Error.InvalidArgumentorg.freedesktop.Telepathy.Error.PermissionDeniedpresence -
a{u(ua{sa{sv}})}(Contact_Presences)Interface has no Telepathy properties.
Interface has no D-Bus core properties.
Connection_Presence_Type_Unset = 0Connection_Presence_Type_Offline = 1Connection_Presence_Type_Available = 2Connection_Presence_Type_Away = 3Connection_Presence_Type_Extended_Away = 4Connection_Presence_Type_Hidden = 5Connection_Presence_Type_Busy = 6Added in version 0.17.0.
Arrays of Last_Activity_And_Statuses don't generally make sense.
Last_Activity -
u(Unix_Timestamp)Statuses -
a{sa{sv}}(Multiple_Status_Map)Arrays of Status_Spec don't generally make sense.
Type -
u(Connection_Presence_Type)May_Set_On_Self -
bExclusive -
bParameter_Types -
a{ss}(String_String_Map)Status -
sParameters -
a{sv}(String_Variant_Map)Contact -
u(Contact_Handle)Presence -
(ua{sa{sv}})(Last_Activity_And_Statuses)Identifier -
sSpec -
(ubba{ss})(Status_Spec)This interface is not well-tested and is likely to cause havoc to your API/ABI if bindings are generated. Don't include it in libraries that care about compatibility.
Implementations of this interface must also implement:
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.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.
name -
sorg.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.NetworkErrororg.freedesktop.Telepathy.Error.NotAvailableorg.freedesktop.Telepathy.Error.InvalidArgumentorg.freedesktop.Telepathy.Error.PermissionDeniedEmitted 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.
original -
u(Contact_Handle)new -
u(Contact_Handle)Interface has no Telepathy properties.
Interface has no D-Bus core properties.
All communication in the Telepathy framework is carried out via channel objects which are created and managed by connections. This interface must be implemented by all channel objects, along with one single channel type, such as Channel.Type.ContactList which represents a list of people (such as a buddy list) or a Channel.Type.Text which represents a channel over which textual messages are sent and received.
Each channel may have an immutable handle associated with it, which may be any handle type, such as a contact, room or list handle, indicating that the channel is for communicating with that handle.
If a channel does not have a handle (an "anonymous channel" with Target_Handle = 0 and Target_Handle_Type = Handle_Type_None), it means that the channel is defined by some other terms, such as it may be a transient group defined only by its members as visible through the Channel.Interface.Group interface.
Other optional interfaces can be implemented to indicate other available functionality, such as Channel.Interface.Group if the channel contains a number of contacts, Channel.Interface.Password to indicate that a channel may have a password set to require entry, and Properties for extra data about channels which represent chat rooms or voice calls. The interfaces implemented may not vary after the channel's creation has been signalled to the bus (with the connection's NewChannel signal).
Specific connection manager implementations may implement channel types and interfaces which are not contained within this specification in order to support further functionality. To aid interoperability between client and connection manager implementations, the interfaces specified here should be used wherever applicable, and new interfaces made protocol-independent wherever possible. Because of the potential for 3rd party interfaces adding methods or signals with conflicting names, the D-Bus interface names should always be used to invoke methods and bind signals.
Changed in version 0.17.7: Previously we guaranteed that, for any handle type other than Handle_Type_None, and for any channel type and any handle, there would be no more than one channel with that combination of channel type, handle type and handle. This guarantee has now been removed in order to accommodate features like message threads.
org.freedesktop.Telepathy.Error.Disconnectedorg.freedesktop.Telepathy.Error.NetworkErrororg.freedesktop.Telepathy.Error.NotImplementedorg.freedesktop.Telepathy.Error.NotAvailableDeprecated since version 0.17.7. Use the ChannelType property if possible.
s(DBus_Interface)Deprecated since version 0.17.7. Use the TargetHandleType and TargetHandle properties if possible.
u(Handle_Type)u(Handle)Deprecated since version 0.17.7. Use the Interfaces property if possible.
as(DBus_Interface[])Interface has no Telepathy properties.
Accessed using the org.freedesktop.DBus.Properties interface.
ChannelType - s(DBus_Interface), read-onlyThe channel's type. This cannot change once the channel has been created.
For compatibility between older connection managers and newer clients, if this is unavailable or is an empty string, clients MUST use the result of calling GetChannelType.
Added in version 0.17.7.
Interfaces - as(DBus_Interface[]), read-onlyExtra interfaces provided by this channel. This SHOULD NOT include the channel type and the Channel interface itself, and cannot change once the channel has been created.
For compatibility between older connection managers and newer clients, if this is unavailable, or if this is an empty list and ChannelType is an empty string, clients MUST use the result of calling GetInterfaces instead. If this is an empty list but ChannelType is non-empty, clients SHOULD NOT call GetInterfaces; this implies that connection managers that implement the ChannelType property MUST also implement the Interfaces property correctly.
Added in version 0.17.7.
TargetHandle - u(Handle), read-onlyThe handle (a representation for the identifier) of the contact, chatroom, etc. with which this handle communicates. Its type is given by the TargetHandleType property.
This is fixed for the lifetime of the channel, so channels which could potentially be used to communicate with multiple contacts (such as streamed media calls defined by their members, or ad-hoc chatrooms like MSN switchboards) must have TargetHandleType set to Handle_Type_None and TargetHandle set to 0.
Unlike in the telepathy-spec 0.16 API, there is no particular uniqueness guarantee - there can be many channels with the same (channel type, handle type, handle) tuple. This is necessary to support conversation threads in XMPP and SIP, for example.
Added in version 0.17.7.
TargetHandleType - u(Handle_Type), read-onlyAdded in version 0.17.7.
This interface is a staging area for future Channel functionality and is likely to cause havoc to your API/ABI if bindings are generated. Don't include it in libraries that care about compatibility.
This interface contains functionality which we intend to incorporate into the Channel interface in future. It should be considered to be conceptually part of the core Channel interface, but without API or ABI guarantees.
If we add new functionality to the Channel interface, libraries that use generated code (notably telepathy-glib) will have it as part of their ABI forever, meaning we can't make incompatible changes. By using this interface as a staging area for future Channel functionality, we can try out new properties, signals and methods as application-specific extensions, then merge them into the core Channel interface when we have enough implementation experience to declare them