WebAPI/WebTelephony

Proposed API

(lkcl29dec11: remember also to include data calls as well as voice calls, so that internet access can be initiated)

navigator.telephony would return an object with the following interface

interface Telephony : EventTarget {
TelephonyCall dial(DOMString number); // Returns a object in "dialing" state
attribute boolean muted;           // Should these live on the call/group?
attribute boolean speakerEnabled;

attribute any active; // Active call, for now. Could be a group in the future.

readonly attribute TelephonyCall[] calls;

void startTone(DOMString tone);
void stopTone();

attribute Function onincoming;
attribute Function oncallschanged;
}

interface TelephonyCall : EventTarget {
readonly attribute DOMString number;

readonly attribute DOMString state;
// "dialing", "ringing", "busy", "connecting", "connected", "disconnecting", "disconnected", "incoming"

attribute Function onstatechange;
attribute Function onringing;
attribute Function onbusy;
attribute Function onconnecting;
attribute Function onconnected;
attribute Function ondisconnecting;
attribute Function ondisconnected;

void answer(); // Should this make the call the active one?
void hangUp();
}

interface CallEvent : Event {
readonly attribute TelephonyCall call;
}

Proposal: Enhance telephony call states to hold a call

The diagram below shows the current design of B2G telephony call states (white blocks) and the proposal for holding a call (yellow blocks).

 State transition in detail:

• Scenario #1: There is no other call on-line (current design)
  When a remote party dials, a new call is generated with its call index (no. 1), and the call state now is CALL_STATE_INCOMING.
  When user answers/hangs up the call, the call state is eventually pushed to CALL_STATE_CONNECTED/CALL_STATE_DISCONNECTED according to user's decision.
• Scenario #2: There is already a call on-line
  When the third party dials, a new call is generated with the state of CALL_STATE_INCOMING. Since there is already a call on-line, the new call's index is no. 2.
  When user answers the new call (call no. 2), its state is going to be transferred to CALL_STATE_CONNECTED. In the meanwhile, the state of the originally connected call (call no. 1) should be forced to CALL_STATE_HELD.
  
• Scenario #3: User wants to hold a call when there's no waiting call
  User can |HoldCall()| to change the call state from CALL_STATE_CONNECTED to CALL_STATE_HELD. User can |ResumeCall()| to make a call from CALL_STATE_HELD back to
  CALL_STATE_CONNECTED.

 

Proposal: Enhance WebTelephony API to hold a call

interface nsIDOMTelephony : nsIDOMEventTarget
{
nsIDOMTelephonyCall dial(in DOMString number);

attribute boolean muted;
attribute boolean speakerEnabled;

// The call that is "active", i.e. receives microphone input and tones
// generated via startTone.
readonly attribute jsval active;

// Array of all calls that are currently connected.
readonly attribute jsval calls;

void startTone(in DOMString tone);
void stopTone();

attribute nsIDOMEventListener onincoming;
attribute nsIDOMEventListener oncallschanged;
};

interface nsIDOMTelephonyCall : nsIDOMEventTarget
{
readonly attribute DOMString number;

// "dialing", "ringing", "busy", "connecting", "connected", "disconnecting", "disconnected", "incoming"
// Add new states: "holding", "held", "resuming"
readonly attribute DOMString state;

void answer();  
void hangUp();

//make a "connected" call into "held"
void holdCall(); 
//make a "held" call back to "connected"
void resumeCall(); 

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;
/* new events */
attribute nsIDOMEventListener onholding; 
attribute nsIDOMEventListener onheld; 
attribute nsIDOMEventListener onresuming; 
};