From 5bb04923b7ef78b8484f0a8b15a2a8c65a0ccd6c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Olivier=20Cr=C3=AAte?= <olivier.crete@collabora.com>
Date: Tue, 13 Mar 2012 20:40:34 -0400
Subject: [PATCH] Explain that Approvers can NOT be used with a Call channel.

Also suggest a different way to offer the same functionality.
---
 spec/Channel_Type_Call.xml |   25 ++++++++++++++++++++-----
 1 files changed, 20 insertions(+), 5 deletions(-)

diff --git a/spec/Channel_Type_Call.xml b/spec/Channel_Type_Call.xml
index 383db25..2c63a05 100644
--- a/spec/Channel_Type_Call.xml
+++ b/spec/Channel_Type_Call.xml
@@ -186,8 +186,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         show that the aforementioned audio and video contents have names
         "audio" and "video".</p>
 
-      <p>Once the handler has notified the local user that there is an
-        incoming call waiting for acceptance, the handler should call
+      <p>Since the user should only be notified of a call when
+        it reaches the <tp:value-ref type="Call_State">Initialised</tp:value-ref>
+        state, the handler must be called before any Approver. There can be
+        only a SINGLE handler for incoming calls and the handler
+        MUST set the <tp:dbus-ref namespace='ofdT.Client.Handler'>BypassApproval</tp:dbus-ref>
+        property to True. Any client other than the handler that wishes to
+        act as an approver must be implemented as an Observer instead and wait
+        until the channel's state reaches the <tp:value-ref type="Call_State">Initialised</tp:value-ref> state before notifying the user.
+        When the handler or any Observer wants to accept or reject the channel,
+        it must call <tp:member-ref>Accept</tp:member-ref> or
+	<tp:member-ref>Hangup</tp:member-ref>. It is then the responsability of
+	the Handler to  <tp:dbus-ref namespace='ofdT.Channel'>Close</tp:dbus-ref> the channel.</p>
+
+      <p>Once the handler or an observer has notified the local user that there is an
+        incoming call waiting for acceptance, the handler or observer should call
         <tp:member-ref>SetRinging</tp:member-ref> to let the CM know.
         The new channel should also be given to telepathy-farstream to
         work out how the two participants will connect together.
@@ -195,7 +208,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         <tp:dbus-ref namespace="ofdT.Call1">Content</tp:dbus-ref>s
         to negotiate codecs and transports.</p>
 
-      <p>To pick up the call, the handler should call
+      <p>To pick up the call, the handler or observer should call
         <tp:member-ref>Accept</tp:member-ref>. The
         <tp:member-ref>CallState</tp:member-ref> property changes to
         <tp:value-ref type="Call_State">Accepted</tp:value-ref> and once media is
@@ -205,14 +218,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         change to <tp:value-ref type="Call_State">Active</tp:value-ref>, to inform the user
         that they have a correctly working call there is nothing amiss.</p>
 
-      <p>To reject the call, the handler should call the
+      <p>To reject the call, the handler or observer should call the
         <tp:member-ref>Hangup</tp:member-ref> method. The
         <tp:member-ref>CallState</tp:member-ref> property will change to
         <tp:value-ref type="Call_State">Ended</tp:value-ref> and the
         <tp:member-ref>CallStateReason</tp:member-ref> property will
         change to (self handle,
         <tp:value-ref type="Call_State_Change_Reason">User_Requested</tp:value-ref>,
-        "org.freedesktop.Telepathy.Error.Rejected").</p>
+        "org.freedesktop.Telepathy.Error.Rejected"). It is then the
+	responsability of the Handler to
+        <tp:dbus-ref namespace='ofdT.Channel'>Close</tp:dbus-ref> the channel.</p>
 
       <h4>Ongoing calls</h4>
 
-- 
1.7.7.6