WebAPI/AlarmAPI

From MozillaWiki
Jump to: navigation, search

Alarm API Specification

Goals

To provide DOM API access to the system 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 E-Mail might need to utilize the Alarm API to wake up the sytem and trigger particular behaviors at specified time points.

Status

See bug 749551 for the Alarm API implementation.

Proposers

Mounir Lamouri, Kan-Ru Chen and Jonas Sicking

Contributors

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

Features

The Alarm API supports the following features:

  • Web applications can add multiple alarms and get a returned ID for each of them.
  • The returned ID is unique and can be further used to specify and remove the added alarm.
  • Web applications can pass a customized JSON object data to descirbe more details about each alarm setting.
  • When the alarm goes off, an alarm message will be fired and can be handled by the System Message Handler.
  • All the alarms that have been added can be automatically restored after rebooting the system.
  • Alarm API actually does more than setTimeout because it can actively *wake up* the system from sleeping.
  • Whenever the system clock or timezone is adjusted at run-time, all the saved alarms will be rescheduled.

Proposed API

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

 partial interface Navigator
 {
   readonly attribute AlarmsManager mozAlarms;
 };

 interface AlarmsManager
 {
   DOMRequest getAll();
   DOMRequest add(in jsval date, in DOMString respectTimezone, [optional] in jsval data);
   void remove(in unsigned long id);
 };
  • Regarding the navigator.add(...), the first argument date can be passed by a Date object and the second argument respectTimezone can be passed by either "honorTimezone" or "ignoreTimezone" to specify if we need to ignore the timezone information of that Date object. When "honorTimezone" is passed, we will alert that application when that time happens in that timezone. I.e. if someone passes a Date object which has the timezone set to US Pacific Time and time set to 7am, we will alert the application when the time is 7am in the US Pacific timezone, even if the user is in New York and thus in US Eastern Time and it's 10am for the user. When "ignoreTimezone" is passed, we will ignore the timezone part of the passed in Date object. I.e. if someone passes a Date object which has the timezone set to US Pacific Time and time set to 7am, we will alert the application when the time is 7am in whatever timezone the user happens to be in. So if the user is in New York, we will alert the user when it's 7am in that timezone. The third argument data can be optionally specified to pass the customized JSON object data, carrying more details about that alarm setting. Finally, a unique ID will be returned to specify the added alarm.
  • We can use navigator.remove(...) to remove an alarm that has been added in the system with a unique ID.
  • We can use navigator.getAll() to retrieve the information of each alarm that has been added in the system, including the unique ID, the customized JSON object data and the setting time (respects to the timezone or not)... etc.

Examples

Example use of the Alarm API for adding, getting and removing and listening to alarms in the applications:

  • How to add an "ignoreTimezone" alarm?
 var alarmId1;
 var request = navigator.mozAlarms.add(new Date("May 15, 2012 16:20:00"), "ignoreTimezone", { mydata: "bar" });
 request.onsuccess = function (e) { alarmId1 = e.target.result; };
 request.onerror = function (e) { alert(e.target.error.name); };
  • How to add an "honorTimezone" alarm?
 var alarmId2;
 var request = navigator.mozAlarms.add(new Date("June 29, 2012 07:30:00"), "honorTimezone", { mydata: "foo" });
 request.onsuccess = function (e) { alarmId2 = e.target.result; };
 request.onerror = function (e) { alert(e.target.error.name); };
  • How to retrieve the information of added alarms?
 var request = navigator.mozAlarms.getAll();
 request.onsuccess = function (e) { alert(JSON.stringify(e.target.result)); };
 request.onerror = function (e) { alert(e.target.error.name); };
  • How to remove the added alarms?
 navigator.mozAlarms.remove(alarmId1);
 navigator.mozAlarms.remove(alarmId2);
  • How to listen to the "alarm" message and handle it with a callback function when the alarm goes off?
 navigator.mozSetMessageHandler("alarm", function (message) { alert("alarm fired: " + JSON.stringify(message)); });
  • How to know in advance if there exists any pending "alarm" messages?
 navigator.mozHasPendingMessage("alarm");

FAQ

  • Why the callback function set by mozSetMessageHandler("alarm", function (message) { ... }) doesn't work when an alarm goes off?
    • You have to add a messages property in the application's manifest. The messages property is used to register the application as a potential target for catching certain types of messages, while mozSetMessageHandler(...) actually sets up the callback function that handles them. If you just call mozSetMessageHandler(...) without registering the "alarm" message previously, you won't receive it when an alarm goes off. Therefore, you have to add a messages property for registering the "alarm" message like below:
 "messages": [
    { "alarm": "/index.html" }
 ]
  • I've already added a messages property for registering the "alarm" message and set the system message handler for handling that. Why can't I receive that when the alarm goes off?
    • Note that the Alarm API works in such a way that it can only deliver the "alarm" message to the page that called the add(...). For example, if you call add(...) from path_1/index.html but set a system message handler for path_2/index.html, the path_2/index.html cannot receive the alarms added in path_1/index.html (bug 800431).
  • Does the getAll(...) return the alarms that were not added by its belonging application? For example, if the Alarm Clock app calls the getAll(...), will the alarms added by the Calendar app also be returned?
    • No, the getAll(...) only returns the alarms scheduled by the application.
  • Similarly, how about the remove(...)? Can an application delete the alarms added by other applications?
    • No, the Alarm API can only interact with alarms scheduled by the same app.
  • Supposing an alarm is set at 8:00am, but the device shuts down from 7:00am to 9:00am. Will the Alarm API fire an "alarm" message for that when the device powers up next time?
    • Yes, it will fire as soon as the device powers up.
  • Does the getAll(...) return the alarms that have already been fired? Or the back-end will keep them before the remove(...) is explicitly called?
    • The back-end won't keep the fired alarms, which means only alarms that have not fired will be returned.
  • 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=1021359"