add ChannelDispatcher.DelegateChannels() (fdo #25293)

1 files changed, 81 insertions, 0 deletions

diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml
index 2dd000b4..0fe506da 100644
--- a/spec/Channel_Dispatcher.xml
+++ b/spec/Channel_Dispatcher.xml
@@ -569,6 +569,87 @@
 
     </method>
 
+    <method name="DelegateChannels"
+            tp:name-for-bindings="Delegate_Channels">
+      <tp:added version="0.23.UNRELEASED" />
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Called by a
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>
+          to redispatch a bunch of channels it is currently handling.</p>
+
+        <p>If another
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>
+          can be found,
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>
+          will be called on it and this function will succeed. In that case,
+          the original <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>
+          does not longer handle those channels.</p>
+
+        <p>If this method fails, the original
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>
+          is still handling the channels.</p>
+
+      </tp:docstring>
+
+      <arg direction="in" name="Channels" type="ao">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The list of channels to redispatch. The caller has to be the current
+            <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>
+            of all of these channels
+          </p>
+        </tp:docstring>
+      </arg>
+
+      <arg direction="in" name="User_Action_Time" type="x"
+        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 channels
+            delegation 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>
+
+      <arg direction="in" name="Preferred_Handler" type="s"
+        tp:type="DBus_Well_Known_Name">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>Either the well-known bus name (starting with
+            <code>org.freedesktop.Telepathy.Client.</code>)
+            of the preferred new handler for these
+            channels, 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>CreateChannelWithHints</tp:member-ref>.</p>
+
+        </tp:docstring>
+      </arg>
+
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+          <tp:docstring>
+            The Preferred_Handler is syntactically invalid or does
+            not start with <code>org.freedesktop.Telepathy.Client.</code> or
+            the Account does not exist.
+          </tp:docstring>
+        </tp:error>
+
+        <tp:error name="org.freedesktop.Telepathy.Error.NotYours">
+          <tp:docstring>
+            The caller is not currently handling the channels.
+          </tp:docstring>
+        </tp:error>
+
+        <tp:error name="org.freedesktop.Telepathy.Error.NotCapable">
+          <tp:docstring>
+            There is no other suitable Handler.
+          </tp:docstring>
+        </tp:error>
+      </tp:possible-errors>
+
+    </method>
+
     <property name="SupportsRequestHints"
               tp:name-for-bindings="Supports_Request_Hints"
               type="b" access="read">