WebAPI/SettingsAPI

From MozillaWiki
Jump to: navigation, search

Status

This was implemented for B2G in bug 678695.

Proposed API

There is a readonly mozSettings attribute in window.navigator that would return an object implementing the SettingsManager interface.

The implementation keeps a queue of active locks. When a lock is created it's placed at the end of the queue. Calls to get/set places a request against the lock on which it's called. Requests run asynchronously and in the order they are placed against a lock. When the last request for a lock is run, and we've fired the success/error event against it, the lock is removed from the queue and we start processing the next lock.

interface SettingsManager : EventTarget
{
 SettingsLock getLock();

 void addObserver(DOMString name, Function observer);
}

interface SettingsLock
{
 // Contains a JSON object with name/value pairs to be set.
 DOMRequest set(any settings);

 // result contains the value of the setting.
 DOMRequest get(DOMString name);

 // XXX not implemented
 // result contains JSON object with name/value pairs.
 DOMRequest get(DOMString[] names);
}
/* Same as used in other specs. */
interface DOMRequest
{
  readonly attribute DOMString     readyState; // "processing" or "done"
  readonly attribute DOMError?     error;
           attribute EventListener onsuccess;
           attribute EventListener onerror;
           attribute readonly any? result;
};
[Constructor(DOMString type, optional SettingsEventInit settingsEventInitDict)]
interface SettingsEvent : Event
{
  readonly attribute DOMString settingName;
  readonly attribute any       settingValue;
};

dictionary SettingsEventInit : EventInit {
  DOMString settingName;
  any       settingValue;
}

SettingsEvent is used for the followings events: - change which is dispatched to the SettingsManager object when a setting value changes

Notes

  • SettingsRequest will be similar to SMSRequest described in WebSMS specification.
  • If a setting is unknown by the platform, it should fail.
  • But some platforms might not know some settings. Do we want to add a method that checks if the platform knows a specific setting?
  • get('*') returns all settings.