WebTelephony API: add API to nsIDOMTelephonyCall to hold a call

[Hsin-Yi Tsai]

Hi there,

Currently we can only answer() or hangUp() a call. However, we should be
able to hold a call and answer it later.
https://bugzilla.mozilla.org/show_bug.cgi?id=735170
<https://bugzilla.mozilla.org/show_bug.cgi?id=735170>

Here are the details of the scenarios of holding a call.

First, we are making a phone call with A, i.e. the call is in connected
state. Then we want to hold A for a while and keep talking to it later.
So, we should make the call into "held" state, then resume connecting
with A later.

Second, we are talking with A, so the call is in connected state. In the
meanwhile, B is trying to reach us via phone. Since we are connected
with A, the call state of B is "waiting." If we want to answer B (make B
from waiting into connected), then we should also make the call of A
into held. Later we can resume connecting with A.

Below you can find an enhanced WebTelephony API for holding a call.

interface nsIDOMTelephonyCall : nsIDOMEventTarget
{
readonly attribute DOMString number;
readonly attribute DOMString state;
// "dialing", "ringing", "busy", "connecting", "connected",
"disconnecting", "disconnected", "incoming",
// Add new states: "waiting", "holding", "held", "resuming"

void answer(); //change an incoming call or a waiting call into
"connected"
void hangUp();
void hold(); //change a connected call into "held"
void resume(); //change a "held" call into connected

attribute nsIDOMEventListener onstatechange;

attribute nsIDOMEventListener ondialing;
attribute nsIDOMEventListener onringing;
attribute nsIDOMEventListener onbusy;
attribute nsIDOMEventListener onconnecting;
attribute nsIDOMEventListener onconnected;
attribute nsIDOMEventListener ondisconnecting;
attribute nsIDOMEventListener ondisconnected;
attribute nsIDOMEventListener onincoming;

attribute nsIDOMEventListener onwaiting; //new
attribute nsIDOMEventListener onholding; //new
attribute nsIDOMEventListener onheld; //new
attribute nsIDOMEventListener onresuming; //new
};


Thanks,
Hsinyi

[Hsin-Yi Tsai]

Hi folks,

More details about the proposal for the improved API are shown below.
How do you think about this? Any feedbacks are welcome. Thanks!


於 2012年03月14日 17:37, Hsin-Yi Tsai 提到:

> Hi there,
>
> Currently we can only answer() or hangUp() a call. However, we should
> be able to hold a call and answer it later.
> https://bugzilla.mozilla.org/show_bug.cgi?id=735170
> <https://bugzilla.mozilla.org/show_bug.cgi?id=735170>
>
> Here are the details of the scenarios of holding a call.
>
> First, we are making a phone call with A, i.e. the call is in
> connected state. Then we want to hold A for a while and keep talking
> to it later. So, we should make the call into "held" state, then
> resume connecting with A later.
>
> Second, we are talking with A, so the call is in connected state. In
> the meanwhile, B is trying to reach us via phone. Since we are
> connected with A, the call state of B is "waiting." If we want to
> answer B (make B from waiting into connected), then we should also
> make the call of A into held. Later we can resume connecting with A.
>
> Below you can find an enhanced WebTelephony API for holding a call.
>
> interface nsIDOMTelephonyCall : nsIDOMEventTarget
> {
> readonly attribute DOMString number;
> readonly attribute DOMString state;
> // "dialing", "ringing", "busy", "connecting", "connected",
> "disconnecting", "disconnected", "incoming",
> // Add new states: "waiting", "holding", "held", "resuming"

//current states:dialing, ringing, busy, connecting, connected,
disconnecting, disconnected, incoming
// NEW states: "waiting", another type of incoming call when there is a
connected call
// NEW states: "holding", "held", "resuming"
readonly attribute DOMString state;

//Specify which call the dialer is handling? Not very sure whether this
is needed.
readonly attribute DOMString callIndex;

>
> void answer(); //change an incoming call or a waiting call into
> "connected"

//Make an incoming call to be connected
// Call A:incoming --> connected
//Make a waiting call to be connected, and switch the existing connected
call to "held" state
// Call A:waiting --> connected, Call B: connected --> held
void answer();
> void hangUp();
//Make a call to be disconnected if there is no waiting call or held call
// A: any --> disconnected
//Reject an incoming call
// A: incoming --> disconnected
//Reject a waiting call, and remain the existing connected call
// A: waiting --> disconnected, B: connected --> connected
//Hang up the existing connected call, and make a waiting call to be
connected
// A: connected --> disconnected, B: waiting --> connected

void hangUp();
> void hold(); //change a connected call into "held"

//Change a connected call to "held" state
// A: connected --> held
void hold();

> void resume(); //change a "held" call into connected

//Switch a "held" call back to "connected" state
// A: held --> connected
//If there has already been a connected call, then switch the existing
connected call to "held" state
// A: held --> connected, B: connected --> held
void resume();

Best regards,
Hsinyi

[Jonas Sicking]

Hi Hsin-Yi,

This looks like a great start! We'll still need lots more work to
enable things like conferance calls etc, but I think what you are
detailing is a good first step towards that.

I don't understand the need for the "waiting" state though. Wouldn't a
incoming call simply be in the "incoming" state even if you have
another call on the line?

/ Jonas

On Wed, Mar 14, 2012 at 2:37 AM, Hsin-Yi Tsai <ht...@mozilla.com> wrote:
> Hi there,
>
> Currently we can only answer() or hangUp() a call. However, we should be
> able to hold a call and answer it later.
> https://bugzilla.mozilla.org/show_bug.cgi?id=735170
> <https://bugzilla.mozilla.org/show_bug.cgi?id=735170>
>
> Here are the details of the scenarios of holding a call.
>
> First, we are making a phone call with A, i.e. the call is in connected
> state. Then we want to hold A for a while and keep talking to it later. So,
> we should make the call into "held" state, then resume connecting with A
> later.
>
> Second, we are talking with A, so the call is in connected state. In the
> meanwhile, B is trying to reach us via phone. Since we are connected with A,
> the call state of B is "waiting." If we want to answer B (make B from
> waiting into connected), then we should also make the call of A into held.
> Later we can resume connecting with A.
>
> Below you can find an enhanced WebTelephony API for holding a call.
>
> interface nsIDOMTelephonyCall : nsIDOMEventTarget
> {
>  readonly attribute DOMString number;
>  readonly attribute DOMString state;
>   // "dialing", "ringing", "busy", "connecting", "connected",
> "disconnecting", "disconnected", "incoming",
>   // Add new states: "waiting", "holding", "held", "resuming"
>

>  void answer(); //change an incoming call or a waiting call into "connected"

>  void hangUp();
>  void hold(); //change a connected call into "held"

>  void resume(); //change a "held" call into connected
>

>  attribute nsIDOMEventListener onstatechange;
>
>  attribute nsIDOMEventListener ondialing;
>  attribute nsIDOMEventListener onringing;
>  attribute nsIDOMEventListener onbusy;
>  attribute nsIDOMEventListener onconnecting;
>  attribute nsIDOMEventListener onconnected;
>  attribute nsIDOMEventListener ondisconnecting;
>  attribute nsIDOMEventListener ondisconnected;
>  attribute nsIDOMEventListener onincoming;
>
>  attribute nsIDOMEventListener onwaiting;  //new
>  attribute nsIDOMEventListener onholding; //new
>  attribute nsIDOMEventListener onheld;      //new
>  attribute nsIDOMEventListener onresuming; //new
> };
>
>
> Thanks,
> Hsinyi
>

> _______________________________________________
> dev-webapi mailing list
> dev-w...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-webapi

[Hsinyi Tsai]

Hi Jonas,

Thanks for the feedback!

I think there is a need for the "waiting state" because it distinguishes the source state and the target state of a triggered event.

Let me express my thoughts by the following cases.

Here's the case 1. When there is no other connected call, the triggered event "a new call comes" pushes a call from "state unknown/initial" to "state incoming".
However, how about when there is already a connected call?
In the case, the source state of the triggered event "a new call comes" is "state connected", instead of "state unknown/initial." In this way, even the triggered event is the same, the call state transition may reach a different target state.
Moreover, even user accepts this newly incoming call in both two cases, the following sequence will be different. In case 1, the new call is connected; in case 2, not only the new call becomes connected but the originally connected call should be held.

Therefore, I think the waiting state is necessary to clearly describe and distinguish the state transition.
How do you think about this? Sounds reasonable?

Thank you,
Hsinyi

[Jonas Sicking]

On Fri, Mar 16, 2012 at 10:41 PM, Hsinyi Tsai <ht...@mozilla.com> wrote:
> Hi Jonas,
>
> Thanks for the feedback!
>
> I think there is a need for the "waiting state" because it distinguishes the source state and the target state of a triggered event.
>
> Let me express my thoughts by the following cases.
>
> Here's the case 1. When there is no other connected call, the triggered event "a new call comes" pushes a call from "state unknown/initial" to "state incoming".
> However, how about when there is already a connected call?
> In the case, the source state of the triggered event "a new call comes" is "state connected", instead of "state unknown/initial." In this way, even the triggered event is the same, the call state transition may reach a different target state.
> Moreover, even user accepts this newly incoming call in both two cases, the following sequence will be different. In case 1, the new call is connected; in case 2, not only the new call becomes connected but the originally connected call should be held.
>
> Therefore, I think the waiting state is necessary to clearly describe and distinguish the state transition.
> How do you think about this? Sounds reasonable?

I'm not sure that I fully understand the above.

I do agree that things will behave differently if the user already has
a call connected compared to if the user already had a different
connection. The application will probably want to show UI which lets
the user choose if the current call should be held or hung up, or if
you want to reject the new incoming call.

However it seems to me that the application will still be carrying
enough state that they on an "incoming" event will easily be able to
tell which UI to show. If we have two events, that means that everyone
will likely have to listen to both of them which seems a bit annoying
for authors.

As an aside, TelephonyCall shouldn't have an 'onincoming' (or
'onwaiting') event since we never transition *into* that state. The
TelephonyCall object is in that state when the page first gets a
reference to it. I.e. the 'onincoming' event would never fire. This is
a bug in our current implementation. Instead onincoming should only be
on the Telephony interface.

/ Jonas

[Hsin-Yi Tsai]

Hi Jonas,

Sorry that I didn't express my thoughts clearly enough.
I drew a call state diagram to help explain the proposal.
You can find it on https://wiki.mozilla.org/WebAPI/WebTelephony

於 2012年03月20日 12:58, Jonas Sicking 提到:

>
> I'm not sure that I fully understand the above.
>
> I do agree that things will behave differently if the user already has
> a call connected compared to if the user already had a different
> connection. The application will probably want to show UI which lets
> the user choose if the current call should be held or hung up, or if
> you want to reject the new incoming call.
>
> However it seems to me that the application will still be carrying
> enough state that they on an "incoming" event will easily be able to
> tell which UI to show. If we have two events, that means that everyone
> will likely have to listen to both of them which seems a bit annoying
> for authors.

Yes, I agree your concern.
However, my thought is ... if we only have the incoming state, then the
application will need additional information to know whether there is
another call or not.
With the waiting state, the application can easily know that there has
already been another connected call, in addition to this new call.
Therefore I proposed the waiting state.
But, both design has its advantages.

> As an aside, TelephonyCall shouldn't have an 'onincoming' (or
> 'onwaiting') event since we never transition *into* that state. The
> TelephonyCall object is in that state when the page first gets a
> reference to it. I.e. the 'onincoming' event would never fire. This is
> a bug in our current implementation. Instead onincoming should only be
> on the Telephony interface.

Good catch! Thanks for pointing this out.
I revised the proposed API according to your comment as well.
https://wiki.mozilla.org/WebAPI/WebTelephony
>
> / Jonas
Thanks,
Hsinyi

[Jonas Sicking]

Given that the state transitions for "waiting" is exactly the same as
the state transitions for "incoming", I think it'll be an easier model
to just merge the two states.

I would be very surprised if the application doesn't trivially can
find out if there's currently another call in progress. In fact you
can easily see that by looking at the Telephony.calls property.

Put it another way, it seems to me that "there is another call
waiting" is an application state. The state for the individual call is
"i'm calling you waiting for you to pick up", independent of if
there's is another call in progress or not.

Another problem is, what happens if two incoming calls happen at the
same time. Which of the two calls end up in the "incoming" state, and
which end up in the "waiting" state? Or are they both in "incoming" in
that case, or both in "waiting"?

Reducing the number of states involved seems like it'll create a simpler model.

/ Jonas

[Hsin-Yi Tsai]

於 2012年03月21日 00:59, Jonas Sicking 提到:

Thanks for the comments. I agree with them.
Here you can find a revised proposal, in that I merged the two states
into only CALL_STATE_INCOMING.
https://wiki.mozilla.org/WebAPI/WebTelephony#Proposal:_Enhance_WebTelephony_API_to_hold_a_call


How do you think about this revision?

Thanks,
Hsinyi

[Jonas Sicking]

Looks great! Thanks!

/ Jonas