Settings API

The Settings API is a way to access, change, and monitor changes to any device's settings. Because device settings can contain a lot of sensitive information that can jeopardize the system, only certified applications can use this API.

Using settings

Settings can be manipulated through the navigator.mozSettings object, which is an instance of the SettingsManager interface.

Accessing settings

To access a setting, you first need to create a lock by calling the createLock() method. Because several applications can access and change a setting at the same time, this ensures that apps won't interfere with one another. To that end, by creating a lock, each application is sure that it will be the only application accessing the settings at that specific moment.

Once your application has a lock, it can read any setting by using the get() method. This method returns a DOMRequest object that will report the success or failure of the operation. In all cases, the lock will automatically be released to let other applications access the settings as soon as the request is completed (whether it's successful or not). If needed, you can check to see if the lock has been released using the lock's closed property.

In this code snippet, a lock is created and the value of the system's wifi.enabled setting is requested. The output is displayed to the console by calling 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);
}

Changing settings

The process of changing a setting's value is exactly the same as accessing it, except you call the set() method. This method returns a DOMRequest object that lets you know if the setting change request succeeded or not.

set() expects an object as its input parameter. This object is a collection of key/value pairs in which each key is a setting name and its corresponding value is the new value for the setting. See Firefox OS settings list for a list of settings (but keep in mind that different devices may have variations on which settings are used).

Here we see a lock being created and the value of the wifi.enabled setting being retrieved and displayed on the console.

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

Listening for change in settings

Beyond reading and changing settings, applications can also listen for changes made to settings. Each time a setting is changed, the system triggers a settingchange event. This event is a MozSettingsEvent, which is a regular event extended with two extra properties:

• settingName, which provides the name of the setting that has been changed.
• settingValue, which provides the setting's new value.

The settingchange event can be monitored by setting SettingsManager.onsettingchange to specify a callback which is called for every setting change. If you'd rather listen for changes to a specific setting, you can call the SettingsManager.addObserver() method to do so, as shown here:

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

Specification

Not part of any specification yet; however, this API will be discussed at W3C as part of the System Applications Working Group.

See also

• Navigator.mozSettings
• SettingsManager
• SettingsLock
• MozSettingsEvent