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

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;
   
   /**
    * Indicates whether the device is connected to a mobile network.
    */
   readonly attribute bool connected;
   
   /**
    * Indicates whether emergency calls are possible.
    *
    * This flag is only relevant when 'connected' is false.
    */
   readonly attribute bool emergencyCallsPossible;
   
   /**
    * Indicates whether the connection is going through a foreign operator
    * (roaming) or not.
    */
   readonly attribute bool roaming;
   
   /**
    * Operator name.
    */
   readonly attribute string operator?;
   
   /**
    * Type of connection.
    *
    * Possible values: 'gprs', 'edge', 'umts', 'hsdpa', 'evdo0', 'evdoa', 'evdob', etc.
    */
   readonly attribute string type?;
   
   /**
    * Signal strength, represented linearly as a number between 0 (weakest signal) and 1.0
    * (full signal).
    */
   readonly attribute float signalStrength?;
   
   /**
    * Signal strength in dBm, or null if no service is available.
    */
   readonly attribute short signalStrengthDbm?;
   
   /**
    * 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();
   
   /**
    * The 'cardstatechange' event is notified when the 'cardState' attribute
    * changes value.
    */
   attribute EventListener oncardstatechange;
   
   /**
    * The 'connectionchange' event is notified whenever one of the 'connected',
    * 'roaming', 'operator', 'type' attributes change, since typically many or
    * all of them change together.
    */
   attribute EventListener onconnectionchange;
    
   /**
    * The 'signalstrengthchange' event is notified whenever the signal strength
    * changes value. The 'bars' attribute is updated accordingly.
    */
   attribute EventListener onsignalstrengthchange;
   
   /**
    * 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(in 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 nsIDOMDOMRequest.
    *         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(in jsval 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 nsIDOMDOMRequest.
    *         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(in jsval info);

 };

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.