[next] telepathy-spec: Remove GetPresences, replaced by the contact attribute

[Xavier Claessens]

Module: telepathy-spec
Branch: next
Commit: 86f82788bbb0166a1abe3e75f3ebd5012dcff778
URL:    http://cgit.freedesktop.org/telepathy/telepathy-spec/commit/?id=86f82788bbb0166a1abe3e75f3ebd5012dcff778

Author: Xavier Claessens <xavier.claessens at collabora.co.uk>
Date:   Fri May 18 15:01:13 2012 +0200

Remove GetPresences, replaced by the contact attribute

---

 spec/Connection_Interface_Contact_List1.xml |   11 ++---
 spec/Connection_Interface_Presence1.xml     |   58 ++++++---------------------
 2 files changed, 17 insertions(+), 52 deletions(-)

diff --git a/spec/Connection_Interface_Contact_List1.xml b/spec/Connection_Interface_Contact_List1.xml
index 346abdc..2c0cbf9 100644
--- a/spec/Connection_Interface_Contact_List1.xml
+++ b/spec/Connection_Interface_Contact_List1.xml
@@ -254,12 +254,11 @@
         </tp:rationale>
 
         <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="im.telepathy1.Connection.Interface.Presence1">GetPresences</tp:dbus-ref>
-          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
+          expect to receive presence from this contact. Their <tp:token-ref
+            namespace="im.telepathy1.Connection.Interface.Presence1">presence</tp:token-ref>
+          contact attribute 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).</p>
 
         <p>If this attribute is Ask, this indicates that the local user has
diff --git a/spec/Connection_Interface_Presence1.xml b/spec/Connection_Interface_Presence1.xml
index 1e27cc2..a49bf4f 100644
--- a/spec/Connection_Interface_Presence1.xml
+++ b/spec/Connection_Interface_Presence1.xml
@@ -64,8 +64,7 @@
 
     <tp:mapping name="Contact_Presence_Map">
       <tp:docstring>
-        Mapping returned by <tp:member-ref>GetPresences</tp:member-ref>
-        and signalled by <tp:member-ref>PresencesChanged</tp:member-ref>,
+        Mapping signalled by <tp:member-ref>PresencesChanged</tp:member-ref>,
         indicating the presence of a number of contacts.
       </tp:docstring>
       <tp:member type="u" tp:type="Contact_Handle" name="Contact">
@@ -199,46 +198,6 @@
       </tp:possible-errors>
     </method>
 
-    <method name="GetPresences" tp:name-for-bindings="Get_Presences">
-      <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
-        <tp:docstring>
-          An array of the contacts whose presence should be obtained.
-        </tp:docstring>
-      </arg>
-      <arg direction="out" name="Presence" type="a{u(uss)}"
-        tp:type="Contact_Presence_Map">
-        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          <p>Presence information in the same format as for the
-            <tp:member-ref>PresencesChanged</tp:member-ref> signal.
-            The returned mapping MUST include an entry for each contact
-            in the method's argument.</p>
-
-          <p>The definition of the connection presence types Unknown
-            and Offline means that if a connection manager will return
-            Unknown for contacts not on the subscribe list, it MUST delay
-            the reply to this method call until it has found out which
-            contacts are, in fact, on the subscribe list.</p>
-        </tp:docstring>
-      </arg>
-      <tp:docstring>
-        Get presence previously emitted by
-        <tp:member-ref>PresencesChanged</tp:member-ref> for the given
-        contacts. Data is returned in the same structure as the
-        PresencesChanged signal; no additional network requests are made.
-      </tp:docstring>
-      <tp:possible-errors>
-        <tp:error name="im.telepathy1.Error.Disconnected"/>
-        <tp:error name="im.telepathy1.Error.InvalidHandle"/>
-        <tp:error name="im.telepathy1.Error.NetworkError">
-          <tp:docstring>
-            While discovering the subscribe list in order to distinguish
-            between Unknown and Offline statuses, a network error occurred.
-          </tp:docstring>
-        </tp:error>
-        <tp:error name="im.telepathy1.Error.NotAvailable"/>
-      </tp:possible-errors>
-    </method>
-
     <property name="Statuses" tp:name-for-bindings="Statuses" access="read"
       type="a{s(ubb)}" tp:type="Status_Spec_Map">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -491,10 +450,17 @@
     <tp:contact-attribute name="presence"
       type="(uss)" tp:type="Presence">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>The same struct that would be returned by
-          <tp:member-ref>GetPresences</tp:member-ref>
-          (always present with some value if information from the
-          Presence interface was requested)</p>
+        <p>The contact's presence.</p>
+
+        <p>The presence is likely to be (Unknown, "unknown", "") unless
+          <tp:token-ref
+            namespace="im.telepathy1.Connection.Interface.ContactList1">subscribe</tp:token-ref>
+          contact attribute is Yes, or 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).</p>
+
+        <p>Always present with some value if information if the
+          Presence interface was requested</p>
       </tp:docstring>
     </tp:contact-attribute>