ChannelDispatchOperation, Approver: be singular

This means we can use immutable properties for the Channel.

2 files changed, 59 insertions, 131 deletions

diff --git a/spec/Channel_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml
index efe1f67b..7810a774 100644
--- a/spec/Channel_Dispatch_Operation.xml
+++ b/spec/Channel_Dispatch_Operation.xml
@@ -26,7 +26,7 @@
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
       <p>A channel dispatch operation is an object in the ChannelDispatcher
-        representing a batch of unrequested channels being announced to
+        representing an unrequested channel being announced to
         client
         <tp:dbus-ref namespace="im.telepathy.v1.Client">Approver</tp:dbus-ref>
         processes.</p>
@@ -118,7 +118,7 @@
       <tp:docstring>
         The <tp:dbus-ref
           namespace="im.telepathy.v1">Connection</tp:dbus-ref>
-        with which the <tp:member-ref>Channels</tp:member-ref> are
+        with which the <tp:member-ref>Channel</tp:member-ref> is
         associated. The well-known bus name to use can be derived from
         this object path by removing the leading '/' and replacing all
         subsequent '/' by '.'. This property cannot change.
@@ -131,72 +131,29 @@
         The <tp:dbus-ref
           namespace="im.telepathy.v1">Account</tp:dbus-ref>
         with which the <tp:member-ref>Connection</tp:member-ref>
-        and <tp:member-ref>Channels</tp:member-ref> are
+        and <tp:member-ref>Channel</tp:member-ref> is
         associated. This property cannot change.
       </tp:docstring>
     </property>
 
-    <property name="Channels" tp:name-for-bindings="Channels"
-      type="a(oa{sv})" access="read" tp:type="Channel_Details[]">
-      <tp:docstring>
-        The <tp:dbus-ref
-          namespace="im.telepathy.v1">Channel</tp:dbus-ref>s
-        to be dispatched, and their properties. Change notification is via
-        the <tp:member-ref>ChannelLost</tp:member-ref> signal (channels
-        cannot be added to this property, only removed).
+    <property name="Channel" type="o" tp:name-for-bindings="Channel"
+      access="read">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The Channel object. Its well-known bus name is the same
+          as that of the <tp:member-ref>Connection</tp:member-ref>.
+          This property cannot change.</p>
       </tp:docstring>
     </property>
 
-    <signal name="ChannelLost" tp:name-for-bindings="Channel_Lost">
+    <property name="ChannelProperties" access="read" type="a{sv}"
+      tp:type="Qualified_Property_Value_Map"
+      tp:name-for-bindings="Channel_Properties">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>A channel has closed before it could be claimed or handled. If
-          this is emitted for the last remaining channel in a channel
-          dispatch operation, it MUST immediately be followed by
-          <tp:member-ref>Finished</tp:member-ref>.</p>
-
-        <p>This signal MUST NOT be emitted until all Approvers that were
-          invoked have returned (successfully or with an error) from
-          their <tp:dbus-ref
-            namespace="im.telepathy.v1.Client.Approver">AddDispatchOperation</tp:dbus-ref>
-          method.</p>
-
-        <tp:rationale>
-          <p>This means that Approvers can connect to the ChannelLost signal
-            in a race-free way. Non-approver processes that discover
-            a channel dispatch operation in some way (such as observers)
-            will have to follow the usual "connect to signals then recover
-            state" model - first connect to ChannelLost and
-            <tp:member-ref>Finished</tp:member-ref>,
-            then download <tp:member-ref>Channels</tp:member-ref> (and
-            on error, perhaps assume that the operation has already
-            Finished).</p>
-        </tp:rationale>
+        <p>Properties of the <tp:member-ref>Channel</tp:member-ref>,
+          equivalent to the properties in <tp:type>Channel_Details</tp:type>.
+          This property cannot change.</p>
       </tp:docstring>
-
-      <arg name="Channel" type="o">
-        <tp:docstring>
-          The <tp:dbus-ref
-            namespace="im.telepathy.v1">Channel</tp:dbus-ref>
-          that closed.
-        </tp:docstring>
-      </arg>
-
-      <arg name="Error" type="s" tp:type="DBus_Error_Name">
-        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          <p>The name of a D-Bus error indicating why the channel closed. If
-            no better reason can be found,
-            <code>im.telepathy.v1.Error.NotAvailable</code> MAY
-            be used as a fallback; this means that this error SHOULD NOT be
-            given any more specific meaning.</p>
-        </tp:docstring>
-      </arg>
-
-      <arg name="Message" type="s">
-        <tp:docstring>
-          A string associated with the D-Bus error.
-        </tp:docstring>
-      </arg>
-    </signal>
+    </property>
 
     <property name="PossibleHandlers" tp:name-for-bindings="Possible_Handlers"
       type="as" access="read" tp:type="DBus_Well_Known_Name[]">
@@ -205,7 +162,7 @@
           <code>im.telepathy.v1.Client.</code>) of the possible
           <tp:dbus-ref
             namespace="im.telepathy.v1.Client">Handler</tp:dbus-ref>s
-          for these channels. The channel dispatcher MUST place the most
+          for this channel. The channel dispatcher MUST place the most
           preferred handlers first, according to some reasonable heuristic.
           As a result, approvers SHOULD use the first handler by default.</p>
 
@@ -233,12 +190,12 @@
           completed and the object has already gone. If this occurs, it
           indicates that another approver has asked for the bundle to be
           handled by a particular handler. The approver MUST NOT attempt
-          to interact with the channels further in this case, unless it is
+          to interact with the channel further in this case, unless it is
           separately invoked as the handler.</p>
 
         <p>Approvers which are also channel handlers SHOULD use
           <tp:member-ref>Claim</tp:member-ref> instead
-          of HandleWith to request that they can handle a channel bundle
+          of HandleWith to request that they can handle a channel
           themselves.</p>
 
         <p>(FIXME: list some possible errors)</p>
@@ -269,15 +226,15 @@
         </tp:error>
         <tp:error name="im.telepathy.v1.Error.NotAvailable">
           <tp:docstring>
-            The selected handler is temporarily unable to handle these
-            channels.
+            The selected handler is temporarily unable to handle this
+            channel.
           </tp:docstring>
         </tp:error>
         <tp:error name="im.telepathy.v1.Error.NotImplemented">
           <tp:docstring>
             The selected handler is syntactically correct, but will never
-            be able to handle these channels (for instance because the channels
-            do not match its HandlerChannelFilter, or because HandleChannel
+            be able to handle this channel (for instance because the channel
+            does not match its HandlerChannelFilter, or because HandleChannel
             raised NotImplemented).
           </tp:docstring>
         </tp:error>
@@ -286,7 +243,7 @@
             At the time that HandleWith was called, this dispatch operation was
             processing an earlier call to HandleWith. The earlier call has
             now succeeded, so some Handler nominated by another approver is
-            now responsible for the channels. In this situation, the second
+            now responsible for the channel. In this situation, the second
             call to HandleWith MUST NOT return until the first one has
             returned successfully or unsuccessfully, and if the first call
             to HandleChannel fails, the channel dispatcher SHOULD try to obey
@@ -341,7 +298,7 @@
 
         <p>This method may fail because the dispatch operation has already
           been completed. Again, see HandleWith for more details. The approver
-          MUST NOT attempt to interact with the channels further in this
+          MUST NOT attempt to interact with the channel further in this
           case.</p>
 
         <p>(FIXME: list some other possible errors)</p>
@@ -398,15 +355,15 @@
         </tp:error>
         <tp:error name="im.telepathy.v1.Error.NotAvailable">
           <tp:docstring>
-            The selected handler is temporarily unable to handle these
-            channels.
+            The selected handler is temporarily unable to handle this
+            channel.
           </tp:docstring>
         </tp:error>
         <tp:error name="im.telepathy.v1.Error.NotImplemented">
           <tp:docstring>
             The selected handler is syntactically correct, but will never
-            be able to handle these channels (for instance because the channels
-            do not match its HandlerChannelFilter, or because HandleChannel
+            be able to handle these channels (for instance because the channel
+            does not match its HandlerChannelFilter, or because HandleChannel
             raised NotImplemented).
           </tp:docstring>
         </tp:error>
@@ -415,7 +372,7 @@
             At the time that HandleWith was called, this dispatch operation was
             processing an earlier call to HandleWith. The earlier call has
             now succeeded, so some Handler nominated by another approver is
-            now responsible for the channels. In this situation, the second
+            now responsible for the channel. In this situation, the second
             call to HandleWith MUST NOT return until the first one has
             returned successfully or unsuccessfully, and if the first call
             to HandleChannel fails, the channel dispatcher SHOULD try to obey
@@ -432,9 +389,7 @@
           called on it.</p>
 
         <p>Approvers that have a user interface SHOULD stop notifying the user
-          about the channels in response to this signal; they MAY assume that
-          on errors, they would have received
-          <tp:member-ref>ChannelLost</tp:member-ref> first.</p>
+          about the channel in response to this signal.</p>
 
         <p>Its object path SHOULD NOT be reused for a subsequent dispatch
           operation; the ChannelDispatcher MUST choose object paths
@@ -454,17 +409,34 @@
           method.</p>
 
         <tp:rationale>
-          <p>This means that Approvers can connect to the ChannelLost signal
+          <p>This means that Approvers can connect to the Finished signal
             in a race-free way. Non-approver processes that discover
             a channel dispatch operation in some way (such as observers)
             will have to follow the usual "connect to signals then recover
-            state" model - first connect to
-            <tp:member-ref>ChannelLost</tp:member-ref> and
-            Finished, then download <tp:member-ref>Channels</tp:member-ref>
+            state" model - first connect to Finished, then download properties
             (and on error, perhaps assume that the operation has already
             Finished).</p>
         </tp:rationale>
       </tp:docstring>
+
+      <arg name="Error" type="s" tp:type="DBus_Error_Name">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>If the channel dispatch operation finished because the
+            channel was successfully dispatched, the empty string.</p>
+
+          <p>Otherwise, the name of a D-Bus error indicating why the channel
+            closed. If no better reason can be found,
+            <code>im.telepathy.v1.Error.NotAvailable</code> MAY
+            be used as a fallback; this means that this error SHOULD NOT be
+            given any more specific meaning.</p>
+        </tp:docstring>
+      </arg>
+
+      <arg name="Message" type="s">
+        <tp:docstring>
+          A string associated with the D-Bus error.
+        </tp:docstring>
+      </arg>
     </signal>
 
   </interface>
diff --git a/spec/Client_Approver.xml b/spec/Client_Approver.xml
index 03504c7e..0296e023 100644
--- a/spec/Client_Approver.xml
+++ b/spec/Client_Approver.xml
@@ -89,8 +89,8 @@
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>A specification of the channels in which this approver is
           interested. The <tp:member-ref>AddDispatchOperation</tp:member-ref>
-          method should be called by the channel dispatcher whenever at least
-          one of the channels in a channel dispatch operation matches this
+          method should be called by the channel dispatcher whenever
+          the channel in a channel dispatch operation matches this
           description.</p>
 
         <p>This property works in exactly the same way as the
@@ -130,54 +130,6 @@
         </tp:rationale>
       </tp:docstring>
 
-      <arg name="Channels" direction="in"
-        type="a(oa{sv})" tp:type="Channel_Details[]">
-        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          <p>The initial value of the <tp:dbus-ref
-              namespace="im.telepathy.v1">ChannelDispatchOperation.Channels</tp:dbus-ref>
-            property, containing the <tp:dbus-ref
-              namespace="im.telepathy.v1">Channel</tp:dbus-ref>s
-            to be dispatched and their properties.</p>
-
-          <tp:rationale>
-            <p>This can't be signalled to the approver through the Properties
-              parameter of this method, because Channels is not an immutable
-              property.</p>
-          </tp:rationale>
-
-          <p>This argument always contains all of the channels in the channel
-            dispatch operation, even if not all of them actually match
-            the <tp:member-ref>ApproverChannelFilter</tp:member-ref>.</p>
-
-          <tp:rationale>
-            <p>This seems the least bad way to handle such a situation;
-              see the discussion on
-              <a href="http://bugs.freedesktop.org/show_bug.cgi?id=21090">bug
-                #21090</a>.</p>
-          </tp:rationale>
-
-          <p>The actual channels to be dispatched may reduce as channels are
-            closed: this is signalled by <tp:dbus-ref
-              namespace="im.telepathy.v1">ChannelDispatchOperation.ChannelLost</tp:dbus-ref>.
-          </p>
-
-          <p>Approvers SHOULD connect to ChannelLost and <tp:dbus-ref
-              namespace="im.telepathy.v1">ChannelDispatchOperation.Finished</tp:dbus-ref>.
-            (if desired) before returning from AddDispatchOperation, since
-            those signals are guaranteed not to be emitted until after all
-            AddDispatchOperation calls have returned (with success or failure)
-            or timed out.</p>
-        </tp:docstring>
-      </arg>
-
-      <arg name="DispatchOperation" type="o" direction="in">
-        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          <p>The
-          <tp:dbus-ref namespace="im.telepathy.v1">ChannelDispatchOperation</tp:dbus-ref>
-            to be processed.</p>
-        </tp:docstring>
-      </arg>
-
       <arg name="Properties" type="a{sv}"
         tp:type="Qualified_Property_Value_Map" direction="in">
         <tp:docstring>
@@ -188,7 +140,11 @@
             <tp:dbus-ref
               namespace="im.telepathy.v1.ChannelDispatchOperation">Account</tp:dbus-ref>,
             <tp:dbus-ref
-              namespace="im.telepathy.v1.ChannelDispatchOperation">Connection</tp:dbus-ref>
+              namespace="im.telepathy.v1.ChannelDispatchOperation">Connection</tp:dbus-ref>,
+            <tp:dbus-ref
+              namespace="im.telepathy.v1.ChannelDispatchOperation">Channel</tp:dbus-ref>,
+            <tp:dbus-ref
+              namespace="im.telepathy.v1.ChannelDispatchOperation">ChannelProperties</tp:dbus-ref>
             and <tp:dbus-ref
               namespace="im.telepathy.v1.ChannelDispatchOperation">PossibleHandlers</tp:dbus-ref>
             properties.</p>