From 2e3a1fb2b627dd5121cf9bd9ab74b6c28bbbec67 Mon Sep 17 00:00:00 2001
From: Guillaume Desmottes <guillaume.desmottes@collabora.co.uk>
Date: Wed, 11 May 2011 14:48:21 +0200
Subject: [PATCH] DelegateChannels: return the list channels of (not) delegated channels (fdo #37109)

---
 spec/Channel_Dispatcher.xml |   75 ++++++++++++++++++++++++++++++++++++-------
 1 files changed, 63 insertions(+), 12 deletions(-)

diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml
index 2de5280..73e59fc 100644
--- a/spec/Channel_Dispatcher.xml
+++ b/spec/Channel_Dispatcher.xml
@@ -572,18 +572,26 @@
     <method name="DelegateChannels"
             tp:name-for-bindings="Delegate_Channels">
       <tp:added version="0.23.1" />
+      <tp:changed version="0.23.UNRELEASED">This methods now returns
+        <var>Delegated</var> and <var>Not_Delegated</var> instead of nothing.
+        <tp:dbus-ref namespace="ofdT.Client.Handler">HandleChannels</tp:dbus-ref>
+        is now called once per <var>Channel</var> in <var>Channels</var>.
+      </tp:changed>
       <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>
+        <p>For each <var>Channel</var> in <var>Channels</var>, if another
+          <tp:dbus-ref namespace="ofdT.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>
+          <tp:dbus-ref namespace="ofdT.Client.Handler">HandleChannels</tp:dbus-ref>
+          will be called on it until a
+          <tp:dbus-ref namespace="ofdT.Client">Handler</tp:dbus-ref>
+          accepts it.</p>
+
+        <p>This method returns once all the <var>Channels</var> have either
+          been accepted or rejected by Handlers.</p>
 
         <p>If this method fails, the original
           <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>
@@ -626,6 +634,25 @@
         </tp:docstring>
       </arg>
 
+      <arg direction="out" name="Delegated" type="ao">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The list of channels which have been delegated; the caller is no
+          longer handling these channels.</p>
+
+          <p>The client should remove these channels from its
+          <tp:dbus-ref namespace="ofdT.Client.Handler">HandledChannels</tp:dbus-ref>
+          property.</p>
+        </tp:docstring>
+      </arg>
+
+      <arg direction="out" name="Not_Delegated" type="a{o(ss)}"
+       tp:type="Not_Delegated_Map">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The list of channels which have NOT been delegated; the caller is still
+          handling these channels.</p>
+        </tp:docstring>
+      </arg>
+
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
           <tp:docstring>
@@ -640,16 +667,40 @@
             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>
 
+    <tp:mapping name="Not_Delegated_Map">
+      <tp:docstring>
+        A mapping associating not delegated channel with an error.
+      </tp:docstring>
+
+      <tp:member type="o" name="Channel">
+        <tp:docstring>
+          The path of the channel
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="(ss)" name="Error" tp:type="Not_Delegated_Error">
+        <tp:docstring>
+          An error describing why the channel has not be delegated
+        </tp:docstring>
+      </tp:member>
+    </tp:mapping>
+
+    <tp:struct name="Not_Delegated_Error">
+      <tp:member type="s" name="Error_Name" tp:type="DBus_Error_Name">
+        <tp:docstring>
+          the name of a D-Bus error describing what went wrong.
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="s" name="Error_Message">
+        <tp:docstring>
+          a human-readable informative error message.
+        </tp:docstring>
+      </tp:member>
+    </tp:struct>
+
     <method name="PresentChannel"
             tp:name-for-bindings="Present_Channel">
       <tp:added version="0.23.1" />
-- 
1.7.4.1