From MozillaWiki
Jump to: navigation, search

Proposal for an improved and simplied Telephony API (José M. Cantera, Telefónica I+D)

Sensor API

navigator.telephony would return an object with the following interface

 interface Telephony : EventTarget {
   TelephonySession newSession(DOMString number); // Multiple number call??
   readonly attribute TelephonySession liveSession;
   attribute Function onincoming;
 interface TelephonySession : EventTarget {
   readonly attribute DOMString originNumber;
   readonly attribute DOMString number;
   // Do the call
   void call();
  attribute boolean muted; 
  attribute boolean speakerOn;
  void startTone(DOMString tone);
  void stopTone();
  void sendTones(DOMString tones,
                 [optional] unsigned long toneDuration,
                 [optional] unsigned long intervalDuration);
   readonly attribute DOMString readyState; // "calling", "incomming", "connected", "closed", "busy"
   // Can we get info on when a call goes from "trying to place call" to "calling"?
   attribute Function onconnect;
   attribute Function ondisconnect;
   attribute Function onbusy;
   attribute Function onreadystatechange;
   void answer(); 
   void hangUp();
 interface IncomingCallEvent : Event {
   readonly attribute TelephonySession session;

philikon's thoughts

  • IMHO navigator.telephony.dial("numbergoeshere"); is nicer than new TelephonyCall("numbergoeshere");, because a constructor with side-effects like that just feels icky.
  • We have a bunch of telephony-related functionality that's not reflected yet:
    • controlling and reading radio power
    • reading radio metadata (operator, signal strength, etc.)
    • ...
  • I would also suggest another readyState, "dialing" that comes before "calling" for outgoing calls.
  • Nits: we should probably define the possible values for readyState on the interface (nit: for XHR they're ints, not strings... I like being consistent, but I also prefers strings... hmmm...). Also, event listener objects should probably be declared as EventListener.

My proposal on this (as a delta to the main proposal):

 interface Telephony {
   // ... all the stuff from the main proposal
   void power(bool on);
   TelephonyCall dial(String number);
   const String RADIOSTATE_UNAVAILABLE = "unavailable";
   const String RADIOSTATE_OFF         = "off";
   const String RADIOSTATE_READY       = "ready";
   const String CARDSTATE_NOT_READY      = "unavailable";
   const String CARDSTATE_ABSENT         = "absent";
   const String CARDSTATE_PIN_REQUIRED   = "pin_required";
   const String CARDSTATE_PUK_REQUIRED   = "puk_required";
   const String CARDSTATE_NETWORK_LOCKED = "network_locked";
   const String CARDSTATE_NOT_READY      = "not_ready";
   const String CARDSTATE_READY          = "ready";
   readonly String radioState;
   readonly String cardState;
   EventListener onradiostatechange
   EventListener oniccstatechange
   EventListener onsignalstrengthchange
   EventListener onoperatorchange
 interface TelephonyCall {
   // ... all the stuff from the main proposal
   const String READYSTATE_DIALING   = "dialing";
   const String READYSTATE_CALLING   = "calling";
   const String READYSTATE_INCOMING  = "incoming";
   const String READYSTATE_CONNECTED = "connected";
   const String READYSTATE_CLOSED    = "closed";
   const String READYSTATE_BUSY      = "busy";