WebAPI/AlarmAPI

Alarm API Specification

Goals

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 such an alarm API to trigger particular device behaviors at specified time points.

Status

See bug 749551 for the Alarm API implementation.

Contributor

Gene Lian (IRC: gene)

Proposed API

There is an object in window.navigator named mozAlarms with the following interface:

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

Examples

Example use of the Alarm API for setting alarms in the device:

 var alarmId1 = navigator.mozAlarms.add(new Date("May 29, 2012 07:30:00"), "honorTimezone", { mydata: "foo" });
 var alarmId2 = navigator.mozAlarms.add(new Date("May 30, 2012 16:20:00"), "honorTimezone", { mydata: "bar" });

 var request = navigator.mozAlarms.get();
 request.onsuccess = function (e) { alert(JSON.stringify(e.target.result)); };
 request.onerror = function (e) { alert("error"); };

 navigator.mozAlarms.remove(alarmId1);
 navigator.mozAlarms.remove(alarmId2);

Example use of the System Message Handler for catching the alarm messages:

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

Clients

Applications using the Alarm API:

• Gaia/AlarmClock

Articles

Articles mentioning / discussing the Alarm API:

• mozilla.dev.webapi: Do we need an Alarm API?
• mozilla.dev.webapi: System Intents

See Also

See bug 755245 for the System Message Handler implementation.