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; 
};