Mobile Connection

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.mozMobileConnections property which is an array of instances 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.mozMobileConnections[0];

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.

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.

var cnx = navigator.mozMobileConnections[0];

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.mozMobileConnections[0];

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.mozMobileConnections[0].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.

Specification

Not part of any specification.

See also

• navigator.mozMobileConnections
• MozMobileConnection
• MozMobileConnectionInfo
• MozMobileICCInfo
• MozMobileNetworkInfo
• MozMobileCFInfo
• MozMobileCellInfo
• MozIccManager
• MozStkCommandEvent