Update Requests spec draft to that from 0.17.9

1 files changed, 47 insertions, 43 deletions

diff --git a/extensions/Connection_Interface_Requests.xml b/extensions/Connection_Interface_Requests.xml
index b2ac3814..ea1eeeb1 100644
--- a/extensions/Connection_Interface_Requests.xml
+++ b/extensions/Connection_Interface_Requests.xml
@@ -24,7 +24,7 @@
   <interface name="org.freedesktop.Telepathy.Connection.Interface.Requests.DRAFT"
     tp:causes-havoc="experimental">
     <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
-    <tp:added version="0.17.UNRELEASED"/>
+    <tp:added version="0.17.9"/>
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
       <p>An enhanced version of the Telepathy connection interface, which can
@@ -78,10 +78,12 @@
 
           <p>Each dictionary MUST contain the keys
             <tp:dbus-ref>org.freedesktop.Telepathy.Channel.ChannelType</tp:dbus-ref>,
-            <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandleType</tp:dbus-ref>
-            and <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandle</tp:dbus-ref>.
+            <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandleType</tp:dbus-ref>,
+            <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandle</tp:dbus-ref>
+            and
+            <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetID</tp:dbus-ref>.
           </p>
-          <!-- FIXME: maybe also TargetID, Requested, InitiatorHandle,
+          <!-- FIXME: maybe also Requested, InitiatorHandle,
           InitiatorID once they leave the FUTURE pseudo-interface -->
 
           <tp:rationale>
@@ -144,7 +146,7 @@
 
       <arg name="Channel" direction="out" type="o">
         <tp:docstring>
-          The Channel object, which SHOULD already have been signalled with
+          The Channel object, which MUST already have been signalled with
           <tp:member-ref>NewChannels</tp:member-ref> by the time this method
           returns.
         </tp:docstring>
@@ -220,7 +222,9 @@
       <arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]">
         <tp:docstring>
           The channels and their details. All channels that are signalled
-          together like this MUST have the same Bundle property, which may
+          together like this MUST have the same
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.FUTURE">Bundle</tp:dbus-ref>
+          property, which may
           either refer to an existing bundle, or establish a new bundle.
         </tp:docstring>
       </arg>
@@ -317,57 +321,57 @@
 
       <tp:member name="Fixed_Properties" type="a{sv}"
         tp:type="Channel_Class">
-        <tp:docstring>
-          The property values that identify this requestable channel class.
-          These properties MUST be included in requests for a channel of this
-          class, and MUST take these values.
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The property values that identify this requestable channel class.
+            These properties MUST be included in requests for a channel of this
+            class, and MUST take these values.</p>
+
+          <p>Clients that do not understand the semantics of all the
+            Fixed_Properties MUST NOT request channels of this class, since
+            they would be unable to avoid making an incorrect request.</p>
+
+          <p>This implies that connection managers wishing to make channels
+            available to old or minimal clients SHOULD have a channel class
+            with the minimum number of Fixed_Properties, and MAY additionally
+            have channel classes with extra Fixed_Properties.</p>
         </tp:docstring>
       </tp:member>
 
-      <tp:member name="Required_Properties" type="as"
+      <tp:member name="Allowed_Properties" type="as"
         tp:type="DBus_Qualified_Member[]">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          <p>Properties that MUST be set when requesting a channel of this
+          <p>Properties that MAY be set when requesting a channel of this
             channel type and handle type.</p>
 
-          <p>Properties MAY have additional requirement semantics not
-            represented in this array. For instance, if TargetHandleType
-            takes a value that is not Handle_Type_None, one or the other of
-            TargetHandle and TargetID is required. In this case,
-            TargetHandle and TargetID would both be listed as optional:
-            clients are expected to understand the documented relationship
-            between the properties.</p>
+          <p>This array MUST NOT include properties that are in the
+            Fixed_Properties mapping.</p>
 
-          <p>Clients that do not understand the semantics of all the
-            Fixed_Properties, and all the properties in this list, MUST NOT
-            request channels of this class (unless they are intended as
-            debugging/development tools to be operated only by users who
-            understand the Telepathy D-Bus API).</p>
-        </tp:docstring>
-      </tp:member>
+          <p>Properties in this array may either be required or optional,
+            according to their documented semantics.</p>
 
-      <tp:member name="Optional_Properties" type="as"
-        tp:type="DBus_Qualified_Member[]">
-        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          <p>Properties that MAY be set when requesting a
-            channel of this channel type and handle type.</p>
-
-          <p>Properties mentioned in Fixed_Properties or Required_Properties
-            SHOULD NOT appear in this array.</p>
-
-          <p>If this array contains the Channel.Bundle property, then this
-            class of channel can be combined with other channels with that
-            property in a request, or added to an existing bundle. If not,
-            this signifies that the connection manager is unable to mark
-            channels of this class as part of a bundle - this means that
-            to the remote contact they are likely to be indistinguishable
-            from channels requested separately.</p>
+          <tp:rationale>
+            <p>For instance, if
+              TargetHandleType takes a value that is not Handle_Type_None,
+              one or the other of TargetHandle and TargetID is required.
+              Clients are expected to understand the documented relationship
+              between the properties, so we do not have separate arrays
+              of required and optional properties.</p>
+          </tp:rationale>
+
+          <p>If this array contains the
+            <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.FUTURE">Bundle</tp:dbus-ref>
+            property, then this class of channel can be combined with other
+            channels with that property in a request, or added to an existing
+            bundle. If not, this signifies that the connection manager is
+            unable to mark channels of this class as part of a bundle - this
+            means that to the remote contact they are likely to be
+            indistinguishable from channels requested separately.</p>
         </tp:docstring>
       </tp:member>
     </tp:struct>
 
     <property name="RequestableChannelClasses" access="read"
-      type="a(a{sv}asas)" tp:type="Requestable_Channel_Class[]">
+      type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The classes of channel that are expected to be available on this
           connection, i.e. those for which