update to spec 0.21.11

Add TP_PROP_CLIENT_OBSERVER_DELAY_APPROVERS

4 files changed, 54 insertions, 9 deletions

diff --git a/spec/Channel_Interface_Credentials_Storage.xml b/spec/Channel_Interface_Credentials_Storage.xml
index 14e6f3d8b..e44b13e32 100644
--- a/spec/Channel_Interface_Credentials_Storage.xml
+++ b/spec/Channel_Interface_Credentials_Storage.xml
@@ -17,7 +17,8 @@ Lesser General Public License for more details.</p>
 License along with this library; if not, write to the Free Software
 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
   </tp:license>
-  <interface name="org.freedesktop.Telepathy.Channel.Interface.CredentialsStorage.DRAFT">
+  <interface name="org.freedesktop.Telepathy.Channel.Interface.CredentialsStorage.DRAFT"
+    tp:causes-havoc="experimental">
     <tp:added version="0.21.10">(draft 1)</tp:added>
     <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.SASLAuthentication"/>
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml
index 1a9c397ef..fbb67925e 100644
--- a/spec/Channel_Request.xml
+++ b/spec/Channel_Request.xml
@@ -2,8 +2,8 @@
 <node name="/Channel_Request"
   xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
 
-  <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
-  <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
+  <tp:copyright>Copyright © 2008–2011 Collabora Ltd.</tp:copyright>
+  <tp:copyright>Copyright © 2008–2009 Nokia Corporation</tp:copyright>
   <tp:license xmlns="http://www.w3.org/1999/xhtml">
     <p>This library is free software; you can redistribute it and/or
       modify it under the terms of the GNU Lesser General Public
@@ -25,12 +25,15 @@
     <tp:added version="0.17.26">(as a stable interface)</tp:added>
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-      <p>A channel request is an object in the ChannelDispatcher representing
-        an ongoing request for some channels to be created or found. There
+      <p>A channel request is an object in the <tp:dbus-ref
+        namespace='ofdT'>ChannelDispatcher</tp:dbus-ref> representing
+        an ongoing request for some channels to be created or found. They are
+        created by methods such as <tp:dbus-ref
+        namespace='ofdT.ChannelDispatcher'>CreateChannel</tp:dbus-ref>. There
         can be any number of ChannelRequest objects at the same time.</p>
 
       <p>Its well-known bus name is the same as that of the ChannelDispatcher,
-        "org.freedesktop.Telepathy.ChannelDispatcher".</p>
+        <code>"org.freedesktop.Telepathy.ChannelDispatcher"</code>.</p>
 
       <tp:rationale>
         <p>See
diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml
index b944ffd02..b42b3b1df 100644
--- a/spec/Client_Observer.xml
+++ b/spec/Client_Observer.xml
@@ -105,14 +105,13 @@
           will return successfully if the channels were successfully
           claimed, or failure if someone else got there first.</li>
       </ol>
-<!--
+
       <p>Non-interactive approvers implemented as observers SHOULD
         also set <tp:member-ref>DelayApprovers</tp:member-ref> to TRUE
         so that other Approvers are not called on until all observers
         return from <tp:member-ref>ObserveChannels</tp:member-ref>.
         This gives non-interactive approvers a chance to claim the
         channels before Approvers are called.</p>
--->
     </tp:docstring>
 
     <property name="ObserverChannelFilter"
@@ -401,6 +400,48 @@ Recover=true
 
     </method>
 
+    <property name="DelayApprovers" type="b" access="read"
+      tp:name-for-bindings="Delay_Approvers">
+      <tp:added version="0.21.11"/>
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>If true, the channel dispatcher will wait for
+            <tp:member-ref>ObserveChannels</tp:member-ref> to return
+            before calling <tp:dbus-ref
+            namespace="ofdT.Client">Approver.AddDispatchOperation</tp:dbus-ref>
+            on appropriate Approvers.</p>
+
+          <p>This property SHOULD be false unless there is a reason
+            why a channel should not be given to approvers. An example
+            of this is if an Observer is also a Handler and wants to
+            <tp:dbus-ref
+            namespace="ofdT.ChannelDispatchOperation">Claim</tp:dbus-ref>
+            a channel so that it becomes its handler and doesn't want
+            any approver to be called, this property should be true.</p>
+
+          <p>Observers and Approvers should be called at the same time
+            in normal operation (with this property set to false) to
+            improve responsiveness. For example, if an incoming call
+            appears, the approver should get the channel as fast as
+            possible to show a dialog, but if an approver has to make
+            round-trips to set itself up, then the approval of the
+            channel is delayed. As a result, it is recommended for this
+            property to remain false unless absolutely necessary.</p>
+
+          <p>For service-activatable clients, this property should be
+            specified in the observer's <tt>.client</tt> file as
+            follows:</p>
+
+          <p>If this property is not implemented (telepathy-mission-control
+            5.7.5 and older), the channel dispatcher SHOULD consider it as
+            being false.</p>
+
+<pre>
+[org.freedesktop.Telepathy.Client.Observer]
+DelayApprovers=true
+</pre>
+        </tp:docstring>
+    </property>
+
   </interface>
 </node>
 <!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/all.xml b/spec/all.xml
index 6f4f8e371..95d8574de 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -3,7 +3,7 @@
   xmlns:xi="http://www.w3.org/2001/XInclude">
 
 <tp:title>Telepathy D-Bus Interface Specification</tp:title>
-<tp:version>0.21.10</tp:version>
+<tp:version>0.21.11</tp:version>
 
 <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright>
 <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright>