Mobile Connection

Brouillon
Cette page n'est pas terminée.

Non standard
Cette fonctionnalité n'est ni standard, ni en voie de standardisation. Ne l'utilisez pas pour des sites accessibles sur le Web : elle ne fonctionnera pas pour tout utilisateur. Il peut également y avoir d'importantes incompatibilités entre les implémentations et son comportement peut être modifié dans le futur.

Cette API est disponible sur Firefox OS pour des applications certifiées seulement.

Résumé

Cette API a été conçue pour 2 choses :

Permettre l'accès à des informations précises sur l'état de la connection mobile de l'appareil
Permettre l'accès à certaines fonctionnalités de l'appareil contenues dans l'ICC (la carte SIM/RUIM).

Cette API peut donc accéder à des fonctionnalités qui pourront avoir un impact sur l'abonnement de l'utilisateur (certaines fonctionnalités seront payantes ou pourront endommager l'ICC) : elle est donc limitée aux applications certifiées.

Le point d'entrée de cette API est la propriété navigator.mozMobileConnection , cette propriété est une instance de l'interface MozMobileConnection.

État de la connexion mobile

L'état de la connexion mobile se partage en deux. D'un côté, la connexion voice et de l'autre la connexion data. Les données relatives à chaque type de connexion sont accessibles à travers les propriétés MozMobileConnection.voice et MozMobileConnection.data qui renvoient toutes les deux un objet MozMobileConnectionInfo.

Ces objets donnent accès à toutes les informations liées à la qualité du réseau (la force du signal, la qualité du signal, la position des cellules réseau, la restriction de l'usage, les données en itinérance, etc.), et à l'opérateur réseau.

var cnx = navigator.mozMobileConnection;

console.log("L'opérateur voix est :" + cnx.voice.network.longName);

if (cnx.voice.connected) {
  console.log("La force du signal est :" + (+cnx.voice.relSignalStrength) + "%");
} else {
  console.log("L'état de la connexion est : " + cnx.voice.state);
}

Les fonctionnalités ICC

Les fonctionnalités offertes par l'ICC peuvent se ranger dans deux catégories : la gestion de l'ICC même ou l'utilisation des commandes disponibles et intégrées au sein de STK (SIM Application Toolkit).

Les actions de base

Le MozMobileConnection fournit un ensemble de méthodes pour gérer les différents comportements des cartes ICC.

Note : L'ensemble des méthodes de l'interface MozMobileConnection sont intégralement asynchrones. Elles renvoient toutes un objet DOMRequest qui possède les gestionnaires d'événements onsuccess et onerror afin de gérer les succès ou échecs suite à l'appel de la méthode.

Verrouillage de la carte

Tant que la carte est verrouillée, un utilisateur sera incapable de l'utiliser pour atteindre le réseau mobile. Il est possible de gérer le verrouillage de la carte avec les méthodes getCardLock(), setCardLock() et unlockCardLock().

Si le getCardLock() permet d'obtenir certaines informations précises sur le verrouillage, il est également possible d'avoir des informations plus concises sur le verrouillage grâce à MozMobileConnection.cardState qui renvoie une chaîne de caractères représentant l'état actuel du verrouillage.

Note : Même dans le cas où les requêtes ont réussi, cela ne signifie pas forcément que les opérations aient été réussies. C'est pourquoi les changements d'état de la carte sont suivis grâce à des événements indépendants :

L'événement icccardlockerror est déclenché à chaque fois qu'un appel à setCardLock() ou unlockCardLock() échoue.
L'événement cardstatechange est déclenché à chaque fois que la propriété cardState change.

var cnx = navigator.mozMobileConnection;

function unlockCard() {
  var unlockOptions = {
    lockType: "pin",
    pin     : prompt("Veuillez saisir votre PIN")
  }

  var unlock = cnx.unlockCardLock(unlockOptions);

  unlock.onsuccess = function () {
    console.log("Le code PIN a bien été reçu.");

    if (this.result.success === false) {
      if (this.result.retryCount > 0) {
        console.log("Vous avez fait une faute dans votre code PIN : " + this.result.retryCount + " essais restants.");
      } else {
        console.log("Votre carte est vérrouillée, vous devez contact votre opérateur afin de recevoir un code de déblocage.");
      }
    }
  }

  unlock.onerror = function () {
    console.log("Il y a eu un problème !")
  }
}

cnx.addEventListener('icccardlockerror', function () {
  // S'il y a une erreur, demander à l'utilisateur de resaisir le code PIN
  unlockCard();
});

cnx.addEventListener('cardsatechange', function () {
  // Dans le cas où l'état de la carte change et nécessite un dévérouillage
  if (cnx.cardState === 'pinRequired') {
    unlockCard();
  }
}

// Le premier appel à unlockCard s'il est nécessaire
if (cnx.cardState === 'pinRequired') {
  unlockCard();
}

Les messages MMI

Un message MMI est un code, lisible par les humains, qui, une fois tapé avec le clavier du téléphone, déclenche une action spécifique depuis le RIL ou d'obtenir une réponse depuis le réseau via une requête USSD. Un exemple : taper un code pour obtenir le numéro IMEI du téléphone.

De tels messages sont envoyés en utilisant la méthode MozMobileConnection.sendMMI() (et peuvent être annulés avec cancelMMI()). Même si la réponse sera un objet DOMRequest, la réponse à un tel message pourra être gérée de deux manières :

Si le code MMI doit envoyer une requête USSD, le success de la requête signifie que le RIL a correctement traîté, puis envoyé la requête USSD sur le réseau. Cependant, la réponse du réseau est renvoyée via l'événement ussdreceived.
Si le code MMI n'est pas associé à un code USSD mais à une autre requête RIL, son résultat (s'il est nécessaire) sera renvoyé grâce aux gestionnaire d'événements success ou error.

var cnx = navigator.mozMobileConnection;

cnx.addEventHandler('ussdreceived', function (evt) {
  console.log('Message réseau : ' + evt.data.message);
});

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

MMIRequest.onerror = function() {
  console.log("Il y a eu un problème...");
}

Options de renvoi d'appels

Les options de renvoi d'appels permettent de définir la façon dont un appel peut, ou non, être transféré vers un autre numéro de téléphone.

Ces options sont gérées par les méthodes getCallForwardingOption() et setCallForwardingOption() .

var options = {
  action      : MozMobileCFInfo.CALL_FORWARD_ACTION_ENABLE,
  reason      : MozMobileCFInfo.CALL_FORWARD_REASON_UNCONDITIONAL,
  serviceClass: MozMobileConnectionInfo.ICC_SERVICE_CLASS_VOICE,
  number      : prompt('À quelle numéro doit être transféré l appel ?'),
  timeSeconds : 5
};

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

setOption.onsuccess = function () {
  console.log('Options paramétrées avec succès');
}

setOption.onerror = function () {
  console.log('Impossible de paramétrer les options : ' + this.error.name);
}

Commandes STK

Les commandes STK dépendent de plusieurs facteurs (opérateur, modèle de puces...) mais sont toujours accessibles via la propriété MozMobileConnection.icc qui renverra un objet MozIccManager.

Avertissement : Il est recommandé de n'utiliser les commandes STK uniquement si vous êtes parfaitement conscient de ce que vous faites. En effet, cela peut endommager la puce électronique et la rendre inutilisable.

Spécification

Cette API n'appartient à aucune spécification.