Abbreviate CreateChannel/EnsureChannel docs: refer to ...WithHints instead.

1 files changed, 27 insertions, 157 deletions

diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml
index c26183e3..1528a096 100644
--- a/spec/Channel_Dispatcher.xml
+++ b/spec/Channel_Dispatcher.xml
@@ -101,41 +101,9 @@
 
     <method name="CreateChannel" tp:name-for-bindings="Create_Channel">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>Start a request to create a channel. This initially just creates a
-          <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
-          object, which can be used to continue the request and track its
-          success or failure.</p>
-
-        <tp:rationale>
-          <p>The request can take a long time - in the worst case, the
-            channel dispatcher has to ask the account manager to put the
-            account online, the account manager has to ask the operating
-            system to obtain an Internet connection, and the operating
-            system has to ask the user whether to activate an Internet
-            connection using an on-demand mechanism like dialup.</p>
-
-          <p>This means that using a single D-Bus method call and response
-            to represent the whole request will tend to lead to that call
-            timing out, which is not the behaviour we want.</p>
-        </tp:rationale>
-
-        <p>If this method is called for an Account that is disabled, invalid
-          or otherwise unusable, no error is signalled until
-          <tp:dbus-ref
-            namespace="org.freedesktop.Telepathy">ChannelRequest.Proceed</tp:dbus-ref>
-          is called, at which point
-          <tp:dbus-ref
-            namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref>
-          is emitted with an appropriate error.</p>
-
-        <tp:rationale>
-          <p>This means there's only one code path for errors, apart from
-            InvalidArgument for "that request makes no sense".</p>
-
-          <p>It also means that the request will proceed if the account is
-            enabled after calling CreateChannel, but before calling
-            Proceed.</p>
-        </tp:rationale>
+        <p>Equivalent to calling
+          <tp:member-ref>CreateChannelWithHints</tp:member-ref> with an empty
+          <var>Hints</var> parameter.</p>
       </tp:docstring>
 
       <arg direction="in" name="Account" type="o">
@@ -149,17 +117,11 @@
       <arg direction="in" name="Requested_Properties" type="a{sv}"
         tp:type="Qualified_Property_Value_Map">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          <p>A dictionary containing desirable properties. This has the same
-            semantics as the corresponding parameter to
-            <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>.
-          </p>
+          <p>A dictionary containing desirable properties.</p>
 
-          <p>Certain properties will not necessarily make sense in this
-            dictionary: for instance,
-            <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
-            can only be given if the requester is able to interact with a
-            <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
-            to the desired account.</p>
+          <p>This parameter is used in the same way as the corresponding
+            parameter to
+            <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
         </tp:docstring>
       </arg>
 
@@ -167,12 +129,11 @@
         tp:type="User_Action_Timestamp">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
           <p>The time at which user action occurred, or 0 if this channel
-            request is for some reason not involving user action.
-            The <tp:dbus-ref
-              namespace="org.freedesktop.Telepathy.ChannelRequest">UserActionTime</tp:dbus-ref>
-            property will be set to this value, and it will eventually be
-            passed as the <code>User_Action_Time</code> parameter of <tp:dbus-ref
-              namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>.</p>
+            request is for some reason not involving user action.</p>
+
+          <p>This parameter is used in the same way as the corresponding
+            parameter to
+            <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
         </tp:docstring>
       </arg>
 
@@ -183,51 +144,12 @@
             <code>org.freedesktop.Telepathy.Client.</code>)
             of the preferred handler for this
             channel, or an empty string to indicate that any handler would be
-            acceptable. The channel dispatcher SHOULD dispatch as many as
-            possible of the resulting channels (ideally, all of them)
-            to that handler—irrespective of whether that handler's <tp:dbus-ref
-              namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>
-            matches the channel—and SHOULD remember the preferred handler
-            so it can try to dispatch subsequent channels in the same bundle
-            to the same handler.</p>
-
-          <tp:rationale>
-            <p>This must be the well-known bus name, not the unique name,
-              to ensure that all handlers do indeed have the Client API,
-              and the Client object on the handler can be located easily.</p>
-
-            <p>This is partly so the channel dispatcher can call
-              <tp:dbus-ref
-                namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>
-              on it, and partly so the channel dispatcher
-              can recover state if it crashes and is restarted.</p>
-
-            <p>The filter should be disregarded for ease of use of this
-              interface: clients will usually use this argument to request
-              channels be sent to themself, and this should trump the filter
-              not matching. This also allows a client to become the handler
-              for a channel produced by one of its own requests, while not
-              being a candidate to handle other channels of that type.</p>
-          </tp:rationale>
+            acceptable.</p>
 
-          <p>If this is a well-known bus name and the handler has the
-            Requests interface, the channel dispatcher SHOULD
-            call <tp:dbus-ref
-              namespace="org.freedesktop.Telepathy.Client.Interface.Requests">AddRequest</tp:dbus-ref>
-            on that Handler after this method has returned.</p>
-
-          <tp:rationale>
-            <p>This ordering allows a Handler which calls CreateChannel with
-              itself as the preferred handler to associate the call to
-              AddRequest with that call.</p>
-          </tp:rationale>
-
-          <p>This is copied to the ChannelRequest that is returned,
-            as the <tp:dbus-ref
-              namespace="org.freedesktop.Telepathy.ChannelRequest">PreferredHandler</tp:dbus-ref>
-            property.</p>
+          <p>This parameter is used in the same way as the corresponding
+            parameter to
+            <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
         </tp:docstring>
-
         <tp:changed version="0.19.0">
           Previously, the spec didn't say that this should disregard the
           handler's filter. This has been implemented since
@@ -258,25 +180,9 @@
 
     <method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>Start a request to ensure that a channel exists, creating it if
-          necessary.  This initially just creates a <tp:dbus-ref
-            namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
-          object, which can be used to continue the request and track its
-          success or failure.</p>
-
-        <p>If this method is called for an Account that is disabled, invalid
-          or otherwise unusable, no error is signalled until
-          <tp:dbus-ref
-            namespace="org.freedesktop.Telepathy">ChannelRequest.Proceed</tp:dbus-ref>
-          is called, at which point
-          <tp:dbus-ref
-            namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref>
-          is emitted with an appropriate error.</p>
-
-        <tp:rationale>
-          <p>The rationale is as for <tp:dbus-ref
-              namespace='org.freedesktop.Telepathy.ChannelDispatcher'>CreateChannel</tp:dbus-ref>.</p>
-        </tp:rationale>
+        <p>Equivalent to calling
+          <tp:member-ref>EnsureChannelWithHints</tp:member-ref> with an empty
+          <var>Hints</var> parameter.</p>
       </tp:docstring>
 
       <arg direction="in" name="Account" type="o">
@@ -290,17 +196,11 @@
       <arg direction="in" name="Requested_Properties" type="a{sv}"
         tp:type="Qualified_Property_Value_Map">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          <p>A dictionary containing desirable properties. This has the same
-            semantics as the corresponding parameter to
-            <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>.
-          </p>
+          <p>A dictionary containing desirable properties.</p>
 
-          <p>Certain properties will not necessarily make sense in this
-            dictionary: for instance,
-            <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
-            can only be given if the requester is able to interact with a
-            <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
-            to the desired account.</p>
+          <p>This parameter is used in the same way as the corresponding
+            parameter to
+            <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
         </tp:docstring>
       </arg>
 
@@ -311,7 +211,8 @@
             request is for some reason not involving user action.</p>
 
           <p>This parameter is used in the same way as the corresponding
-            parameter to <tp:member-ref>CreateChannel</tp:member-ref>.</p>
+            parameter to
+            <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
         </tp:docstring>
       </arg>
 
@@ -324,38 +225,7 @@
             channel, or an empty string to indicate that any handler would be
             acceptable. The behaviour and rationale are the same as for the
             corresponding parameter to
-            <tp:member-ref>CreateChannel</tp:member-ref>, except as noted
-            here.</p>
-
-          <p>If any new channels are created in response to this
-            request, the channel dispatcher SHOULD dispatch as many as
-            possible of the resulting channels (ideally, all of them)
-            to that handler, and SHOULD remember the preferred handler
-            so it can try to dispatch subsequent channels in the same bundle
-            to the same handler. If the requested channel already exists (that
-            is, <tp:dbus-ref
-              namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>
-            returns <code>Yours=False</code>) then the channel dispatcher
-            SHOULD re-dispatch the channel to its existing handler, and MUST
-            NOT dispatch it to this client (unless it is the existing handler);
-            the request is still deemed to have succeeded in this case.</p>
-
-          <tp:rationale>
-            <p>An address book application, for example, might call <tp:dbus-ref
-                namespace='org.freedesktop.Telepathy.ChannelDispatcher'>EnsureChannel</tp:dbus-ref>
-              to ensure that a text channel with a particular contact is
-              displayed to the user; it does not care whether a new channel was
-              made. An IM client might call <tp:dbus-ref
-                namespace='org.freedesktop.Telepathy.ChannelDispatcher'>EnsureChannel</tp:dbus-ref>
-              in response to the user double-clicking an entry in the contact
-              list, with itself as the <code>Preferred_Handler</code>; if the
-              user already has a conversation with that contact in another
-              application, they would expect the existing window to be
-              presented, rather than their double-click leading to an error
-              message.  So the request should succeed, even if its
-              <code>Preferred_Handler</code> is not used.</p>
-          </tp:rationale>
-
+            <tp:member-ref>EnsureChannelWithHints</tp:member-ref>.</p>
         </tp:docstring>
       </arg>
 
@@ -585,7 +455,7 @@
 
         <tp:rationale>
           <p>The rationale is as for <tp:dbus-ref
-              namespace='org.freedesktop.Telepathy.ChannelDispatcher'>CreateChannel</tp:dbus-ref>.</p>
+              namespace='org.freedesktop.Telepathy.ChannelDispatcher'>CreateChannelWithHints</tp:dbus-ref>.</p>
         </tp:rationale>
       </tp:docstring>