Web Telephony API の使用

この記事は、Web Telephony API を使い始めるための基本を説明します。

Manifest 許可設定

Firefox OS アプリでこの API を使用するには、manifest.webapp ファイルに次の内容を記述する必要があります:

"type": "certified",
"permissions": {
  "telephony": {
    "description": "Required to control telephony functions"
  }
},

API アクセス

端末の電話機能へアクセスするための開始点は、Navigator.mozTelephony です。このオブジェクトの参照を得れば、通話の発信と着信を始められます。

// Telephony object
var tel = navigator.mozTelephony;

端末ハードウェアの調査

返される Telephony オブジェクトは、電話機のハードウェアをプログラム的に表し、その多くのアスペクトを制御する機能を与えます。例えば、消音や消音解除、スピーカーフォンの有効化と無効化などです:

// Check if the phone is muted (read/write property)
console.log(tel.muted);

// Check if the speaker is enabled (read/write property)
console.log(tel.speakerEnabled);

発信

通話の発信は、Telephony オブジェクトで Telephony.dial を呼び出すだけの簡単なものです。これは、Firefox OS 1.4 以降で使用できる Promise ベースの API です (以前は標準のコールバック関数でした)。これは、resolve で通話を表す TelephonyCall オブジェクトを返します。このオブジェクトには、いくつものプロパティ、メソッド、イベントハンドラが含まれており、通話のプロパティを監視し、通話の ハングアップ や 保留 などの操作ができ、通話状態の変化に対する動作も指定できます。

// Place a call
var call = tel.dial("123456789").then(function(call) {

  // Events for that call
  call.onstatechange = function (event) {
      /*
          Possible values for state:
          "dialing", "ringing", "busy", "connecting", "connected", 
          "disconnecting", "disconnected", "incoming"
      */
      console.log(event.state);
  };

  // Above options as direct events
  call.onconnected = function () {
      // Call was connected
  };

  call.ondisconnected = function () {
      // Call was disconnected
  };
});

着信

通話の着信は、発信と異なりますが単純です。着信時に発動する Telephony.onincoming イベントリスナを書く必要があります。この関数は、call プロパティを含むイベントオブジェクト (CallEvent) が含まれます。このプロパティは、通話の TelephonyCall オブジェクトへのアクセスを取得し、呼び出しへの応答 などの動作ができます。

// Receiving a call
tel.onincoming = function (event) {
  var incomingCall = event.call;

  // Get the number of the incoming call
  console.log(incomingCall.id);

  // Answer the call
  incomingCall.answer();
  
  // Let's say we have a button set up to hang up the call when pressed.
  hangupButton.onclick = function() {
    // Disconnect a call
    call.hangUp();
  }
};

複数の通話を端末上で同時にアクティブにすることが可能です。Telephony.calls プロパティを通じて各通話をイテレートし、それぞれに対して適切な動作を行ってください。

// Iterating over calls, and taking action depending on their changed status
tel.oncallschanged = function (event) {
  tel.calls.forEach(function (call) {
    // Log the state of each call
    console.log(call.state); 
  });
};

仕様

ブラウザ実装状況

明らかな理由により、サポートはモバイルブラウザが優先されます。

関連情報

• WebTelephony