Update Requests spec plus EnsureChannel to that from a spec branch

(rather than using a placeholder spec for EnsureChannel)

1 files changed, 96 insertions, 74 deletions

diff --git a/spec/Connection_Interface_Requests.xml b/spec/Connection_Interface_Requests.xml
index a9699765a..c409dcaf1 100644
--- a/spec/Connection_Interface_Requests.xml
+++ b/spec/Connection_Interface_Requests.xml
@@ -201,11 +201,11 @@
                 time</li>
               <li>a channel matching the request has already been requested
                 (by a previous call to CreateChannel,
+                <tp:member-ref>EnsureChannel</tp:member-ref>,
                 <tp:dbus-ref
                   namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref>
-                or some future channel-requesting method)
-                and the protocol requires that only one such channel can exist
-                at a time</li>
+                or similar) and the protocol requires that only one such
+                channel can exist at a time</li>
             </ul>
           </tp:docstring>
         </tp:error>
@@ -215,85 +215,51 @@
       </tp:possible-errors>
     </method>
 
-    <signal name="NewChannels" tp:name-for-bindings="New_Channels">
-      <tp:added version="0.17.11">(as stable API)</tp:added>
-
+    <method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>New channels have been created. The connection manager SHOULD emit
-          a single signal for any group of closely related channels that are
-          created at the same time, so that the channel dispatcher can try to
-          dispatch them to a handler as a unit.</p>
-
-        <p>In particular, if additional channels are created as a side-effect
-          of a call to <tp:member-ref>CreateChannel</tp:member-ref>,
-          these channels SHOULD appear in the same NewChannels signal as
-          the channel that satisfies the request.</p>
+        <p>Request that channels are ensured to exist.</p>
 
         <tp:rationale>
-          <p>Joining a MUC Tube in XMPP requires joining the corresponding
-            MUC (chatroom), so a Text channel can be created as a
-            side-effect.</p>
+          <p>The connection manager is in the best position to determine which
+            existing channels could satisfy which requests.</p>
         </tp:rationale>
-      </tp:docstring>
 
-      <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
-          <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>
-    </signal>
-
-    <method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel">
-      <tp:added version="0.17.UNRELEASED"/>
-
-      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>Request a channel with certain properties; whether or not the
-          channel existed before this method call, it should exist when it
-          returns.</p>
       </tp:docstring>
 
       <arg direction="in" name="Request" type="a{sv}"
         tp:type="Qualified_Property_Value_Map">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          <p>A dictionary containing desirable properties. Some properties
-            are defined such that only an exact match makes sense, and
-            connection managers MUST NOT satisfy a request with a channel
-            where that property does not match; some properties are defined
-            such that the connection manager MAY treat the request as merely
-            a hint, and make a best-effort attempt to satisfy it. This is
-            documented separately for each property.</p>
-
-          <p>If this dictionary contains a property whose semantics
-            are not known to the connection manager, this method MUST fail
-            without side-effects (in particular it must not create a new
-            channel).</p>
-
-          <tp:rationale>
-            <p>This is necessary if we want to be able to invent properties
-              in future that, when used in a request, are hard requirements
-              rather than just hints. A connection manager that did not know
-              the semantics of those properties could incorrectly return a
-              new channel that did not satisfy the requirements.</p>
-          </tp:rationale>
-
-          <p>The connection manager MUST NOT respond successfully,
-            and SHOULD NOT create a new channel or cause any other
-            side-effects, unless it can create a new channel or return an
-            existing channel that satisfies the client's requirements.</p>
+          <p>A dictionary containing desirable properties, with the same
+            semantics as the corresponding parameter to
+            <tp:member-ref>CreateChannel</tp:member-ref>.</p>
+        </tp:docstring>
+      </arg>
 
-          <p>Properties that will be set by this argument need not have write
-            access on the returned channel - indeed, it is
-            expected that most will be read-only.</p>
+      <arg name="Yours" direction="out" type="b">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>If false, the caller of EnsureChannel MUST assume that some
+            other process is handling this channel; if true, the caller of
+            EnsureChannel SHOULD handle it themselves or delegate it to another
+            client.</p>
+
+          <p>If the creation of a channel makes several calls to EnsureChannel
+            (and no other requests) successful, exactly one of those calls MUST
+            return a true value for this argument.</p>
+
+          <p>If the creation of a channel makes other requests successful,
+            the value returned for this argument MUST be such that exactly
+            one of the clients making requests ends up responsible for the
+            channel. In particular, if CreateChannel returns a channel
+            <em>C</em>, any EnsureChannel calls that also return <em>C</em>
+            MUST return a false value for this argument.</p>
         </tp:docstring>
       </arg>
 
       <arg name="Channel" direction="out" type="o">
         <tp:docstring>
-          The Channel object.
+          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>
       </arg>
 
@@ -308,16 +274,72 @@
         </tp:docstring>
       </arg>
 
-      <arg name="Yours" direction="out" type="b">
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+          <tp:docstring>
+            The channel request was one that can never succeed,
+            such as requesting an unsupported channel type, or requesting
+            a channel type which this connection manager does not support with
+            the given target handle type.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
+          <tp:docstring>
+            An invalid handle was requested as the value of a property whose
+            value is a handle (like
+            <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.TargetHandle</tp:dbus-ref>),
+            or a syntactically invalid identifier was requested as the value
+            of a property whose value is the string corresponding to a handle
+            (like TargetID).
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+          <tp:docstring>
+            The requested channel cannot be created, but in
+            principle, a similar request might succeed in future. For instance,
+            this might be because the requested contact is using a client
+            that lacks a particular feature.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/>
+      </tp:possible-errors>
+    </method>
+
+    <signal name="NewChannels" tp:name-for-bindings="New_Channels">
+      <tp:added version="0.17.11">(as stable API)</tp:added>
+
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>New channels have been created. The connection manager SHOULD emit
+          a single signal for any group of closely related channels that are
+          created at the same time, so that the channel dispatcher can try to
+          dispatch them to a handler as a unit.</p>
+
+        <p>In particular, if additional channels are created as a side-effect
+          of a call to <tp:member-ref>CreateChannel</tp:member-ref>,
+          these channels SHOULD appear in the same NewChannels signal as
+          the channel that satisfies the request.</p>
+
+        <tp:rationale>
+          <p>Joining a MUC Tube in XMPP requires joining the corresponding
+            MUC (chatroom), so a Text channel can be created as a
+            side-effect.</p>
+        </tp:rationale>
+      </tp:docstring>
+
+      <arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]">
         <tp:docstring>
-          True if the channel was created afresh to satisfy the caller's
-          request, and hence the caller should take responsibility for it as if
-          it had called CreateChannel.  This parameter MUST NOT be True for
-          more than one call of EnsureChannel per channel, and MUST NOT be True
-          if the channel is also returned to a caller of CreateChannel.
+          The channels and their details. All channels that are signalled
+          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>
-    </method>
+    </signal>
 
     <property name="Channels" tp:name-for-bindings="Channels"
       type="a(oa{sv})" access="read" tp:type="Channel_Details[]">
@@ -349,7 +371,7 @@
       </arg>
     </signal>
 
-    <tp:mapping name="Channel_Class">
+    <tp:mapping name="Channel_Class" array-name="Channel_Class_List">
       <tp:added version="0.17.11">(as stable API)</tp:added>
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>Mapping representing a class of channels that can be requested