Settings API

This is an archived page. It's not actively maintained.

非標準
この機能は現在 W3C の標準化のプロセスに乗っていませんが、Firefox OS プラットフォームではサポートされています。将来は動作が変わるかもしれませんし、他のブラウザーで広くサポートされているわけでもありませんが、Firefox OS アプリ専用のコードで使うには適しています。

この API は 認定済みアプリのみ、 Firefox OS で有効になります。

Settings API はデバイス設定へのアクセス、監視、変更を行うための手段です。デバイス設定にはシステムを危険に晒す可能性のある、慎重に取り扱うべき情報が含まれるため、認定アプリのみこのAPIを利用することができます。

デバイス設定の利用

デバイス設定は SettingsManager インターフェースのインスタンスである navigator.mozSettings オブジェクトを経由して操作することができます。

デバイス設定へのアクセス

デバイス設定にアクセスするには、まず createLock() メソッドを呼び出して "lock" を作成する必要があります。これは複数のアプリがデバイス設定を同時に呼び出して設定の変更を行う可能性があるため、他のアプリに干渉しないようにする必要があるからです。"lock" 作成することで、特定の期間内にひとつのアプリのみがデバイス設定にアクセスできることを保証します。

"lock" を作成したら、アプリは get() 関数を利用して様々な設定情報を取得することができます。この関数はリクエストの成功または失敗を示す DOMRequest オブジェクトを返します。リクエストが完了すると、（結果の成功または失敗にかかわらず）"lock" は例外なく自動的に解放されて他のアプリにデバイス設定へのアクセスを譲ります。必要に応じて "lock" の closed プロパティを参照し "lock" が解放されたかどうか確認することもできます。

以下のコードは "lock" を作成してシステムの wifi.enabled 設定を取得しています。取得結果は console.log() によりコンソールに出力されます。

var lock    = navigator.mozSettings.createLock();
var setting = lock.get('wifi.enabled');

setting.onsuccess = function () {
  console.log('wifi.enabled: ' + setting.result);
}

setting.onerror = function () {
  console.warn('An error occured: ' + setting.error);
}

デバイス設定の変更

設定値の変更手順は、set() 関数を呼び出す以外は設定値の取得と全く同じです。この関数は設定変更の成功または失敗を示す DOMRequest オブジェクトを返します。

set() は引数としてオブジェクトを渡す必要があります。オブジェクトは設定名称をキーとし、変更後の値を対とするキーペアの集合です。設定可能な値については Firefox OS settings list を参照して下さい（ただし設定できる項目がデバイス毎に異なる場合があることに注意して下さい）。

以下のコードは "lock" を作成してシステムの wifi.enabled 設定を変更し、その結果をコンソールに出力します。

var lock = navigator.mozSettings.createLock();
var result = lock.set({
  'wifi.enabled': true
});

result.onsuccess = function () {
  console.log("the settings has been changed");
}

result.onerror = function () {
  console.log("An error occure, the settings remain unchanged");
}

デバイス設定の変更を監視する

設定の取得や変更だけでなく、アプリはデバイス設定への変更を監視することもできます。システムは設定が変更される毎に settingchange イベントを発火します。. これは MozSettingsEvent イベントの一つで、通常のイベントに加えて以下の追加プロパティを保持します。

settingchange イベントを監視するには、設定の変更毎に呼び出される SettingsManager.onsettingchange にコールバック関数を渡します。また、SettingsManager.addObserver() 関数を利用すると、特定の設定に限定して変更を監視する事もできます。

function handleWifi(event) {
  if (event.settingValue === true) {
    console.log("Hey! I can download that crazy heavy 4GB file")
  } else {
    console.log("Oh! I should stop downloading that crazy 4GB file")
  }
}

navigator.mozSettings.addObserver('wifi.enabled', handleWifi);

仕様

草案。これは正式な仕様ではありませんが、W3Cにおいて System Applications Working Group の一部として協議される予定です。

参考