WebAPI/AlarmAPI: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(Undo revision 448255 by Janv (talk))
(Update the descriptions.)
Line 9: Line 9:
== Status ==
== Status ==


See {{bug|749551}} for the Alarm API implementation (still under construction).
See {{bug|749551}} for the Alarm API implementation (done except for the timezone-changed detection).


== Proposers ==  
== Proposers ==  
Line 24: Line 24:
The Alarm API supports the following 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 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.
* 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.
* When the alarm goes off, an alarm message will be fired and can be handled by a callback fucnction through the System Message Handler.
* An alarm message will be fired when the system goes to its specified alarm time and can be handled by the System Message Handler.
* All the alarms that have been set can be automatically restored even if a device reboot is encountered.
* 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 ==
== Proposed API ==
Line 41: Line 40:
   };
   };


Regarding the <code>navigator.add(...)</code>, the first argument <code>date</code> can be passed by a ''Date'' object and the second argument <code>respectTimezone</code> can be passed by either <code>"honorTimezone"</code> or <code>"ignoreTimezone"</code> to specify if we need to ignore the timezone information of that ''Date'' object. When <code>"honorTimezone"</code> 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 <code>"ignoreTimezone"</code> 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. Finally, the third argument <code>data</code> can be optionally specified to pass the customized JSON object data for that alarm.
* Regarding the <code>navigator.add(...)</code>, the first argument <code>date</code> can be passed by a ''Date'' object and the second argument <code>respectTimezone</code> can be passed by either <code>"honorTimezone"</code> or <code>"ignoreTimezone"</code> to specify if we need to ignore the timezone information of that ''Date'' object. When <code>"honorTimezone"</code> 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 <code>"ignoreTimezone"</code> 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. Finally, the third argument <code>data</code> can be optionally specified to pass the customized JSON object data for that alarm. Note that an unique ID will be returned to refer to the added alarm.
 
* We can use <code>navigator.remove(in unsigned long id)</code> to remove an alarm that has been added in the device with a unique ID.
 
* We can use <code>navigator.getAll()</code> to retrieve the information of each alarm that has been added in the device, including the unique ID, customized JSON object data and setting time (respects to the timezone or not)... etc.


== Examples ==
== Examples ==


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:
* How to add an "ignoreTimezone" alarm?


   var alarmId1;
   var alarmId1;
   var requestAddAlarm1 = navigator.mozAlarms.add(new Date("May 15, 2012 16:20:00"), "ignoreTimezone", { mydata: "bar" });
   var request = navigator.mozAlarms.add(new Date("May 15, 2012 16:20:00"), "ignoreTimezone", { mydata: "bar" });
   requestAddAlarm1.onsuccess = function (e) { alarmId1 = e.target.result; };
   request.onsuccess = function (e) { alarmId1 = e.target.result; };
   requestAddAlarm1.onerror = function (e) { alert("error"); };
   request.onerror = function (e) { alert("error"); };
 
* How to add an "honorTimezone" alarm?
 
   var alarmId2;
   var alarmId2;
   var requestAddAlarm2 = navigator.mozAlarms.add(new Date("June 29, 2012 07:30:00"), "honorTimezone", { mydata: "foo" });
   var request = navigator.mozAlarms.add(new Date("June 29, 2012 07:30:00"), "honorTimezone", { mydata: "foo" });
   requestAddAlarm2.onsuccess = function (e) { alarmId2 = e.target.result; };
   request.onsuccess = function (e) { alarmId2 = e.target.result; };
   requestAddAlarm2.onerror = function (e) { alert("error"); };
   request.onerror = function (e) { alert("error"); };
   var requestGetAll = navigator.mozAlarms.getAll();
 
   requestGetAll.onsuccess = function (e) { alert(JSON.stringify(e.target.result)); };
* How to retrieve the information of added alarms?
   requestGetAll.onerror = function (e) { alert("error"); };
 
   var request = navigator.mozAlarms.getAll();
   request.onsuccess = function (e) { alert(JSON.stringify(e.target.result)); };
   request.onerror = function (e) { alert("error"); };
 
* How to remove the added alarms?
 
   navigator.mozAlarms.remove(alarmId1);
   navigator.mozAlarms.remove(alarmId1);
   navigator.mozAlarms.remove(alarmId2);
   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:
* How to listen to the alarm-fired message with a callback function (executed when the alarm goes off)?
 
  navigator.setMessageHandler("alarm", function (message) { alert("alarm fired: " + JSON.stringify(message)); });
 
* How to know in advance if there exists any pending alarm-fired messages?


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


Line 76: Line 93:


* [[Gaia/Clock]]
* [[Gaia/Clock]]
* [[Gaia/Calendar]]
* [[WebAPI/CalendarAPI]]


== Articles ==
== Articles ==

Revision as of 04:32, 11 July 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 (done except for the timezone-changed detection).

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 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.
  • When the alarm goes off, an alarm message will be fired and can be handled by a callback fucnction through the System Message Handler.
  • All the alarms that have been set can be automatically restored even if a device reboot is encountered.

Proposed API

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

 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. Finally, the third argument data can be optionally specified to pass the customized JSON object data for that alarm. Note that an unique ID will be returned to refer to the added alarm.
  • We can use navigator.remove(in unsigned long id) to remove an alarm that has been added in the device with a unique ID.
  • We can use navigator.getAll() to retrieve the information of each alarm that has been added in the device, including the unique ID, customized JSON object data and setting time (respects to the timezone or not)... etc.

Examples

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

  • 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("error"); };
  • 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("error"); };
  • 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("error"); };
  • How to remove the added alarms?
 navigator.mozAlarms.remove(alarmId1);
 navigator.mozAlarms.remove(alarmId2);
  • How to listen to the alarm-fired message with a callback function (executed when the alarm goes off)?
 navigator.setMessageHandler("alarm", function (message) { alert("alarm fired: " + JSON.stringify(message)); });
  • How to know in advance if there exists any pending alarm-fired messages?
 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.allizom.org/index.php?title=WebAPI/AlarmAPI&oldid=449464"