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.

 <img src="/images/thumb/b/b9/Proposal_TelephonyCallStates_v2.png/777px-Proposal_TelephonyCallStates_v2.png" _fck_mw_filename="Proposal TelephonyCallStates v2.png" _fck_mw_width="778" _fck_mw_height="865" alt="Proposal of telephony call states to support call holding" />

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 onwaiting; //new
   attribute nsIDOMEventListener oncallschanged;
 };
  
 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(); //make an incoming call or a waiting call into
   //"connected"
   void hangUp();
   void holdCal(); //change a connected call into "held"
   void resumeCall(); //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 onholding; //new
   attribute nsIDOMEventListener onheld; //new
   attribute nsIDOMEventListener onresuming; //new
 };