Update spec to 0.21.0 for stable ContactList and ContactGroups

3 files changed, 132 insertions, 83 deletions

diff --git a/spec/Connection_Interface_Contact_Groups.xml b/spec/Connection_Interface_Contact_Groups.xml
index 856dec178..5282a8272 100644
--- a/spec/Connection_Interface_Contact_Groups.xml
+++ b/spec/Connection_Interface_Contact_Groups.xml
@@ -18,15 +18,63 @@
       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
       USA.</p>
   </tp:license>
-  <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactGroups.DRAFT"
-    tp:causes-havoc="experimental">
+  <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactGroups">
     <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
-    <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactList.DRAFT3"/>
-    <tp:added version="0.19.6">(draft 1)</tp:added>
+    <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactList"/>
+    <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 in which contacts can be placed in
         user-defined groups.</p>
+
+      <p>The most basic functionality of this interface is to list and monitor
+        a contact's set of groups. To do this, use the
+        <tp:member-ref>GroupsChanged</tp:member-ref> signal, and the
+        <tp:token-ref>groups</tp:token-ref> contact attribute (this should
+        usually be done by connecting to the GroupsChanged signal, then
+        calling <tp:dbus-ref
+          namespace="ofdT.Connection.Interface.ContactList"
+          >GetContactListAttributes</tp:dbus-ref> with this interface
+        included in the Interfaces argument). Simple user interfaces can
+        limit themselves to displaying that information, and ignore the rest
+        of this interface: to ensure that this works,
+        <tp:member-ref>GroupsChanged</tp:member-ref> is emitted for every
+        change, even if that change could be inferred from another signal
+        such as <tp:member-ref>GroupsRemoved</tp:member-ref>.</p>
+
+      <p>Looking at contacts' lists of groups is sufficient to present a
+        user interface resembling XMPP's data model, in which groups behave
+        like tags applied to contacts, and so an empty group cannot exist
+        or is not interesting. However, some protocols model groups as
+        objects in their own right. User interfaces may either track
+        the set of groups via the <tp:member-ref>Groups</tp:member-ref>
+        property and the <tp:member-ref>GroupsCreated</tp:member-ref> and
+        <tp:member-ref>GroupsRemoved</tp:member-ref> signals, or ignore
+        this extra information.</p>
+
+      <p>Similarly, in some protocols it is possible to rename a group as
+        a single atomic operation. Simpler user interfaces will
+        see the new name being created, the old name being removed, and the
+        members moving to the new name, via the signals described above.
+        More advanced user interfaces can optionally distinguish between an
+        atomic rename and a create/remove pair, and display renamed groups
+        differently, by monitoring the
+        <tp:member-ref>GroupRenamed</tp:member-ref> signal.</p>
+
+      <p>This interface also provides various methods to manipulate
+        user-defined groups, which can be expected to work if
+        <tp:member-ref>GroupStorage</tp:member-ref> is not None.</p>
+
+      <p>Depending on the protocol, some methods might be implemented by
+        more than one protocol operation; for instance, in a
+        "contact-centric" protocol like XMPP,
+        <tp:member-ref>SetContactGroups</tp:member-ref> is a single
+        protocol operation and <tp:member-ref>SetGroupMembers</tp:member-ref>
+        requires a protocol operation per contact, whereas in a more
+        "group-centric" protocol it might be the other way around. User
+        interfaces SHOULD call whichever method most closely resembles the
+        way in which the user's action was represented in the UI, and
+        let the connection manager deal with the details.</p>
     </tp:docstring>
 
     <property name="DisjointGroups" tp:name-for-bindings="Disjoint_Groups"
@@ -65,6 +113,26 @@
       </tp:docstring>
     </tp:contact-attribute>
 
+    <signal name="GroupsChanged" tp:name-for-bindings="Groups_Changed">
+      <tp:docstring>
+        Emitted when contacts' groups change.
+      </tp:docstring>
+
+      <arg name="Contact" type="au" tp:type="Contact_Handle">
+        <tp:docstring>The relevant contacts.</tp:docstring>
+      </arg>
+
+      <arg name="Added" type="as">
+        <tp:docstring>The names of groups to which the contacts were
+          added.</tp:docstring>
+      </arg>
+
+      <arg name="Removed" type="as">
+        <tp:docstring>The names of groups from which the contacts were
+          removed.</tp:docstring>
+      </arg>
+    </signal>
+
     <property name="Groups" type="as" access="read"
       tp:name-for-bindings="Groups">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -80,7 +148,7 @@
           receiving <tp:member-ref>GroupRenamed</tp:member-ref>.</p>
 
         <p>This property's value is not meaningful until the
-          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3"
+          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
             >ContactListState</tp:dbus-ref> has become Success.</p>
       </tp:docstring>
     </property>
@@ -99,7 +167,9 @@
 
     <signal name="GroupRenamed" tp:name-for-bindings="Group_Renamed">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>Emitted when a group is renamed.</p>
+        <p>Emitted when a group is renamed, in protocols where this can
+          be distinguished from group creation, removal and membership
+          changes.</p>
 
         <p>Immediately after this signal is emitted,
           <tp:member-ref>GroupsCreated</tp:member-ref> MUST signal the
@@ -110,7 +180,7 @@
         <tp:rationale>
           <p>Emitting these extra signals, in this order, means that clients
             that are interested in the set of groups that exist (but treat a
-            rename and a create/remove pair identically) to ignore the
+            rename and a create/remove pair identically) can ignore the
             GroupRenamed signal entirely.</p>
         </tp:rationale>
 
@@ -166,26 +236,6 @@
       </arg>
     </signal>
 
-    <signal name="GroupsChanged" tp:name-for-bindings="Groups_Changed">
-      <tp:docstring>
-        Emitted when contacts' groups change.
-      </tp:docstring>
-
-      <arg name="Contact" type="au" tp:type="Contact_Handle">
-        <tp:docstring>The relevant contacts.</tp:docstring>
-      </arg>
-
-      <arg name="Added" type="as">
-        <tp:docstring>The names of groups to which the contacts were
-          added.</tp:docstring>
-      </arg>
-
-      <arg name="Removed" type="as">
-        <tp:docstring>The names of groups from which the contacts were
-          removed.</tp:docstring>
-      </arg>
-    </signal>
-
     <method name="SetContactGroups" tp:name-for-bindings="Set_Contact_Groups">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>Add the given contact to the given groups (creating new groups
@@ -213,11 +263,11 @@
           this method call MUST be emitted before the method returns.</p>
 
         <p>This method SHOULD NOT be called until the
-          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3"
+          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
             >ContactListState</tp:dbus-ref> changes to Success.
           If the ContactListState is Failure, this method SHOULD raise the
           same error as
-          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3"
+          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
             >GetContactListAttributes</tp:dbus-ref>.</p>
       </tp:docstring>
 
@@ -274,11 +324,11 @@
           this method call MUST be emitted before the method returns.</p>
 
         <p>This method SHOULD NOT be called until the
-          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3"
+          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
             >ContactListState</tp:dbus-ref> changes to Success.
           If the ContactListState is Failure, this method SHOULD raise the
           same error as
-          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3"
+          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
             >GetContactListAttributes</tp:dbus-ref>.</p>
       </tp:docstring>
 
@@ -324,11 +374,11 @@
           this method call MUST be emitted before the method returns.</p>
 
         <p>This method SHOULD NOT be called until the
-          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3"
+          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
             >ContactListState</tp:dbus-ref> changes to Success.
           If the ContactListState is Failure, this method SHOULD raise the
           same error as
-          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3"
+          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
             >GetContactListAttributes</tp:dbus-ref>.</p>
       </tp:docstring>
 
@@ -368,11 +418,11 @@
           this method call MUST be emitted before the method returns.</p>
 
         <p>This method SHOULD NOT be called until the
-          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3"
+          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
             >ContactListState</tp:dbus-ref> changes to Success.
           If the ContactListState is Failure, this method SHOULD raise the
           same error as
-          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3"
+          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
             >GetContactListAttributes</tp:dbus-ref>.</p>
       </tp:docstring>
 
@@ -414,11 +464,11 @@
           this method call MUST be emitted before the method returns.</p>
 
         <p>This method SHOULD NOT be called until the
-          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3"
+          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
             >ContactListState</tp:dbus-ref> changes to Success.
           If the ContactListState is Failure, this method SHOULD raise the
           same error as
-          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3"
+          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
             >GetContactListAttributes</tp:dbus-ref>.</p>
       </tp:docstring>
 
@@ -457,11 +507,11 @@
           this method call MUST be emitted before the method returns.</p>
 
         <p>This method SHOULD NOT be called until the
-          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3"
+          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
             >ContactListState</tp:dbus-ref> changes to Success.
           If the ContactListState is Failure, this method SHOULD raise the
           same error as
-          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList.DRAFT3"
+          <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
             >GetContactListAttributes</tp:dbus-ref>.</p>
       </tp:docstring>
 
diff --git a/spec/Connection_Interface_Contact_List.xml b/spec/Connection_Interface_Contact_List.xml
index 3366b57e2..d602c19f1 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.DRAFT3"
-    tp:causes-havoc="experimental">
+  <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactList">
     <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
-    <tp:added version="0.19.12">(draft 3)</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
@@ -100,7 +99,6 @@
 
     <property name="ContactListState" tp:name-for-bindings="Contact_List_State"
       type="u" tp:type="Contact_List_State" access="read">
-      <tp:added version="0.19.12">(in draft 3)</tp:added>
       <tp:docstring>
         The progress made in retrieving the contact list.
         Change notification is via
@@ -110,7 +108,6 @@
 
     <signal name="ContactListStateChanged"
       tp:name-for-bindings="Contact_List_State_Changed">
-      <tp:added version="0.19.12">(in draft 3)</tp:added>
       <tp:docstring>
         Emitted when <tp:member-ref>ContactListState</tp:member-ref>
         changes.
@@ -125,8 +122,6 @@
 
     <method name="GetContactListAttributes"
       tp:name-for-bindings="Get_Contact_List_Attributes">
-      <tp:changed version="0.19.12">(semantics changed in draft
-        3)</tp:changed>
       <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>
@@ -384,7 +379,6 @@
 
     <property name="ContactListPersists"
       tp:name-for-bindings="Contact_List_Persists" type="b" access="read">
-      <tp:changed version="0.19.12">(renamed in draft 3)</tp:changed>
       <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>
@@ -439,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">
@@ -471,23 +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
-            or subscribe=Rejected, 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>
 
@@ -500,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>
 
diff --git a/spec/all.xml b/spec/all.xml
index 68cd56fc8..96ed5de7d 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -3,7 +3,7 @@
   xmlns:xi="http://www.w3.org/2001/XInclude">
 
 <tp:title>Telepathy D-Bus Interface Specification</tp:title>
-<tp:version>0.20.1</tp:version>
+<tp:version>0.21.0</tp:version>
 
 <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright>
 <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright>