WebAPI/WebMobileConnection

This exposes information about the current mobile voice and data connection to (certain) HTML content. The primary use case for this is the status bar of the main phone UI. It typically shows the operator name, signal strength, data connection type, etc. This API also includes ICC-related (SIM/RUIM card) functionalities, such as :

• entering PIN, PIN2, PUK, PUK2 to unlock various states of the SIM card.
• changing the PIN (also serves as enabling/disabling the PIN lock.)

Status

• Implemented in bug 729173.
• ICC lock(PIN/PIN2/PUK/PUK2) is implemented in bug 729173.
• getNetworks() and WebMobileOperatorInfo were added in bug 744344
• data status is not exposed until bug 753170 is resolved.
• Move icc/sim related stuff to iccManager in bug 857414. And also separate IccManager from MobileConnection.

Proposed API

 interface MobileConnection : EventTarget
 {
   /**
    * Indicates the state of the device's ICC card.
    *
    * Possible values: 'unavailable', 'absent', 'pin_required', 'puk_required',
    * 'network_locked', 'not_ready', 'ready'.
    */
   readonly attribute string cardState;
    
   /**
    * Information about the voice connection.
    */
   readonly attribute MobileConnectionInfo voice;
    
   /**
    * Information about the data connection.
    */
   readonly attribute MobileConnectionInfo data;
   
   /**
    * The 'cardstatechange' event is notified when the 'cardState' attribute
    * changes value.
    */
   attribute EventListener oncardstatechange;
   
   /**
    * The 'voicechange' event is notified whenever the voice connection object
    * changes.
    */
   attribute EventListener onvoicechange;
   
   /**
    * The 'datachange' event is notified whenever the data connection object
    * changes values.
    */
   attribute EventListener ondatachange;
   
   /**
    * Search for available networks.
    *
    * If successful, the request's onsuccess will be called, and the request's
    * result will be an array of MobileOperatorInfo.
    *
    * Otherwise, the request's onerror will be called, and the request's error
    * will be either 'RadioNotAvailable', 'RequestNotSupported', or 'GenericFailure'.
    */
   DOMRequest getNetworks();
   
   /**
    * Find out about the status of an ICC lock (e.g. the PIN lock).
    *
    * @param lockType
    *        Identifies the lock type, e.g. "pin" for the PIN lock.
    *
    * @return a DOM Request.
    *         The request's result will be an object containing 
    *         information about the specified lock's status,
    *         e.g. {lockType: "pin", enabled: true}.
    */
   DOMRequest getCardLock(DOMString lockType);
   
   /**
    * Unlock a card lock.
    *
    * @param info
    *        An object containing the information necessary to unlock
    *        the given lock. At a minimum, this object must have a
    *        "lockType" attribute which specifies the type of lock, e.g.
    *        "pin" for the PIN lock. Other attributes are dependent on
    *        the lock type.
    *
    * Examples:
    *
    * (1) Unlocking the PIN:
    *
    *   unlockCardLock({lockType: "pin",
    *                   pin: "..."});
    *
    * (2) Unlocking the PUK and supplying a new PIN:
    *
    *   unlockCardLock({lockType: "puk",
    *                   puk: "...",
    *                   newPin: "..."});
    *
    * @return a DOMRequest.
    *         The request's result will be an object containing 
    *         information about the unlock operation.
    *
    * Examples:
    *
    * (1) Unlocking failed:
    *
    *     {
    *       lockType:   "pin",
    *       result:     false,
    *       retryCount: 2
    *     }
    *
    * (2) Unlocking succeeded:
    *
    *     {
    *       lockType:  "pin",
    *       result:    true
    *     }
    */
   DOMRequest unlockCardLock(Object info);
   
   /**
    * Modify the state of a card lock.
    *
    * @param info
    *        An object containing information about the lock and
    *        how to modify its state. At a minimum, this object
    *        must have a "lockType" attribute which specifies the
    *        type of lock, e.g. "pin" for the PIN lock. Other
    *        attributes are dependent on the lock type.
    *
    * Examples:
    *
    * (1) Disabling the PIN lock:
    *
    *   setCardLock({lockType: "pin",
    *                pin: "...",
    *                enabled: false});
    *
    * (2) Changing the PIN:
    *
    *   setCardLock({lockType: "pin",
    *                pin: "...",
    *                newPin: "..."});
    *
    * @return a DOMRequest.
    *         The request's result will be an object containing 
    *         information about the operation.
    *
    * Examples:
    *
    * (1) Enabling/Disabling card lock failed or change card lock failed.
    *
    *     {
    *       lockType: "pin",
    *       result: false,
    *       retryCount: 2
    *     }
    *
    * (2) Enabling/Disabling card lock succeed or change card lock succeed.
    *
    *     {
    *       lockType: "pin",
    *       result: true
    *     }
    */
   DOMRequest setCardLock(Object info);
   
 };

 interface MobileConnectionInfo
 {
   /**
    * Indicates whether the device is connected to a mobile network.
    */
   readonly attribute bool connected;
   
   /**
    * Indicates whether only emergency calls are possible.
    *
    * This flag is only relevant to voice connections and when 'connected' is
    * false.
    */
   readonly attribute bool emergencyCallsOnly;
   
   /**
    * Indicates whether the connection is going through a foreign operator
    * (roaming) or not.
    */
   readonly attribute bool roaming;
   
   /**
    * Network operator
    */
   readonly attribute DOMString operator;
   
   /**
    * Type of connection.
    *
    * Possible values: 'gsm', 'cdma', gprs', 'edge', 'umts', 'hsdpa', 'evdo0',
    * 'evdoa', 'evdob', etc.
    */
   readonly attribute DOMString type;
   
   /**
    * Signal strength in dBm, or null if no service is available.
    */
   readonly attribute int signalStrength;
   
   /**
    * Signal strength, represented linearly as a number between 0 (weakest
    * signal) and 100 (full signal).
    */
   readonly attribute int relSignalStrength;
   
 };

 interface MobileOperatorInfo
 {
   /**
    * Short name of the network operator
    */
   readonly attribute DOMString shortName;
   
   /**
    * Long name of the network operator
    */
   readonly attribute DOMString longName;
   
   /**
    * Mobile Country Code (MCC) of the network operator
    */
   readonly attribute unsigned short mcc;
   
   /**
    * Mobile Network Code (MNC) of the network operator
    */
   readonly attribute unsigned short mnc;
   
   /**
    * State of this network operator.
    *
    * Possible values: 'available', 'connected', 'forbidden', or null (unknown)
    */
   readonly attribute DOMString state;
 };

Other radio-related functionality

The following radio/mobile connection related features will be exposed as settings in SettingsAPI:

• radio on/off (e.g. for aeroplane mode)
• caller ID on/off/provider default (called "CLIR" in TS 27.007)
• call forwarding preferences
• manual override for operator selection

There are also some more features of the radio that should be exposed to (privileged) content in some shape or form:

• ICC-related (SIM/RUIM card)
  • own phone number and other ICC I/O related features.(Currently these information are not exposed in WebAPI, see bug 736941.)
• device-related
  • get IMEI, IMEISV
  • depersonalize (remove network lock)
  • baseband-related information and features

The latter, device-related features seem to be more exotic than the ICC-related ones and hopefully also mostly unnecessary. The question remains where these APIs should live.