WebAPI/WebTelephony

Status

Implemented in 674726

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;
  
  /* new events */
  attribute nsIDOMEventListener onoutgoing;
  attribute nsIDOMEventListener onconnected;
  attribute nsIDOMEventlistener ondisconnected; 
};

interface nsIDOMTelephonyCall: nsIDOMEventTarget
{
  readonly attribute DOMString number;

  // "dialing", "alerting", "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 hold(); 
  //make a "held" call back to "connected"
  void resume(); 

  attribute nsIDOMEventListener onstatechange;

  ／／attribute nsIDOMEventListener ondialing;
  
  attribute nsIDOMEventListener onalerting;
  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; 
};