Navigator.mozMobileConnection

  • Revision slug: DOM/window.navigator.mozMobileConnection
  • Revision title: window.navigator.mozMobileConnection
  • Revision id: 357799
  • Created:
  • Creator: Jeremie
  • Is current revision? No
  • Comment

Revision Content

{{ non-standard_header() }}

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

Summary

Returns a MozMobileConnection object you can use to get information about the current mobile voice and data connection states of the device.

This object 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.)

Syntax

var mobileConnection = window.navigator.mozMobileConnection;

Properties

Name Type Description
cardState string

Indicates the state of the device's ICC card.

Possible values are:

  • unknown
  • absent
  • pinRequired
  • pukRequired
  • networkLocked
  • ready

This property can also be null.

iccInfo {{domxref("MozMobileICCInfo")}} Gives access to information stored in the device's ICC card
voice {{domxref("MozMobileConnectionInfo")}} Gives access to information about the voice connection
data {{domxref("MozMobileConnectionInfo")}} Gives access to information about the data connection
networkSelectionMode string

The selection mode of the voice and data networks.

Possible values are:

  • automatic
  • manual

This property can also be null.

icc {{domxref("MozIccManager")}} Provides access to ICC related funcionality

Event Handler

Name Type Description
oncardstatechange callback The cardstatechange event is fired when the cardState attribute changes value
oncfstatechange callback The oncfstatechange event is fired whenever the call forwarding state changes
ondatachange callback The datachange event is fired whenever the data connection object changes values
ondataerror callback The dataerror event is fired whenever the data connection object receives an error from the RIL
onicccardlockerror callback The icccardlockerror event is fired whenever unlockCardLock or setCardLock methods fails
oniccinfochange callback The iccinfochange event is fired whenever the iccInfo object changes
onussdreceived callback The ussdreceived event is fired whenever a new USSD message is received.
onvoicechange callback The voicechange event is notified whenever the voice connection object changes

Constants

  • ICC_SERVICE_CLASS_VOICE
  • ICC_SERVICE_CLASS_DATA
  • ICC_SERVICE_CLASS_FAX
  • ICC_SERVICE_CLASS_SMS
  • ICC_SERVICE_CLASS_DATA_SYNC
  • ICC_SERVICE_CLASS_DATA_ASYNC
  • ICC_SERVICE_CLASS_PACKET
  • ICC_SERVICE_CLASS_PAD
  • ICC_SERVICE_CLASS_MAX

Methods

Note: All the methods of the MozMobileConnection object are fully asynchronous. They all return a {{domxref("DOMRequest")}} has which has two onsuccess and onerror event handler to handle the success or failur of the method call.

cancelMMI()
Cancel the current MMI request if one exists.
getCardLock(string lockType)

Find out about the status of an ICC lock (e.g. the PIN lock).

The lockType parameter identifies the lock type, e.g. "pin" for the PIN lock.

The request's result will be an object containing information about the specified lock's status, e.g. {lockType: "pin", enabled: true}.

getCallForwardingOption(unsigned short reason)

Queries current call forward options.

The reason property indicates the reason the call is being forwarded. It will be either unconditional (0), mobile busy (1), no reply (2), not reachable (3), all call forwarding (4), or all conditional call forwarding (5).

If successful, the request's onsuccess will be called, and the request's result will be an array of {{domxref("MozMobileCFInfo")}}.

Otherwise, the request's onerror will be called, and the request's error will be either RadioNotAvailable, RequestNotSupported, or GenericFailure.

getNetworks()

Search for available networks.

If successful, the request's onsuccess will be called, and the request's result will be an array of {{domxref("MozMobileNetworkInfo")}} objects.

Otherwise, the request's onerror will be called, and the request's error will be either RadioNotAvailable, RequestNotSupported, or GenericFailure.

selectNetwork({{domxref("MozMobileNetworkInfo")}} network)

Manually selects the passed in network, overriding the radio's current selection.

If successful, the request's onsuccess will be called.

Note: If the network was actually changed by this request, the voicechange and datachange events will also be fired.

Otherwise, the request's onerror will be called, and the request's error will be either RadioNotAvailable, RequestNotSupported, IllegalSIMorME, or GenericFailure.

selectNetworkAutomatically()

Tell the radio to automatically select a network.

The condition of success and error are the same as for the selectNetwork method.
sendMMI(string mmi)

Send a MMI message.

The mmi property is a MMI string that can be associated to a USSD request or other RIL functionality.

The request's result will be an object containing information about the operation.

In case that the MMI code requires sending an USSD request, the request's success event means that the RIL has successfully processed and sent the USSD request to the network. The network reply will be reported via onussdreceived event handler. If the MMI code is not associated to a USSD but to other RIL request its result, if one is needed, will be notified via the returned request's success or error event.

setCallForwardingOption({{domxref("MozMobileCFInfo")}} CFInfo)

Configures call forward options.

The CFInfo property is an object of type {{domxref("MozMobileCFInfo")}} containing the call forward rule to set.

If successful, the request's onsuccess will be called.

Otherwise, the request's onerror will be called, and the request's error will be either RadioNotAvailable, RequestNotSupported, IllegalSIMorME, or GenericFailure.

setCardLock(object info)

Modify the state of a card lock.

The info parameter is 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:

Disabling the PIN lock
setCardLock({
  lockType: "pin", 
  pin: "...",
  enabled: false
});
Changing the PIN
setCardLock({
  lockType: "nck", 
  pin: "...",
  newPin: "..."
});

The request's result will be an object containing information about the operation.

Examples:

Enabling/Disabling card lock failed or change card lock failed
{
  lockType:   "pin",
  result:     false,
  retryCount: 2
}
Enabling/Disabling card lock succeed or change card lock succeed
{
  lockType: "pin",
  result: true
}
unlockCardLock(object info)

Unlock a card lock.

The info parameter is 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:

Unlocking the PIN
unlockCardLock({
  lockType: "pin", 
  pin: "..."
});
Network depersonalization. Unlocking the network control key (NCK).
unlockCardLock({
  lockType: "nck", 
  pin: "..."
});
Unlocking the PUK and supplying a new PIN
unlockCardLock({
  lockType: "puk", 
  puk: "...", 
  newPin: "..."
});

The request's result will be an object containing information about the unlock operation.

Examples:

Unlocking failed
{
  lockType:   "pin",
  result:     false,
  retryCount: 2
}
Unlocking succeeded
{
  lockType: "pin",
  result: true
}

Specification

Not part of any specification

Revision Source

<p>{{ non-standard_header() }}</p>
<div class="warning">
  <p style="text-align: center;">This API is available on <a href="/en-US/docs/Mozilla/Firefox_OS" title="/en-US/docs/Mozilla/Firefox_OS">Firefox OS</a> only and for <a href="/en-US/docs/Apps/Packaged_apps#Types_of_packaged_apps" title="/en-US/docs/Mozilla/Firefox_OS/Security/Application_security">certified applications</a> only.</p>
</div>
<h2 id="Summary" name="Summary">Summary</h2>
<p>Returns a <code>MozMobileConnection</code> object you can use to get information about the current mobile voice and data connection states of the device.</p>
<p>This object also includes ICC-related (SIM/RUIM card) functionalities, such as&nbsp;:</p>
<ul>
  <li>entering PIN, PIN2, PUK, PUK2 to unlock various states of the SIM card.</li>
  <li>changing the PIN (also serves as enabling/disabling the PIN lock.)</li>
</ul>
<h2 id="Syntax" name="Syntax">Syntax</h2>
<pre class="eval">
var mobileConnection = window.navigator.mozMobileConnection;
</pre>
<h2 id="Properties">Properties</h2>
<table class="standard-table">
  <tbody>
    <tr>
      <th scope="col">Name</th>
      <th scope="col">Type</th>
      <th scope="col">Description</th>
    </tr>
    <tr>
      <td><code>cardState</code></td>
      <td><code>string</code></td>
      <td>
        <p>Indicates the state of the device's ICC card.</p>
        <p>Possible values are:</p>
        <ul>
          <li><code>unknown</code></li>
          <li><code>absent</code></li>
          <li><code>pinRequired</code></li>
          <li><code>pukRequired</code></li>
          <li><code>networkLocked</code></li>
          <li><code>ready</code></li>
        </ul>
        <p>This property can also be <code>null</code>.</p>
      </td>
    </tr>
    <tr>
      <td><code>iccInfo</code></td>
      <td>{{domxref("MozMobileICCInfo")}}</td>
      <td>Gives access to information stored in the device's ICC card</td>
    </tr>
    <tr>
      <td><code>voice</code></td>
      <td>{{domxref("MozMobileConnectionInfo")}}</td>
      <td>Gives access to information about the voice connection</td>
    </tr>
    <tr>
      <td><code>data</code></td>
      <td>{{domxref("MozMobileConnectionInfo")}}</td>
      <td>Gives access to information about the data connection</td>
    </tr>
    <tr>
      <td><code>networkSelectionMode</code></td>
      <td><code>string</code></td>
      <td>
        <p>The selection mode of the voice and data networks.</p>
        <p>Possible values are:</p>
        <ul>
          <li><code>automatic</code></li>
          <li><code>manual</code></li>
        </ul>
        <p>This property can also be <code>null</code>.</p>
      </td>
    </tr>
    <tr>
      <td><code>icc</code></td>
      <td>{{domxref("MozIccManager")}}</td>
      <td>Provides access to ICC related funcionality</td>
    </tr>
  </tbody>
</table>
<h3 id="Event_Handler">Event Handler</h3>
<table class="standard-table">
  <tbody>
    <tr>
      <th scope="col">Name</th>
      <th scope="col">Type</th>
      <th scope="col">Description</th>
    </tr>
    <tr>
      <td><code>oncardstatechange</code></td>
      <td><code>callback</code></td>
      <td>The <code>cardstatechange</code> event is fired when the <code>cardState</code> attribute changes value</td>
    </tr>
    <tr>
      <td><code>oncfstatechange</code></td>
      <td><code>callback</code></td>
      <td>The <code>oncfstatechange</code> event is fired whenever the call forwarding state changes</td>
    </tr>
    <tr>
      <td><code>ondatachange</code></td>
      <td><code>callback</code></td>
      <td>The <code>datachange</code> event is fired whenever the <code>data</code> connection object changes values</td>
    </tr>
    <tr>
      <td><code>ondataerror</code></td>
      <td><code>callback</code></td>
      <td>The <code>dataerror</code> event is fired whenever the <code>data</code> connection object receives an error from the RIL</td>
    </tr>
    <tr>
      <td><code>onicccardlockerror</code></td>
      <td><code>callback</code></td>
      <td>The <code>icccardlockerror</code> event is fired whenever <code>unlockCardLock</code> or <code>setCardLock</code> methods fails</td>
    </tr>
    <tr>
      <td><code>oniccinfochange</code></td>
      <td><code>callback</code></td>
      <td>The <code>iccinfochange</code> event is fired whenever the <code>iccInfo</code> object changes</td>
    </tr>
    <tr>
      <td><code>onussdreceived</code></td>
      <td><code>callback</code></td>
      <td>The <code>ussdreceived</code> event is fired whenever a new USSD message is received.</td>
    </tr>
    <tr>
      <td><code>onvoicechange</code></td>
      <td><code>callback</code></td>
      <td>The <code>voicechange</code> event is notified whenever the <code>voice</code> connection object changes</td>
    </tr>
  </tbody>
</table>
<h3 id="Constants">Constants</h3>
<ul>
  <li><code>ICC_SERVICE_CLASS_VOICE</code></li>
  <li><code>ICC_SERVICE_CLASS_DATA</code></li>
  <li><code>ICC_SERVICE_CLASS_FAX</code></li>
  <li><code>ICC_SERVICE_CLASS_SMS</code></li>
  <li><code>ICC_SERVICE_CLASS_DATA_SYNC</code></li>
  <li><code>ICC_SERVICE_CLASS_DATA_ASYNC</code></li>
  <li><code>ICC_SERVICE_CLASS_PACKET</code></li>
  <li><code>ICC_SERVICE_CLASS_PAD</code></li>
  <li><code>ICC_SERVICE_CLASS_MAX</code></li>
</ul>
<h2 id="Methods">Methods</h2>
<div class="note">
  <p><strong>Note:</strong> All the methods of the <code>MozMobileConnection</code> object are fully asynchronous. They all return a {{domxref("DOMRequest")}} has which has two <code>onsuccess</code> and <code>onerror</code> event handler to handle the success or failur of the method call.</p>
</div>
<dl>
  <dt>
    <code>cancelMMI()</code></dt>
  <dd>
    Cancel the current MMI request if one exists.</dd>
  <dt>
    <code>getCardLock(<em>string</em> lockType)</code></dt>
  <dd>
    <p>Find out about the status of an ICC lock (e.g. the PIN lock).</p>
    <p>The <code>lockType</code> parameter identifies the lock type, e.g. "pin" for the PIN lock.</p>
    <p>The request's result will be an object containing information about the specified lock's status, e.g. <code>{lockType: "pin", enabled: true}</code>.</p>
  </dd>
  <dt>
    <code>getCallForwardingOption(<em>unsigned short</em> reason)</code></dt>
  <dd>
    <p>Queries current call forward options.</p>
    <p>The <code>reason</code> property indicates the reason the call is being forwarded. It will be either unconditional (<code>0</code>), mobile busy (<code>1</code>), no reply (<code>2</code>), not reachable (<code>3</code>), all call forwarding (<code>4</code>), or all conditional call forwarding (<code>5</code>).</p>
    <p>If successful, the request's <code>onsuccess</code> will be called, and the request's result will be an array of {{domxref("MozMobileCFInfo")}}.</p>
    <p>Otherwise, the request's <code>onerror</code> will be called, and the request's error will be either <code>RadioNotAvailable</code>, <code>RequestNotSupported</code>, or <code>GenericFailure</code>.</p>
  </dd>
  <dt>
    <code>getNetworks()</code></dt>
  <dd>
    <p>Search for available networks.</p>
    <p>If successful, the request's <code>onsuccess</code> will be called, and the request's result will be an array of {{domxref("MozMobileNetworkInfo")}} objects.<br />
      <br />
      Otherwise, the request's <code>onerror</code> will be called, and the request's error will be either <code>RadioNotAvailable</code>, <code>RequestNotSupported</code>, or <code>GenericFailure</code>.</p>
  </dd>
  <dt>
    <code>selectNetwork(</code><em>{{domxref("MozMobileNetworkInfo")}}</em><code> network)</code></dt>
  <dd>
    <p>Manually selects the passed in network, overriding the radio's current selection.</p>
    <p>If successful, the request's <code>onsuccess</code> will be called.</p>
    <div class="note">
      <p><strong>Note:</strong> If the network was actually changed by this request, the <code>voicechange</code> and <code>datachange</code> events will also be fired.</p>
    </div>
    <p>Otherwise, the request's <code>onerror</code> will be called, and the request's error will be either <code>RadioNotAvailable</code>, <code>RequestNotSupported</code>, <code>IllegalSIMorME</code>, or <code>GenericFailure</code>.</p>
  </dd>
  <dt>
    <code>selectNetworkAutomatically()</code></dt>
  <dd>
    <p>Tell the radio to automatically select a network.</p>
    The condition of success and error are the same as for the <code>selectNetwork</code> method.</dd>
  <dt>
    <code>sendMMI(<em>string</em> mmi)</code></dt>
  <dd>
    <p>Send a MMI message.</p>
    <p>The <code>mmi</code> property is a MMI string that can be associated to a USSD request or other RIL functionality.</p>
    <p>The request's result will be an object containing information about the operation.</p>
    <p>In case that the MMI code requires sending an USSD request, the request's <code>success</code> event means that the RIL has successfully processed and sent the USSD request to the network. The network reply will be reported via <code>onussdreceived</code> event handler. If the MMI code is not associated to a USSD but to other RIL request its result, if one is needed, will be notified via the returned request's <code>success</code> or <code>error</code> event.</p>
  </dd>
  <dt>
    <code>setCallForwardingOption(</code><em>{{domxref("MozMobileCFInfo")}}</em><code> CFInfo)</code></dt>
  <dd>
    <p>Configures call forward options.</p>
    <p>The <code>CFInfo</code> property is an object of type {{domxref("MozMobileCFInfo")}} containing the call forward rule to set.</p>
    <p>If successful, the request's <code>onsuccess</code> will be called.</p>
    <p>Otherwise, the request's <code>onerror</code> will be called, and the request's error will be either <code>RadioNotAvailable</code>, <code>RequestNotSupported</code>, <code>IllegalSIMorME</code>, or <code>GenericFailure</code>.</p>
  </dd>
  <dt>
    <code>setCardLock(<em>object</em> info)</code></dt>
  <dd>
    <p>Modify the state of a card lock.</p>
    <p>The <code>info</code> parameter is an object containing information about the lock and how to modify its state. At a minimum, this object must have a <code>lockType</code> attribute which specifies the type of lock, e.g. "pin" for the PIN lock. Other attributes are dependent on the lock type.</p>
    <p>Examples:</p>
    <dl>
      <dt>
        Disabling the PIN lock</dt>
      <dd>
        <pre class="brush: js">
setCardLock({
  lockType: "pin", 
  pin: "...",
  enabled: false
});</pre>
      </dd>
      <dt>
        Changing the PIN</dt>
      <dd>
        <pre class="brush: js">
setCardLock({
  lockType: "nck", 
  pin: "...",
  newPin: "..."
});</pre>
      </dd>
    </dl>
    <p>The request's result will be an object containing information about the operation.</p>
    <p>Examples:</p>
    <dl>
      <dt>
        Enabling/Disabling card lock failed or change card lock failed</dt>
      <dd>
        <pre class="brush: js">
{
  lockType:   "pin",
  result:     false,
  retryCount: 2
}</pre>
      </dd>
      <dt>
        Enabling/Disabling card lock succeed or change card lock succeed</dt>
      <dd>
        <pre class="brush: js">
{
  lockType: "pin",
  result: true
}</pre>
      </dd>
    </dl>
  </dd>
  <dt>
    <code>unlockCardLock(<em>object</em> info)</code></dt>
  <dd>
    <p>Unlock a card lock.</p>
    <p>The <code>info</code> parameter is an object containing the information necessary to unlock the given lock. At a minimum, this object must have a <code>lockType</code> attribute which specifies the type of lock, e.g. "pin" for the PIN lock. Other attributes are dependent on the lock type.</p>
    <p>Examples:</p>
    <dl>
      <dt>
        Unlocking the PIN</dt>
      <dd>
        <pre class="brush: js">
unlockCardLock({
  lockType: "pin", 
  pin: "..."
});</pre>
      </dd>
      <dt>
        Network depersonalization. Unlocking the network control key (NCK).</dt>
      <dd>
        <pre class="brush: js">
unlockCardLock({
  lockType: "nck", 
  pin: "..."
});</pre>
      </dd>
      <dt>
        Unlocking the PUK and supplying a new PIN</dt>
      <dd>
        <pre class="brush: js">
unlockCardLock({
  lockType: "puk", 
  puk: "...", 
  newPin: "..."
});</pre>
      </dd>
    </dl>
    <p>The request's result will be an object containing information about the unlock operation.</p>
    <p>Examples:</p>
    <dl>
      <dt>
        Unlocking failed</dt>
      <dd>
        <pre class="brush: js">
{
  lockType:   "pin",
  result:     false,
  retryCount: 2
}</pre>
      </dd>
      <dt>
        Unlocking succeeded</dt>
      <dd>
        <pre class="brush: js">
{
  lockType: "pin",
  result: true
}</pre>
      </dd>
    </dl>
  </dd>
</dl>
<h2 id="Specification" name="Specification">Specification</h2>
<p>Not part of any specification</p>
Revert to this revision