[telepathy-mission-control/master] fd.o #20909: Observer: add Dispatch_Operation and Requests_Satisfied

[Simon McVittie]

This is a D-Bus API break - we now pass more parameters to Observers.
---
 src/mcd-dispatcher.c    |    7 +----
 xml/Client_Observer.xml |   48 +++++++++++++++++++++++++++++++++++++++-------
 2 files changed, 42 insertions(+), 13 deletions(-)

diff --git a/src/mcd-dispatcher.c b/src/mcd-dispatcher.c
index e54b0e6..e9f539b 100644
--- a/src/mcd-dispatcher.c
+++ b/src/mcd-dispatcher.c
@@ -1344,14 +1344,11 @@ mcd_dispatcher_run_observers (McdDispatcherContext *context)
                 mcd_dispatch_operation_get_path (context->operation);
         }
 
-        /* will only be passed to the Observer when we break API */
-        (void) dispatch_operation_path;
-        (void) satisfied_requests;
-
         context->client_locks++;
         mcd_dispatcher_context_ref (context);
         mc_cli_client_observer_call_observe_channels (client->proxy, -1,
-            account_path, connection_path, channels_array, observer_info,
+            account_path, connection_path, channels_array,
+            dispatch_operation_path, satisfied_requests, observer_info,
             observe_channels_cb,
             context, (GDestroyNotify)mcd_dispatcher_context_unref,
             (GObject *)context->dispatcher);
diff --git a/xml/Client_Observer.xml b/xml/Client_Observer.xml
index 09e32f5..0d1d5a1 100644
--- a/xml/Client_Observer.xml
+++ b/xml/Client_Observer.xml
@@ -245,17 +245,49 @@ org.freedesktop.Telepathy.Channel.Requested b=true
 
       <arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]"
         direction="in">
+        <tp:docstring>
+          The <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s
+          and their properties. Their well-known bus names are all the same as
+          that of the Connection.
+        </tp:docstring>
+      </arg>
+
+      <arg name="Dispatch_Operation" type="o" direction="in">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          <p>The
-            <tp:dbus-ref
-              namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s
-            and their properties. Their well-known bus names are all the same
-            as that of the Connection.</p>
+          <p>The path to the <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.DRAFT</tp:dbus-ref>
+            for these channels, or the special value '/' if there is no
+            ChannelDispatchOperation (because the channels were requested, not
+            incoming).</p>
+
+          <p>If the Observer calls <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">Claim</tp:dbus-ref>
+            or <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">HandleWith</tp:dbus-ref>
+            on the dispatch operation, it MUST be careful to avoid deadlock,
+            since these methods cannot return until the Observer has returned
+            from <tp:member-ref>ObserveChannels</tp:member-ref>.</p>
+
+          <tp:rationale>
+            <p>This allows an Observer to <tp:dbus-ref
+                namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">Claim</tp:dbus-ref>
+              a set of channels without having to match up calls to this method
+              with calls to <tp:dbus-ref
+                namespace="org.freedesktop.Telepathy.Client.Approver.DRAFT">AddDispatchOperation</tp:dbus-ref>.</p>
+          </tp:rationale>
+        </tp:docstring>
+      </arg>
+
+      <arg name="Requests_Satisfied" type="ao" direction="in">
+        <tp:docstring>
+          The requests satisfied by these channels.
 
           <tp:rationale>
-            <p>The ChannelDispatchOperation is <em>not</em> supplied: for
-              requests, there isn't one, and for incoming channels, it hasn't
-              been created yet.</p>
+            If the same process is an Observer and a Handler, it can be useful
+            to be given this information as soon as possible (it will also
+            be passed to <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy.Client">Handler.DRAFT.HandleChannels</tp:dbus-ref>).
           </tp:rationale>
         </tp:docstring>
       </arg>
-- 
1.5.6.5