W3C

Web Alarms API Specification

W3C Working Draft 5 February 2013

This version:
http://www.w3.org/TR/2013/WD-web-alarms-20130205/
Latest published version:
http://www.w3.org/TR/web-alarms/
Latest editor's draft:
http://sysapps.github.com/sysapps/proposals/alarm/Overview.html
Editors:
Christophe Dumez, Intel Corporation,

Abstract

This specification defines a System Level API to provide 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 of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document defines a System Level API to provide access to the device alarm settings, which can be used to either schedule a notification or to indicate that an application is to be started at a specific time.

This document was published by the System Applications Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-sysapps@w3.org (subscribe, archives). All feedback is welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

  1. 1 Introduction
  2. 2 Conformance
  3. 3 Terminology
  4. 4 Web Alarms API
    1. 4.1 Interface Navigator
    2. 4.2 Interface AlarmManager
    3. 4.3 Interface Alarm
    4. 4.4 Interface AlarmRequest
    5. 4.5 Interface AlarmEvent
    6. 4.6 Timezones and daylight savings
      1. 4.6.1 Crossing daylight savings time boundaries
      2. 4.6.2 Crossing timezone boundaries
  5. References
  6. Acknowledgements

1 Introduction

This section is non-normative.

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

How to add an "ignoreTimezone" alarm?

 var alarmId1;
 var request = navigator.alarms.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 "respectTimezone" alarm?

 var alarmId2;
 var request = navigator.alarms.add(new Date("June 29, 2012 07:30:00"), "respectTimezone", { 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.alarms.getAll();
 request.onsuccess = function (e) { alert(JSON.stringify(e.target.result)); };
 request.onerror = function (e) { alert(e.target.error.name); };

How to remove an added alarm?

 var request = navigator.alarms.remove(alarmId1);
 request.onsuccess = function (e) { alert("alarm removed"); };
 request.onerror = function (e) { alert(e.target.error.name); };

How to listen to the alarm event with a callback function which will run whem an alarm goes off?

 navigator.alarms.addEventListener("alarm", function (e) { alert("alarm fired: " + JSON.stringify(e)); }, false);

2 Conformance

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL], as this specification uses that specification and terminology.

3 Terminology

The EventHandler interface represents a callback used for event handlers as defined in [HTML5].

The concepts queue a task, event handler attributes and fire a simple event are defined in [HTML5].

The terms event handler and event handler event types are defined in [HTML5].

4 Web Alarms API

The Alarm API supports the following features:

4.1 Interface Navigator

partial interface Navigator {
  readonly attribute AlarmManager alarms;
}

The alarms attribute must return the object through which the alarms functionality can be accessed.

4.2 Interface AlarmManager

The AlarmManager interface exposes methods to get, set or remove alarms. Alarms are application specific, so there is no way to see the alarms scheduled by other applications nor to modify them. This interface also notifies the application when an alarm goes off, using an event handler attribute [DOM3EVENTS].
enum TimezoneDirective { "respectTimezone", "ignoreTimezone" };

[NoInterfaceObject]
interface AlarmManager : EventTarget {
  AlarmRequest getAll();
  AlarmRequest add(Date date, TimezoneDirective respectTimezone, optional Object data);
  AlarmRequest remove(DOMString alarmId);

  [TreatNonCallableAsNull]
  attribute Function? onalarm;
};

The getAll() method is used to to retrieve all the alarms added to the device as an array of Alarm objects.

The error cases must be handled as follows:

  1. If any error is returned, the implementation must set the error attribute of the AlarmRequest to a DOMError whose name is "UnknownError", and fire an event named error at the request.

The add(date, respectTimezone[, data]) method is used to register an alarm.

  1. The first argument date can is a Date object indicating when the alarm should trigger.
  2. The second argument respectTimezone can be either "respectTimezone" or "ignoreTimezone" to specify if we need to ignore the timezone information of that Date object. When "respectTimezone" is passed, we will alert that application when that time happens in that timezone. See Timezones and daylight savings section for examples.
  3. The third argument data can be optionally specified to pass the customized JSON object data for that alarm. Note that a unique ID will be returned to refer to the added alarm.

The error cases must be handled as follows:

  1. If the date argument is in the past, the implementation must set the error attribute of the AlarmRequest to a DOMError whose name is "InvalidStateError", and fire an event named error at the request.
  2. For other error cases, a DOMError whose name is "UnknownError" is used.

The remove(alarmId) method is used to remove an alarm that has been added in the device with a unique ID.

If the alarm was successfully removed, the implementation must set the result attribute of the AlarmRequest to true, and fire an event named success at the request. If there was no alarm with the given identifier, the implementation must follow the same steps but set the result attribute of the AlarmRequest to false.

The error cases must be handled as follows:

  1. If any error is returned, the implementation must set the error attribute of the AlarmRequest to a DOMError whose name is "UnknownError", and dispatch an error event at the request.

The onalarm attribute is the event handler of type Function for the alarm event. This event uses the AlarmEvent interface is fired when an alarm goes off.

4.3 Interface Alarm

The Alarm interface captures the properties of a registered alarm.

interface Alarm {
  readonly attribute DOMString id;

  attribute Date date;
  attribute TimezoneDirective respectTimezone;
  attribute Object data;
};

The id attribute must return an identifier for the given Alarm object that is unique within the origin. An implementation must maintain this identifier when a Alarm is added.

The date attribute is a Date object indicating when the alarm goes off.

The respectTimezone attribute indicates if the timezone information of the Date object is ignored.

The data attribute optionally defines the customized JSON object data pass to the alarm.

4.4 Interface AlarmRequest

An AlarmRequest object represents an ongoing operation; it notifies the application when the operation completes using event handler attributes [DOM3EVENTS], as well as a reference to the operation's result. A DOM method that initiates an ongoing operation may return a AlarmRequest object that you can use to monitor the progress of that operation.

This interface is identical to the DOMRequest interface [DOMREQUEST].

interface AlarmRequest : EventTarget
  readonly attribute DOMString readyState;

  readonly attribute any result;
  readonly attribute DOMError error;

  [TreatNonCallableAsNull]
  attribute Function? onsuccess;

  [TreatNonCallableAsNull]
  attribute Function? onerror;
};

The readyState attribute must return the state of this AlarmRequest. Possible values are "pending" and "done".

The result attribute must return the result of this AlarmRequest (if any), once the readyState is "done" and the success event is fired.

The error attribute must return the error that occurred for this AlarmRequest (if any). This attribute is populated when the error event is fired.

The onsuccess attribute is the event handler of type Function for the success event.

The onerror attribute is the event handler of type Function for the error event.

4.5 Interface AlarmEvent

The alarm event is fired when an alarm goes off.

When this happens, the user agent must queue a task to fire an event with the name alarm, which does not bubble and is not cancelable, and which uses the AlarmEvent interface, at each AlarmManager object that is affected.

[Constructor(DOMString type, optional AlarmEventInit eventInitDict)]
interface AlarmEvent : Event {
  readonly attribute Alarm alarm;
};

dictionary AlarmEventInit : EventInit {
  Alarm alarm;
};

The alarm attribute must return the alarm that is going off.

4.6 Timezones and daylight savings

The implementation needs to consider timezones and respect daylight savings. We will provide examples in this section to clarify how non-obvious cases should be handled.

4.6.1 Crossing daylight savings time boundaries

Let's consider an alarm on March 10, 2013 at 2:00am in a timezone where daylight savings time starts at that time (e.g. in San Francisco, CA):

add(new Date(2013, 2, 10, 2, 00, 00), "ignoreTimezone");
In San Francisco, CA, clocks are turned forward 1 hour on Sunday, March 10, 2013 at 2:00am due to daylight savings. In this case, the alarm must fire at 3:00am, i.e. one minute after 1:59am.

Let's consider an alarm on November 3, 2013 at 1:10am in a timezone where daylight savings time ends on that date (e.g. in San Francisco, CA):

add(new Date(2013, 10, 3, 1, 10, 00), "ignoreTimezone");

In San Francisco, CA, clocks are turned backward 1 hour on Sunday, November 3, 2013 at 2:00am. In this case, the alarm fires once the first time that the device is running and the local time is past 1:10am on November 3, 2013. After that the alarm is deleted.

4.6.2 Crossing timezone boundaries

Let's consider an alarm set for January 21, 2013 at 7:00am in Pacific Standard Time (PST) with respectTimezone argument set to "ignoreTimezone":

add(new Date(2013, 0, 21, 7, 0, 00), "ignoreTimezone"); // User is currently in Pacific Standard Time (PST)
If the user is traveling to New York on that day and currently in Eastern Standard Time (EST), the alarm must fire on January 21, 2013 when it is 7:00am in Eastern Standard Time (EST).

Let's consider an alarm set for January 21, 2013 at 7:00am in Pacific Standard Time (PST) with respectTimezone argument set to "respectTimezone":

add(new Date(2013, 0, 21, 7, 0, 00), "respectTimezone"); // User is currently in Pacific Standard Time (PST)
If the user is traveling to New York on that day and currently in Eastern Standard Time (EST), the alarm must fire on January 21, 2013 when it is 7:00am in Pacific Standard Time (PST), that is 10:00am for the user in Eastern Standard Time (EST).

References

[B2G-ALARM]
B2G Alarm API Specification, Mounir Lamouri, Kan-Ru Chen and Jonas Sicking. Mozilla.
[DOM3EVENTS]
Document Object Model (DOM) Level 3 Events Specification, Travis Leithead. W3C.
[DOMREQUEST]
DOMRequest Reference. Mozilla.
[HTML5]
HTML5, Ian Hickson. W3C.
[WEBIDL]
Web IDL, Cameron McCormack. W3C.

Acknowledgements

We would like to thank Kan-Ru Chen, Mounir Lamouri, Gene Lian and Jonas Sicking for their work on the API design, as well as the WebAPI/B2G teams at Mozilla [B2G-ALARM].