Methods
GetContactListAttributes | (as: Interfaces, b: Hold) | → | a{ua{sv}}: Attributes | |
RequestSubscription | (au: Contacts, s: Message) | → | nothing | |
AuthorizePublication | (au: Contacts) | → | nothing | |
RemoveContacts | (au: Contacts) | → | nothing | |
Unsubscribe | (au: Contacts) | → | nothing | |
Unpublish | (au: Contacts) | → | nothing |
Signals
ContactListStateChanged | (u: Contact_List_State) | |
ContactsChangedWithID | (a{u(uus)}: Changes, a{us}: Identifiers, a{us}: Removals) | |
ContactsChanged | (a{u(uus)}: Changes, au: Removals) | (deprecated) |
Properties
ContactListState | u (Contact_List_State) | Read only | ||
ContactListPersists | b | Read only | ||
CanChangeContactList | b | Read only | ||
RequestUsesMessage | b | Read only |
Contact Attributes
Types
Contact_List_State | Enum | u | |
Subscription_State | Enum | u | |
Contact_Metadata_Storage_Type | Enum | u | |
Contact_Subscription_Map | Mapping | a{u(uus)} | |
Contact_Subscriptions | Struct | (uus) |
Description
An interface for connections that have any concept of a list of known contacts (roster, buddy list, friends list etc.)
Rationale:
The list of contacts is not exposed as a D-Bus property; it can be fetched using GetContactListAttributes.
Rationale:
Methods
GetContactListAttributes (as: Interfaces, b: Hold) → a{ua{sv}}: Attributes
Parameters
- Interfaces — as (DBus_Interface_List)
- Hold — b
A list of strings indicating which D-Bus interfaces the calling process is interested in. Equivalent to the corresponding argument to GetContactAttributes, except that if this list does not contain the ContactList interface itself, it is treated as though that interface was also requested.
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 Connection.HoldHandles. (If HasImmortalHandles is true, which SHOULD be the case in all new connection managers, this has no effect.)
Returns
- Attributes — a{ua{sv}} (Contact_Attributes_Map)
A dictionary mapping the contact handles to contact attributes, equivalent to the result of GetContactAttributes.
Return some contact attributes for a list of contacts associated with the user. This list MUST include at least:
but MAY contain other contacts.
Rationale:
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 subscribe or publish attribute for some reason.
Rationale:
Possible Errors
- Network Error
- Not Implemented
- Not Available
- Service Busy
- Not Yet
Rationale:
The ContactListState is None or Waiting. In particular, this error is raised if the Status is not yet Connection_Status_Connected.
RequestSubscription (au: Contacts, s: Message) → nothing
Parameters
- Contacts — au (Contact_Handle_List)
- Message — s
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 RequestUsesMessage property indicates whether this message will be used or ignored.
Clients SHOULD NOT send a non-empty message without first giving the user an opportunity to edit it.
Rationale:
Connections where this message is not useful MUST still allow it to be non-empty.
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 AuthorizePublication at the same time as this method.
Rationale:
Before calling this method on a connection where GetAliasFlags returns the User_Set
flag,
user interfaces SHOULD obtain, from the user, an alias to
identify the contact in future, and store it using SetAliases.
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.
Rationale:
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 ContactsChanged before this method returns.
Rationale:
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 ContactListState changes to Success. If the ContactListState changes to Failure, this method SHOULD raise the same error as GetContactListAttributes.
Possible Errors
- Disconnected
- Invalid Handle
- Network Error
- Not Yet
- Not Implemented
Rationale:
AuthorizePublication (au: Contacts) → nothing
Parameters
- Contacts — au (Contact_Handle_List)
One or more contacts to authorize.
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 RequestSubscription at the same time as this method.
Rationale:
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.
Rationale:
Any state changes that immediately result from this request MUST be signalled via ContactsChanged before this method returns.
Rationale:
This method SHOULD NOT be called until the ContactListState changes to Success. If the ContactListState changes to Failure, this method SHOULD raise the same error as GetContactListAttributes.
Possible Errors
- Disconnected
- Invalid Handle
- Network Error
- Not Implemented
- Not Yet
Rationale:
RemoveContacts (au: Contacts) → nothing
Parameters
- Contacts — au (Contact_Handle_List)
One or more contacts to remove.
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 GetContactListAttributes.
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.
Rationale:
This method SHOULD NOT be called until the ContactListState changes to Success. If the ContactListState changes to Failure, this method SHOULD raise the same error as GetContactListAttributes.
Possible Errors
- Disconnected
- Invalid Handle
- Network Error
- Not Implemented
- Not Yet
Rationale:
Unsubscribe (au: Contacts) → nothing
Parameters
- Contacts — au (Contact_Handle_List)
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 RemoveContacts, this method SHOULD succeed even if it was not possible to carry out the request entirely or for all contacts; however, all signals that immediately result from this method call MUST be emitted before it returns.
This method SHOULD NOT be called until the ContactListState changes to Success. If the ContactListState changes to Failure, this method SHOULD raise the same error as GetContactListAttributes.
Possible Errors
- Disconnected
- Invalid Handle
- Network Error
- Not Implemented
Rationale:
Unpublish (au: Contacts) → nothing
Parameters
- Contacts — au (Contact_Handle_List)
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 RemoveContacts, this method SHOULD succeed even if it was not possible to carry out the request entirely or for all contacts; however, all signals that immediately result from this method call MUST be emitted before it returns.
This method SHOULD NOT be called until the ContactListState changes to Success. If the ContactListState changes to Failure, this method SHOULD raise the same error as GetContactListAttributes.
Possible Errors
- Disconnected
- Invalid Handle
- Network Error
- Not Implemented
- Not Yet
Rationale:
Signals
ContactListStateChanged (u: Contact_List_State)
Parameters
- Contact_List_State — u (Contact_List_State)
ContactsChangedWithID (a{u(uus)}: Changes, a{us}: Identifiers, a{us}: Removals)
Parameters
- Changes — a{u(uus)} (Contact_Subscription_Map)
- Identifiers — a{us} (Handle_Identifier_Map)
- Removals — a{us} (Handle_Identifier_Map)
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 GetContactListAttributes, or when contacts are removed from that list.
Rationale:
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
Rationale:
ContactsChanged (a{u(uus)}: Changes, au: Removals)
Parameters
- Changes — a{u(uus)} (Contact_Subscription_Map)
- Removals — au (Contact_Handle_List)
Emitted immediately after ContactsChangedWithID, under the same circumstances.
If clients receive this signal without first receiving a corresponding ContactsChangedWithID, they MUST assume that only this signal will be emitted.
Properties
ContactListState — u (Contact_List_State)
ContactListPersists — b
If true, presence subscriptions (in both directions) on this connection are stored by the server or other infrastructure.
Rationale:
If false, presence subscriptions on this connection are not stored.
Rationale:
If CanChangeContactList is true, Telepathy clients (e.g. user interfaces or address books) MAY keep a record of permission to publish and requests to subscribe locally, and attempt to restore it for each Connection. If ContactListPersists is false, clients MAY do this for all contacts; if ContactListPersists is true, clients SHOULD NOT change the state of contacts that were not changed locally.
Rationale:
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.
CanChangeContactList — b
If true, presence subscription and publication can be changed using the RequestSubscription, AuthorizePublication and RemoveContacts methods.
If false, all of those methods will always fail; they SHOULD raise the error org.freedesktop.Telepathy.Error.NotImplemented.
Rationale:
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.
RequestUsesMessage — b
If true, the Message parameter to RequestSubscription is likely to be significant, and user interfaces SHOULD prompt the user for a message to send with the request; a message such as "I would like to add you to my contact list", translated into the local user's language, might make a suitable default.
Rationale:
If false, the parameter is ignored; user interfaces SHOULD avoid prompting the user, and SHOULD pass an empty string to RequestSubscription.
Rationale:
Contact Attributes
org.freedesktop.Telepathy.Connection.Interface.ContactList/subscribe — u (Subscription_State)
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.
Rationale:
If this attribute is not Yes, the local user cannot generally expect to receive presence from this contact. Their presence status as returned by GetPresences is likely to be (Unknown, "unknown", ""), unless the local user can temporarily see their presence for some other reason (for instance, on XMPP, contacts seen in chatrooms will temporarily have available presence).
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.
Rationale:
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 Unsubscribe or RemoveContacts, which will set subscribe to No (and perhaps remove the contact). This allows user interfaces to detect that the user has been notified about the rejected request.
This attribute's value will be Unknown or omitted until the ContactListState has changed to Success.
org.freedesktop.Telepathy.Connection.Interface.ContactList/publish — u (Subscription_State)
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.).
Rationale:
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.
Rationale:
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 Unpublish or RemoveContacts.
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 ContactListState has changed to Success.
org.freedesktop.Telepathy.Connection.Interface.ContactList/publish-request — s
If the publish attribute is Ask, an optional message that was sent by the contact asking to receive the local user's presence; omitted if none was given.
Rationale:
Otherwise, this SHOULD be omitted.
This attribute will also be omitted until the ContactListState has changed to Success.
Types
Contact_List_State — u
- None (0)
- Waiting (1)
- Failure (2)
- Success (3)
The connection has tried and failed to retrieve the contact list. If GetContactListAttributes is called in this state, it will immediately raise an error indicating the reason for failure.
The connection manager SHOULD try again to obtain the contact list, if appropriate for the protocol. If it succeeds later, the ContactListState MUST advance to Success.
Subscription_State — u
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 subscribe and publish contact attributes for details.
- Unknown (0)
- No (1)
- Removed_Remotely (2)
- Ask (3)
- Yes (4)
Contact_Metadata_Storage_Type — u
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.
Rationale:
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.
Rationale:
- None (0)
- Subscribed_Or_Pending (1)
- Subscribed (2)
- Anyone (3)
This connection cannot store this type of metadata at all, and attempting to do so will fail with NotImplemented.
Rationale:
This type of metadata can only be stored permanently for contacts whose subscribe attribute is Ask or Yes.
Rationale:
This type of metadata can only be stored permanently for contacts whose subscribe attribute is Yes.
Rationale:
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.
Rationale:
Contact_Subscription_Map — a{u(uus)}
- Contact — u (Contact_Handle)
- States — (uus) (Contact_Subscriptions)
Contact_Subscriptions — (uus)
- Subscribe — u (Subscription_State)
- Publish — u (Subscription_State)
- Publish_Request — s