diff options
Diffstat (limited to 'spec/Connection_Interface_Contact_List.xml')
| -rw-r--r-- | spec/Connection_Interface_Contact_List.xml | 492 |
1 files changed, 322 insertions, 170 deletions
diff --git a/spec/Connection_Interface_Contact_List.xml b/spec/Connection_Interface_Contact_List.xml index 9db86aa..d602c19 100644 --- a/spec/Connection_Interface_Contact_List.xml +++ b/spec/Connection_Interface_Contact_List.xml @@ -18,10 +18,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactList.DRAFT2" - tp:causes-havoc="experimental"> + <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactList"> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <tp:added version="0.19.8">(draft 2)</tp:added> + <tp:added version="0.21.0">(as stable API)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An interface for connections that have any concept of a list of @@ -35,7 +34,7 @@ <p>In some protocols (like link-local XMPP), while there might not be any server or roster, it's possible to list "nearby" contacts.</p> - <p>In Telepathy 0.18 and older, we represented contact lists as a + <p>In Telepathy 0.20 and older, we represented contact lists as a collection of <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type" >ContactList</tp:dbus-ref> channels. This is remarkably difficult to @@ -46,87 +45,115 @@ </tp:rationale> <p>The list of contacts is not exposed as a D-Bus property; it can be - fetched using <tp:member-ref>RequestContactList</tp:member-ref>. + fetched using <tp:member-ref>GetContactListAttributes</tp:member-ref>. </p> <tp:rationale> <p>In some protocols, such as XMPP, the contact list may not be available immediately. The - <tp:member-ref>RequestContactList</tp:member-ref> method - will wait until the contact list is available before returning. + <tp:member-ref>GetContactListAttributes</tp:member-ref> method + will fail until the contact list is available. Using a method also allows extra attributes to be retrieved at the same time.</p> </tp:rationale> </tp:docstring> - <method name="RequestContactList" - tp:name-for-bindings="Request_Contact_List"> - <tp:changed version="0.19.8">(in draft: renamed from - GetContactListAttributes)</tp:changed> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Return some contact attributes for a list of contacts somehow - associated with the user.</p> + <tp:enum name="Contact_List_State" type="u"> + <tp:docstring> + The progress made in retrieving the contact list. + </tp:docstring> + + <tp:enumvalue suffix="None" value="0"> + <tp:docstring>The connection has not started to retrieve the contact + list. If <tp:member-ref>GetContactListAttributes</tp:member-ref> is + called in this state, it will raise NotYet.</tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Waiting" value="1"> + <tp:docstring>The connection has started to retrieve the contact + list, but has not yet succeeded or failed. + If <tp:member-ref>GetContactListAttributes</tp:member-ref> is called + in this state, it will raise NotYet.</tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Failure" value="2"> + <tp:docstring> + <p>The connection has tried and failed to retrieve the contact + list. If <tp:member-ref>GetContactListAttributes</tp:member-ref> + is called in this state, it will immediately raise an error + indicating the reason for failure.</p> + + <p>The connection manager SHOULD try again to obtain the contact + list, if appropriate for the protocol. If it succeeds later, + the <tp:member-ref>ContactListState</tp:member-ref> MUST advance + to Success.</p> + </tp:docstring> + </tp:enumvalue> - <p>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:</p> + <tp:enumvalue suffix="Success" value="3"> + <tp:docstring>The connection has successfully retrieved the contact + list. If <tp:member-ref>GetContactListAttributes</tp:member-ref> + is called in this state, it will return successfully.</tp:docstring> + </tp:enumvalue> + </tp:enum> + + <property name="ContactListState" tp:name-for-bindings="Contact_List_State" + type="u" tp:type="Contact_List_State" access="read"> + <tp:docstring> + The progress made in retrieving the contact list. + Change notification is via + <tp:member-ref>ContactListStateChanged</tp:member-ref>. + </tp:docstring> + </property> + + <signal name="ContactListStateChanged" + tp:name-for-bindings="Contact_List_State_Changed"> + <tp:docstring> + Emitted when <tp:member-ref>ContactListState</tp:member-ref> + changes. + </tp:docstring> + + <arg name="Contact_List_State" type="u" tp:type="Contact_List_State"> + <tp:docstring> + The new value of <tp:member-ref>ContactListState</tp:member-ref>. + </tp:docstring> + </arg> + </signal> + + <method name="GetContactListAttributes" + tp:name-for-bindings="Get_Contact_List_Attributes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Return some contact attributes for a list of contacts + associated with the user. This list MUST include at least:</p> <ul> - <li>all contacts whose "subscribe" attribute is Ask or Yes</li> - <li>all contacts whose "publish" attribute is Ask or Yes</li> - <li>all contacts with a persistently-stored stored alias, if - supported</li> - <li>all contacts in user-defined contact groups, if supported</li> + <li>all contacts whose <tp:token-ref>subscribe</tp:token-ref> + attribute is not No</li> + <li>all contacts whose <tp:token-ref>publish</tp:token-ref> + attribute is not No</li> </ul> - <p>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.</p> + <p>but MAY contain other contacts.</p> <tp:rationale> - <p>This is basically the union of the historical <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type" - >ContactList</tp:dbus-ref> subscribe, publish and stored - channels.</p> - - <p>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.</p> - - <p>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.</p> - - <p>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.</p> + <p>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).</p> </tp:rationale> - <p>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.</p> + <p>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-<tt>No</tt> <tp:token-ref>subscribe</tp:token-ref> or + <tp:token-ref>publish</tp:token-ref> attribute + for some reason.</p> <tp:rationale> - <p>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.</p> + <p>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.</p> </tp:rationale> </tp:docstring> @@ -150,12 +177,6 @@ Equivalent to the corresponding argument to <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts" >GetContactAttributes</tp:dbus-ref>.</p> - - <p><em>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.</em></p> </tp:docstring> </arg> @@ -171,31 +192,64 @@ </arg> <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotYet"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The <tp:member-ref>ContactListState</tp:member-ref> is + None or Waiting. In particular, this error is raised if the + <tp:dbus-ref namespace="ofdT.Connection">Status</tp:dbus-ref> + is not yet Connection_Status_Connected.</p> + </tp:docstring> + </tp:error> </tp:possible-errors> </method> - <tp:enum name="Presence_State" type="u"> + <tp:enum name="Subscription_State" type="u"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A tristate indicating whether presence subscription is denied, + <p>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.</p> + vary according to where this type is used: see the + <tp:token-ref>subscribe</tp:token-ref> and + <tp:token-ref>publish</tp:token-ref> contact attributes for + details.</p> </tp:docstring> - <tp:enumvalue suffix="No" value="0"> - <tp:docstring>Presence information cannot be seen.</tp:docstring> + <tp:enumvalue suffix="Unknown" value="0"> + <tp:docstring>The presence subscription state is + unknown.</tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="No" value="1"> + <tp:docstring>Presence information cannot be seen, and either the + subscription state Removed_Remotely does not apply, or it is + not known whether that state applies. + </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="Ask" value="1"> - <tp:docstring>Presence information cannot be seen, but permission - to see presence information has been requested.</tp:docstring> + + <tp:enumvalue suffix="Removed_Remotely" value="2"> + <tp:docstring>Presence information cannot be seen because the + remote contact took action: either the local user's request to + see the remote contact's presence was denied, or the remote + contact requested to see the local user's presence but then + cancelled their request.</tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Ask" value="3"> + <tp:docstring>Presence information cannot be seen. Permission + to see presence information has been requested, and the request + has not yet been declined or accepted.</tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="Yes" value="2"> + + <tp:enumvalue suffix="Yes" value="4"> <tp:docstring>Presence information can be seen.</tp:docstring> </tp:enumvalue> </tp:enum> <tp:contact-attribute name="subscribe" - type="u" tp:type="Presence_State"> + type="u" tp:type="Subscription_State"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If this attribute on a contact is Yes, this connection can expect to receive their presence, along with any other information @@ -207,7 +261,7 @@ the local user's buddy list" in ICQ, for example.</p> </tp:rationale> - <p>If this attribute is No or Ask, the local user cannot generally + <p>If this attribute is not Yes, the local user cannot generally expect to receive presence from this contact. Their presence status as returned by <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence">GetPresences</tp:dbus-ref> @@ -229,18 +283,30 @@ asked during the current session will ever have Ask status.</p> </tp:rationale> - <p>This attribute SHOULD be omitted from the - <tp:type>Contact_Attributes_Map</tp:type> returned by - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts" - >GetContactAttributes</tp:dbus-ref> until the initial contact - list has been received, in protocols where this is applicable. - Clients MAY wait for this by calling - <tp:member-ref>RequestContactList</tp:member-ref>.</p> + <p>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.</p> + + <p>After notifying the user, user interfaces MAY acknowledge a change + to <tt>subscribe</tt>=Removed_Remotely by calling either + <tp:member-ref>Unsubscribe</tp:member-ref> or + <tp:member-ref>RemoveContacts</tp:member-ref>, which will set + <tt>subscribe</tt> to No (and perhaps remove the contact). This + allows user interfaces to detect that the user has been notified + about the rejected request.</p> + + <p>This attribute's value will be Unknown or omitted until the + <tp:member-ref>ContactListState</tp:member-ref> has changed to + Success.</p> </tp:docstring> </tp:contact-attribute> <tp:contact-attribute name="publish" - type="u" tp:type="Presence_State"> + type="u" tp:type="Subscription_State"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If this attribute on a contact is Yes, the local user's presence is published to that contact, along with any other information that @@ -254,12 +320,12 @@ the contact's buddy list" in ICQ, for example.</p> </tp:rationale> - <p>If this attribute is No or Ask, the + <p>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.</p> - <p>It is implementation-dependent whether contacts' publish + <p>It is implementation-dependent whether contacts' <tt>publish</tt> attributes can remain set to Ask, or are reset to No, when the connection disconnects.</p> @@ -270,21 +336,32 @@ during the current session will ever have Ask status.</p> </tp:rationale> - <p>This attribute SHOULD be omitted from the - <tp:type>Contact_Attributes_Map</tp:type> returned by - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts" - >GetContactAttributes</tp:dbus-ref> until the initial contact - list has been received, in protocols where this is applicable. - Clients MAY wait for this by calling - <tp:member-ref>RequestContactList</tp:member-ref>.</p> + <p>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 <tt>publish</tt> from + Removed_Remotely to No, by calling either + <tp:member-ref>Unpublish</tp:member-ref> or + <tp:member-ref>RemoveContacts</tp:member-ref>.</p> + + <p>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 + <a href="http://xmpp.org/extensions/xep-0016.html">XEP-0016 Privacy + Lists</a>, SHOULD have publish=No.</p> + + <p>This attribute's value will be Unknown or omitted until the + <tp:member-ref>ContactListState</tp:member-ref> has changed to + Success.</p> </tp:docstring> </tp:contact-attribute> <tp:contact-attribute name="publish-request" type="s"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>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.</p> + <p>If the <tp:token-ref>publish</tp:token-ref> 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.</p> <tp:rationale> <p>If the contact asking to receive our presence is also using @@ -294,17 +371,14 @@ <p>Otherwise, this SHOULD be omitted.</p> - <p>This attribute SHOULD be omitted from the - <tp:type>Contact_Attributes_Map</tp:type> returned by - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts" - >GetContactAttributes</tp:dbus-ref> until the initial contact - list has been received. Clients MAY wait for this by calling - <tp:member-ref>RequestContactList</tp:member-ref>.</p> + <p>This attribute will also be omitted until the + <tp:member-ref>ContactListState</tp:member-ref> has changed to + Success.</p> </tp:docstring> </tp:contact-attribute> - <property name="SubscriptionsPersist" - tp:name-for-bindings="Subscriptions_Persist" type="b" access="read"> + <property name="ContactListPersists" + tp:name-for-bindings="Contact_List_Persists" type="b" access="read"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If true, presence subscriptions (in both directions) on this connection are stored by the server or other infrastructure.</p> @@ -323,17 +397,17 @@ presence from everyone else) so nothing is ever stored.</p> </tp:rationale> - <p>If <tp:member-ref>CanChangeSubscriptions</tp:member-ref> + <p>If <tp:member-ref>CanChangeContactList</tp:member-ref> 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 + 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.</p> <tp:rationale> - <p>In SIMPLE (SIP), SubscriptionsPersist is false, but - CanChangeSubscriptions is true. Presence will not be received + <p>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 @@ -359,10 +433,45 @@ </property> <tp:enum name="Contact_Metadata_Storage_Type" type="u"> - <tp:docstring> - 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. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>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.</p> + + <p>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.</p> + + <p>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.</p> + + <p>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.</p> + + <tp:rationale> + <p>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.</p> + </tp:rationale> + + <p>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.</p> + + <tp:rationale> + <p>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.</p> + </tp:rationale> </tp:docstring> <tp:enumvalue suffix="None" value="0"> @@ -391,22 +500,6 @@ <tp:rationale> <p>Contact aliases and groups on MSN have this behaviour.</p> </tp:rationale> - - <p>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.</p> - - <tp:rationale> - <p>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.</p> - </tp:rationale> </tp:docstring> </tp:enumvalue> @@ -419,19 +512,6 @@ <p>No service with this behaviour is currently known, but it's a stricter form of Subscribed_Or_Pending.</p> </tp:rationale> - - <p>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.</p> - - <tp:rationale> - <p>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.</p> - </tp:rationale> </tp:docstring> </tp:enumvalue> @@ -455,13 +535,13 @@ A single contact's subscribe, publish and publish-request attributes. </tp:docstring> - <tp:member name="Subscribe" type="u" tp:type="Presence_State"> + <tp:member name="Subscribe" type="u" tp:type="Subscription_State"> <tp:docstring> The new value of the contact's "subscribe" attribute. </tp:docstring> </tp:member> - <tp:member name="Publish" type="u" tp:type="Presence_State"> + <tp:member name="Publish" type="u" tp:type="Subscription_State"> <tp:docstring> The new value of the contact's "publish" attribute. </tp:docstring> @@ -500,19 +580,32 @@ <p>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 - <tp:member-ref>RequestContactList</tp:member-ref>, + <tp:member-ref>GetContactListAttributes</tp:member-ref>, or when contacts are removed from that list.</p> <tp:rationale> <p>This provides change notification for that list, and for - contacts' "subscribe", "publish" and - "publish-request" attributes.</p> + contacts' <tp:token-ref>subscribe</tp:token-ref>, + <tp:token-ref>publish</tp:token-ref> and + <tp:token-ref>publish-request</tp:token-ref> attributes.</p> + </tp:rationale> + + <p>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 <tp:token>publish</tp:token> attribute is already + Ask and the <tp:token>publish-request</tp:token> has not changed.</p> + + <tp:rationale> + <p>If the same contact sends 10 identical requests, 10 identical + signals should be emitted.</p> </tp:rationale> </tp:docstring> <arg type="a{u(uus)}" name="Changes" tp:type="Contact_Subscription_Map"> <tp:docstring> - The new subscribe, publish and publish-request attributes of all the + The new <tp:token-ref>subscribe</tp:token-ref>, + <tp:token-ref>publish</tp:token-ref> and + <tp:token-ref>publish-request</tp:token-ref> attributes of all the contacts that have been added, and all the contacts for which those attributes have changed. </tp:docstring> @@ -522,15 +615,15 @@ <tp:docstring> The contacts that have been removed from the list that would be returned by - <tp:member-ref>RequestContactList</tp:member-ref>. + <tp:member-ref>GetContactListAttributes</tp:member-ref>. This also implies that they have subscribe = No and publish = No; contacts MUST NOT be listed both here and in Changes. </tp:docstring> </arg> </signal> - <property name="CanChangeSubscriptions" type="b" access="read" - tp:name-for-bindings="Can_Change_Subscriptions"> + <property name="CanChangeContactList" type="b" access="read" + tp:name-for-bindings="Can_Change_Contact_List"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If true, presence subscription and publication can be changed using the @@ -590,10 +683,10 @@ request, with the given message, if allowed by the underlying protocol.</p> - <p>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 + <p>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).</p> <p>Any state changes that immediately result from this request MUST @@ -606,9 +699,20 @@ </tp:rationale> <p>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.</p> + attribute will later change from Ask to Yes.</p> + + <p>If the remote contact explicitly rejects the request (in protocols + that allow this), their subscribe attribute will later change from + Ask to Rejected.</p> + + <p>If the subscription request is cancelled by the local user, the + contact's subscribe attribute will change from Ask to No.</p> + + <p>This method SHOULD NOT be called until the + <tp:member-ref>ContactListState</tp:member-ref> changes to Success. + If the <tp:member-ref>ContactListState</tp:member-ref> changes to + Failure, this method SHOULD raise the same error as + <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p> </tp:docstring> <arg name="Contacts" direction="in" @@ -643,10 +747,16 @@ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotYet"> + <tp:docstring> + The <tp:member-ref>ContactListState</tp:member-ref> is None + or Waiting. + </tp:docstring> + </tp:error> <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> <tp:docstring> It was not possible to perform the requested action, because - <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false. + <tp:member-ref>CanChangeContactList</tp:member-ref> is false. </tp:docstring> </tp:error> </tp:possible-errors> @@ -714,6 +824,12 @@ <p>This makes it easy for user interfaces to see what practical effect this method had.</p> </tp:rationale> + + <p>This method SHOULD NOT be called until the + <tp:member-ref>ContactListState</tp:member-ref> changes to Success. + If the <tp:member-ref>ContactListState</tp:member-ref> changes to + Failure, this method SHOULD raise the same error as + <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p> </tp:docstring> <arg name="Contacts" direction="in" @@ -730,7 +846,13 @@ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> <tp:docstring> It was not possible to perform the requested action, because - <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false. + <tp:member-ref>CanChangeContactList</tp:member-ref> is false. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotYet"> + <tp:docstring> + The <tp:member-ref>ContactListState</tp:member-ref> is None + or Waiting. </tp:docstring> </tp:error> </tp:possible-errors> @@ -745,7 +867,7 @@ <p>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 - <tp:member-ref>RequestContactList</tp:member-ref>.</p> + <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p> <p>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 @@ -764,6 +886,12 @@ contact list's state), then consult its local cache of the contact list's state to see whether the contact is still there.</p> </tp:rationale> + + <p>This method SHOULD NOT be called until the + <tp:member-ref>ContactListState</tp:member-ref> changes to Success. + If the <tp:member-ref>ContactListState</tp:member-ref> changes to + Failure, this method SHOULD raise the same error as + <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p> </tp:docstring> <arg name="Contacts" direction="in" @@ -780,7 +908,13 @@ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> <tp:docstring> It was not possible to perform the requested action because - <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false. + <tp:member-ref>CanChangeContactList</tp:member-ref> is false. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotYet"> + <tp:docstring> + The <tp:member-ref>ContactListState</tp:member-ref> is None + or Waiting. </tp:docstring> </tp:error> </tp:possible-errors> @@ -801,6 +935,12 @@ entirely or for all contacts; however, all signals that immediately result from this method call MUST be emitted before it returns.</p> + + <p>This method SHOULD NOT be called until the + <tp:member-ref>ContactListState</tp:member-ref> changes to Success. + If the <tp:member-ref>ContactListState</tp:member-ref> changes to + Failure, this method SHOULD raise the same error as + <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p> </tp:docstring> <arg name="Contacts" direction="in" @@ -817,7 +957,7 @@ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> <tp:docstring> It was not possible to perform the requested action because - <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false. + <tp:member-ref>CanChangeContactList</tp:member-ref> is false. </tp:docstring> </tp:error> </tp:possible-errors> @@ -838,6 +978,12 @@ entirely or for all contacts; however, all signals that immediately result from this method call MUST be emitted before it returns.</p> + + <p>This method SHOULD NOT be called until the + <tp:member-ref>ContactListState</tp:member-ref> changes to Success. + If the <tp:member-ref>ContactListState</tp:member-ref> changes to + Failure, this method SHOULD raise the same error as + <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p> </tp:docstring> <arg name="Contacts" direction="in" @@ -854,7 +1000,13 @@ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> <tp:docstring> It was not possible to perform the requested action because - <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false. + <tp:member-ref>CanChangeContactList</tp:member-ref> is false. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotYet"> + <tp:docstring> + The <tp:member-ref>ContactListState</tp:member-ref> is None + or Waiting. </tp:docstring> </tp:error> </tp:possible-errors> |