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
If true, all handles that appear as keys in the result have been
held on behalf of the calling process, as if by a call 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.
Connection managers SHOULD NOT attempt to enforce a
mutual-subscription policy (i.e. when this method is called, they
should not automatically allow the contacts to see the local user's
presence). User interfaces that require mutual subscription
MAY call
Whether to enforce mutual subscription is a matter of policy, so it is left to the user interface and/or the server.
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
The user MAY be prompted using the contact's current self-assigned nickname, or something derived from the contact's (presumably self-assigned) identifier, as a default, but these names chosen by the contact SHOULD NOT be used without user approval.
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.
Connection managers SHOULD NOT attempt to enforce a
mutual-subscription policy (i.e. when this method is called, they
should not automatically request that the contacts allow the user to
subscribe to their presence). User interfaces that require mutual
subscription MAY call
Whether to enforce mutual subscription is a matter of policy, so it is left to the user interface and/or the server.
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.