Mobile Connection

Draft
This page is not complete.

Non-standard
This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

This API is available on Firefox OS for certified applications only.

Summary

This API has 2 purposes:

Giving access to detailed information about the current states of the mobile connection of the device
Giving access to the specific capacities embedded within the ICC (the SIM/RUIM card)

As this API can access functionalities that can have an impact on the mobile plan subscribed by the user (some of the functionalities can cost money to use or can damage the ICC), it is restricted to certified applications only.

The main entry point for this API is the navigator.mozMobileConnection property which is an instance of the MozMobileConnection interface.

State of mobile connection

The state of the mobile connection is divided in two: on the one hand the voice connection, on the other hand the data connection. The data related to each type of connection are accessible through the MozMobileConnection.voice and MozMobileConnection.data properties which both return a MozMobileConnectionInfo object.

Those objects give access to all information related to the quality of the network (signal strength, quality of the signal, position of the network's cells, restricted usage, roaming, etc.), and related to the carrier operating the network.

var cnx = navigator.mozMobileConnection;

console.log("The voice operator is " + cnx.voice.network.longName);

if (cnx.voice.connected) {
  console.log("The signal has a strength of " + (+cnx.voice.relSignalStrength) + "%");
} else {
  console.log("The state of the connection is: " + cnx.voice.state);
}

ICC Functionalities

The functionalities available for the ICC can be divided into two categories: the management of the ICC itself and the use of the integrated command available within the STK (SIM Application Toolkit).

Basic actions

The MozMobileConnection provides a set of methods to deal with common behaviors on ICCs.

Note: All original methods from the MozMobileConnection interface are fully asynchronous. They all return a DOMRequest object which has an onsuccess and onerror event handler to handle the success or failure of the method call.

Card lock

As long as a card is locked, a user is unable to use it to reach its mobile network. It's possible to manage the card lock with the getCardLock(), setCardLock(), and unlockCardLock() methods.

If getCardLock() allows to get some detailed information about the lock, it's also possible to have quick info about the lock through MozMobileConnection.cardState which returns a string representing the current state of the lock.

Note: Even if the state change requests are successfully handled, it does not mean that the operations are necessarily successful. For that reason, any change in the card state is tracked independently through events:

The icccardlockerror event is triggered each time a call to setCardLock() or unlockCardLock() fails.
The cardstatechange event is triggered each time the cardState property changes.

var cnx = navigator.mozMobileConnection;

function unlockCard() {
  var unlockOptions = {
    lockType: "pin",
    pin     : prompt("Please, enter your PIN")
  }

  var unlock = cnx.unlockCardLock(unlockOptions);

  unlock.onsuccess = function () {
    console.log("The card has successfully handled the PIN number.");

    if (this.result.success === false) {
      if (this.result.retryCount > 0) {
        console.log("But you mistyped your PIN, you have " + this.result.retryCount + " tries left.");
      } else {
        console.log("But your card is hard locked, you need to contact your carrier to get a special unlocking code.");
      }
    }
  }

  unlock.onerror = function () {
    console.log("Hu! Something goes very wrong!")
  }
}

cnx.addEventListener('icccardlockerror', function () {
  // In case of error, ask the user for his PIN again
  unlockCard();
});

cnx.addEventListener('cardsatechange', function () {
  // In case the card state change and required to be unlocked
  if (cnx.cardState === 'pinRequired') {
    unlockCard();
  }
}

// First call to unlockCard if required
if (cnx.cardState === 'pinRequired') {
  unlockCard();
}

MMI Messages

MMI messages are human understandable code that, once typed with a phone keyboard, allow to trigger specific action from the RIL or get response from the network through a USSD request. A common example is typing a short code to get the IMEI phone number.

Such messages are sent using the MozMobileConnection.sendMMI() method (and can be canceled with cancelMMI()). Even if it will return a DOMRequest object, the response to such messages are handled in two ways:

If the MMI code requires sending a USSD request, the request's success means that the RIL has successfully processed and sent the USSD request to the network. However, the network reply is reported through the ussdreceived event.
If the MMI code is not associated with a USSD but with another RIL request, its result, if one is needed, is sent via the returned request's success or error.

var cnx = navigator.mozMobileConnection;

cnx.addEventHandler('ussdreceived', function (evt) {
  console.log('Network message: ' + evt.data.message);
});

var MMIRequest = cnx.sendMMI(prompt('Provide a valid MMI'));

MMIRequest.onerror = function() {
  console.log("Mmmh... Something goes wrong.");
}

Call forwarding options

Call forwarding options allow to define how a call can or cannot be forwarded to another phone number.

Those options are handled with the getCallForwardingOption() and setCallForwardingOption() methods.

var options = {
  action      : MozMobileCFInfo.CALL_FORWARD_ACTION_ENABLE,
  reason      : MozMobileCFInfo.CALL_FORWARD_REASON_UNCONDITIONAL,
  serviceClass: MozMobileConnectionInfo.ICC_SERVICE_CLASS_VOICE,
  number      : prompt('To which phone number would you wish to forward the calls?'),
  timeSeconds : 5
};

var setOption = navigator.mozMobileConnection.setCallForwardingOption(options);

setOption.onsuccess = function () {
  console.log('Options successfully set');
}

setOption.onerror = function () {
  console.log('Unable to set options: ' + this.error.name);
}

STK commands

The STK commands depend on many factors (carriers, chips model, etc.) but can always be accessed through the MozMobileConnection.icc property which returns a MozIccManager object.

Warning: It's recommended to use the STK command only if you already know exactly what you are doing, as a misusage can damage the chip and make it unusable.

Specification

Not part of any specification.