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