Interface Connection.Interface.ContactList.DRAFT2

Interface Index (Compact) | Summary | Description | Methods | Signals | Properties | Contact Attributes | Types

Methods

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

ContactsChanged (a{u(uus)}: Changes, au: Removals)

Properties

SubscriptionsPersist b Read only
CanChangeSubscriptions b Read only
RequestUsesMessage b Read only

Contact Attributes

org.freedesktop.Telepathy.Connection.Interface.ContactList.DRAFT2/subscribe u (Presence_State)
org.freedesktop.Telepathy.Connection.Interface.ContactList.DRAFT2/publish u (Presence_State)
org.freedesktop.Telepathy.Connection.Interface.ContactList.DRAFT2/publish-request s

Types

Presence_State Enum u
Contact_Metadata_Storage_Type Enum u
Contact_Subscription_Map Mapping a{u(uus)}
Contact_Subscriptions Struct (uus)
WARNING: This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Do not include this interface in libraries that care about compatibility.
Added in 0.19.8. (draft 2)
Objects implementing this interface must also implement:

Description

An interface for connections that have any concept of a list of known contacts (roster, buddy list, friends list etc.)

Rationale:

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.18 and older, we represented contact lists as a collection of ContactList channels. This is remarkably difficult to work with in practice - every client that cares about contact lists has to take the union of some hard-to-define set of these channels - and conflicts with the idea that channels that cannot be dispatched to a handler should be closed.

The list of contacts is not exposed as a D-Bus property; it can be fetched using RequestContactList.

Rationale:

In some protocols, such as XMPP, the contact list may not be available immediately. The RequestContactList method will wait until the contact list is available before returning. Using a method also allows extra attributes to be retrieved at the same time.

Methods

(Permalink)

RequestContactList (as: Interfaces, b: Hold) → a{ua{sv}}: Attributes

Changed in 0.19.8. (in draft: renamed from GetContactListAttributes)

Parameters

  • Interfaces — as (DBus_Interface_List)

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

  • Hold — b

    • Whether to hold the handles on behalf of the calling process. Equivalent to the corresponding argument to GetContactAttributes.

    FIXME: if we do distributed refcounting, we should probably rename this to 'Reference' and implement handle-refcounting semantics first? On the other hand, if we make handles persist for the lifetime of the connection, we can just remove this parameter.

Returns

Return some contact attributes for a list of contacts somehow associated with the user.

This definition is deliberately vague: in practice, most user interfaces should display some subset of this list, by filtering it by some contact attributes (for instance, displaying all contacts whose "subscribe" attribute is Yes is expected to be a common case). This list MAY contain any contacts whatsoever, but MUST contain at least the following:

  • all contacts whose "subscribe" attribute is Ask or Yes
  • all contacts whose "publish" attribute is Ask or Yes
  • all contacts with a persistently-stored stored alias, if supported
  • all contacts in user-defined contact groups, if supported

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 either, unless they are still stored in a persistent roster/contact list as well as being blocked.

Rationale:

This is basically the union of the historical ContactList subscribe, publish and stored channels.

For example, XMPP, it's the roster; on link-local XMPP, it's the set of visible users on the local network; on MSN, it's the union of the forward and reverse buddy lists.

An easy way for an application to display a contact list is to call this method with at least this interface in the Interfaces argument, then check which subset of contacts should be displayed (perhaps based on their subscribe attribute, for instance) and display them. Any additional information required to display the contact list, like aliases or presence, can be retrieved at the same time.

In practice, most user interfaces for the contact list will usually display a large proportion of this list (for instance, most contacts on the contact list will usually have subscribe=Yes in practice, so contact lists that display subscribe=Yes contacts need to display almost the entire list), so the overhead of returning information about too many contacts is small.

This method SHOULD NOT return before the contact list has been retrieved, on protocols where this is possible. As a result, clients SHOULD use a longer-than-default timeout for this method call, since retrieving the contact list can take a significant time on some servers.

Rationale:

This makes it possible for clients to wait for the contact list. For instance, on XMPP this method shouldn't return until the roster has been retrieved, which is an asynchronous process. However, on link-local XMPP you can't know when you have the complete list, so this method would have to return immediately.

Possible Errors

  • Disconnected
    • The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
    Rationale:
    The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
(Permalink)

RequestSubscription (au: Contacts, s: Message) → nothing

Parameters

  • Contacts — au (Contact_Handle_List)

    • One or more contacts to whom requests are to be sent.

  • Message — s

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

    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.

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

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, this method SHOULD request that the contact allows the local user to subscribe to their presence; in general, this will change their publish attribute from No to Ask (although it could change directly from No to Yes in some situations).

Any state changes that immediately result from this request MUST be signalled via ContactsChanged before this method returns.

Rationale:

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 they explicitly reject the request (in protocols that allow this), their subscribe attribute will later change from Ask to No.

Possible Errors

  • Disconnected
    • The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
    Rationale:
    The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  • Invalid Handle
    • The handle specified is unknown on this channel or connection.
  • Network Error
    • Raised when there is an error reading from or writing to the network.
  • Not Implemented
    • It was not possible to perform the requested action, because CanChangeSubscriptions is false.
(Permalink)

AuthorizePublication (au: Contacts) → nothing

Parameters

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.

Rationale:

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 ContactsChanged before this method returns.

Rationale:

This makes it easy for user interfaces to see what practical effect this method had.

Possible Errors

  • Disconnected
    • The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
    Rationale:
    The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  • Invalid Handle
    • The handle specified is unknown on this channel or connection.
  • Network Error
    • Raised when there is an error reading from or writing to the network.
  • Not Implemented
    • It was not possible to perform the requested action, because CanChangeSubscriptions is false.
(Permalink)

RemoveContacts (au: Contacts) → nothing

Parameters

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

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:

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.

Possible Errors

  • Disconnected
    • The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
    Rationale:
    The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  • Invalid Handle
    • The handle specified is unknown on this channel or connection.
  • Network Error
    • Raised when there is an error reading from or writing to the network.
  • Not Implemented
    • It was not possible to perform the requested action because CanChangeSubscriptions is false.
(Permalink)

Unsubscribe (au: Contacts) → nothing

Parameters

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.

Possible Errors

  • Disconnected
    • The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
    Rationale:
    The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  • Invalid Handle
    • The handle specified is unknown on this channel or connection.
  • Network Error
    • Raised when there is an error reading from or writing to the network.
  • Not Implemented
    • It was not possible to perform the requested action because CanChangeSubscriptions is false.
(Permalink)

Unpublish (au: Contacts) → nothing

Parameters

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.

Possible Errors

  • Disconnected
    • The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
    Rationale:
    The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  • Invalid Handle
    • The handle specified is unknown on this channel or connection.
  • Network Error
    • Raised when there is an error reading from or writing to the network.
  • Not Implemented
    • It was not possible to perform the requested action because CanChangeSubscriptions is false.

Signals

(Permalink)

ContactsChanged (a{u(uus)}: Changes, au: Removals)

Parameters

  • Changes — a{u(uus)} (Contact_Subscription_Map)
    • The new subscribe, publish and publish-request attributes of all the contacts that have been added, and all the contacts for which those attributes have changed.
  • Removals — au (Contact_Handle_List)
    • The contacts that have been removed from the list that would be returned by RequestContactList. This also implies that they have subscribe = No and publish = No; contacts MUST NOT be listed both here and in Changes.

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 RequestContactList, or when contacts are removed from that list.

Rationale:

This provides change notification for that list, and for contacts' "subscribe", "publish" and "publish-request" attributes.

Properties

Accessed using the org.freedesktop.DBus.Properties interface.
(Permalink)

SubscriptionsPersist — b

Read only

If true, presence subscriptions (in both directions) on this connection are stored by the server or other infrastructure.

Rationale:

XMPP, MSN, ICQ, etc. all behave like this.

If false, presence subscriptions on this connection are not stored.

Rationale:

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 CanChangeSubscriptions 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 SubscriptionsPersist is false, clients MAY do this for all contacts; if SubscriptionsPersist is true, clients SHOULD NOT change the state of contacts that were not changed locally.

Rationale:

In SIMPLE (SIP), SubscriptionsPersist is false, but CanChangeSubscriptions 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.

(Permalink)

CanChangeSubscriptions — b

Read only

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:

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.

(Permalink)

RequestUsesMessage — b

Read only

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:

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.

Rationale:

FIXME: is there any such protocol?

Contact Attributes

Attributes that a contact can have, accessed with the org.freedesktop.Telepathy.Connection.Interface.Contacts interface.
(Permalink)

org.freedesktop.Telepathy.Connection.Interface.ContactList.DRAFT2/subscribe — u (Presence_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:

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 No or Ask, 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:

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.

This attribute SHOULD be omitted from the Contact_Attributes_Map returned by GetContactAttributes until the initial contact list has been received, in protocols where this is applicable. Clients MAY wait for this by calling RequestContactList.

(Permalink)

org.freedesktop.Telepathy.Connection.Interface.ContactList.DRAFT2/publish — u (Presence_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:

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 No or Ask, 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:

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.

This attribute SHOULD be omitted from the Contact_Attributes_Map returned by GetContactAttributes until the initial contact list has been received, in protocols where this is applicable. Clients MAY wait for this by calling RequestContactList.

(Permalink)

org.freedesktop.Telepathy.Connection.Interface.ContactList.DRAFT2/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:

If the contact asking to receive our presence is also using Telepathy, this is the message they supplied as the Message argument to RequestSubscription.

Otherwise, this SHOULD be omitted.

This attribute SHOULD be omitted from the Contact_Attributes_Map returned by GetContactAttributes until the initial contact list has been received. Clients MAY wait for this by calling RequestContactList.

Types

Enum (Permalink)

Presence_State — u

A tristate indicating whether presence subscription is denied, denied but pending permission, or allowed. The exact semantics vary according to where this type is used.

  • No (0)
    • Presence information cannot be seen.
  • Ask (1)
    • Presence information cannot be seen, but permission to see presence information has been requested.
  • Yes (2)
    • Presence information can be seen.
Enum (Permalink)

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.
  • None (0)

    • This connection cannot store this type of metadata at all, and attempting to do so will fail with NotImplemented.

    Rationale:

    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.

  • Subscribed_Or_Pending (1)

    • This type of metadata can only be stored permanently for contacts whose subscribe attribute is Ask or Yes.

    Rationale:

    Contact aliases and groups on MSN have this behaviour.

    If this type of metadata is set on a contact with subscribe=No, the Connection MUST cache it until disconnected, and return it if requested. If subscription to the contact's presence is subsequently requested, making it possible to store this metadata, the Connection MUST store the cached value at that time.

    Rationale:

    This supports the recommended calling pattern for adding a new contact, in which alias and groups are set (without necessarily waiting for a reply) before requesting the contact's presence. Until the subscription request is processed by the server, the alias and groups will be cached in memory; when the subscription request has been processed, the connection manager will store the metadata on the server.

  • Subscribed (2)

    • This type of metadata can only be stored permanently for contacts whose subscribe attribute is Yes.

    Rationale:

    No service with this behaviour is currently known, but it's a stricter form of Subscribed_Or_Pending.

    If this type of metadata is set on a contact with subscribe != Yes, the Connection MUST cache it until disconnected, and return it if requested. If subscription to the contact's presence is subsequently allowed, making it possible to store this metadata, the Connection MUST store the cached value at that time.

    Rationale:

    The same rationale applies as for Subscribed_Or_Pending, except that metadata must be stored until the subscription request is not only processed by the server, but also allowed by the remote user.

  • Anyone (3)

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

Mapping (Permalink)

Contact_Subscription_Map — a{u(uus)}

A map from contacts to their subscribe, publish and publish-request attributes.
Struct (Permalink)

Contact_Subscriptions — (uus)

A single contact's subscribe, publish and publish-request attributes.
  • Subscribe — u (Presence_State)
    • The new value of the contact's "subscribe" attribute.
  • Publish — u (Presence_State)
    • The new value of the contact's "publish" attribute.
  • Publish_Request — s
    • The new value of the contact's "publish-request" attribute, or the empty string if that attribute would be omitted.