Mobile Connection

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.

Sumário

Essa API tem 2 propósitos:

Dar acesso a informações detalhadas sobre os estados atuais da conexão móvel do dispositivo
Dar acesso a uma capacidade específica junto com ICC (o cartão SIM/RUIM)

Como essa API pode acessar funcionalidades que podem ter um impacto no plano móvel assinado pelo usuário (algumas funcionalidades pode ter custo para utilizar ou causar danos ao ICC), é restrita para aplicações certificadas apenas.

O ponto inicial principal dessa API é a propriedade navigator.mozMobileConnection que é uma instância da interface MozMobileConnection.

Estado da conexão móvel

O estado da conexão móvel é dividida em dois: de um lado a conexão voice, do outro conexão data. O dado relacionado a cada tipo de conexão é acessível através pelas propriedades MozMobileConnection.voice e MozMobileConnection.data que ambas retornarão o objeto MozMobileConnectionInfo.

Esses objetos permitem acesso a todas as informações relacionadas a qualidade da rede (signal strength, quality of the signal, posição das network's cells, restricted usage, roaming, etc.), e relacionado à 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);
}

Funcionalidades ICC

As funcionalidades disponíveis para o ICC pode ser dividida dentro de duas categorias: o gerenciamento do próprio ICC e a utilização do comando integrado disponível dentro do STK (SIM Application Toolkit).

Ações Básicas

O MozMobileConnection fornece métodos para lidar com comportamentos comuns no ICCs.

Nota: 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.

Bloqueio do Cartão

Enquanto o cartão estiver bloqueado, o usuário é incapaz de utilizar uma rede móvel. É possível gerenciar o bloqueio do cartão com os métodos getCardLock(), setCardLock(), e unlockCardLock().

Se getCardLock() permite pegar algumas informações detalhadas sobre o bloqueio, também possível ter informação rápida sobre o bloqueio através MozMobileConnection.cardState que retorna uma string representando o estado atual do bloqueio.

Nota: 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();
}

Mensagens MMI

Mensagens MMI são códigos legíveis para humanos que, uma vez digitado no teclado do aparelho, permite disparo de ações específicas do RIL ou pegar resposta da rede pela requisição USSD. Um exemplo comum é digitar um código curto para receber número IMEI do aparelho.

Essas mensagens são enviadas utilizando o método MozMobileConnection.sendMMI() (e pode ser cancelado com cancelMMI()). Mesmo com isso irá retornar um objeto DOMRequest, a resposta para este tipo de mensagem é manuseada de duas maneiras:

Se o código MMI necessita enviar uma requisição USSD, o success da requesição significa que o RIL foi processado com sucesso e enviou a requisição USSD para a rede. Porém, a resposta da rede é reportada através do evento ussdreceived.
Se o código MMI não for associado com o USSD mas com outra requisição RIL, seu resultado, se um for necessário, é enviado pelo retorno requisitado success ou 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.");
}

Opções encaminhamento de chamada

Opções de encaminhamento permite definir como uma ligação pode ou não ser encaminhada para outro número de telefone.

Essas opções são manuseadas com os métodos getCallForwardingOption() e setCallForwardingOption().

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);
}

Comandos STK

Os comandos STK dependem em vários fatores (operadoras, modelos de chips, etc.) mas podem sempre ser acessados pela propriedade MozMobileConnection.icc que retorna um objeto MozIccManager.

Atenção: É recomendado utilizando comando STK apenas se você já sabe exatamente o que você está fazendo, porque a utilização errada pode danificar o chip e torná-lo inutilizável.

Especificações

Não faz parte de nenhuma especificação.