Update to spec 0.19.4 (Observer.Recover)

1 files changed, 54 insertions, 4 deletions

diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml
index 35e6d91d5..a2256a753 100644
--- a/spec/Client_Observer.xml
+++ b/spec/Client_Observer.xml
@@ -180,6 +180,43 @@ org.freedesktop.Telepathy.Channel.Requested b=true
       </tp:docstring>
     </property>
 
+    <property name="Recover" tp:name-for-bindings="Recover" type="b"
+      access="read">
+      <tp:added version="0.19.4">
+        When using telepathy-mission-control, version 5.4.0 or later is
+        needed for this property to be useful.
+      </tp:added>
+
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>If true, upon the startup of this observer, <tp:dbus-ref
+        namespace="org.freedesktop.Telepathy.Client.Observer">ObserveChannels</tp:dbus-ref>
+        will be called for every already existing channel matching
+        its <tp:dbus-ref
+        namespace="org.freedesktop.Telepathy.Client.Observer">ObserverChannelFilter</tp:dbus-ref></p>
+
+        <p>When activatable client having this property disappears from the bus
+        and there are channels matching its ObserverChannelFilter,
+        ObserveChannels will be called immediately to reactivate it again.</p>
+        <tp:rationale>
+          <p>This means that if an activatable Observer crashes, it will
+            be restarted as soon as possible; while there is an unavoidable
+            possibility that it will miss some events during this process
+            (particularly <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>
+            messages), this window of event loss is kept to a minimum.</p>
+
+           <p>Non-activatable observers can't take advantage of this
+            mechanism, but setting this property on a non-activatable
+            observer does allow it to "catch up" on channels that are
+            currently active at the time that it starts up.</p>
+        </tp:rationale>
+
+        <p>When the ObserveChannels method is called due to observer recovery,
+        the "Observer_Info" dictionary will contain one extra item with key
+        "recovering" and boolean value of True.</p>
+      </tp:docstring>
+    </property>
+
     <method name="ObserveChannels" tp:name-for-bindings="Observe_Channels">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>Called by the channel dispatcher when channels in which the
@@ -294,10 +331,23 @@ org.freedesktop.Telepathy.Channel.Requested b=true
 
       <arg name="Observer_Info" type="a{sv}" direction="in">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          <p>Additional information about these channels. No keys are
-            currently defined.</p>
-
-          <p>If keys are defined for this dictionary, all will be optional;
+          <p>Additional information about these channels. Currently defined
+            keys are:</p>
+
+          <dl>
+            <dt><code>recovering</code> - b</dt>
+            <dd>True if ObserveChannels was called on existing channel due to
+              observer recovery, otherwise False.
+              <tp:rationale>
+                This allows observers to distinguish between new channels (the normal
+                case), and existing channels that were given to the observer in order
+                to catch up on previous events (perhaps after a previous instance of
+                the same observer crashed).
+              </tp:rationale>
+            </dd>
+          </dl>
+
+          <p>All defined keys for this dictionary are optional;
             observers MAY safely ignore any entry in this dictionary.</p>
         </tp:docstring>
       </arg>