Update to spec 0.21.8

The only change to stable API is the addition of a ContactsChangedWithID
signal to Connection.Interface.ContactList.

3 files changed, 94 insertions, 127 deletions

diff --git a/spec/Account_Interface_Minimum_Presence.xml b/spec/Account_Interface_Minimum_Presence.xml
deleted file mode 100644
index eb829b824..000000000
--- a/spec/Account_Interface_Minimum_Presence.xml
+++ /dev/null
@@ -1,108 +0,0 @@
-<?xml version="1.0" ?>
-<node name="/Account_Interface_Minimum_Presence"
-  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright>
-  <tp:copyright>Copyright © 2010 Nokia Corporation</tp:copyright>
-  <tp:license xmlns="http://www.w3.org/1999/xhtml">
-<p>This library is free software; you can redistribute it and/or
-modify it under the terms of the GNU Lesser General Public
-License as published by the Free Software Foundation; either
-version 2.1 of the License, or (at your option) any later version.</p>
-
-<p>This library is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-Lesser General Public License for more details.</p>
-
-<p>You should have received a copy of the GNU Lesser General Public
-License along with this library; if not, write to the Free Software
-Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
-</p>
-  </tp:license>
-  <interface name="org.freedesktop.Telepathy.Account.Interface.MinimumPresence.DRAFT2"
-    tp:causes-havoc="experimental">
-    <tp:requires interface="org.freedesktop.Telepathy.Account"/>
-    <tp:added version="0.19.12">(draft 2)</tp:added>
-
-    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-      <p>This interface extends the core Account interface to provide a way
-        for applications to request minimum presence on the account.</p>
-
-      <tp:rationale>
-        <p>Some applications, for example mail notifiers or address book
-          synchronisation, can make use of account's connection even while
-          the user is nominally offline.</p>
-      </tp:rationale>
-
-      <p>Each client's unique name may set a minimum desired presence on the
-        account. The combined presence is the most available presence
-        of the minimum presences set and of <tp:dbus-ref
-          namespace="org.freedesktop.Telepathy.Account">RequestedPresence</tp:dbus-ref>
-        set by the user. The account manager should attempt to manipulate
-        the connection to set the combined presence.</p>
-    </tp:docstring>
-
-    <property name="MinimumPresenceRequests"
-      tp:name-for-bindings="MinimumPresenceRequests" access="read"
-      type="a{s(uss)}" tp:type="Minimum_Presence_Request_Map">
-      <tp:docstring>
-        Active requests for minimum presence status, a map of client unique
-        name to the (non-offline) minimum presence they set.
-      </tp:docstring>
-    </property>
-
-    <method name="SetMinimumPresence" tp:name-for-bindings="Set_Minimum_Presence">
-      <tp:docstring>
-        <p>Set a minimum presence needed by the client for this account. Setting
-          (Offline, "offline", "") removes the minimum presence requirement for
-          the client's unique name.</p>
-      </tp:docstring>
-
-      <arg direction="in" name="status" type="(uss)" tp:type="Simple_Presence">
-        <tp:docstring>
-          Requested presence status.
-        </tp:docstring>
-      </arg>
-    </method>
-
-    <signal name="MinimumPresenceRequestsChanged"
-      tp:name-for-bindings="Minimum_Presence_Requests_Changed">
-      <tp:docstring>
-        Emitted when the
-        <tp:member-ref>MinimumPresenceRequests</tp:member-ref> property
-        changes.
-      </tp:docstring>
-
-      <arg name="MinimumPresenceRequests" type="a{s(uss)}"
-        tp:type="Minimum_Presence_Request_Map">
-        <tp:docstring>
-          A new value of MinimumPresenceRequests property.
-        </tp:docstring>
-      </arg>
-    </signal>
-
-    <tp:mapping name="Minimum_Presence_Request_Map">
-      <tp:docstring>
-        <p>A map of active minimum presence requests.</p>
-      </tp:docstring>
-      <tp:member type="s" name="Key" tp:type="DBus_Unique_Name">
-        <tp:docstring>
-          <p>Client unique name.</p>
-        </tp:docstring>
-      </tp:member>
-      <tp:member type="(uss)" name="Value" tp:type="Simple_Presence">
-        <tp:docstring>
-          <p>Requested minimum presence.</p>
-
-          <tp:rationale>
-            <p>Some applications may want to monitor the currently active
-              minimum presences required. An example is an tool allowing
-              the user to inspect applications maintaining open connections and
-              close those applications.</p>
-          </tp:rationale>
-        </tp:docstring>
-      </tp:member>
-    </tp:mapping>
-  </interface>
-</node>
-<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Contact_List.xml b/spec/Connection_Interface_Contact_List.xml
index e0cccd541..033c64d1d 100644
--- a/spec/Connection_Interface_Contact_List.xml
+++ b/spec/Connection_Interface_Contact_List.xml
@@ -576,8 +576,9 @@
       </tp:member>
     </tp:mapping>
 
-    <signal name="ContactsChanged"
-      tp:name-for-bindings="Contacts_Changed">
+    <signal name="ContactsChangedWithID"
+      tp:name-for-bindings="Contacts_Changed_With_ID">
+      <tp:added version="0.21.8"/>
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>Emitted when the contact list becomes available, when contacts'
           basic stored properties change, when new contacts are added to the
@@ -613,13 +614,53 @@
         </tp:docstring>
       </arg>
 
-      <arg name="Removals" type="au" tp:type="Contact_Handle[]">
-        <tp:docstring>
+      <arg name="Identifiers" type="a{us}" tp:type="Handle_Identifier_Map">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          The identifiers of the contacts in the <var>Changes</var> map.
+        </tp:docstring>
+      </arg>
+
+      <arg name="Removals" type="a{us}" tp:type="Handle_Identifier_Map">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
           The contacts that have been removed from the list that would be
           returned by
           <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.
+          contacts MUST NOT be listed both here and in <var>Changes</var>.
+        </tp:docstring>
+      </arg>
+    </signal>
+
+    <signal name="ContactsChanged"
+      tp:name-for-bindings="Contacts_Changed">
+      <tp:deprecated version="0.21.8">Connection managers MUST still
+        emit this signal, but clients SHOULD listen for the
+        <tp:member-ref>ContactsChangedWithID</tp:member-ref> signal in
+        addition, and ignore this signal after ContactsChangedWithID has been
+        emitted at least once.
+      </tp:deprecated>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Emitted immediately after
+          <tp:member-ref>ContactsChangedWithID</tp:member-ref>, under the same
+          circumstances.</p>
+
+        <p>If clients receive this signal without first receiving a
+          corresponding <tp:member-ref>ContactsChangedWithID</tp:member-ref>,
+          they MUST assume that only this signal will be emitted.</p>
+      </tp:docstring>
+
+      <arg type="a{u(uus)}" name="Changes" tp:type="Contact_Subscription_Map">
+        <tp:docstring>
+          The same as the corresponding argument to
+          <tp:member-ref>ContactsChangedWithID</tp:member-ref>.
+        </tp:docstring>
+      </arg>
+
+      <arg name="Removals" type="au" tp:type="Contact_Handle[]">
+        <tp:docstring>
+          The same as the corresponding argument to
+          <tp:member-ref>ContactsChangedWithID</tp:member-ref>, except that it
+          only includes handles and not identifiers.
         </tp:docstring>
       </arg>
     </signal>
diff --git a/spec/all.xml b/spec/all.xml
index 61a97c795..312340127 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.21.7</tp:version>
+<tp:version>0.21.8</tp:version>
 
 <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright>
 <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright>
@@ -150,30 +150,65 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
     <p>
      A Channel may also implement one or more of the following interfaces,
-     depending on its type:
+     depending on its type. Some interfaces are only applicable to particular
+     channel types, while others may (in principle) appear on any type of
+     channel.
     </p>
    </tp:docstring>
+
    <xi:include href="Channel_Interface_Addressing.xml"/>
    <xi:include href="Channel_Interface_Anonymity.xml"/>
-   <xi:include href="Channel_Interface_Call_State.xml"/>
-   <xi:include href="Channel_Interface_Chat_State.xml"/>
-   <xi:include href="Channel_Interface_Conference.xml"/>
-   <xi:include href="Channel_Interface_DTMF.xml"/>
    <xi:include href="Channel_Interface_Destroyable.xml"/>
    <xi:include href="Channel_Interface_Group.xml"/>
-   <xi:include href="Channel_Interface_HTML.xml"/>
-   <xi:include href="Channel_Interface_Hold.xml"/>
-   <xi:include href="Channel_Interface_Media_Signalling.xml"/>
-   <xi:include href="Channel_Interface_Mergeable_Conference.xml"/>
-   <xi:include href="Channel_Interface_Messages.xml"/>
    <xi:include href="Channel_Interface_Password.xml"/>
    <xi:include href="Channel_Interface_Room.xml"/>
    <xi:include href="Channel_Interface_SASL_Authentication.xml"/>
-   <xi:include href="Channel_Interface_SMS.xml"/>
    <xi:include href="Channel_Interface_Securable.xml"/>
    <xi:include href="Channel_Interface_Service_Point.xml"/>
-   <xi:include href="Channel_Interface_Splittable.xml"/>
    <xi:include href="Channel_Interface_Tube.xml"/>
+
+   <tp:section name="Text-specific interfaces">
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <p>These interfaces may only appear on channels of type <tp:dbus-ref
+        namespace='ofdT.Channel.Type'>Text</tp:dbus-ref>.</p>
+    </tp:docstring>
+
+    <xi:include href="Channel_Interface_Chat_State.xml"/>
+    <xi:include href="Channel_Interface_HTML.xml"/>
+    <xi:include href="Channel_Interface_Messages.xml"/>
+    <xi:include href="Channel_Interface_SMS.xml"/>
+   </tp:section>
+
+   <tp:section name="Streamed Media-related interfaces">
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+     <p>These interfaces are only applicable to channels of type <tp:dbus-ref
+       namespace='ofdT.Channel.Type'>StreamedMedia</tp:dbus-ref>, with the
+       exception of the <tp:dbus-ref
+       namespace='ofdT.Channel.Interface'>Hold</tp:dbus-ref> interface, which
+       may also appear on <tp:dbus-ref
+       namespace='ofdT.Channel.Type'>Call.DRAFT</tp:dbus-ref> channels.</p>
+    </tp:docstring>
+
+    <xi:include href="Channel_Interface_Call_State.xml"/>
+    <xi:include href="Channel_Interface_DTMF.xml"/>
+    <xi:include href="Channel_Interface_Hold.xml"/>
+    <xi:include href="Channel_Interface_Media_Signalling.xml"/>
+   </tp:section>
+
+   <tp:section name="Conference-related interfaces">
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+     <p>These interfaces provide functionality for ad-hoc conference calls and
+       chat rooms. They are primarily intended for <tp:dbus-ref
+       namespace='ofdT.Channel.Type'>Text</tp:dbus-ref>, <tp:dbus-ref
+       namespace='ofdT.Channel.Type'>StreamedMedia</tp:dbus-ref> and
+       <tp:dbus-ref namespace='ofdT.Channel.Type'>Call.DRAFT</tp:dbus-ref>
+       channels, but may also appear on other types of channel.</p>
+    </tp:docstring>
+
+    <xi:include href="Channel_Interface_Conference.xml"/>
+    <xi:include href="Channel_Interface_Splittable.xml"/>
+    <xi:include href="Channel_Interface_Mergeable_Conference.xml"/>
+   </tp:section>
   </tp:section>
  </tp:section>
 
@@ -222,7 +257,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
  <xi:include href="Account_Interface_Addressing.xml"/>
  <xi:include href="Account_Interface_Avatar.xml"/>
  <xi:include href="Account_Interface_Storage.xml"/>
- <xi:include href="Account_Interface_Minimum_Presence.xml"/>
 </tp:section>
 
 <tp:section name="The Channel Dispatcher">