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