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.
This interface provides properties that can be used for requesting channels through different contact addressing schemes like vCard addresses or URIs.
The vCard field, normalized to lower case,
The url vCard field MUST NOT appear here; see
In practice, protocols have a limited set of URI schemes that make sense to resolve as a contact.
If this is omitted from a request,
The URI scheme used in
While this seems redundant, since the scheme is included in
If this is omitted from a request,
The vCard address of the Channel's target.
If this is present in a channel request,
The URI of the Channel's target. The URI's scheme (i.e. the
part before the first colon) MUST be identical to
If this is present in a channel request,
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.
A channel type for searching server-stored user directories. A new channel should be requested by a client for each search attempt, and closed when the search is completed or the required result has been found.
Before searching, the
Not_Started to In_Progress. As results are
returned by the server, the
Completed. If the search fails after Search
has been called, the state will change to Failed. A
running search can be cancelled by calling
If the protocol supports limiting the number of results returned by a
search and subsequently requesting more results, after
More_Available. Clients may
call
The client should call the channel's
Each channel can only be used for a single search; a new channel should be requested for each subsequent search. Connection managers MUST support multiple ContactSearch channels being open at once (even to the same server, if applicable).
It does not make sense to request this channel type using
A contact search channel that is already in use for a different search isn't useful.
Failed, the name of a D-Bus error
describing what went wrong. Otherwise, the empty string.
Additional information about the state transition, which may include the following well-known keys:
This argument allows for future extensions. For instance,
if moving to state Failed because the server
rejected one of our search terms, we could define a key
that indicates which terms were invalid.
Emitted when the
Not_Started → In_ProgressIn_Progress → More_AvailableMore_Available → In_ProgressIn_Progress → CompletedIn_Progress → FailedAny of the following search keys, with the indicated result for the search:
nickname would search nicknames, and
tel would search any available phone number,
regardless of its work/home/mobile/... status).;" and a
type=..."tel;type=mobile).x-telepathy-identifierx-jabber) or not exist at all.
x-genderx-n-familyn).
x-n-givenn).
x-n-family.
x-onlinex-adr-localityadr).
If supported by the protocol, the maximum number of results that
should be returned, where 0 represents no limit. If the
protocol does not support limiting results, this should be
0.
For example, if the terms passed to
2, the search service SHOULD only return Antonius
and Bridget.
This property cannot change during the lifetime of the channel.
This property SHOULD be in the Allowed_Properties of a
0 as the default if possible, or a protocol-specific
sensible default otherwise.
More_Available move back to state In_Progress
and continue listing up to More_Available.
Stop the current search. This may not be called while the
org.freedesktop.Telepathy.Error..
Calling this method on a search in state Completed or Failed succeeds, but has no effect.
Specifying Stop to succeed when the search has finished means that
clients who call Stop just before receiving
Depending on the protocol, the connection manager may not be able to prevent the server from sending further results after this method returns; if this is the case, it MUST ignore any further results.
An array of fields representing information about this
contact, in the same format used in the
For protocols which support searching for contacts on multiple servers with different DNS names (like XMPP), the DNS name of the server being searched by this channel, e.g. "characters.shakespeare.lit". Otherwise, the empty string.
XEP 0055 defines a mechanism for XMPP clients to search services of their choice for contacts, such as users.jabber.org (the "Jabber User Directory").
This property cannot change during the lifetime of the channel.
This property SHOULD be in the Allowed_Properties of a
This allows a client to perform searches on a protocol it knows nothing about without requiring the user to guess a valid server's hostname.
A tube is a mechanism for arbitrary data transfer between
two or more IM users, used to allow applications on the users'
systems to communicate without having to establish network
connections themselves. Currently, two types of tube exist:
Tube channels can be requested for
As an exception to the usual handling of capabilities, connection managers
for protocols with capability discovery (such as XMPP) SHOULD advertise the
capability representing each Tube type that they support
(
This lowers the barrier to entry for those writing new tube applications, and preserves interoperability with older versions of the Telepathy stack which did not support rich capabilities.
Each tube has a dictionary of arbitrary parameters. Parameters are commonly used to bootstrap legacy protocols where you can't negotiate parameters in-band. The allowable keys, types and values are defined by the service, but connection managers must support the value being a string (D-Bus type 's'), array of bytes (D-Bus type 'ay'), unsigned integer (D-Bus type 'u'), integer (D-Bus type 'i') and boolean (D-Bus type 'b').
When the tube is offered, the parameters are transmitted with the offer and appear as a property of the incoming tube for other participants.
For example, a stream tube for
{ 'u': 'some-username',
'p': 'top-secret-password',
'path': '/etc/passwd',
}
When requesting a tube with
When receiving an incoming tube, this property is immutable and so advertised in the
State of the tube in this channel.
When requesting a tube with
May only be used on UNIX sockets. The connecting process must send a byte when it first connects, which is not considered to be part of the data stream. If the operating system uses sendmsg() with SCM_CREDS or SCM_CREDENTIALS to pass credentials over sockets, the connecting process must do so if possible; if not, it must still send the byte.
The listening process will disconnect the connection unless it can determine by OS-specific means that the connecting process has the same user ID as the listening process.
The associated variant must be ignored.
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.
This interface contains functionality which we intend to incorporate
into the
If true, channels destined for this handler are not passed to observers for observing.
This is useful in use-cases where the handler doesn't want anyone observing the channel - for example, because channels it handles shouldn't be logged.
For service-activatable handlers, this property should be specified in the handler's .client file as follows:
[org.freedesktop.Telepathy.Client.Handler] BypassObservers=true
If true, channels destined for this handler that have the
It would be reasonable for a user interface to accept invitations to continuations of an existing channel automatically, or not; this is a matter of UI policy.
It's somewhat complex for an Approver to keep track of which channels are being handled by a particular Handler, but the Channel Dispatcher already has to track this, so it's useful for the channel dispatcher to assist here.
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.
This interface contains functionality which we intend to incorporate
into the
Start a request to create a channel. This initially just creates a
The request can take a long time - in the worst case, the channel dispatcher has to ask the account manager to put the account online, the account manager has to ask the operating system to obtain an Internet connection, and the operating system has to ask the user whether to activate an Internet connection using an on-demand mechanism like dialup.
This means that using a single D-Bus method call and response to represent the whole request will tend to lead to that call timing out, which is not the behaviour we want.
If this method is called for an Account that is disabled, invalid
or otherwise unusable, no error is signalled until
This means there's only one code path for errors, apart from InvalidArgument for "that request makes no sense".
It also means that the request will proceed if the account is enabled after calling CreateChannel, but before calling Proceed.
A dictionary containing desirable properties. This has the same
semantics as the corresponding parameter to
Certain properties will not necessarily make sense in this
dictionary: for instance,
The time at which user action occurred, or 0 if this channel
request is for some reason not involving user action.
The User_Action_Time parameter of
Either the well-known bus name (starting with
org.freedesktop.Telepathy.Client.)
of the preferred handler for this
channel, or an empty string to indicate that any handler would be
acceptable. The channel dispatcher SHOULD dispatch as many as
possible of the resulting channels (ideally, all of them)
to that handler—irrespective of whether that handler's
This must be the well-known bus name, not the unique name, to ensure that all handlers do indeed have the Client API, and the Client object on the handler can be located easily.
This is partly so the channel dispatcher can call
The filter should be disregarded for ease of use of this interface: clients will usually use this argument to request channels be sent to themself, and this should trump the filter not matching. This also allows a client to become the handler for a channel produced by one of its own requests, while not being a candidate to handle other channels of that type.
If this is a well-known bus name and the handler has the
Requests interface, the channel dispatcher SHOULD
call
This ordering allows a Handler which calls CreateChannel with itself as the preferred handler to associate the call to AddRequest with that call.
This is copied to the ChannelRequest that is returned,
as the
Additional information about the channel request, which will be
used as the value for the resulting request's
See the Hints property's documentation for rationale.
org.freedesktop.Telepathy.Client.,
the Account does not exist, or one of the Requested_Properties
is invalid
Start a request to ensure that a channel exists, creating it if
necessary. This initially just creates a
If this method is called for an Account that is disabled, invalid
or otherwise unusable, no error is signalled until
The rationale is as for
A dictionary containing desirable properties. This has the same
semantics as the corresponding parameter to
Certain properties will not necessarily make sense in this
dictionary: for instance,
The time at which user action occurred, or 0 if this channel request is for some reason not involving user action.
This parameter is used in the same way as the corresponding
parameter to
Either the well-known bus name (starting with
org.freedesktop.Telepathy.Client.)
of the preferred handler for this
channel, or an empty string to indicate that any handler would be
acceptable. The behaviour and rationale are the same as for the
corresponding parameter to
If any new channels are created in response to this
request, the channel dispatcher SHOULD dispatch as many as
possible of the resulting channels (ideally, all of them)
to that handler, and SHOULD remember the preferred handler
so it can try to dispatch subsequent channels in the same bundle
to the same handler. If the requested channel already exists (that
is, Yours=False) then the channel dispatcher
SHOULD re-dispatch the channel to its existing handler, and MUST
NOT dispatch it to this client (unless it is the existing handler);
the request is still deemed to have succeeded in this case.
An address book application, for example, might call Preferred_Handler; if the
user already has a conversation with that contact in another
application, they would expect the existing window to be
presented, rather than their double-click leading to an error
message. So the request should succeed, even if its
Preferred_Handler is not used.
org.freedesktop.Telepathy.Client.,
the Account does not exist, or one of the Requested_Properties
is invalid
True, the channel dispatcher is new enough to support
False or missing, only the metadata-less
variants are supported.
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.
An interface for protocols where it might be possible to set the user's avatar, and the expected size limits and supported MIME types are known before connecting.
If the avatar requirements cannot be discovered while offline,
it's impossible to avoid setting the
Each property on this interface SHOULD be cached in the
.manager file, using a key of the same name as the
property in the [Protocol proto]
group. All properties are encoded in ASCII decimal in the obvious
way, except for
For instance, an XMPP connection manager might have this
.manager file:
[Protocol jabber] Interfaces=org.freedesktop.Telepathy.Protocol.Interface.Avatars; param-account=s required param-password=s required SupportedAvatarMIMETypes=image/png;image/jpeg;image/gif; MinimumAvatarHeight=32 RecommendedAvatarHeight=64 MaximumAvatarHeight=96 MinimumAvatarWidth=32 RecommendedAvatarWidth=64 MaximumAvatarWidth=96 MaximumAvatarBytes=8192
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.
An interface for channels that can be made conceptually part of a
This interface addresses part of freedesktop.org bug #24906 (GSM-compatible conference calls). GSM is currently the only protocol known to implement this; PBXs might implement it too.
Request that this channel is removed from any
This implies that the media streams within the conference are put on hold and the media streams within the member channel leaving the conference are unheld.
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.
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
Attempting to add contacts who are already members is allowed; connection managers must silently accept this, without error.
The members of this group have handles which are specific to
this channel, and are not valid as general-purpose handles on
the connection. Depending on the channel, it may be possible to
check the
Connection managers must ensure that any given handle is not simultaneously a general-purpose handle and a channel-specific handle.
The reason for a set of handles to move to one of
No reason was provided for this change.
In particular, this reason SHOULD be used when representing users joining a named chatroom in the usual way, users leaving a chatroom by their own request, and normal termination of a StreamedMedia call by the remote user.
If the org.freedesktop.Telepathy.Error.Terminated.
If the SelfHandle is removed from a group for this reason and
the actor is also the SelfHandle, the equivalent D-Bus error is
org.freedesktop.Telepathy.Error.Cancelled.
The change is due to a user going offline. Also used when user is already offline, but this wasn't known previously.
If a one-to-one
If a handle is removed from a group for this reason, the
equivalent D-Bus error is
org.freedesktop.Telepathy.Error.Offline.
The change is due to a kick operation.
If the org.freedesktop.Telepathy.Error.Channel.Kicked.
The change is due to a busy indication.
If a one-to-one
If the org.freedesktop.Telepathy.Error.Busy.
The change is due to a kick+ban operation.
If the org.freedesktop.Telepathy.Error.Channel.Banned.
The change is because the requested contact does not exist.
For instance, if the user invites a nonexistent contact to a chatroom or attempts to call a nonexistent contact, this could be indicated by the CM adding that contact's handle to remote-pending for reason None or Invited, then removing it for reason Invalid_Contact. In the case of a 1-1 StreamedMedia call, the CM SHOULD remove the self handle from the Group in the same signal.
If a contact is removed from a group for this reason, the
equivalent D-Bus error is
org.freedesktop.Telepathy.Error.DoesNotExist.
The change is because the requested contact did not respond.
If a one-to-one
If a contact is removed from a group for this reason, the
equivalent D-Bus error is
org.freedesktop.Telepathy.Error.NoAnswer.
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
The change is because there was no permission to contact the requested handle.
If a contact is removed from a group for this reason, the
equivalent D-Bus error is
org.freedesktop.Telepathy.Error.PermissionDenied.
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.
Note that from the added contacts' perspective, they have been in the group all along, and the contacts we indicate to be in the group (including the local user) have just rejoined the group with reason Separated. Application protocols in Tubes should be prepared to cope with this situation.
The
Emitted when contacts join any of the three lists (members, local pending or remote pending) or when they leave any of the three lists. There may also be a message from the server regarding this change, which may be displayed to the user if desired.
All channel-specific handles that are mentioned in this signal
MUST be represented in the value of the
See
Information about the change, which may include the following well-known keys:
The string identifiers for handles mentioned in this signal, to give clients the minimal information necessary to react to the event without waiting for round-trips. Connection managers SHOULD include the identifiers for members added to the group and for the actor (if any); they MAY omit the identifiers for handles which have been removed from the group.
On IRC, an event such as a netsplit could cause the vast majority of a channel to leave. Given that clients should already know the identifiers of a channel's members, including potentially hundreds of strings in the netsplit signal is unnecessary.
Clients MUST NOT assume that the presence or absence of a handle in this mapping is meaningful. This mapping is merely an optimization for round-trip reduction, and connection managers MAY add additional handles, omit some handles, or omit the mapping completely.
Emitted when contacts join any of the three lists (members, local
pending or remote pending) or when they leave any of the three
lists. This signal provides a superset of the information provided by
All channel-specific handles that are mentioned in this signal
MUST be represented in the value of the
See
Requests the removal of contacts from a channel, reject their request for channel membership on the pending local list, or rescind their invitation on the pending remote list.
If the
Accordingly, connection managers SHOULD support
doing this, regardless of the value of
Removing any contact from the local pending list is always
allowed. Removing contacts other than the
A message may be provided along with the request, which will be
sent to the server if supported. See the
Channel_Group_Flag_Message_Remove,
Channel_Group_Flag_Message_Depart,
Channel_Group_Flag_Message_Reject and
Channel_Group_Flag_Message_Rescind
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
(
If the
Addition of members to the channel may be requested by using
Removal of contacts from the channel may be requested by using
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.
Interface for calls which may be muted. This only makes sense for channels where audio or video is streaming between members.
Muting a call content indicates that the user does not wish to send outgoing audio or video.
Although it's client's responsibility to actually mute the microphone or turn off the camera, using this interface the client can also inform the CM and other clients of that fact.
Inform the CM that the call content has been muted or unmuted by the client.
It is the client's responsibility to actually mute or unmute the microphone or camera used for the content. However, the client MUST call this whenever it mutes or unmutes the content.
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.
Extra interfaces provided by this codec offer. This SHOULD NOT include the CodecOffer interface itself, and cannot change once the content has been created.
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.
The tube is D-Bus tube as described by the org.freedesktop.Telepathy.Channel.Type.DBusTube interface.
The tube is stream tube as described by the org.freedesktop.Telepathy.Channel.Type.StreamTube interface.
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.
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.
The raw data contained in a TLS certificate.
For X.509 certificates (
For PGP certificates (
Struct representing one reason why a TLS certificate was rejected.
Since there can be multiple things wrong with a TLS certificate, arrays of this type are used to represent lists of reasons for rejection. In that case, the most important reason SHOULD be placed first in the list.
The value of the TLS_Certificate_Reject_Reason enumeration for
this certificate rejection.
Error member,
which may be implementation-specific, can use this property to
classify rejection reasons into common categories.
The DBus error name for this certificate rejection.
This MAY correspond to the value of the Reason member,
or MAY be a more specific D-Bus error name, perhaps implementation-specific.
Additional information about why the certificate was rejected. This MAY also include one or more of the following well-known keys:
For instance, if you try to connect to gmail.com but are presented with a TLS certificate issued to evil.example.org, the error details for Hostname_Mismatch MAY include:
{
'expected-hostname': 'gmail.com',
'certificate-hostname': 'evil.example.org',
}
If the
If the
The first rejection in the list MAY be assumed to be the most important; if the array contains more than one element, the CM MAY either use the values after the first, or ignore them.
This property is immutable
One or more TLS certificates forming a trust chain, each encoded as
specified by
The first certificate in the chain MUST be the server certificate, followed by the issuer's certificate, followed by the issuer's issuer and so on.
The new value of the
This MUST NOT be an empty array.
Pending, or when the provided rejection list is empty.
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.
An interface on connections to support protocols which allow users to publish their current geographical location, and subscribe to the current location of their contacts.
This interface is geared strongly towards automatic propagation and use of this information, so focuses on latitude, longitude and altitude which can be determined by GPS, although provision is also included for an optional human-readable description of locations. All co-ordinate information is required to be relative to the WGS84 datum.
The information published through this interface is intended to have the same scope as presence information, so will normally be made available to those individuals on the user's "publish" contact list. Even so, user interfaces should not automatically publish location information without the consent of the user, and it is recommended that an option is made available to reduce the accuracy of the reported information to allow the user to maintain their privacy.
Location information is represented using the terminology of XMPP's XEP-0080 or the XEP-0080-derived Geoclue API where possible.
Clients of this interface SHOULD register an interest in it by calling
Civic addresses are represented by the following well-known keys (all of which have string values), which should be kept in sync with those used in XEP-0080 and in the Geoclue project:
The following address keys are defined in XEP-0080 but not by Geoclue, and are also allowed:
Since the previous strings have data intended to be read by users, the language used should be stated using:
Positions are represented by the following well-known keys:
Velocities are represented by the following well-known keys:
Other well-known keys:
Return the current locations of the given contacts, if they are
already known. If any of the given contacts' locations are not known,
request their current locations, but return immediately without waiting
for a reply; if a reply with a non-empty location is later received
for those contacts, the
This method is appropriate for "lazy" location finding, for instance displaying the location (if available) of everyone in your contact list.
For backwards compatibility, if this method is called by a client
whose "interest count" for this interface, as defined by
Can_Set flag will not be set in
Connected, but MUST remain constant thereafter.
The same mapping that would be returned by
For backwards compatibility, if contact attributes that include
this interface are requested
by a client whose "interest count" for this interface, as defined by
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.
A channel dispatch operation is an object in the ChannelDispatcher
representing a batch of unrequested channels being announced to
client
These objects can result from new incoming channels or channels which are automatically created for some reason, but cannot result from outgoing requests for channels.
More specifically, whenever the
(If some channels in a NewChannels signal are in different bundles, this is an error. The channel dispatcher SHOULD recover by treating the NewChannels signal as if it had been several NewChannels signals each containing one channel.)
First, the channel dispatcher SHOULD construct a list of all the
If no handler at all can handle a channel, the channel dispatcher
SHOULD terminate that channel instead of creating a channel dispatcher
for it. It is RECOMMENDED that the channel dispatcher closes
the channels using
ContactList channels are strange. We hope to replace them with something better, such as an interface on the Connection, in a future version of this specification.
When listing channel handlers, priority SHOULD be given to channel handlers that are already handling channels from the same bundle.
If a handler with = True could handle all of the channels in the dispatch
operation, then the channel dispatcher SHOULD call
Some channel types can be picked up "quietly" by an existing
channel handler. If a
Otherwise, the channel dispatcher SHOULD send the channel dispatch
operation to all relevant approvers (in parallel) and wait for an
approver to claim the channels or request that they are handled.
See
Finally, if the approver requested it, the channel dispatcher SHOULD send the channels to a handler.
A channel has closed before it could be claimed or handled. If
this is emitted for the last remaining channel in a channel
dispatch operation, it MUST immediately be followed by
This signal MUST NOT be emitted until all Approvers that were
invoked have returned (successfully or with an error) from
their
This means that Approvers can connect to the ChannelLost signal
in a race-free way. Non-approver processes that discover
a channel dispatch operation in some way (such as observers)
will have to follow the usual "connect to signals then recover
state" model - first connect to ChannelLost and
The name of a D-Bus error indicating why the channel closed. If
no better reason can be found,
org.freedesktop.Telepathy.Error.NotAvailable MAY
be used as a fallback; this means that this error SHOULD NOT be
given any more specific meaning.
The well known bus names (starting with
org.freedesktop.Telepathy.Client.) of the possible
The heuristic used to prioritize handlers SHOULD give a higher priority to handlers that are already running.
If, for instance, Empathy and Kopete have similar functionality, and Empathy is running, we should prefer to send channels to it rather than launching Kopete via service activation.
Called by an approver to accept a channel bundle and request that the given handler be used to handle it.
If successful, this method will cause the ChannelDispatchOperation
object to disappear, emitting
However, this method may fail because the dispatch has already been completed and the object has already gone. If this occurs, it indicates that another approver has asked for the bundle to be handled by a particular handler. The approver MUST NOT attempt to interact with the channels further in this case, unless it is separately invoked as the handler.
Approvers which are also channel handlers SHOULD use
(FIXME: list some possible errors)
If the channel handler raises an error from
The well-known bus name (starting with
org.freedesktop.Telepathy.Client.) of the channel
handler that should handle the channel, or the empty string
if the client has no preferred channel handler.
org.freedesktop.Telepathy.Client.".
Called by an approver to claim channels for handling
internally. If this method is called successfully, the process
calling this method becomes the handler for the channel, but
does not have the
Clients that call Claim on channels but do not immediately
close them SHOULD implement the Handler interface and its
Approvers wishing to reject channels MUST call this method to
claim ownership of them, and MUST NOT call
The channel dispatcher can't know how best to close arbitrary
channel types, so it leaves it up to the approver to do so.
For instance, for Text channels it is necessary
to acknowledge any messages that have already been displayed to
the user first - ideally, the approver would display and then
acknowledge the messages - or to call
Similarly, an Approver for StreamedMedia channels can close the channel with a reason (e.g. "busy") if desired. The channel dispatcher, which is designed to have no specific knowledge of particular channel types, can't do that.
If successful, this method will cause the ChannelDispatchOperation
object to disappear, emitting
This method may fail because the dispatch operation has already been completed. Again, see HandleWith for more details. The approver MUST NOT attempt to interact with the channels further in this case.
(FIXME: list some other possible errors)
A variant of
The well-known bus name (starting with
org.freedesktop.Telepathy.Client.) of the channel
handler that should handle the channel, or the empty string
if the client has no preferred channel handler.
The time at which user action occurred.
org.freedesktop.Telepathy.Client.".
Emitted when this dispatch operation finishes. The dispatch operation is no longer present and further methods must not be called on it.
Approvers that have a user interface SHOULD stop notifying the user
about the channels in response to this signal; they MAY assume that
on errors, they would have received
Its object path SHOULD NOT be reused for a subsequent dispatch operation; the ChannelDispatcher MUST choose object paths in a way that avoids immediate re-use.
Otherwise, clients might accidentally call
This signal MUST NOT be emitted until all Approvers that were
invoked have returned (successfully or with an error) from
their
This means that Approvers can connect to the ChannelLost signal
in a race-free way. Non-approver processes that discover
a channel dispatch operation in some way (such as observers)
will have to follow the usual "connect to signals then recover
state" model - first connect to
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.
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.
This interface exists to support channels where
Close the channel abruptly, possibly with loss of data. The connection manager MUST NOT re-create the channel unless/until more events occur.
The main motivating situation for this method is that when a Text channel with pending messages is closed with Close, it comes back as an incoming channel (to avoid a race between Close and an incoming message). If Destroy is called on a Text channel, the CM should delete all pending messages and close the channel, and the channel shouldn't be re-created until/unless another message arrives.
Most clients SHOULD call
In particular, channel dispatchers SHOULD use this method if available when terminating channels that cannot be handled correctly (for instance, if no handler has been installed for a channel type, or if the handler crashes repeatedly).
Connection managers do not need to implement this interface on channels where Close and Destroy would be equivalent.
Callers need to be able to fall back to Close in any case.
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.
Handlers are the user interface for a channel. They turn an abstract Telepathy channel into something the user wants to see, like a text message stream or an audio and/or video call.
For its entire lifetime, each channel on a connection known to the channel dispatcher is either being processed by the channel dispatcher, or being handled by precisely one Handler.
Because each channel is only handled by one Handler, handlers may
perform actions that only make sense to do once, such as acknowledging
When a new incoming channel (one with
When a new outgoing channel (one with
A specification of the channels that this channel handler can deal with. It will be offered to approvers as a potential channel handler for bundles that contain only suitable channels, or for suitable channels that must be handled separately.
This property works in exactly the same way as the
In the .client file, it is represented in the same way as ObserverChannelFilter, but the group has the same name as this interface and the keys start with HandlerChannelFilter instead of ObserverChannelFilter.
If true, channels destined for this handler are automatically handled, without invoking approvers.
The intended usage is to allow a client handling one channel to
pick up closely related channels. Suppose a client capable of
handling both Text and StreamedMedia,
org.freedesktop.Telepathy.Client.Empathy, is
handling a StreamedMedia channel. That client can take a second
well-known bus name, say
org.freedesktop.Telepathy.Client.Empathy._1._42.Bundle1,
and configure an object at
/org/freedesktop/Telepathy/Client/Empathy/_1/_42/Bundle1
with BypassApproval = TRUE,
whose
For service-activatable handlers, this property should be specified in the handler's .client file as follows:
[org.freedesktop.Telepathy.Client.Handler] BypassApproval=true
So far, all client capabilities are defined by the
The set of additional capabilities supported by this handler. This describes things like support for streamed media codecs and NAT traversal mechanisms: see the Contact Capabilities interface for more details.
For handlers that have a .client file, the
channel dispatcher may discover this property from the
org.freedesktop.Telepathy.Client.Handler.Capabilities
group; for each capability, that group contains a key
whose name is the capability, with value true.
Keys with other values SHOULD NOT appear in this group.
For instance, the .client file for a streamed media
handler that supports ICE-UDP NAT traversal, Speex audio,
and Theora and H264 video might contain this group:
[org.freedesktop.Telepathy.Client.Handler.Capabilities] org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/ice-udp=true org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/audio/speex=true org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/theora=true org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264=true
Like the .client file, if any,
can change (due to upgrades or installation of pluggable codecs),
and the capabilities really supported by the handler might not
exactly match what is cached in the .client file.
The client file is installed statically and is intended to list codecs etc. that the handler guarantees it can support (e.g. by having a hard dependency on them), whereas the running handler process might be able to find additional codecs.
Called by the channel dispatcher when this client should handle these channels, or when this client should present channels that it is already handling to the user (e.g. bring them into the foreground).
Clients are expected to know what channels they're already handling, and which channel object path corresponds to which window or tab. This can easily be done using a hash table keyed by channels' object paths.
This method can raise any D-Bus error. If it does, the handler is assumed to have failed or crashed, and the channel dispatcher MUST recover in an implementation-specific way; it MAY attempt to dispatch the channels to another handler, or close the channels.
If closing the channels, it is RECOMMENDED that the channel
dispatcher attempts to close the channels using
After HandleChannels returns successfully, the client process is considered to be responsible for the channel until it its unique name disappears from the bus.
If a process has multiple Client bus names - some temporary and some long-lived - and drops one of the temporary bus names in order to reduce the set of channels that it will handle, any channels that it is already handling should remain unaffected.
The requests satisfied by these channels.
If the handler implements Requests, this tells it
that these channels match previous
There can be more than one, if they were EnsureChannel requests.
Additional information about these channels. Currently defined keys are:
request-properties - a{oa{sv}}When more keys are defined for this dictionary, all will be optional; handlers MAY safely ignore any entry in this dictionary.
A list of the channels that this process is currently handling.
There is no change notification.
This property exists for state recovery - it makes it possible for channel handling to survive a ChannelDispatcher crash.
If the channel dispatcher is automatically replaced, the replacement can discover all Handlers by looking for the Client well-known bus names, and discover which channels they are currently handling. Once this has been done, all unhandled channels can be re-dispatched, and the only issue visible to the user is that unhandled channels that they have already approved might be sent back to Approvers.
The value of this property SHOULD be the same for all Client instances that share a unique bus name, and SHOULD include all channels that are being handled, even if they were conceptually handled by a different Client instance.
Otherwise, when a process released a temporary Client name, channels that it handled because of that Client name would no longer be state-recoverable.
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.
An array of structs containing:
An array of structs containing:
The array should contain only properties whose values have actually changed.
An array of structs containing:
The array should contain only properties whose flags have actually changed.
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.
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.
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.
A group of related channels, which should all be dispatched to the same handler if possible.
Bundles currently have no functionality of their own, so clients SHOULD NOT examine this interface, but should instead treat the bundle object-path as an opaque identifier. If more functionality is added to bundles in future, this interface will be used for capability discovery.
The lifetime of a bundle is defined by its component channels - as long as one or more channels whose Bundle property is B exist, the bundle B will also exist.
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.
Different IM protocols use a variety of ways to name chat rooms. The
simplest example is perhaps IRC, where chat rooms have short,
persistent, human-readable string names, and are generally global
across the network. Skype chat rooms have persistent string names, so
you can leave and re-join a room, but these names are opaque unique
identifiers. MSN chat rooms are unnamed, and you can only join one by
being invited. And XMPP wins the coveted “most complicated chat rooms”
prize: chat rooms may be hosted by different servers with different DNS
names; normally they have human-readable names, except that all MUCs on
Google Talk's conference server have UUIDs as names, and XEP-0045 §10.1.4
Requesting a Unique Room Name
defines a protocol for
requesting a unique, opaque room name on the server.
This interface intends to support and differentiate these mechanisms
more clearly than the
Room,
"#telepathy",
"#telepathy",
"", indicating
that the room has a human-readable identifier, and is not confined to
a particular server on the network.
Room,
"0xdeadbeef",
"",
"", indicating
that the room has an identifier but no human-readable name.
None,
"",
"", indicating
that the room has neither an identifier (so it cannot be re-joined
later) nor a human-readable name.
Room,
"jdev@conference.jabber.org",
"jdev",
"conference.jabber.org".
Room,
"private-chat-11111x1x-11xx-111x-1111-111x1xx11x11@groupchat.google.com",
"",
"groupchat.google.com", indicating that the room has a
persistent identifier, no human-readable name, and is hosted by a
particular server.
Room,
"lrcgsnthzvwm@conference.jabber.org",
"",
"conference.jabber.org", indicating that the room has a
persistent identifier, no human-readable name, and is hosted by a
particular server.
If the connection supports joining text chat rooms by unique
identifier, like Skype, it should advertise a
( Fixed = { ...ChannelType : ...Text ,
...TargetHandleType : Room,
},
Allowed = [ ...TargetID ,
...TargetHandle ,
]
)
Channel requests must specify either
If, like IRC, the room identifiers are also human-readable, the RCCs should also include RoomID in Allowed_Properties:
( Fixed = { ...ChannelType : ...Text ,
...TargetHandleType : Room,
},
Allowed = [ ...TargetID ,
...TargetHandle ,
...RoomID
]
),
( Fixed = { ...ChannelType : ...Text
},
Allowed = [ ...RoomID ,
]
)
Requests may specify the RoomID in place of
If rooms may be on different servers,
If the protocol supports unnamed rooms,
( Fixed = { ...ChannelType : ...Text ,
...TargetHandleType : None,
...RoomID : "",
},
Allowed = [ ]
)
When explicitly joining a room, the CM cannot know whether the room
ID is unique or not. As a result, if this is the case, adding an
empty string
{ ...ChannelType : ...Text ,
...TargetHandleType : Room,
...TargetID : "qwerasdfzxcv@conference.jabber.org",
...RoomID : ""
}
If
To create a XEP-0045 §10.1.4 uniquely-named room channel on the conference.jabber.org server, then the following channel request should be made:
{ ...ChannelType : ...Text ,
...RoomID : ""
...Server : "conference.jabber.org"
}
If everything is successful, then when the channel request is satisfied, a new channel will appear with the following properties:
{ ...ChannelType : ...Text ,
...TargetHandleType : Room,
...TargetID : "kajsdhkajshdfjkshdfjkhs@conference.jabber.org",
...RoomID : ""
...Server : "conference.jabber.org"
}
The CM will have received the unique room name (kajsdhkajshdfjkshdfjkhs)
and then created a room with such a name on the said server. The empty
The human-readable identifier of a chat room. Note that if
non-empty, this property (and perhaps also
This property cannot change during the lifetime of the channel. It
should appear in the Allowed_Properties of a
For protocols with a concept of chatrooms on multiple servers with different DNS names (like XMPP), the DNS name of the server hosting this channel (for example, "conference.jabber.org" or "groupchat.google.com"). For other protocols, the empty string.
This property cannot change during the lifetime of the channel. It
should appear in the Allowed_Properties of a
The subject on the room such as the topic in an IRC channel, or the room name in XMPP MUCs. In protocols which do not support subjects (like MSN), this property should be ("", "", 0).
This property may change during the lifetime of the channel and MUST not be included in a channel request.
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.
An interface on connections to support protocols which allows users to subscribe to the client types of their contacts.
One can connect to instant messaging networks on a huge variety of devices, from PCs, to phones to consoles. It can be useful for users to know what kind of device a contact is using so that he or she can decide not to send that big file or start a video chat. This interface exposes exactly this information for clients to display.
The client types are represented in strings, using the values documented by the XMPP registrar with some additional types added for other protocols. A contact can set one or more client types so this interface returns a list of strings to denote client types for a contact. The well-known client types to be used are:
If the empty list is given as the client types, this means that
details about the contact's client types are unknown. If there are
multiple resources of a contact online at one point in time, the
client types of the most available resource will be returned. In
other words, the returned client types are those for the resource whose
presence will be retreived using the
For example, if a contact has two resources:
then the methods in this interface will return an array (with
one element: "phone") as the client types because that is the more
available resource. If at some later time the contact's phone's presence
changes to "away", the
The same mapping that would be returned by
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.
This interface extends the core Account interface to provide a way for applications to request minimum presence on the account.
Some applications, for example mail notifiers or address book synchronisation, can make use of account's connection even while the user is nominally offline.
Each client's unique name may set a minimum desired presence on the
account. The combined presence is the most available presence
of the minimum presences set and of
Set a minimum presence needed by the client for this account. Setting (Offline, "offline", "") removes the minimum presence requirement for the client's unique name.
A map of active minimum presence requests.
Client unique name.
Requested minimum presence.
Some applications may want to monitor the currently active minimum presences required. An example is an tool allowing the user to inspect applications maintaining open connections and close those applications.
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.
An interface for channels that can indicate when/if they are connected to some form of service point. For example, when dialing 9-1-1 in the US, a GSM modem/network will recognize that as an emergency call, and inform higher levels of the stack that the call is being handled by an emergency service. In this example, the call is handled by a Public Safety Answering Point (PSAP) which is labeled as "urn:service:sos". Other networks and protocols may handle this differently while still using this interface.
Note that while the majority of examples given in this documentation are for GSM calls, they could just as easily be SIP calls, GSM SMS's, etc.
This property is used to indicate that the channel target is a
well-known service point. Please note that the CM (or lower layers
of the stack or network) may forward the connection to other other
service points, which the CM SHOULD indicate via
This property SHOULD be set for channel requests that are specifically targeting service points.
Emitted when a channel changes the service point that it's connected to. This might be a new call being connected to a service, a call connected to a service being routed to a different service (ie, an emergency call being routed from a generic emergency PSAP to a poison control PSAP), or any number of other things.
Note that this should be emitted as soon as the CM has been notified of the switch, and has updated its internal state. The CM MAY still be in the process of connecting to the new service point.
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.
The user-defined status message, e.g. "Back soon!".
Clients SHOULD set the status message for the local user to the empty string, unless the user has actually provided a specific message (i.e. one that conveys more information than the Status).
User interfaces SHOULD regard an empty status message as unset, and MAY replace it with a localized string corresponding to the Status or Type.
The string identifier of the desired status. Possible status
identifiers are defined in the
Clients MUST NOT set a status whose string value they do not recognise, even if its presence type in Statuses matches what the user requested.
Suppose a protocol has statuses that include 'phone' (of type BUSY) and 'in-a-meeting' (of type BUSY), but there is no generic 'busy' status.
If the user requests "Busy" status from a menu, a client author might be tempted to pick an arbitrary status that has type BUSY. However, on this protocol, neither of the choices would be appropriate, and incorrect information about the user would be conveyed.
Statuses whose
To go offline, call
Request that the presence status and status message are published for
the connection. Changes will be indicated by
This method may be called on a newly-created connection while it is still in the DISCONNECTED state, to request that when the connection connects, it will do so with the selected status.
In DISCONNECTED state the
Presence information in the same format as for the
The definition of the connection presence types Unknown and Offline means that if a connection manager will return Unknown for contacts not on the subscribe list, it MUST delay the reply to this method call until it has found out which contacts are, in fact, on the subscribe list.
A dictionary where the keys are the presence statuses that are available on this connection, and the values are the corresponding presence types.
While the connection is in the DISCONNECTED state, it contains the set of presence statuses allowed to be set before connecting. The connection manager will attempt to set the appropriate status when the connection becomes connected, but cannot necessarily guarantee it. The available statuses cannot change until the connection status changes, so there is no change notification.
While the connection is in the CONNECTED state, this property contains the set of presence statuses which are actually available on this protocol. This set is constant for the remaining lifetime of the connection, so again, there is no change notification.
While the connection is in the CONNECTING state, the value of this property is undefined and SHOULD NOT be used. It can change at any time without notification (in particular, any cached values from when the connection was in the DISCONNECTED or CONNECTING state MUST NOT be assumed to still be correct when the state has become CONNECTED).
This property MUST include the special statuses "unknown" and "error" if and only if the connection manager can emit them as a contact's status.
A type for communication access control. These control
policies are used in
New interfaces should use this type, and NOT
Only allow contacts that are in a certain whitelist.
The associated variant
in au.
Only allow contacts that are in a certain group.
The associated variant in
The access control rule is too complex to be represented in the current Telepathy API. The associated variant is meaningless. Setting this mode is never valid; the connection manager MUST raise an error if this is attempted.
The associated variant in
A type of access control for Rich_Presence_Access_Control. For most types, the exact access control is given by an associated variant.
These are the access control types from XMPP publish/subscribe (XEP-0060).
An access control mode for extended presence items like geolocation. This type isn't actually used by the SimplePresence interface, but it's included here so it can be referenced by rich presence interfaces.
New interfaces should use this type, and NOT
An access control mode for extended presence items like geolocation.
This type isn't actually used by the SimplePresence interface, but
it's included here so it can be referenced by rich presence interfaces
such as
The same struct that would be returned by
This interface is for services which have a concept of presence which can be published for yourself and monitored on your contacts.
Presence on an individual (yourself or one of your contacts) is
modelled as a status and a status message. Valid statuses are defined
per connection, and a list of those that can be set on youself
can be obtained from the
Each status has an arbitrary string identifier which should have an agreed meaning between the connection manager and any client which is expected to make use of it. The following well-known values should be used where possible to allow clients to identify common choices:
| status identifier | Connection_Presence_Type | comments |
|---|---|---|
| available | Connection_Presence_Type_Available | |
| away | Connection_Presence_Type_Away | |
| brb | Connection_Presence_Type_Away | Be Right Back (a more specific form of Away) |
| busy | Connection_Presence_Type_Busy | |
| dnd | Connection_Presence_Type_Busy | Do Not Disturb (a more specific form of Busy) |
| xa | Connection_Presence_Type_Extended_Away | Extended Away |
| hidden | Connection_Presence_Type_Hidden | Also known as "Invisible" or "Appear Offline" |
| offline | Connection_Presence_Type_Offline | |
| unknown | Connection_Presence_Type_Unknown | special, see below |
| error | Connection_Presence_Type_Error | special, see below |
As well as these well-known status identifiers, every status also has
a numerical type value chosen from
These numerical types exist so that even if a client does not understand the string identifier being used, and hence cannot present the presence to the user to set on themselves, it may display an approximation of the presence if it is set on a contact.
As well as the normal status identifiers, there are two special ones that may be present: 'unknown' with type Unknown and 'error' with type Error. 'unknown' indicates that it is impossible to determine the presence of a contact at this time, for example because it's not on the 'subscribe' list and the protocol only allows one to determine the presence of contacts you're subscribed to. 'error' indicates that there was a failure in determining the status of a contact.
If the connection has a 'subscribe' contact list,
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.
An interface for protocols where it might be possible to set the user's presence, and the supported presence types can be predicted before connecting.
This allows UIs to show or hide presence types that aren't always supported, such as "invisible", while not online.
The properties on this interface SHOULD be cached in the
.manager file, in the
[Protocol proto]
group. For each status s in
status-s whose value
is the
Unrecognised tokens MUST be ignored.
For instance, an XMPP connection manager might have this
.manager file:
[Protocol jabber] Interfaces=org.freedesktop.Telepathy.Protocol.Interface.Presence; param-account=s required param-password=s required status-offline=1 status-unknown=7 status-error=8 status-hidden=5 settable message status-xa=4 settable message status-away=3 settable message status-dnd=6 settable message status-available=2 settable message status-chat=2 settable message
which corresponds to these property values (using a Python-like syntax):
Statuses = {
'offline': (OFFLINE, False, False),
'unknown': (UNKNOWN, False, False),
'error': (ERROR, False, False),
'hidden': (HIDDEN, True, True),
'xa': (EXTENDED_AWAY, True, True),
'away': (AWAY, True, True),
'dnd': (BUSY, True, True),
'available': (AVAILABLE, True, True),
'chat': (AVAILABLE, True, True),
}
The statuses that might appear in the
Depending on server capabilities, it is possible that not all of these will actually appear on the Connection.
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.
This interface extends the core Account interface to specify details regarding the storage of this account.
Single-sign-on systems do not generally have directly user-editable properties for Accounts, and require the user to visit a specific UI to alter their account properties. User interfaces should know not to expose these account properties as user-editable, and instead redirect the user to the appropriate interface.
The name of the account storage implementation, which SHOULD start with a reversed domain name in the same way as D-Bus interface names. When this is the empty string the account is internally stored.
This property cannot change once an Account has been created.
Unique identification of the account within the storage backend.
The contents of the variant are defined by the
This property cannot change once an Account has been created.
Different storage systems will have their own way of uniquely identifying an account, typically an integer or a string. Given that all users of this property should have direct knowledge of the backend they should know what types to expect and how to handle it.
Map containing information specific to the storage backend. The keys
and the types of their values are defined by the
As the values in this map may change at any time (due to an external application manipulating the storage provider directly), this property should not be cached; it should instead be retrieved each time it is needed.
This can be used to provide additional hints to user interfaces
aware of a specific storage provider, without requiring those user
interfaces to use the
Bitfield which defines what restrictions this Storage method has.
This property cannot change once an Account has been created.
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.
An interface for connections that have any concept of a list of known contacts (roster, buddy list, friends list etc.)
On many protocols, there's a server-side roster (as in XMPP), or a set of server-side lists that can be combined to form a roster (as in MSN).
In some protocols (like link-local XMPP), while there might not be any server or roster, it's possible to list "nearby" contacts.
In Telepathy 0.20 and older, we represented contact lists as a
collection of
The list of contacts is not exposed as a D-Bus property; it can be
fetched using
In some protocols, such as XMPP, the contact list may not be
available immediately. The
The connection has tried and failed to retrieve the contact
list. If
The connection manager SHOULD try again to obtain the contact
list, if appropriate for the protocol. If it succeeds later,
the
Return some contact attributes for a list of contacts associated with the user. This list MUST include at least:
but MAY contain other contacts.
For instance, on XMPP, all contacts on the roster would appear here even if they have subscription="none", unless there's reason to believe the user does not want to see them (such as having been blocked).
This list does not need to contain every visible contact: for
instance, contacts seen in XMPP or IRC chatrooms SHOULD NOT appear
here. Blocked contacts SHOULD NOT appear here, unless they still
have a non-No
It's reasonable to assume that blocked contacts should not be visible to the user unless they specifically go looking for them, at least in protocols like XMPP where blocking a contact suppresses presence.
A list of strings indicating which D-Bus interfaces the calling
process is interested in. Equivalent to the corresponding argument
to
Whether to hold the handles on behalf of the calling process.
Equivalent to the corresponding argument to
A dictionary mapping the contact handles to contact attributes,
equivalent to the result of
The
An enumeration indicating whether presence subscription is denied,
denied but pending permission, or allowed. The exact semantics
vary according to where this type is used: see the
If this attribute on a contact is Yes, this connection can expect to receive their presence, along with any other information that has the same access control.
This is subscription="from" or subscription="both" in XMPP, the "forward list" on MSN, or the contact being "added to the local user's buddy list" in ICQ, for example.
If this attribute is not Yes, the local user cannot generally
expect to receive presence from this contact. Their presence status
as returned by
If this attribute is Ask, this indicates that the local user has asked to receive the contact's presence at some time. It is implementation-dependent whether contacts' subscribe attributes can remain set to Ask, or are reset to No, when the connection disconnects.
Some protocols store the fact that we wishes to see a contact's presence; on these protocols, this attribute can remain Ask indefinitely. On other protocols, only contacts who have been asked during the current session will ever have Ask status.
If this attribute is Removed_Remotely, this indicates that the local user has asked to receive the contact's presence at some time, but the remote contact has rejected that request, and a local user interface has not yet acknowledged this. It is implementation-dependent whether contacts' subscribe attributes can remain set to Removed_Remotely, or are reset to No, when the connection disconnects.
After notifying the user, user interfaces MAY acknowledge a change
to subscribe=Removed_Remotely by calling either
This attribute's value will be Unknown or omitted until the
If this attribute on a contact is Yes, the local user's presence is published to that contact, along with any other information that shares an access-control mechanism with presence (depending on protocol, server configuration and/or user configuration, this may include avatars, "rich presence" such as location, etc.).
This is subscription="to" or subscription="both" in XMPP, the "reverse list" on MSN, or the state of "being added to the contact's buddy list" in ICQ, for example.
If this attribute is not Yes, the local user's presence is not published to that contact; however, if it is Ask, the contact has requested that the local user's presence is made available to them.
It is implementation-dependent whether contacts' publish attributes can remain set to Ask, or are reset to No, when the connection disconnects.
Some protocols store the fact that a contact wishes to see our presence; on these protocols, this attribute can remain Ask indefinitely. On other protocols, only contacts who have asked during the current session will ever have Ask status.
If this attribute is Removed_Remotely, this indicates that the
remote contact has asked to receive the user's presence at some time,
but has then cancelled that request before a response was given by
the local user. User interfaces MAY reset publish from
Removed_Remotely to No, by calling either
If multiple factors affect whether a contact can receive the local user's presence, this attribute SHOULD reflect the overall result. For instance, an XMPP contact with subscription="to" or subscription="both", but who has been blocked via XEP-0016 Privacy Lists, SHOULD have publish=No.
This attribute's value will be Unknown or omitted until the
If the
If the contact asking to receive our presence is also using
Telepathy, this is the message they supplied as the Message
argument to
Otherwise, this SHOULD be omitted.
This attribute will also be omitted until the
If true, presence subscriptions (in both directions) on this connection are stored by the server or other infrastructure.
XMPP, MSN, ICQ, etc. all behave like this.
If false, presence subscriptions on this connection are not stored.
In SIMPLE (SIP), clients are expected to keep a record of subscriptions, as described below. In link-local XMPP, subscriptions are implicit (everyone on the local network receives presence from everyone else) so nothing is ever stored.
If
In SIMPLE (SIP), ContactListPersists is false, but CanChangeContactList is true. Presence will not be received unless clients renew any subscriptions they have for each connection, in the way described. There is no server-side storage, so clients have no alternative but to maintain independent contact lists.
In protocols like XMPP and MSN, it may be useful for clients to queue up subscription requests or removals made while offline and process them next time the connection is online. However, clients should only replay the changes, rather than resetting the contact list to match a stored copy, to avoid overwriting changes that were made on the server.
Clients that replay requests like this SHOULD do so by calling AuthorizePublication to pre-approve publication of presence to the appropriate contacts, followed by RequestSubscription to request the appropriate contacts' presences.
This property cannot change after the connection has moved to the Connected state. Until then, its value is undefined, and it may change at any time, without notification.
Values of this enumeration indicate the extent to which metadata such as aliases and group memberships can be stored for the contacts on a particular connection.
On some protocols, certain metadata (for instance, contact aliases) can only be stored for contacts on the contact list, or contacts with a particular contact list state.
To make it easier to deal with such protocols, if clients set metadata on a contact who is not in the required state, the Connection MUST cache the metadata for the duration of the session. If clients request the attributes of that contact after the appropriate "set" method has returned successfully, the Connection MUST return the new (cached) value.
If the contact is later placed in the required state to store metadata (for instance, if subscription to the contact's presence is requested, on a protocol like MSN where the alias has storage type Subscribed_Or_Pending), the connection MUST store the cached metadata at that time.
If the Connection didn't cache changes in this way, a client intending to change the alias on MSN would have to wait until the server acknowledged the subscription request; in the meantime, other clients would still display the old alias.
The only exception to that general rule is that if the Connection cannot store particular metadata at all (i.e. the storage type is None), it MUST reject attempts to set it.
If the implementation knows that metadata can't be stored at all, it's useful to report that, which can be done synchronously. In general, user interfaces should detect storage type None and not display editing controls at all.
This connection cannot store this type of metadata at all, and attempting to do so will fail with NotImplemented.
Link-local XMPP can't store aliases or group memberships at all, and subscription and presence states are implicit (all contacts on the local network have subscribe = publish = Yes and no other contacts exist).
As of April 2010, the XMPP server for Facebook Chat provides a read-only view of the user's Facebook contacts, so it could also usefully have this storage type.
This type of metadata can only be stored permanently for contacts whose subscribe attribute is Ask or Yes.
Contact aliases and groups on MSN have this behaviour.
This type of metadata can only be stored permanently for contacts whose subscribe attribute is Yes.
No service with this behaviour is currently known, but it's a stricter form of Subscribed_Or_Pending.
The user can set this metadata for any valid contact identifier, whether or not they have any presence subscription relationship to it, and it will be stored on their contact list.
Contact aliases and groups on XMPP have this behaviour; it is possible to put a contact in a group, or assign an alias to them, without requesting that presence be shared.
Emitted when the contact list becomes available, when contacts'
basic stored properties change, when new contacts are added to the
list that would be returned by
This provides change notification for that list, and for
contacts'
Connection managers SHOULD also emit this signal when a contact
requests that the user's presence is published to them, even if
that contact's
If the same contact sends 10 identical requests, 10 identical signals should be emitted.
If true, presence subscription and publication can be changed
using the
If false, all of those methods will always fail; they SHOULD raise the error org.freedesktop.Telepathy.Error.NotImplemented.
In XEP-0174 "Serverless Messaging" (link-local XMPP), presence is implicitly published to everyone in the local subnet, so the user cannot control their presence publication.
This property cannot change after the connection has moved to the Connected state. Until then, its value is undefined, and it may change at any time, without notification.
Request that the given contacts allow the local user to subscribe to their presence, i.e. that their subscribe attribute becomes Yes.
Before calling this method on a connection where User_Set flag,
user interfaces SHOULD obtain, from the user, an alias to
identify the contact in future, and store it using
This is a generalization of XEP-0165 "Best Practices to Discourage JID Mimicking") to protocols other than XMPP. A reasonable user interface for this, as used in many XMPP clients, is to have a text entry for the alias adjacent to the text entry for the identifier to add.
For contacts with subscribe=Yes, this method has no effect. It MUST return successfully if all contacts are in this state.
For contacts with subscribe=Ask, this method SHOULD send a new request, with the given message, if allowed by the underlying protocol.
For contacts with subscribe=No or subscribe=Rejected, this method SHOULD request that the contact allows the local user to subscribe to their presence; in general, this will change their publish attribute to Ask (although it could change directly to Yes in some situations).
Any state changes that immediately result from this request MUST
be signalled via
This makes it easy for user interfaces to see what practical effect this method had.
If the remote contact accepts the request, their subscribe attribute will later change from Ask to Yes.
If the remote contact explicitly rejects the request (in protocols that allow this), their subscribe attribute will later change from Ask to Rejected.
If the subscription request is cancelled by the local user, the contact's subscribe attribute will change from Ask to No.
This method SHOULD NOT be called until the
One or more contacts to whom requests are to be sent.
An optional plain-text message from the user, to send to those
contacts with the subscription request. The
Clients SHOULD NOT send a non-empty message without first giving the user an opportunity to edit it.
These messages are typically presented to the remote contact as if the user had typed them, so as a minimum, the user should be allowed to see what the UI will be saying on their behalf.
Connections where this message is not useful MUST still allow it to be non-empty.
If true, the Message parameter to
This matches user expectations in XMPP and ICQ, for instance.
If false, the parameter is ignored; user interfaces SHOULD avoid prompting the user, and SHOULD pass an empty string to RequestSubscription.
FIXME: is there any such protocol?
For each of the given contacts, request that the local user's presence is sent to that contact, i.e. that their publish attribute becomes Yes.
For contacts with publish=Yes, this method has no effect; it MUST return successfully if all contacts given have this state.
For contacts with publish=Ask, this method accepts the contact's request to see the local user's presence, changing their publish attribute from Ask to Yes.
For contacts with publish=No, if the protocol allows it, this method allows the contacts to see the local user's presence even though they have not requested it, changing their publish attribute from No to Yes. Otherwise, it merely records the fact that presence publication to those contacts is allowed; if any of those contacts ask to receive the local user's presence later in the lifetime of the connection, the connection SHOULD immediately allow them to do so, changing their publish attribute directly from No to Yes.
This makes it easy to implement the common UI policy that if the user attempts to subscribe to a contact's presence, requests for reciprocal subscription are automatically approved.
Any state changes that immediately result from this request MUST
be signalled via
This makes it easy for user interfaces to see what practical effect this method had.
This method SHOULD NOT be called until the
One or more contacts to authorize.
Remove the given contacts from the contact list entirely. It is protocol-dependent whether this works, and under which circumstances.
If possible, this method SHOULD set the contacts' subscribe and
publish attributes to No, remove any stored aliases for those
contacts, and remove the contacts from the result of
This method SHOULD succeed even if it was not possible to carry out the request entirely or for all contacts (for instance, if there is an outstanding request to subscribe to the contact's presence, and it's not possible to cancel such requests). However, all signals that immediately result from this method call MUST be emitted before it returns, so that clients can interpret the result.
User interfaces removing a contact from the contact list are unlikely to want spurious failure notifications resulting from limitations of a particular protocol. However, emitting the signals first means that if a client does want to check exactly what happened, it can wait for the method to return (while applying change-notification signals to its local cache of the contact list's state), then consult its local cache of the contact list's state to see whether the contact is still there.
This method SHOULD NOT be called until the
One or more contacts to remove.
Attempt to set the given contacts' subscribe attribute to No, i.e. stop receiving their presence.
For contacts with subscribe=Ask, this attempts to cancel an earlier request to subscribe to the contact's presence; for contacts with subscribe=Yes, this attempts to unsubscribe from the contact's presence.
As with
This method SHOULD NOT be called until the
One or more contacts to remove.
Attempt to set the given contacts' publish attribute to No, i.e. stop sending presence to them.
For contacts with publish=Ask, this method explicitly rejects the contact's request to subscribe to the user's presence; for contacts with publish=Yes, this method attempts to prevent the user's presence from being received by the contact.
As with
This method SHOULD NOT be called until the
One or more contacts to remove.
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.
In many real-time communication services the user can pay for certain services, typically calls to the PSTN, in advance. In (at least) Skype, it's possible to query the current balance in a machine-readable way.
An amount of money in a specified currency. For example, 3.21 British pounds would conventionally be represented by (Amount = 321, Scale = 2, Currency = "GBP"), but could be represented by (Amount = 3210, Scale = 3, Currency = "GBP") in a service that records balance in units of 0.001 pounds.
As a special case, if Amount = 0, Scale = 2**32 - 1 (i.e. the largest possible 32-bit unsigned integer) and Currency = "", this indicates an unknown amount.
The amount, expressed as a fixed-point number with decimal scale defined by the Scale field; for instance, an Amount value of 1234 with Scale of 2 represents 12.34 in the currency unit given by the Currency field.
The decimal scale for the fixed point value of the Amount field, defining the number of rightmost decimal digits from the integer value which form the fractional part of the resulting currency value.
As well as defining the interpretation of Amount, user interfaces may use this value to determine the precision with which to display the amount.
The user's balance on the account corresponding to this
On initial connection, this property may have an unknown value, represented by Amount = 0, Scale = 2**32 - 1 (the largest possible 32-bit unsigned integer) and Currency = "".
Emitted when the user's balance has changed.
The new value of the
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.
This connection interface is for protocols that are capable of signaling to remote contacts that incoming communication channels should be instead sent to a separate contact. This might apply to things such as call forwarding, for example.
In some cases, a CM may register forwarding rules with an external service; in those cases, it will never see the incoming channel, and the forwarding will happen automatically.
In other cases, the CM will handle the forwarding itself. When an
incoming channel is detected, the status of the local user will
determine whether or not a forwarding rule is matched. For some
rules, this MAY happen immediately (ie, if the user is Busy); for
others, there MAY be a timeout (in seconds) that must expire
before the forwarding rule is matched (the timeout is specified
by the first element in the
Once a forwarding rule is matched and any necessary timeouts have expired, the CM can forward the incoming channel to the specified handle. If for whatever reason the remote handle does not accept the channel AND the CM supports multiple forwarding entries AND any necessary timeouts have expired (specified by the next entry in the list), the CM can forward the incoming channel to the next handle in the entry list. This continues until the list is exhausted, or the incoming channel is accepted.
Note that the rule matches are only for the first entry in the in the forwarding rule list. Once the incoming channel has been forwarded, the next entry in the list (assuming one exists and the contact that the channel has been forwarded to does not respond after any necessary timeouts) is used regardless of the status of the forwarded channel. The initial match rule might have been Busy, whereas the contact that the channel has been forwarded to might be offline. Even in this case, the Busy list is still traversed until the channel is handled (or there are no more forwarding entries in the list).
For example, assuming the following dict for Forwarding_Rules:
ForwardingRules = {
Busy: ( initial-timeout: 30, [
(handle: 3, timeout: 15),
(handle: 5, timeout: 20)
]),
NoReply: ( initial-timeout: 15, [
(handle: 5, timeout: 30),
(handle: 3, timeout: 20)
])
}
We can imagine a scenario where an incoming channel is detected, the media stream is available (ie, not Busy), and the local user is online. While the CM is waiting for the local user to accept the channel, it looks at NoReply's first timeout value. After 15s if the local user hasn't accepted, the CM forwards the channel to Handle #5. The CM then waits 30s for Handle #5 to accept the channel. If after 30s it does not, the CM forwards the incoming channel to Handle #3, which will have 20s to accept the channel.
When an unanswered No_Answer or
Busy, as appropriate. For Forwarded
should be used.
The incoming channel should be forwarded if a busy signal is
detected. What defines "Busy" is CM-specific (perhaps a single
resource is already in use, or a user's status is set to Busy
If initial timeout is specified for Busy condition and call waiting is not supported by the service, the timeout will be ignored.
A forwarding rule entry. These MAY be chained together for CMs that support chaining of forwards (in other words, a forwarding rule may have multiple entries; if the contact in the first entry doesn't respond, the incoming channel might be forwarded to the contact in the second entry).
For CMs and protocols that don't support chaining of entries, only the first entry would be used.
The length of time (in seconds) to wait the contact to respond to the forwarded channel. This MAY be ignored by the CM if it isn't supported by the underlying network/protocol for the specific status of the remote contact (for example, a GSM call that is forwarded may return Not_Reachable immediately without waiting for the timeout value to expire).
A value of 0 means the condition can match immediately. A value of MAX_UINT32 means that the CM's default should be used.
A map of forwarding conditions supported on this connection to
maximum number of
When forwarding is done by the provider, different providers might support different chain sizes, or provider and local implementation chain sizes might differ.
The current forwarding rules that are enabled for this connection.
Forwarding rules each contain an array of type
Emitted when the
By the time this is emitted, the property MUST have been updated with the new rules being active. If any protocol/network requests must be made, they should be completed before the signal is emitted.
The forwarding rule to override. Note that this SHOULD not affect other rules; setting a rule that overrides others (such as Forwarding_Rule_Unconditional) will not modify other rules. This means that when a client sets Forwarding_Rule_Busy and then temporarily sets Forwarding_Rule_Unconditional, the Forwarding_Rule_Busy rule will retain settings after Forwarding_Rule_Unconditional, has been unset.
If the CM has no choice but to adjust multiple rules after a call
to this function (ie, due to the network or protocol forcing such
behavior), the CM MUST emit multiple
Each forwarding condition will occur no more than once in
the rule array. Setting a rule will overwrite the old rule
with the same
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.
Telepathy clients use connection managers, the channel dispatcher and optionally the account manager to provide useful functionality.
User interface processes are the obvious example of Telepathy clients, but they can provide other functionality, such as address-book synchronization.
Every running or activatable process with a well-known name of the form org.freedesktop.Telepathy.Client.clientname should be probed by the channel dispatcher to discover its capabilities. Each client is either an observer, an approver, a channel handler, or some combination of these.
Activatable services (those with a D-Bus .service
file) must be supported so that we can run clients
in response to channel creation.
Non-activatable services (those that do not register a D-Bus
.service file for their well-known name, but do
request it at runtime) must be supported so that we can have
programs that process channels, but only if they are already
running - for instance, a full-screen media centre
application might do this.
The client name, clientname, MUST be a non-empty string of ASCII digits, letters, dots and/or underscores, starting with a letter, and without sets of two consecutive dots or a dot followed by a digit. For non-activatable services, it MAY contain a part that is generated per instance at runtime.
If each of a client Foo's instances should be able to manipulate
channels separately, the instance with unique name
:1.25 might request a well-known name like
org.freedesktop.Telepathy.Client.Foo._1._25.
(Note that well-known bus-name components may not start with a digit, so o.f.T.Client.Foo.1.25 would not be acceptable.)
Each Client MUST export an object whose object path may be determined by replacing '.' with '/' in the well-known name and prepending '/'. This object represents its API as a Telepathy client; the channel dispatcher will call its methods and read its properties when appropriate.
As an optimization, activatable clients SHOULD install a file
$XDG_DATA_DIRS/telepathy/clients/clientname.client
containing a cached version of its immutable properties,
so that for most clients, the channel dispatcher can
just read a file to discover capabilities, instead of
having to service-activate the client immediately in order to fetch
its read-only properties. However, the D-Bus API is canonical, and
the channel dispatcher MUST support clients without such a file.
Non-activatable clients MAY install a .client file,
but there's not much point in them doing so.
The .client files MUST contain UTF-8 text with the same syntax
as
Desktop
Entry files (although the allowed groups, keys and values differ).
Every .client file MUST contain a group whose name is
the name of this interface.
The groups, keys and values in the .client file are
defined by individual interfaces. Each interface that can usefully
cache information in the .client file SHOULD correspond
to a group with the same name.
A list of the extra interfaces provided by this client.
This SHOULD include at least one of
In the .client file, this is represented by key
"Interfaces" in the group named after this interface.
The value of the key is a list of interface names each followed by
a semicolon (so it always ends with a semicolon unless it is empty),
i.e. a key of type "strings" as described in the Desktop Entry
specification.
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.
For protocols with a concept of chatrooms on multiple servers with different DNS names (like XMPP), the DNS name of the server whose rooms are listed by this channel, e.g. "conference.jabber.org". Otherwise, the empty string.
This property cannot change during the lifetime of the channel.
Emitted when information about rooms on the server becomes available.
The array contains the room handle (as can be passed to the
A channel type for listing named channels available on the server. Once the
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
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.
This interface extends the Messages interface to support capability discovery, so clients can decide what subset of HTML is supported.
(However, the capability discovery mechanism has not been written yet, so this interface MUST NOT be used. It exists only to indicate what direction we intend to go in.)
XMPP supports all of XHTML-IM, and SIP (at least theoretically) supports all of XHTML. However, many protocols are more limited - for instance, in MSN you can only set font properties for a whole message at a time. We should not mislead users into thinking they can send MSN messages where individual words are emphasized.
If this interface is present, clients MAY send XHTML formatted text in message parts with type "text/html", and SHOULD interpret "text/html" message parts received in reply.
Client authors SHOULD pay careful attention to the security considerations in XEP-0071, "XHTML-IM", to avoid exposing client users to security risks. Clients MUST NOT assume that connection managers will filter messages to remove unsafe HTML.
Connection managers are the components in Telepathy that are most likely to be exploitable by a remote attacker to run malicious code (since they are network-facing), so any filtering that the CM does might be subverted.
To avoid misleading users, clients SHOULD only present UI for the subset of HTML that is indicated to be supported by this interface. It follows that clients SHOULD NOT send unsupported markup to the connection manager. However, even if the connection manager cannot send arbitrary XHTML, it MUST cope gracefully with being given arbitrary XHTML by a client.
Connection managers should be lenient in what they receive.
Clients MUST NOT send HTML that is not well-formed XML, but connection managers MAY signal HTML that is malformed or invalid. Clients SHOULD attempt to parse messages as XHTML, but fall back to using a permissive "tag-soup" HTML parser if that fails. (FIXME: or should the presence of this interface imply that the CM fixes up "text/html" to be XHTML? In practice that would result in all the CMs having to link against libxml2 or something... the rationale above no longer applies here, since dropping a malformed message is "safe")
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.
An interface for connections in which contacts can be placed in user-defined groups.
The most basic functionality of this interface is to list and monitor
a contact's set of groups. To do this, use the
Looking at contacts' lists of groups is sufficient to present a
user interface resembling XMPP's data model, in which groups behave
like tags applied to contacts, and so an empty group cannot exist
or is not interesting. However, some protocols model groups as
objects in their own right. User interfaces may either track
the set of groups via the
Similarly, in some protocols it is possible to rename a group as
a single atomic operation. Simpler user interfaces will
see the new name being created, the old name being removed, and the
members moving to the new name, via the signals described above.
More advanced user interfaces can optionally distinguish between an
atomic rename and a create/remove pair, and display renamed groups
differently, by monitoring the
This interface also provides various methods to manipulate
user-defined groups, which can be expected to work if
Depending on the protocol, some methods might be implemented by
more than one protocol operation; for instance, in a
"contact-centric" protocol like XMPP,
True if each contact can be in at most one group; false if each contact can be in many groups.
This property cannot change after the connection has moved to the Connected state. Until then, its value is undefined, and it may change at any time, without notification.
Indicates the extent to which contacts' groups can be set and stored.
This property cannot change after the connection has moved to the Connected state. Until then, its value is undefined, and it may change at any time, without notification.
The names of groups of which a contact is a member.
Change notification is via
The names of all groups that currently exist. This may be a
larger set than the union of all contacts' groups
contact attributes, if the connection allows groups to be
empty.
Change notification is via
This property's value is not meaningful until the
Emitted when a group is renamed, in protocols where this can be distinguished from group creation, removal and membership changes.
Immediately after this signal is emitted,
Emitting these extra signals, in this order, means that clients that are interested in the set of groups that exist (but treat a rename and a create/remove pair identically) can ignore the GroupRenamed signal entirely.
If the group was not empty, immediately after those signals are
emitted,
On connection managers where groups behave like tags, renaming a
group MAY be signalled as a set of
On protocols like XMPP, another resource "renaming a group" is indistinguishable from changing contacts' groups individually.
Emitted when one or more groups are removed. If they had members at
the time that they were removed, then immediately after this signal
is emitted,
Emitting the signals in this order allows for two modes of
operation. A client interested only in a contact's set of groups
can ignore
Add the given contact to the given groups (creating new groups if necessary), and remove them from all other groups.
This is the easiest and most correct way to implement user interfaces that display a single contact with a list of groups, resulting in a user expectation that when they apply the changes, the contact's set of groups will become exactly what was displayed.
If the user is removed from a group of which they were the only member, the group MAY be removed automatically.
In protocols like XMPP where groups behave like tags, a group with no members has no protocol representation.
Any
This method SHOULD NOT be called until the
Add the given members to the given group (creating it if necessary), and remove all other members.
This is the easiest and most correct way to implement user interfaces that display a single group with a list of contacts, resulting in a user expectation that when they apply the changes, the groups's set of members will become exactly what was displayed.
If
If the user is removed from a group of which they were the only member, the group MAY be removed automatically.
Any
This method SHOULD NOT be called until the
Add the given members to the given group, creating it if necessary.
If
This is good for user interfaces in which you can edit groups via drag-and-drop.
Any
This method SHOULD NOT be called until the
Remove the given members from the given group.
This is good for user interfaces in which you can edit groups via drag-and-drop.
Any
This method SHOULD NOT be called until the
Remove all members from the given group, then remove the group itself. If the group already does not exist, this method SHOULD return successfully.
Any
This method SHOULD NOT be called until the
Rename the given group.
On protocols where groups behave like tags, this is an API short-cut for adding all of the group's members to a group with the new name, then removing the old group.
Otherwise, clients can't perform this operation atomically, even if the connection could.
Any
This method SHOULD NOT be called until the
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.
Request that a message be sent on this channel. When the message has
been submitted for delivery, this method will return and the
This method SHOULD return before the Sent signal is emitted.
When a Text channel implements the
Signals that an outgoing message has failed to send. The error will be one of the values from ChannelTextSendError.
This signal should only be emitted for messages for which
Signals that a message has been submitted for sending.
The incoming message contained non-text content which cannot be
represented by this interface, but has been signalled
in the
Connection managers SHOULD only set this flag if the non-text content appears to be relatively significant (exactly how significant is up to the implementor). The intention is that if this flag is set, clients using this interface SHOULD inform the user that part of the message was not understood.
The incoming message was part of a replay of message history.
In XMPP multi-user chat, a few past messages are replayed when you join a chatroom. A sufficiently capable IRC connection manager could also set this flag on historical messages when connected to a proxy like bip or irssi-proxy. The existence of this flag allows loggers and UIs to use better heuristics when eliminating duplicates (a simple implementation made possible by this flag would be to avoid logging scrollback at all).
The incoming message has been seen in a previous channel during
the lifetime of the
This means that a logger (which should already have seen the message in the previous channel) is able to recognise and ignore these replayed messages.
A channel type for sending and receiving messages in plain text, with no formatting. In future specifications, channels for sending and receiving messages that can be reduced to plain text (i.e. formatted text) should also have this type.
When a message is received, an identifier is assigned and a
Each message has an associated 'type' value, which should be one
of the values allowed by
Each message also has a flags value, which is a bitwise OR of the
flags given in
Sending messages can be requested using the
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
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
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
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
If a channel of type Text is closed while it has pending messages,
the connection manager MUST allow this, but SHOULD open a new,
identical channel to deliver those messages, signalling it as a new
channel with the
If messages were sent on the old channel but the
In effect, this turns this situation, in which a client is likely to lose messages:
into something nearly equivalent to this situation, which is fine:
suppress_handler must be set to FALSE so the replacement channel will be handled by something.
As a result, Text channels SHOULD implement
This "respawning" behaviour becomes problematic if there is no suitable handler for Text channels, or if a particular message repeatedly crashes the Text channel handler; a channel dispatcher can't just Close() the channel in these situations, because it will come back.
In these situations, the channel dispatcher needs a last-resort way to destroy the channel and stop it respawning. It could either acknowledge the messages itself, or use the Destroyable interface; the Destroyable interface has the advantage that it's not channel-type-dependent, so the channel dispatcher only has to understand one extra interface, however many channel types eventually need a distinction between Close and Destroy.
This interface contains SMS-specific properties for text channels. This currently only includes whether the SMSes received on the channel should be displayed immediately to the user, without prompting.
A handler for class 0 SMSes should advertise the following filter:
{ ...ChannelType :
...Text ,
...TargetHandleType :
Handle_Type _Contact,
...SMS.Flash :
True,
}It should also set its True, so that it is invoked immediately for new
channels.
If True, then this channel is exclusively for
receiving class 0 SMSes (and no SMSes can be sent using False, no incoming class 0 SMSes
will appear on this channel.
This property is immutable (cannot change), and therefore SHOULD
appear wherever immutable properties are reported, e.g.
Class 0 SMSes should be displayed immediately to the user, and need not be saved to the device memory unless the user explicitly chooses to do so. This is unlike “normal”, class 1 SMSes, which must be stored, but need not be shown immediately in their entirity to the user.
Separating class 0 SMSes into their own channel with this
immutable property allows them to be dispatched to a different
Currently, no mechanism is defined for sending class 0
SMSes. It seems reasonable to support specifying the class of an
outgoing SMS in its header True are read-only.
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.
An object representing a protocol for which this
Each Protocol object has the same well-known bus name as its parent
ConnectionManager. Its object path is formed by taking the
ConnectionManager's object path and appending '/', followed by the
This is the same as the representation of protocol names
in Account object paths, and in Connection object paths and bus
names. For instance, telepathy-gabble and telepathy-salut would
implement objects at
/org/freedesktop/Telepathy/ConnectionManager/gabble/jabber
and
/org/freedesktop/Telepathy/ConnectionManager/salut/local_xmpp,
respectively.
If the ConnectionManager has a .manager file, each Protocol's immutable properties must be represented in that file; the representation is described as part of the documentation for each property. For instance, a very simple ConnectionManager with one Protocol might be represented like this:
[ConnectionManager] Interfaces= [Protocol example] Interfaces= ConnectionInterfaces=org.freedesktop.Telepathy.Connection.Interface.Requests; param-account=s required param-password=s required secret RequestableChannelClasses=text; VCardField=x-example EnglishName=Example Icon=im-example [text] org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text org.freedesktop.Telepathy.Channel.TargetHandleType u=1 allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID;
A list of interfaces supported by this Protocol object.
This property is immutable, and should not be confused with
Connection managers with a .manager file
(as described as part of the
.manager
file, using the key Interfaces. The corresponding value
is a list of D-Bus interface names, each followed by a semicolon.
The parameters which must or may be provided to the
Connection managers with a .manager file
(as described as part of the
.manager
file via keys of the form param-p and
default-p, as documented in the
A list of interface names which might be in the
This property is immutable, and should not be confused with
Connection managers with a .manager file
MUST cache this property in the protocol's section of the
.manager file, using the key
ConnectionInterfaces. The corresponding value
is a list of D-Bus interface names, each followed by a semicolon.
A list of channel classes which might be requestable from a
Whether a Connection will have all, some or none of these requestable channel classes depends on server capabilities; similarly, individual contacts are not guaranteed to support all of these channel classes.
This property is immutable.
Connection managers with a .manager file
MUST cache this property in the protocol's section of the
.manager file, using the key
RequestableChannelClasses. The corresponding value
is a list of opaque strings, each followed by a semicolon; each
of those strings is the name of a group in the .manager
file which represents a channel class.
The names of the groups representing channel classes are not significant, and MUST NOT be interpreted. When writing .manager files, authors MAY choose mnemonic group names, generate group names mechanically (e.g. with an incrementing integer), or use some combination of these.
Each group representing a channel class has a key
allowed which is a list of D-Bus property names
representing allowed parameters. Any other keys that do not contain
a space MUST be ignored. Any key containing a space represents
a fixed property; the key has the form
"propertyname type", and the value
is encoded in the same way as for the default-p
keys described in the
Connection managers that have channel classes whose fixed
properties are not representable in this form SHOULD NOT have
.manager files.
For instance, this .manager file could represent
a connection manager that supports 1-1 Text messages and
StreamedMedia audio calls:
[Protocol jabber] param-account=s required param-password=s required RequestableChannelClasses=rcc0;rcc1; [rcc0] org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text org.freedesktop.Telepathy.Channel.TargetHandleType u=1 allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID; [rcc1] org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.StreamedMedia org.freedesktop.Telepathy.Channel.TargetHandleType u=1 allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID;org.freedesktop.Telepathy.Channel.Type.StreamedMedia.InitialAudio;
The name of the most common vCard field used for this protocol's contact identifiers, normalized to lower case, or the empty string if there is no such field.
For example, this would be x-jabber for
Jabber/XMPP (including Google Talk), or tel for
the PSTN.
A more exhaustive list of addressable vCard fields can be found in
the Protocol's Addressing interface's
It is not necessarily valid to interpret contacts' identifiers
as values of this vCard field. For instance, telepathy-sofiasip
supports contacts whose identifiers are of the form
sip:jenny@example.com or tel:8675309, which would not normally
both be represented by any single vCard field. Arbitrary
handles/identifiers as vCard fields are represented
through the Connection's
This is taken from Mission Control profiles as used on Maemo 5. One valid use of this field is to answer the question: given a contact's vCard containing an X-JABBER field, how can you communicate with the contact? By iterating through protocols looking for an x-jabber VCardField, one can build up a list of protocols that handle x-jabber, then offer the user a list of accounts for those protocols and/or the option to create a new account for one of those protocols.
Connection managers with a .manager file
MUST cache this property in the protocol's section of the
.manager file if it is non-empty, using the key
VCardField. The corresponding value
is a string, following the syntax of the "localestring" type from
the Desktop Entry Specification.
The name of the protocol in a form suitable for display to users, such as "AIM" or "Yahoo!", or the empty string if none is available.
This is effectively in the C locale (international English);
user interfaces requiring a localized protocol name SHOULD look
one up in their own message catalog based on either the Telepathy
Many protocols are named after a company or product which isn't translated in non-English locales. This also provides a fallback display name, for UIs with no prior knowledge of a particular protocol.
If this property's value is empty, clients MAY fall back to using
the Telepathy
Connection managers with a .manager file
MUST cache this property in the protocol's section of the
.manager file if it is non-empty, using the key
EnglishName. The corresponding value
is a string, following the syntax of the "localestring" type from
the Desktop Entry Specification.
The name of an icon in the system's icon theme, such as "im-msn", or the empty string.
This can be used as a default if the
If this property's value is empty, clients MAY fall back to
generating a name based on the
Connection managers with a .manager file
MUST cache this property in the protocol's section of the
.manager file if it is non-empty, using the key
Icon. The corresponding value
is a string, following the syntax of the "localestring" type from
the Desktop Entry Specification.
Return a string which uniquely identifies the account to which the given parameters would connect.
For many protocols, this would return the well-known 'account' parameter. However, for IRC the returned string would be composed from the 'account' (i.e. nickname) and 'server' parameters. AccountManager implementations can use this to form the account-specific part of an Account's object path.
An opaque string suitable for use as the account-specific part of
an
For a pathological case, consider a user signing in as 'me@example.com' with 'server' set to either jabber1.example.com or jabber2.example.com. Both of these should result in me@example.com being returned from this method, even if the user can actually be signed in to those two servers simultaneously.
Attempt to normalize the given contact ID. Where possible, this
SHOULD return the same thing that would be returned by
InspectHandles(RequestHandles(CONTACT, [Contact_ID])) on a connected
If full normalization requires network activity or is otherwise
impossible to do without a
One common example of a best-effort offline normalization differing from the ideal normalization is XMPP.
On XMPP, contacts' JIDs should normally have the resource removed during normalization, but for contacts in a MUC (chatroom), the resource is an integral part of the JID - so the contact JID alice@example.com/Empathy should normalize to alice@example.com, but the in-MUC JID wonderland@conference.example.com/Alice should normalize to itself.
While online, the connection manager has enough context to know which chatrooms the user is in, and can infer from that whether to remove resources, but the best-effort normalization performed while offline does not have this context, so the best that can be done is to remove the resource from all JIDs.
This method MAY simply raise NotImplemented on some protocols.
In link-local XMPP, you can't talk to someone who isn't present on your local network, so normalizing identifiers in advance is meaningless.
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.
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.
An interface for providing debug messages.
This interface is primarily provided by one object per service, at the path /org/freedesktop/Telepathy/debug.
Domain of the debug message. This is used to identify the source of debug messages. For example, debug messages from a connection manager could have this Domain struct member be the name of the connection manager, and logs from any helper library could have the name of the helper library.
The domain could also contain a category as to where the log message originated separated by a forward-slash. For example, if a debug message was output in a connection manager called "dummy", in the file-transfer code, this Domain struct member might be dummy/file-transfer.
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.
This interface allows many attributes of many contacts to be obtained in a single D-Bus round trip.
Each contact attribute has an string identifier
(
A list of strings indicating which D-Bus interfaces the calling process is interested in. All supported attributes from these interfaces, whose values can be obtained without additional network activity, will be in the reply.
Connection managers SHOULD ignore interfaces requested which they
do not support (i.e. those not mentioned in the
This simplifies client-side code. Clients which care may
distinguish between unsupported interfaces (e.g. this Connection
does not support Avatars), and interfaces on which no information
is known for these contacts (e.g. we don't know the avatar tokens
of any of the contacts, so we omitted them all) by inspecting
Attributes from the interface
As well as returning cached information immediately, the
connection MAY start asynchronous requests to obtain better
values for the contact attributes. If better values are later
obtained by this process, they will be indicated with the usual
signals (such as
A dictionary mapping the contact handles to contact attributes. If any of the requested handles are in fact invalid, they are simply omitted from this mapping. If contact attributes are not immediately known, the behaviour is defined by the interface; the attribute should either be omitted from the result or replaced with a default value.
Each contact's attributes will always include at least the
identifier that would be obtained by inspecting the handle
(org.freedesktop.Telepathy.Connection/contact-id).
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.
Request that the user's presence be changed to the given statuses
and desired parameters. Changes will be reflected by
Statuses whose
The same rationale as for
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.
This interface is for services which have a concept of presence which can be published for yourself and monitored on your contacts. Telepathy's definition of presence is based on that used by the Galago project.
Presence on an individual (yourself or one of your contacts) is modelled as
a last activity time along with a set of zero or more statuses, each of
which may have arbitrary key/value parameters. Valid statuses are defined
per connection, and a list of them can be obtained with the
(The SimplePresence interface which replaces this one restricts presences to one status per contact, with an optional message, which is in practice all that was implemented on this interface.)
Each status has an arbitrary string identifier which should have an agreed
meaning between the connection manager and any client which is expected to
make use of it. The well-known values defined by the
As well as these well-known status identifiers, every status also has a
numerical type value chosen from
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,
On some protocols,
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.
The channel dispatcher is responsible for responding to new channels and launching client processes to handle them. It also provides functionality for client processes to request that new channels are created.
If a channel dispatcher is running, it is responsible for dispatching
new channels on all
Connections created by standalone Telepathy clients that do not intend to interact with the channel dispatcher should be ignored - otherwise, the channel dispatcher would try to launch handlers for channels that the standalone client was already handling internally.
The current channel dispatcher is defined to be the process that
owns the well-known bus name
org.freedesktop.Telepathy.ChannelDispatcher on
the session bus. This process MUST export an object with this
interface at the object path
/org/freedesktop/Telepathy/ChannelDispatcher.
Until a mechanism exists for making a reasonable automatic choice of ChannelDispatcher implementation, implementations SHOULD NOT register as an activatable service for the ChannelDispatcher's well-known bus name. Instead, it is RECOMMENDED that some component of the user's session will select and activate a particular implementation, and that other Telepathy-enabled programs can detect whether channel request/dispatch functionality is available by checking whether the ChannelDispatcher's well-known name is in use at runtime.
There are three categories of client process defined by this specification:
Observers monitor the creation of new channels. This functionality can be used for things like message logging. All observers are notified simultaneously.
Approvers notify the user that new channels have been created, and also select which channel handler will be used for the channel, either by asking the user or by choosing the most appropriate channel handler.
Each new channel or set of channels is passed to exactly one handler as its final destination. A typical channel handler is a user interface process handling channels of a particular type.
Start a request to create a channel. This initially just creates a
The request can take a long time - in the worst case, the channel dispatcher has to ask the account manager to put the account online, the account manager has to ask the operating system to obtain an Internet connection, and the operating system has to ask the user whether to activate an Internet connection using an on-demand mechanism like dialup.
This means that using a single D-Bus method call and response to represent the whole request will tend to lead to that call timing out, which is not the behaviour we want.
If this method is called for an Account that is disabled, invalid
or otherwise unusable, no error is signalled until
This means there's only one code path for errors, apart from InvalidArgument for "that request makes no sense".
It also means that the request will proceed if the account is enabled after calling CreateChannel, but before calling Proceed.
A dictionary containing desirable properties. This has the same
semantics as the corresponding parameter to
Certain properties will not necessarily make sense in this
dictionary: for instance,
The time at which user action occurred, or 0 if this channel
request is for some reason not involving user action.
The User_Action_Time parameter of
Either the well-known bus name (starting with
org.freedesktop.Telepathy.Client.)
of the preferred handler for this
channel, or an empty string to indicate that any handler would be
acceptable. The channel dispatcher SHOULD dispatch as many as
possible of the resulting channels (ideally, all of them)
to that handler—irrespective of whether that handler's
This must be the well-known bus name, not the unique name, to ensure that all handlers do indeed have the Client API, and the Client object on the handler can be located easily.
This is partly so the channel dispatcher can call
The filter should be disregarded for ease of use of this interface: clients will usually use this argument to request channels be sent to themself, and this should trump the filter not matching. This also allows a client to become the handler for a channel produced by one of its own requests, while not being a candidate to handle other channels of that type.
If this is a well-known bus name and the handler has the
Requests interface, the channel dispatcher SHOULD
call
This ordering allows a Handler which calls CreateChannel with itself as the preferred handler to associate the call to AddRequest with that call.
This is copied to the ChannelRequest that is returned,
as the
org.freedesktop.Telepathy.Client.,
the Account does not exist, or one of the Requested_Properties
is invalid
Start a request to ensure that a channel exists, creating it if
necessary. This initially just creates a
If this method is called for an Account that is disabled, invalid
or otherwise unusable, no error is signalled until
The rationale is as for
A dictionary containing desirable properties. This has the same
semantics as the corresponding parameter to
Certain properties will not necessarily make sense in this
dictionary: for instance,
The time at which user action occurred, or 0 if this channel request is for some reason not involving user action.
This parameter is used in the same way as the corresponding
parameter to
Either the well-known bus name (starting with
org.freedesktop.Telepathy.Client.)
of the preferred handler for this
channel, or an empty string to indicate that any handler would be
acceptable. The behaviour and rationale are the same as for the
corresponding parameter to
If any new channels are created in response to this
request, the channel dispatcher SHOULD dispatch as many as
possible of the resulting channels (ideally, all of them)
to that handler, and SHOULD remember the preferred handler
so it can try to dispatch subsequent channels in the same bundle
to the same handler. If the requested channel already exists (that
is, Yours=False) then the channel dispatcher
SHOULD re-dispatch the channel to its existing handler, and MUST
NOT dispatch it to this client (unless it is the existing handler);
the request is still deemed to have succeeded in this case.
An address book application, for example, might call Preferred_Handler; if the
user already has a conversation with that contact in another
application, they would expect the existing window to be
presented, rather than their double-click leading to an error
message. So the request should succeed, even if its
Preferred_Handler is not used.
org.freedesktop.Telepathy.Client.,
the Account does not exist, or one of the Requested_Properties
is invalid
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.
This interface extends the
Incoming messages, outgoing messages, and delivery reports are all
represented as lists of
If observers were allowed to acknowledge messages, then messages might have been acknowledged before the handler even got to see the channel, and hence could not be shown to the user.
If this interface is present, clients that support it SHOULD
listen for the
Although this specification supports formatted (rich-text) messages with unformatted alternatives, implementations SHOULD NOT attempt to send formatted messages until the Telepathy specification has also been extended to cover capability discovery for message formatting.
A list of MIME types supported by this channel, with more preferred MIME types appearing earlier in the list. The list MAY include "*/*" to indicate that attachments with arbitrary MIME types can be sent. This list MUST NOT be empty, since all Messages implementations MUST accept messages containing a single "text/plain" part.
Some examples of how this property interacts with the
Flags indicating the level of support for message parts on this channel. They are designed such that setting more flags always implies that the channel has more capabilities.
If no flags are set, this indicates that messages may contain a single message part whose content-type is any of the types from SupportedContentTypes, possibly with some alternatives.
There is no flag indicating support for alternatives. This is because the SendMessage implementation can always accept messages containing alternatives, even if the underlying protocol does not, by deleting all alternatives except the first (most preferred) that is supported.
See
Part of a message's content. In practice, this mapping never
appears in isolation: incoming messages are represented by a list of
The first part of the message contains "headers", which refer
to the entire message. The second and subsequent parts contain the
message's content, including plain text, formatted text and/or
attached files. Well-known keys for the header and body parts are
defined by the
Instead of representing messages as aa{sv} where the first dictionary is special (a dictionary of headers), we could have used a signature like (a{sv}aa{sv}) to separate out the headers and the body parts.
However, this would make access to the messages more awkward.
In Python, the syntax for access to a header field would remain
message[0]['message-type'], but access to a body
field in the second body part would change from
message[2]['content'] to message[1][1]['content']. In
GLib, the message would change from being a
GPtrArray(GHashTable) to being a
GValueArray(GHashTable, GPtrArray(GHashTable)) which
is rather inconvenient to dereference.
In any group of parts with the same non-empty value for the alternative key (which represent alternative versions of the same content), more faithful versions of the intended message MUST come before less faithful versions (note that this order is the opposite of MIME multipart/alternative parts). Clients SHOULD display the first alternative that they understand.
Specifying the preference order means that if the underlying protocol doesn't support alternatives, the CM can safely delete everything apart from the first supported alternative when sending messages.
The order is the reverse of MIME because MIME's rationale for placing the "plainest" part first (legibility in pre-MIME UAs) does not apply to us, and placing the most preferred part first simplifies display (a client can iterate the message in order, display the first alternative that it understands, and skip displaying all subsequent parts with the same "alternative" key).
Clients SHOULD present all parts that are not redundant alternatives in the order they appear in this array, possibly excluding parts that are referenced by another displayed part. It is implementation-specific how the parts are presented to the user.
This allows CMs to assume that all parts are actually shown to the user, even if they are not explicitly referenced - we do not yet recommend formatted text, and there is no way for plain text to reference an attachment since it has no concept of markup or references. This also forces clients to do something sensible with messages that consist entirely of "attachments", with no "body" at all.
For instance, when displaying the above example, a client that understands the HTML part should display the JPEG image once, between the two lines "Here is a photo of my cat:" and "Isn't it cute?"; it may additionally present the image in some way for a second time, after "Isn't it cute?", or may choose not to.
A client that does not understand HTML, displaying the same message, should display the plain-text part, followed by the JPEG image.
A rich-text message, with an embedded image, might be represented as:
[
{
'message-token': '9de9546a-3400-4419-a505-3ea270cb834c',
'message-sender': 42,
'message-sent': 1210067943,
'message-received': 1210067947,
'message-type': 0, # = Channel_Text_Message_Type_Normal
'pending-message-id': 437,
},
{ 'alternative': 'main',
'content-type': 'text/html',
'content': 'Here is a photo of my cat:<br />' +
'<img src="cid:catphoto" alt="lol!" />' +
'<br />Isn't it cute?',
},
{ 'alternative': 'main',
'content-type': 'text/plain',
'content': 'Here is a photo of my cat:\n[IMG: lol!]\nIsn't it cute?',
},
{ 'identifier': 'catphoto',
'content-type': 'image/jpeg',
'size': 101000,
'needs-retrieval': True,
},
]
telepathy-ring, Nokia's GSM connection manager, represents vCards sent via SMS as:
[
{
'message-token': '9de9546a-3400-4419-a505-3ea270cb834c',
'message-sender': 42,
'message-sent': 1210067943,
'message-received': 1210067947,
'message-type': 0, # = Channel_Text_Message_Type_Normal
'pending-message-id': 437,
},
{ 'content-type': 'text/x-vcard',
'content': [ 0x66, 0x69, 0x71, ...], # vCard data as an array of bytes
},
]
Delivery reports are also represented as messages with the
message-type header mapping to
For backwards- and forwards-compatibility, whenever a delivery
error report is signalled—that is, with delivery-status
mapping to
The result of attempting to send delivery reports using
b9a991bd-8845-4d7f-a704-215186f43bb4 for an unknown
reason
[{
# header
'message-sender': 123,
'message-type': Channel_Text_Message_Type_Delivery_Report,
'delivery-status': Delivery_Status_Permanently_Failed,
'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
}
# no body
]
[{ # header
'message-sender': 123,
'message-type': Channel_Text_Message_Type_Delivery_Report,
'delivery-status': Delivery_Status_Temporarily_Failed,
'delivery-error': Channel_Text_Send_Error_Offline,
'delivery-echo':
[{ # header of original message
'message-sender': 1,
'message-sent': 1210067943,
},
{ # body of original message
'content-type': 'text/plain',
'content': 'Hello, world!',
}]
],
# no body
]b9a991bd-8845-4d7f-a704-215186f43bb4 to a contact
with handle 123, but that handle represents a contact who does not
actually exist
[{ # header
'message-sender': 123,
'message-type': Channel_Text_Message_Type_Delivery_Report,
'delivery-status': Delivery_Status_Permanently_Failed,
'delivery-error': Channel_Text_Send_Error_Invalid_Contact,
'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
'delivery-echo':
[{ # header of original message
'message-sender': 1,
'message-sent': 1210067943,
},
{ # body of original message
'content-type': 'text/plain',
'content': 'Hello, world!',
}]
],
},
{ # message from server (alternative in English)
'alternative': '404',
'content-type': 'text/plain',
'lang': 'en',
'content': 'I have no contact with that name',
},
{ # message from server (alternative in German)
'alternative': '404'.
'content-type': 'text/plain',
'lang': 'de',
'content', 'Ich habe keinen Kontakt mit diesem Namen',
}
]b9a991bd-8845-4d7f-a704-215186f43bb4
[{
# header
'message-sender': 123,
'message-type': Channel_Text_Message_Type_Delivery_Report,
'delivery-status': Delivery_Status_Delivered,
'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
}
# no body
]Well-known keys for the first
An opaque, globally-unique identifier for the entire message. This MAY be treated as if it were a MIME Message-ID, e.g. for the mid: and cid: URI schemes. If omitted, there is no suitable token; the protocol-token key SHOULD be provided if the protocol identifies messages in some less unique way.
An opaque token for the entire message, with whatever uniqueness guarantee is provided by the underlying protocol. As described for the Protocol_Message_Token type, this token is not guaranteed to be unique between contacts, or even within the scope of a Channel.
In practice, in most protocols there is no token with the uniqueness guarantees demanded for message-token; the definition of message-token was inappropriate, but must now be preserved for the benefit of clients that rely on it, at least until Telepathy breaks backwards compatibility.
The message-token and protocol-token SHOULD NOT both be present; clients requiring an identifier with the semantics of the protocol-token SHOULD look for the message-token first, falling back to the protocol-token.
This is for compatibility with CMs older than the protocol-token key.
Well-known keys for the second and subsequent
If present, this part of the message is an alternative for all other parts with the same value for "alternative". Clients SHOULD only display one of them (this is expected to be used for XHTML messages in a future version of this specification).
If omitted, this part is not an alternative for any other part.
Parts of a message MAY reference the group of alternatives as a whole (i.e. a reference to whichever of them is chosen) by treating this identifier as if it were the MIME Content-ID of a multipart/alternative part, and using the cid: URI scheme.
The MIME type of this part. See the documentation
for
Connection managers MUST NOT signal parts without a 'content-type' key; if a protocol provides no way to determine the MIME type, the connection manager is responsible for guessing it, but MAY fall back to "text/plain" for text and "application/octet-stream" for non-text.
Clients MUST ignore parts without a 'content-type' key, which are reserved for future expansion.
This part is a thumbnail. To represent an image together with its thumbnail in a single message, there should be one part for the full image followed by a part for the thumbnail (following the “more complete versions first” requirement), with the same 'alternative' value. For example:
[ ... ,
{ 'alternative': 'catphoto',
'content-type': 'image/jpeg',
'size': 150000,
'content': [0xFF, 0xD8, ... 0xFF 0xD9],
},
{ 'alternative': 'catphoto',
'content-type': 'image/jpeg'
'size': 1024,
'thumbnail': True,
'content': [0xFF, 0xD8, ... 0xFF 0xD9],
},
...
]
Well-known keys for the first
An identifier for the message to which this delivery report refers. MUST NOT be an empty string. Omitted if not available.
Clients may match this against the token produced by the SendMessage method and MessageSent signal. A status report with no token could match any sent message, and a sent message with an empty token could match any status report. If multiple sent messages match, clients SHOULD use some reasonable heuristic.
The message content, as defined by the Messages interface. Omitted if no content is available. Content MAY have been truncated, message parts MAY have been removed, and message parts MAY have had their content removed (i.e. the message part metadata is present, but the 'content' key is not).
Unlike in the Messages interface, content not visible in the value for this key cannot be retrieved by another means, so the connection manager SHOULD be more aggressive about including (possibly truncated) message content in the 'content' key.
An opaque token used to identify messages in the underlying. protocol. As a special case, the empty string indicates that there is no particular identification for a message.
CM implementations SHOULD use an identifier expected to be unique, such as a UUID, if possible.
Some protocols can only track a limited number of messages in a small message-ID space (SMS messages are identified by a single byte), and some implementations send non-unique identifiers (some XMPP clients use very simple message IDs, such as an incrementing integer that resets to 1 at the beginning of each connection). As a result, clients MUST NOT assume that protocol tokens will not be re-used.
In particular, clients SHOULD use a heuristic to assign delivery reports to messages, such as matching on message content or timestamp (if available), or assuming that the delivery report refers to the most recent message with that ID.
A protocol-specific identifier for a blob of content, as used for
the identifier key in a
On XMPP, these identifiers might be Content-IDs for custom smileys implemented using XEP-0232 Bits of Binary; the same smiley might well appear in multiple messages.
Submit a message to the server for sending.
If this method returns successfully, the message has been submitted
to the server and the
This method MUST return before the MessageSent signal is emitted.
This means that the process sending the message is the first
to see the
If this method fails, message submission to the server has failed and no signal on this interface (or the Text interface) is emitted.
Provide a successful delivery report if possible, even if this is not the default for this protocol. Ignored if delivery reports are not possible on this protocol.
In some protocols, like XMPP, it is not conventional to request or send positive delivery notifications.
Delivery failure reports SHOULD always be sent, but if this flag is present, the connection manager MAY also try harder to obtain failed delivery reports or allow them to be matched to outgoing messages.
Provide a delivery report when the message is read by the recipient, even if this is not the default for this protocol. Ignored if read reports are not possible on this protocol.
Provide a delivery report when the message is deleted by the recipient, even if this is not the default for this protocol. Ignored if such reports are not possible on this protocol.
Signals that a message has been submitted for sending. This
MUST be emitted exactly once per emission of the
This SHOULD be emitted as soon as the CM determines it's theoretically possible to send the message (e.g. the parameters are supported and correct).
This signal allows a process that is not the caller of SendMessage to log sent messages.
The message content (see
If the connection manager can predict that the message will be altered during transmission, this argument SHOULD reflect what other contacts will receive, rather than being a copy of the argument to SendMessage (if the message is truncated, formatting or alternatives are dropped, etc., then the edited version SHOULD appear in this signal).
Flags affecting how the message was sent. The flags might be a subset of those passed to SendMessage if the caller requested unsupported flags.
A list of incoming messages that have neither been acknowledged nor
rejected. This list is a more detailed version of the one returned
by
Change notification is via
The content of the requested parts. The keys in this mapping
are positions in the array of message parts; the values are
either of type 's' or 'ay' (UTF-8 text string, or byte array),
following the same rules as for the value of the 'content' key in
the
If the one of the requested part numbers was greater than zero but referred to a part that had no content (i.e. it had no 'content-type' key or no 'content' key), it is simply omitted from this mapping; this is not considered to be an error condition.
The message content, including any attachments or alternatives. If
the incoming message contains formatted text without a plain text
alternative, the connection manager MUST generate a
text/plain alternative from the formatted text, and
include it in this message (both here, and in the
The status of a message as indicated by a delivery report.
If this enum is extended in future specifications, this should
only be to add new, non-overlapping conditions (i.e. all failures
should still be signalled as either Temporarily_Failed
or Permanently_Failed). If additional detail is required (e.g.
distinguishing between the various types of permanent failure) this
will be done using additional
Read if the message was read before being deleted.
Read reports if Message_Sending_Flag_Report_Read
is specified when sending.
Deleted reports if Message_Sending_Flag_Report_Deleted
is specified when sending.
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.
A map containing the chat states of all contacts in this channel whose chat state is not Inactive.
Contacts in this channel, but who are not listed in this map, may be assumed to be in the Inactive state.
In implementations that do not have this property, its value may be
assumed to be empty until a
This property was not present in older versions of telepathy-spec, because chat states in XMPP are not state-recoverable (if you miss the change notification signal, there's no way to know the state). However, this property still allows clients to recover state changes that were seen by the CM before the client started to deal with the channel.
In CMs that follow older spec versions, assuming Inactive will mean that initial chat states will always be assumed to be Inactive, which is the best we can do. XEP 0085 specifies Inactive as the "neutral" state to be assumed unless told otherwise.
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.
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.
An Account object encapsulates the necessary details to make a Telepathy connection.
Accounts are uniquely identified by object path. The object path
of an Account MUST take the form
/org/freedesktop/Telepathy/Account/cm/proto/acct, where:
This API avoids specifying the "profiles" used in Mission Control 4.x or the "presets" that have been proposed to replace them. An optional interface will be provided for AM implementations that want to provide presets.
There is deliberately no functionality here for opening channels; we intend to provide that in the channel dispatcher.
Other missing features which would be better in their own interfaces:
This property gives the users the possibility to prevent an account from being used. This flag does not change the validity of the account.
A disabled account can never be put online.
Use cases:
The AccountManager SHOULD allow this property to be set on invalid accounts, but MUST NOT attempt to put invalid accounts online even if they become Enabled.
There doesn't seem to be any good reason not to allow this.
Some protocols, like XMPP and SIP, are used by various different
user-recognised brands, such as Google Talk and Ovi by
Nokia. On accounts for such services, this property SHOULD be
set to a string describing the service, which MUST consist only of
ASCII letters, numbers and hyphen/minus signs, and start with a
letter (matching the requirements for
The
This property MAY be set, if appropriate, when calling
Cannot_Set_Service.
A map from connection manager parameter names (as in the
This property cannot be altered using Set() - use
Change the value of the
If any of the changed parameters'
DBus_Property, the change will be applied immediately to
the
corresponding D-Bus Property on the active
In general, reconnecting is a destructive operation that shouldn't happen as a side-effect. In particular, migration tools that twiddle the settings of all accounts shouldn't cause an automatic disconnect and reconnect.
If all of the parameters had the DBus_Property flag,
the empty list, signifying that no reconnection is required for the
new parameters to take effect. For example, if the only parameter
updated is ...Cellular.
Otherwise, a list of the names of parameters with changes that
will not take effect until the account is reconnected. User
interfaces that require "instant apply" semantics MAY call
["require-encryption"].
The presence status that this account should have if it is brought online.
Setting this property MUST NOT actually change the account's status until the next time it is (re)connected for some reason.
The value of this property MUST be one that would be acceptable
for
Otherwise, it would not be possible to use this presence to bring the account online for a channel request.
Either the object path of the '/' if there is no
connection.
If this object path is not '/', the Connection's well-known bus name can be derived from this object path by removing the first '/' and replacing subsequent '/' characters with '.'.
If the last connection to this account failed with an error,
the D-Bus error name of that error; otherwise, the empty string.
The account manager is expected to set this by observing the
If ConnectionError is received before the connection disconnects, its first argument should be used to set this property; otherwise, the Reason argument of StatusChanged should be converted to a suitable D-Bus error name.
Whenever the Connection connects successfully, this property should be reset to the empty string.
This combines the state-recoverability of
If the last connection to this account failed with an error,
a mapping representing any additional information about the last
disconnection; otherwise, the empty map. The keys and values are
the same as for the second argument of
Whenever the Connection connects successfully, this property should be reset to the empty map.
This combines the state-recoverability of
The requested presence for this account. When this is changed, the
account manager should attempt to manipulate the connection manager to
make
When the account manager automatically connects an account,
it must signal this by setting the RequestedPresence to the same
thing as the
The
Requesting those presence types doesn't make sense.
If true, a change to the presence of this account is in progress.
Whenever
When the account manager succeeds or fails in changing the presence,
or the connection disconnects due to an error, ChangingPresence MUST
change to False as part of the same
This allows UIs to indicate that a presence change is in progress or has finished, even if the change was initiated by a different UI.
For instance, Maemo 5 and Empathy indicate a presence change by
having the presence indicator alternate between the
Re-connect this account. If the account is currently disconnected
and the requested presence is offline, or if the account
is not
If the account is disconnected and the requested presence is not offline, this forces an attempt to connect with the requested presence immediately.
If the account is connecting or connected, this is equivalent to
remembering the current value of
Clients desiring "instant apply" semantics for CM parameters MAY call this method to achieve that.
In particular, if the account's
This is necessary to ensure that the new parameters are picked up.
The normalized user ID of the local user on this account (i.e. the
string returned when the
It is unspecified whether this user ID is globally unique.
As currently implemented, IRC user IDs are only unique within the same IRCnet. On some saner protocols, the user ID includes a DNS name which provides global uniqueness.
If this value is not known yet (which will always be the case for accounts that have never been online), it will be an empty string.
It is possible that this value will change if the connection manager's normalization algorithm changes, although this SHOULD be avoided.
It's not always completely clear what normalization algorithm should be used; for instance, in Gabble, we currently use JIDs, but it would also have been reasonable to use xmpp URIs.
The time at which an user action occurred. This type has the 2 following special values:
0: the action doesn't involve any user action. Clients SHOULD avoid stealing focus when presenting the channel.
MAX_INT64: clients SHOULD behave as though the user action happened at the current time, e.g. a client MAY request that its window gains focus.
This can be used by clients that can't know the X server time like command line applications for example.
For all the other values it corresponds to the time of the user action. Clients SHOULD use this for focus-stealing prevention, if applicable. Note that the time is dependant on the local environment and so is not necessarily a wall-clock time. For example in an X environment it's expected to be the X timestamp of events. This corresponds to the _NET_WM_USER_TIME property in EWMH.
Interface for channels where you may put the channel on hold.
This only makes sense for channels where
you are streaming media to or from the members. (To see whether the
other participant has put you on hold, see
If you place a channel on hold, this indicates that you do not wish to be sent media streams by any of its members and will be ignoring any media streams you continue to receive. It also requests that the connection manager free up any resources that are only needed for an actively used channel (e.g. in a GSM or PBX call, it will be necessary to place an active call on hold before you can start another call).
Request that the channel be put on hold (be instructed not to send any media streams to you) or be taken off hold.
If the connection manager can immediately tell that the requested state change could not possibly succeed, this method SHOULD return the NotAvailable error. If the requested state is the same as the current state, this method SHOULD return successfully without doing anything.
Otherwise, this method SHOULD immediately set the hold state to
Local_Hold_State_Pending_Hold or Local_Hold_State_Pending_Unhold
(as appropriate), emitting
The eventual success or failure of the request is indicated by a subsequent HoldStateChanged signal, changing the hold state to Local_Hold_State_Held or Local_Hold_State_Unheld.
If the channel has multiple streams, and the connection manager succeeds in changing the hold state of one stream but fails to change the hold state of another, it SHOULD attempt to revert all streams to their previous hold states.
The following state transitions SHOULD be used, where appropriate:
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.
The channel's type. This cannot change once the channel has been created.
For compatibility between older connection managers and newer
clients, if this is unavailable or is an empty string,
clients MUST use the result of calling
When requesting a channel, the request MUST specify a channel type, and the request MUST fail if the specified channel type cannot be supplied.
Extra interfaces provided by this channel. This SHOULD NOT include the channel type and the Channel interface itself, and cannot change once the channel has been created.
For compatibility between older connection managers and newer
clients, if this is unavailable, or if this is an empty list and
When requesting a channel with a particular value for this property, the request must fail without side-effects unless the connection manager expects to be able to provide a channel whose interfaces include at least the interfaces requested.
The handle (a representation for the identifier) of the contact,
chatroom, etc. with which this handle communicates. Its type
is given by the
This is fixed for the lifetime of the channel, so channels which could potentially be used to communicate with multiple contacts (such as streamed media calls defined by their members, or ad-hoc chatrooms like MSN switchboards) must have TargetHandleType set to Handle_Type_None and TargetHandle set to 0.
Unlike in the telepathy-spec 0.16 API, there is no particular uniqueness guarantee - there can be many channels with the same (channel type, handle type, handle) tuple. This is necessary to support conversation threads in XMPP and SIP, for example.
If this is present in a channel request, it must be nonzero,
The channel that satisfies the request MUST either:
The string that would result from inspecting the
The presence of this property avoids the following race condition:
If this is present in a channel request,
The returned channel must be related to the handle corresponding to the given identifier, in the same way as if TargetHandle had been part of the request instead.
Requesting channels with a string identifier saves a round-trip (the call to RequestHandles). It also allows the channel dispatcher to accept a channel request for an account that is not yet connected (and thus has no valid handles), bring the account online, and pass on the same parameters to the new connection's CreateChannel method.
The type of
If this is omitted from a channel request, connection managers SHOULD treat this as equivalent to Handle_Type_None.
If this is omitted or is Handle_Type_None,
True if this channel was created in response to a local request,
such as a call to
The idea of this property is to distinguish between "incoming" and "outgoing" channels, in a way that doesn't break down when considering special cases like contact lists that are automatically created on connection to the server, or chatrooms that an IRC proxy/bouncer like irssi-proxy or bip was already in.
The reason we want to make that distinction is that UIs for things that the user explicitly requested should start up automatically, whereas for incoming messages and VoIP calls we should first ask the user whether they want to open the messaging UI or accept the call.
If the channel was not explicitly requested (even if it was created as a side-effect of a call to one of those functions, e.g. because joining a Tube in a MUC context on XMPP implies joining that MUC), then this property is false.
For compatibility with older connection managers, clients SHOULD
assume that this property is true if they see a channel announced
by the
In a correct connection manager, the only way to get such a channel is to request it.
Clients MAY additionally assume that this property is false if they see a channel announced by the NewChannel signal with the suppress_handler parameter set to false.
This is more controversial, since it's possible to get that parameter set to false by requesting a channel. However, there's no good reason to do so, and we've deprecated this practice.
In the particular case of the channel dispatcher, the only side-effect of wrongly thinking a channel is unrequested is likely to be that the user has to confirm that they want to use it, so it seems fairly harmless to assume in the channel dispatcher that channels with suppress_handler false are indeed unrequested.
It does not make sense for this property to be in channel requests—it will always be true for channels returned by CreateChannel, and callers of EnsureChannel cannot control whether an existing channel was originally requested locally—so it MUST NOT be accepted.
The contact who initiated the channel; for instance, the contact who invited the local user to a chatroom, or the contact who initiated a call.
This does not necessarily represent the contact who created the underlying protocol-level construct. For instance, if Rob creates a chatroom, Will joins that chatroom, and Will invites Simon to join it, then Simon will see Will as the InitiatorHandle of the channel representing the chatroom.
The room creator is generally a less useful piece of information than the inviter, is less likely to be available at invitation time (i.e. can't necessarily be an immutable property), and is less likely to be available at all. The creator of a chatroom is not currently available via Telepathy; if added in future, it is likely to be made available as a property on the Chatroom interface (bug 23151).
For channels requested by the
local user, this MUST be the value of
On some protocols, the SelfHandle may change (as signalled by
For channels requested by a remote user, this MUST be their handle. If unavailable or not applicable, this MUST be 0 (for instance, contact lists are not really initiated by anyone in particular, and it's easy to imagine a protocol where chatroom invitations can be anonymous).
For channels with the
This SHOULD NOT be a channel-specific handle, if possible.
It does not make sense for this property to be in channel requests - the initiator will always be the local user - so it MUST NOT be accepted.
The string that would result from inspecting the
The presence of this property avoids the following race condition:
It does not make sense for this property to be in channel requests - the initiator will always be the local user - so it MUST NOT be accepted.
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
Each Channel's object path MUST start with the object path of
its associated
This ensures that Channel object paths are unique, even between Connections and CMs, because Connection object paths are guaranteed-unique via their link to the well-known bus name.
If all connection managers in use are known to comply with at least spec version 0.17.10, then the Connection's object path can even be determined from the Channel's without any additional information, by taking the first 7 components.
Each channel has a number of immutable properties (which cannot vary
after the channel has been announced with
Other optional
Some channels are “anonymous”, with
None,
which indicates that the channel is defined by some other properties. For
instance, transient ad-hoc chat rooms may be defined only by their members (as visible
through the
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.
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.
An interface for connections where it is possible to know what channel types may be requested before the request is made to the connection object. Each capability represents a commitment by the connection manager that it will ordinarily be able to create a channel when given a request with the given type and handle.
Capabilities pertain to particular contact handles, and represent activities such as having a text chat or a voice call with the user. The activities are represented by the D-Bus interface name of the channel type for that activity.
The generic capability flags are defined by
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
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
On connections managed by the
Announce that there has been a change of capabilities on the given handle.
If the handle is zero, the capabilities refer to the connection itself, in some poorly defined way. This usage is deprecated and clients should ignore it.
An array of contact handles for this connection.
This may include zero, which originally meant a query for capabilities available on the connection itself. This usage is deprecated; clients SHOULD NOT do this, and connection managers SHOULD proceed as though zero had not been present in this list.
The same structs that would be returned by
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.
The account manager is a central service used to store account details.
The current account manager is defined to be the process that owns the well-known bus name org.freedesktop.Telepathy.AccountManager on the session bus. This process must export an /org/freedesktop/Telepathy/AccountManager object with the AccountManager interface.
Until a mechanism exists for making a reasonable automatic choice of AccountManager implementation, implementations SHOULD NOT register as an activatable service for the AccountManager's well-known bus name. Instead, it is RECOMMENDED that some component of the user's session will select and activate a particular implementation, and that other Telepathy-enabled programs can detect whether Telepathy is in use by checking whether the AccountManager's well-known name is in use at runtime.
A list of the fully qualified names of properties that can be set
via the Properties argument to
Examples of good properties to support here include
Examples of properties that would make no sense here include
This property MUST NOT include include the
This property MAY include the names of properties that, after account creation, will be read-only: this indicates that the property can be set at account creation but not changed later.
For example, an account manager might support migration tools that
use this to preserve the
The account creation UI may ask the user for a name for the new account. If the author of the UI chooses not to do this, the account creation UI is better able to suggest a default display name because it has protocol-specific knowledge which the account manager does not.
The account manager always knows the complete list of accounts so it can easily tell whether it should append something to the display name to avoid presenting two identically-named accounts to the user.
The values of any other properties to be set immediately on the new Account.
Only the properties mentioned in
Account manager implementations SHOULD support creating accounts with an empty value for this argument.
The Connection_Manager is not installed or does not implement the given Protocol, or one of the properties in the Properties argument is unsupported.
The Parameters provided omit a required parameter or provide unsupported parameter, or the type of one of the Parameters or Properties is inappropriate.
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.
An interface for protocols that support multiple forms of addressing contacts, for example through vCard addresses and URIs.
If the ConnectionManager has a .manager file, and it supports this interface, the interface's immutable properties must be represented in the file; the representation is described as part of the documentation for each property.
For instance, a SIP connection manager might have the following lines in the .manager file.
[Protocol sip] AddressableVCardFields=tel;x-sip; AddressableURISchemes=tel;sip;
The vCard fields that can be used to request a contact with
normalized to lower case. If the URL vCard
field is addressable, a colon, followed by the supported URI
schemes will be concatenated.
For example: ["tel", "x-sip"].
The url vCard field MUST NOT appear here; see
In practice, protocols have a limited set of URI schemes that make sense to resolve as a contact.
This property should only be used when the connection is
offline. When it is connected the addressable fields should be
retrieved from the
Connection managers with a .manager file
MUST cache this property in the protocol's section of the
.manager file if it is non-empty, using the key
AddressableVCardFields. The corresponding value
is a list of strings, each followed with a semicolon and in the
syntax of the "localestring" type from the Desktop Entry
Specification.
Well-known vCard fields:
telx-sipx-aimx-icqx-skypex-skype is preferredx-groupwisex-gadugadux-jabberx-msnx-yahooThe URI schemes that are supported by this protocol.
For example: ["tel", "sip"].
This property should only be used when the connection is
offline. When it is connected the addressable URI schemes should be
retrieved from the
Connection managers with a .manager file
MUST cache this property in the protocol's section of the
.manager file if it is non-empty, using the key
AddressableURISchemes. The corresponding value
is a list of strings, each followed with a semicolon and in the
syntax of the "localestring" type from the Desktop Entry
Specification.
Well-known URI schemes:
sipsip:julien@example.com.sipssips:julien@example.com.teltel:+12065551234.xmppxmpp:julien@example.com.msnimadd; the
contact field in the query string is used to
identify the contact.
For example: msnim:add?contact=julien.aimaddbuddy; the
screenname field in the query string is used to
identify the contact.
For example: aim:addbuddy?screenname=julien.skypeskype:julien.ymsgraddfriend; the
query string is used to identify the contact.
For example: ymsgr:addfriend?julien.gggg:julien.Attempt to normalize the given vCard address. Where possible, this
SHOULD return an address that would appear in the
org.freedesktop.Telepathy.Connection.Interface.Addressing.DRAFT/addresses
attribute for a contact on a connected
If full normalization requires network activity or is otherwise
impossible to do without a
An example would be a vCard TEL field with a formatted
number in the form of +1 (206) 555 1234, this would be
normalized to +12065551234.
This method MAY simply raise NotImplemented on some protocols, if it has no use.
Attempt to normalize the given contact URI. Where possible, this
SHOULD return an address that would appear in the
org.freedesktop.Telepathy.Connection.Interface.Addressing.DRAFT/uris
attribute for a contact on a connected
If full normalization requires network activity or is otherwise
impossible to do without a
Example: xmpp:eitan@EXAMPLE.COM would be normalized to
xmpp:eitan@example.com.
This method MAY simply raise NotImplemented on some protocols, if it has no use.
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.
Used to set the username fragment and password for streams that have global credentials.
Extra information about the candidate. Allowed and mandatory keys depend on the transport protocol used. The following keys are commenly used:
The IP addresses of possible STUN servers to use for NAT
traversal, as dotted-quad IPv4 address literals or RFC2373
IPv6 address literals. Change notification is via the
A list of mappings describing TURN or Google relay servers available for the client to use in its candidate gathering, as determined from the protocol. Map keys are:
ip - stype - sEither udp for UDP (UDP MUST be assumed if this
key is omitted), tcp for TCP, or
tls.
The precise meaning of this key depends on the
tls means
TLS over TCP as referenced by ICE draft 19, and if
Transport is GTalk_P2P, tls means
a fake SSL session over TCP as implemented by libjingle.
port - qusername - spassword - scomponent - uAn equivalent of the gtalk-p2p-relay-token property on MediaSignalling channels is not included here. The connection manager should be responsible for making the necessary HTTP requests to turn the token into a username and password.
The type of relay server that this represents depends on
the value of the
If relaying is not possible for this stream, the list is empty.
Change notification is given via the
Signals that the initial information about STUN and Relay servers
has been retrieved, i.e. the
True if all the initial information about STUN servers and Relay
servers has been retrieved. Change notification is via the
The list of
Change notification is via the
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.
Observers monitor the creation of new channels. This functionality can be used for things like message logging. All observers are notified simultaneously.
Observers SHOULD NOT modify the state of a channel except via user interaction.
We want Observer UIs for file transfer channels (a progress bar for the transfer) to be able to have a Cancel button.
Observers MUST NOT carry out actions that exactly one process must take responsibility for (e.g. acknowledging Text messages, or carrying out the actual transfer in a file transfer channel).
Since arbitrarily many observers can be activated for
each channel, it would not make sense for observers to do things
that can only be done by one process (acknowledging
Handlers MAY, of course, delegate responsibility for these tasks to other processes (including those run as observers), but this MUST be done explicitly via a request from the Handler to the Observer.
Whenever a collection of new channels is signalled, the channel
dispatcher will notify all running or activatable observers whose
Observers are activated for all channels in which they have
registered an interest - incoming, outgoing or automatically created -
although of course the ObserverChannelFilter property can be set
to filter on the
Because it might take time for an observer to become ready (for
instance, a Text logger needs to wait until pending messages have been
downloaded), the channel dispatcher must wait (up to some timeout) for
all observers to return from
A specification of the channels in which this observer is
interested. The
Only certain D-Bus types have useful semantics for matching like this, so only certain types are allowed:
This property never changes while the observer process owns its Client bus name. For activatable processes, the filter can change due to an upgrade - the channel dispatcher SHOULD observe changes to .client files using a mechanism like inotify.
Not allowing this property to change is a simplification, particularly for activatable processes (we reject the possibility that a process with a .client file, when activated, has a filter that differs from what its .client file said).
If an Observer wants to add extra channels to its list of interests at runtime, it can register an additional Client bus name (for instance, the org.freedesktop.Telepathy.Client.Empathy process with unique name :1.42 could additionally register org.freedesktop.Telepathy.Client.Empathy._1_42) with additional filters. To remove those filters, it can release the bus name; it could even re-claim the bus name immediately, with different filters.
The same principle is applied to Approvers and Handlers.
For observers that have a .client file, the channel dispatcher
may discover this property from keys of the form
"propertyname type",
in groups in the .client file whose name is the name of this
interface followed by .ObserverChannelFilter,
a space and an ASCII decimal number starting from 0.
Values in the .client file are encoded in exactly the same way as
the default-p keys in .manager files, as
described in the
For instance, a .client file for an observer that is only interested in Text channels, with CONTACT or ROOM handles, that were requested by a local client:
[org.freedesktop.Telepathy.Client] Interfaces=org.freedesktop.Telepathy.Client.Observer; [org.freedesktop.Telepathy.Client.Observer.ObserverChannelFilter 0] org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text org.freedesktop.Telepathy.Channel.TargetHandleType u=1 org.freedesktop.Telepathy.Channel.Requested b=true [org.freedesktop.Telepathy.Client.Observer.ObserverChannelFilter 1] org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text org.freedesktop.Telepathy.Channel.TargetHandleType u=2 org.freedesktop.Telepathy.Channel.Requested b=true
If true, upon the startup of this observer,
When an activatable client having this property disappears from the bus and there are channels matching its ObserverChannelFilter, ObserveChannels will be called immediately to reactivate it again. Such clients should specify this property in their .client file as follows:
[org.freedesktop.Telepathy.Client.Observer] Recover=true
This means that if an activatable Observer crashes, it will
be restarted as soon as possible; while there is an unavoidable
possibility that it will miss some events during this process
(particularly
Non-activatable observers can't take advantage of this mechanism, but setting this property on a non-activatable observer does allow it to "catch up" on channels that are currently active at the time that it starts up.
When the ObserveChannels method is called due to observer recovery,
the Observer_Info dictionary will contain one extra item
mapping the key "recovering" to True.
Called by the channel dispatcher when channels in which the
observer has registered an interest are announced in a
If the same NewChannels signal announces some channels that match the filter, and some that do not, then only a subset of the channels (those that do match the filter) are passed to this method.
If the channel dispatcher will split up the channels from a single NewChannels signal and dispatch them separately (for instance because no installed Handler can handle all of them), it will call ObserveChannels several times.
The observer MUST NOT return from this method call until it is ready for a handler for the channel to run (which may change the channel's state).
The channel dispatcher must wait for observers to start up,
to avoid the following race: text channel logger (observer) gets
ObserveChannels, text channel handler gets
The channel dispatcher SHOULD NOT change its behaviour based on whether this method succeeds or fails: there are no defined D-Bus errors for this method, and if it fails, this only indicates that an Observer is somehow broken.
The expected error response in the channel dispatcher is to log a warning, and otherwise continue as though this method had succeeded.
The path to the
If the Observer calls
This allows an Observer to
Additional information about these channels. Currently defined keys are:
recovering - bTrue if ObserveChannels was called for an existing
channel (due to the True); False or omitted
otherwise.
request-properties - a{oa{sv}}All defined keys for this dictionary are optional; observers MAY safely ignore any entry in this dictionary.
A channel type that carries a TLS certificate between a server and a client connecting to it.
Channels of this kind always have
In this case, handlers SHOULD accept or reject the certificate, using
the relevant methods on the provided object, or MAY just
For example, channels of this kind can pop up while a client is connecting to an XMPP server.
A
This property is immutable.
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.
An interface for connections whose channels may be able to indicate specific they are connected to some form of service station. For example, when dialing 9-1-1 in the US, a GSM modem/network will recognize that as an emergency call, and inform higher levels of the stack that the call is being handled by an emergency service. In this example, the call is handled by a Public Safety Answering Point (PSAP) which is labeled as "urn:service:sos". Other networks and protocols may handle this differently while still using this interface.
Description of a service point and IDs which are mapped to it.
An example Service Point info for GSM emergency calls (callable through "911" and "112") could look like:
ServicePointInfo = (
Service_Point: (
Service_Point_Type: 1 (Emergency),
Service_Point: "urn:service:sos"
),
Service_IDs: [ "911", "112" ]
)
The new value of
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.
The transport (NAT traversal technique) to be used for this stream. Well-known values include:
This property cannot change once the stream has been created, so there is no change notification.
A list of mappings describing TURN or Google relay servers available for the client to use in its candidate gathering, as determined from the protocol. Map keys are:
ip - stype - sEither udp for UDP (UDP MUST be assumed if this
key is omitted), tcp for TCP, or
tls.
The precise meaning of this key depends on the
ice-udp, tls means
TLS over TCP as referenced by ICE draft 19, and if
NATTraversal is gtalk-p2p, tls means
a fake SSL session over TCP as implemented by libjingle.
port - qusername - spassword - scomponent - uAn equivalent of the gtalk-p2p-relay-token property on MediaSignalling channels is not included here. The connection manager should be responsible for making the necessary HTTP requests to turn the token into a username and password.
The type of relay server that this represents depends on
the value of the
If relaying is not possible for this stream, the list is empty.
This property cannot change once the stream has been created, so there is no change notification.
Informs the connection manager that a valid transport pair has been discovered and streaming is in progress. Component id MUST be the same for both transports and the pair is only valid for that component.
The connection manager might need to send the details of
the active transport pair (e.g. c and o parameters of SDP
body need to contain address of selected native RTP transport
as stipulated by RFC 5245). However, the candidate ID might
not be enough to determine these info if the transport was
found after
This method must be called before
This way, connection managers supporting this method can
safely ignore subsequent
Connection managers SHOULD NOT implement this method unless they need to inform the peer about selected transports. As a result, streaming implementations MUST NOT treat errors raised by this method as fatal.
Usually, connection managers only need to do one answer/offer round-trip. However, some protocols give the possibility to to send an updated offer (e.g. ICE defines such mechanism to avoid some race conditions and to properly set the state of gateway devices).
Used to provide codecs after Ready(), so the media client can go ready for an incoming call and exchange candidates/codecs before knowing what local codecs are available.
This is useful for gatewaying calls between two connection managers.
Given an incoming call, you need to call
In this situation, you would pass an empty list of codecs to the incoming call's Ready method, then later call SetLocalCodecs on the incoming call in order to respond to the offer.
Emitted when the connection manager wishes to place the stream on hold (so the streaming client should free hardware or software resources) or take the stream off hold (so the streaming client should reacquire the necessary resources).
When placing a channel's streams on hold, the connection manager SHOULD notify the remote contact that this will be done (if appropriate in the protocol) before it emits this signal.
It is assumed that relinquishing a resource will not fail. If it does, the call is probably doomed anyway.
When unholding a channel's streams, the connection manager SHOULD emit this signal and wait for success to be indicated via HoldState before it notifies the remote contact that the channel has been taken off hold.
This means that if a resource is unavailable, the remote contact will never even be told that we tried to acquire it.
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.
This interface contains functionality which we intend to incorporate
into the
A dictionary of metadata provided by the channel requester, which the handler and other clients MAY choose to interpret. Currently no standard keys are defined; clients MAY choose to use platform-specific keys for their own purposes, but MUST ignore unknown keys and MUST cope with expected keys being missing.
The channel dispatcher will not interpret these hints: they are solely for communication between cooperating clients.
Any extra parameters that do affect the channel dispatcher should be designed separately.
This property may be set when the channel request is created, and
can never change. Since it is immutable, it SHOULD be included in the
dictionary of properties passed to
Variant of the
The Connection owning the channel.
The channel which has been created.
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.
An enhanced version of the Telepathy connection interface, which can represent bundles of channels that should be dispatched together, and does not assume any particular properties by which channels are uniquely identifiable.
If this interface is implemented on a connection, then
Properties of the channel.
Connection managers MUST NOT include properties in this mapping if their values can change. Clients MUST ignore properties that appear in this mapping if their values can change.
If properties that could change were included, the following race condition would be likely to exist in some cases:
We've taken the opportunity to make the API encourage the client author to get it right. Where possible, we intend that properties whose value will be used in channel dispatching or other "early" processing will be defined so that they are immutable (can never change).
Each dictionary MUST contain the keys
We expect these to be crucial to the channel-dispatching process.
Request that an entirely new channel is created.
There is deliberately no flag corresponding to the
suppress_handler argument to
A dictionary containing desirable properties, which MUST include
If this dictionary contains a property whose semantics are not known to the connection manager, this method MUST fail without side-effects (in particular it must not create a new channel).
This is necessary if we want to be able to invent properties in future that, when used in a request, are hard requirements rather than just hints. A connection manager that did not know the semantics of those properties could incorrectly return a new channel that did not satisfy the requirements.
The connection manager MUST NOT respond successfully, and SHOULD NOT create a new channel or cause any other side-effects, unless it can create a new channel that satisfies the client's requirements.
Properties that will be set by this argument need not have write access after the channel has been created - indeed, it is expected that most will be read-only.
The Channel object, which MUST NOT be signalled with
This allows the requester to alter its handling of NewChannels by knowing whether one of the channels satisfied a request it made.
Properties of the channel that was produced, equivalent to
the properties in
The requested channel cannot be created, but in principle, a similar request might succeed in future. For instance, this might be because:
Request that channels are ensured to exist.
The connection manager is in the best position to determine which existing channels could satisfy which requests.
A dictionary containing desirable properties, with the same
semantics as the corresponding parameter to
If false, the caller of EnsureChannel MUST assume that some other process is handling this channel; if true, the caller of EnsureChannel SHOULD handle it themselves or delegate it to another client.
If the creation of a channel makes several calls to EnsureChannel (and no other requests) successful, exactly one of those calls MUST return a true value for this argument.
If the creation of a channel makes other requests successful,
the value returned for this argument MUST be such that exactly
one of the clients making requests ends up responsible for the
channel. In particular, if
This allows the requester to alter its handling of NewChannels by knowing whether one of the channels satisfied a request it made.
Properties of the channel that was produced, equivalent to
the properties in
New channels have been created. The connection manager SHOULD emit a single signal for any group of closely related channels that are created at the same time, so that the channel dispatcher can try to dispatch them to a handler as a unit.
In particular, if additional channels are created as a side-effect
of a call to
Joining a MUC Tube in XMPP requires joining the corresponding
MUC (chatroom), so a
Every time NewChannels is emitted, it MUST be followed by
a
The double signal emission is for the benefit of older Telepathy clients, which won't be listening for NewChannels.
The more informative NewChannels signal comes first so that clients that did not examine the connection to find out whether Requests is supported will see the more informative signal for each channel first, and then ignore the less informative signal because it announces a new channel of which they are already aware.
Mapping representing a class of channels that can be requested from a connection manager, can be handled by a user interface, are supported by a contact, etc.
Classes of channel are identified by the fixed values of a subset of their properties.
Channel classes SHOULD always include the keys
Structure representing a class of channels that can be requested, identified by a set of properties that identify that class of channel.
This will often just be the channel type and the handle type, but can include other properties of the channel - for instance, encrypted channels might require properties that unencrypted channels do not, like an encryption key.
In some cases, these classes of channel may overlap, in the sense that one class fixes all the properties that another class does, plus some more properties.
For older clients to still be able to understand how to request channels in the presence of a hypothetical "encryption" interface, we'd need to represent it like this:
The property values that identify this requestable channel class. These properties MUST be included in requests for a channel of this class, and MUST take these values.
Clients that do not understand the semantics of all the Fixed_Properties MUST NOT request channels of this class, since they would be unable to avoid making an incorrect request.
This implies that connection managers wishing to make channels available to old or minimal clients SHOULD have a channel class with the minimum number of Fixed_Properties, and MAY additionally have channel classes with extra Fixed_Properties.
Interface designers SHOULD avoid introducing fixed properties
whose types are not serializable in a .manager
file.
Connection managers with a fixed property that is not
serializable cannot have a complete .manager
file.
Properties that MAY be set when requesting a channel of this channel type and handle type.
This array MUST NOT include properties that are in the Fixed_Properties mapping.
Properties in this array may either be required or optional, according to their documented semantics.
For instance, if TargetHandleType takes a value that is not Handle_Type_None, one or the other of TargetHandle and TargetID is required. Clients are expected to understand the documented relationship between the properties, so we do not have separate arrays of required and optional properties.
If this array contains the
The classes of channel that are expected to be available on this
connection, i.e. those for which
This property cannot change after the connection has gone to state Connection_Status_Connected, so there is no change notification (if the connection has context-dependent capabilities, it SHOULD advertise support for all classes of channel that it might support during its lifetime). Before this state has been reached, the value of this property is undefined.
This is not on an optional interface, because connection managers can always offer some sort of clue about the channel classes they expect to support (at worst, they can announce support for everything for which they have code).
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.
Some protocols support mechanisms for reducing bandwidth usage—and
hence power usage, on mobile devices—when the user is not directly
interacting with their IM client. For instance, Google Talk's XMPP
server supports queueing incoming presence updates at the client's
instruction; the client can instruct the server to deliver all
outstanding presence updates at a later time. This interface may be
used to instruct the connection manager to enable and disable such
protocol-level features when a screensaver is activated, the device
screen is locked, and so on, by calling the
Enabling power saving SHOULD NOT change behaviour in any way
that is noticable to a user not actively interacting with their client.
For example, delaying presence updates somewhat is unlikely to be
noticed by a user not staring at their device waiting for a contact to
come online; on the other hand, requesting that the server queue
incoming messages would be noticable by the user, so is not an
acceptable effect of calling
Turn power saving mode on or off.
Depending on the device's activity level, the connection can have its power saving mode turned on or off.
Errors raised by this method indicate that power saving could not be enabled, which SHOULD NOT generally be treated as fatal.
NotImplemented), or because of the service
(NotAvailable), Mission Control (or whoever manages this)
should be made aware. The error could be ignored or, in the extreme,
be fascist and disconnect the account.
True if protocol-level power saving features should be
activated; False if they should be de-activated.
True if protocol-level power saving features are
currently activated. This property can be changed using the
A channel type for making audio and video calls. Call
channels supersede the old
Handlers are advised against executing all the media signalling, codec and candidate negotiation themselves but instead use a helper library such as telepathy-farsight which when given a new Call channel will set up the transports and codecs and create GStreamer pads which can be added to the handler UI. This is useful as it means the handler does not have to worry how exactly the connection between the call participants is being made.
The
To make an audio-only call to a contact foo@example.com handlers should call: