WebAPI/AlarmAPI: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
Line 45: Line 45:
Example use of the Alarm API for adding, getting and removing alarms in the device:
Example use of the Alarm API for adding, getting and removing alarms in the device:


   var alarmId1 = navigator.mozAlarms.add(new Date("May 15, 2012 16:20:00"), "ignoreTimezone", { mydata: "bar" });
   var alarmId1;
   var alarmId2 = navigator.mozAlarms.add(new Date("June 29, 2012 07:30:00"), "honorTimezone", { mydata: "foo" });
  var requestAddAlarm1 = navigator.mozAlarms.add(new Date("May 15, 2012 16:20:00"), "ignoreTimezone", { mydata: "bar" });
   var request = navigator.mozAlarms.getAll();
  requestAddAlarm1.onsuccess = function (e) { alarmId1 = e.target.result; };
   request.onsuccess = function (e) { alert(JSON.stringify(e.target.result)); };
  requestAddAlarm1.onerror = function (e) { alert("error"); };
   request.onerror = function (e) { alert("error"); };
   var alarmId2;
  var requestAddAlarm2 = navigator.mozAlarms.add(new Date("June 29, 2012 07:30:00"), "honorTimezone", { mydata: "foo" });
  requestAddAlarm2.onsuccess = function (e) { alarmId2 = e.target.result; };
  requestAddAlarm2.onerror = function (e) { alert("error"); };
   var requestGetAll = navigator.mozAlarms.getAll();
   requestGetAll.onsuccess = function (e) { alert(JSON.stringify(e.target.result)); };
   requestGetAll.onerror = function (e) { alert("error"); };
   navigator.mozAlarms.remove(alarmId1);
   navigator.mozAlarms.remove(alarmId1);
   navigator.mozAlarms.remove(alarmId2);
   navigator.mozAlarms.remove(alarmId2);

Revision as of 02:42, 6 June 2012

Alarm API Specification

Goals

To provide DOM API access to the device alarm settings, which can schedule a notification or for an application to be started at a specific time. For example, some applications like alarm-clock, calendar or auto-update might need to utilize Alarm API to trigger particular device behaviors at specified time points.

Status

See bug 749551 for the Alarm API implementation (still under construction).

Proposers

Mounir Lamouri, Kan-Ru Chen and Jonas Sicking

Contributors

  • Alarm API: Gene Lian (IRC: gene)
  • System Message Handler: Fabrice Desré

Features

The Alarm API supports the following features:

  • Web application developer can arbitrarily add multiple alarms and get a unique ID for each of them to be removed later.
  • Web application developer can also specify customized JSON object data corresponding to each alarm setting.
  • All the alarms that have been set can be automatically restored even if a device reboot is encountered since the back-end service is maintained by an indexedDB database.
  • An alarm message will be fired when the system goes to its specified alarm time and can be handled by the System Message Handler.
  • Alarm behaviors are done by asynchronizing codes and multiple threads, which means clients are able to keep doing other processes when alarms are concurrently being added, removed, queried, listened and gone off.

Proposed API

There is an object in window.navigator named mozAlarms with the following interface, where the respectTimezone can be specified by either "honorTimezone" or "ignoreTimezone" and the data can save customized JSON objec data for each alarm setting. 

 interface AlarmsManager
 {
   DOMRequest getAll();
   DOMRequest add(in jsval date, in DOMString respectTimezone, [optional] in jsval data);
   void remove(in unsigned long id);
 };

Examples

Example use of the Alarm API for adding, getting and removing alarms in the device: 

 var alarmId1;
 var requestAddAlarm1 = navigator.mozAlarms.add(new Date("May 15, 2012 16:20:00"), "ignoreTimezone", { mydata: "bar" });
 requestAddAlarm1.onsuccess = function (e) { alarmId1 = e.target.result; };
 requestAddAlarm1.onerror = function (e) { alert("error"); };
 var alarmId2;
 var requestAddAlarm2 = navigator.mozAlarms.add(new Date("June 29, 2012 07:30:00"), "honorTimezone", { mydata: "foo" });
 requestAddAlarm2.onsuccess = function (e) { alarmId2 = e.target.result; };
 requestAddAlarm2.onerror = function (e) { alert("error"); };
 var requestGetAll = navigator.mozAlarms.getAll();
 requestGetAll.onsuccess = function (e) { alert(JSON.stringify(e.target.result)); };
 requestGetAll.onerror = function (e) { alert("error"); };
 navigator.mozAlarms.remove(alarmId1);
 navigator.mozAlarms.remove(alarmId2);

Example use of the System Message Handler (bug 755245 implemented by Fabrice Desré) for listening to the alarm messages and setting the corresponding callback function: 

 navigator.setMessageHandler("alarm", function (message) { alert("alarm fired!"); });
 navigator.hasPendingMessage("alarm");

FAQ

  • Why?
    • Answer.

Clients

Applications using the Alarm API:

Articles

Articles mentioning / discussing the Alarm API:

Related

Android references:

Android sources:

See Also

Other Web APIs related to the Alarm API:

Retrieved from "https://wiki.mozilla.org/index.php?title=WebAPI/AlarmAPI&oldid=438226"