Mobile Connection
Non-standard
This feature is not on a current W3C standards track, but it is supported on the Firefox OS platform. Although implementations may change in the future and it is not supported widely across browsers, it is suitable for use in code dedicated to Firefox OS apps.
This API is available on Firefox OS for internal 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.mozMobileConnections
property which is an array of instances of the MozMobileConnection
interface.
Note: For simplicity's sake all the code examples below will be using the first mobile connection. Production code should be aware that there might be more than one connection - or none at all - and react accordingly.
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.
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 tosetCardLock()
orunlockCardLock()
fails. - The
cardstatechange
event is triggered each time thecardState
property changes.
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 theussdreceived
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
orerror
.
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.
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.
See also
navigator.mozMobileConnections
MozMobileConnection
MozMobileConnectionInfo
MozMobileICCInfo
MozMobileNetworkInfo
MozMobileCFInfo
MozMobileCellInfo
MozIccManager
MozStkCommandEvent
License
© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/api/mobile_connection_api