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).

We propose the waiting state because the extra waiting state helps the application understand that there has already been another connected call. If we only have the incoming state, then the application will need to retrieve extra information to know whether there is another call or not.

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 its call index. Since there is already a call on-line, the new call's index is no. 2. And the state of Call no. 2 is CALL_STATE_WAITING. 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. |Answer()| an INCOMING call and |Answer()| a WAITING call are different.
• 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 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
 };