Task Scheduler API Specification

Abstract

This specification defines an API to schedule a task at a specified time. When the indicated time is reached, the application that scheduled the task will be notified via a system message. If the application is not running when this happens, the system message will cause the application will be launched. Applications such as an alarm clock or an auto-updater may utilize this API to perform some action at a specified time.

Table of Contents

1. 1 Introduction
2. 2 Conformance
3. 3 Terminology
4. 4 Task Scheduler API
   1. 4.1 Interface Navigator
   2. 4.2 Interface TaskScheduler
   3. 4.3 Interface ScheduledTask
   4. 4.4 The task system message
   5. 4.5 Timezones and daylight savings
      1. 4.5.1 Crossing daylight savings time boundaries
      2. 4.5.2 Crossing timezone boundaries
5. References
6. Acknowledgments

1 Introduction

This section is non-normative.

function onTaskAdded(task) {
  console.log(task.data.message);
}
function onError(error) {
  alert("Sorry, couldn't set the alarm: " + error);
}

var date = new Date("May 15, 2012 16:20:00");
navigator.taskScheduler.add(date, "ignoreTimezone", {
  message: "Your soup is ready!"
}).done(onTaskAdded, onError);

function onTaskAdded(task) {
  console.log(task.data.message);
}
function onError(error) {
  alert("Sorry, couldn't set the alarm: " + error);
}

// Wake me up in 7 hours 
var time = new Date(new Date(Date.now() + (3600000 * 7)));
navigator.taskScheduler.add(time, "respectTimezone", {
  message: "Wake up!"
}).done(onTaskAdded, onError);

navigator.taskScheduler.getPendingTasks().done(function(tasks) {
  alert("There are " + tasks.length + " tasks set."));
}, function(error) {
    alert("An error occurred getting the scheduled tasks.");
});

var request = navigator.taskScheduler.remove(id).done(function() {
  alert("Task removed");
}, function(error) {
  alert("Sorry, can't remove the task.");
});

function onScheduledTaskFired(task) {
  alert("task scheduled at: " + task.date);
}
navigator.setMessageHandler("task", onScheduledTaskFired);

if (navigator.hasPendingMessages("task"))
  alert("There is at least 1 pending 'task' system message.");

2 Conformance

This specification defines conformance criteria for 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

A JSON-serializable object is an object that when serialized or stringified conforms to the JSON Grammar as defined in [ECMASCRIPT].

The EventHandler interface represents a callback used for handling events as defined in [HTML5].

The Future interface provides asynchronous access to the result of an operation that is ongoing, has yet to start, or has completed, as defined in [DOM].

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

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

The term system message is defined in [RUNTIME].

4 Task Scheduler API

This section is non-normative.

The task scheduler supports the following features:

• Web applications can schedule multiple tasks and get a returned ID for each of them.
• The returned ID is unique (within the application origin) and can be used to specify and remove the scheduled task.
• Web applications can pass a JSON-serializable object to describe more details about each task setting.
• Web applications can only access their own scheduled tasks.
• When a scheduled time is reached, an task system message is sent to the application.
• All the tasks that have been scheduled are automatically restored after rebooting the system.
• ScheduledTask API actually does more than setTimeout() because it can actively wake the system from sleeping.
• Whenever the system clock or timezone is adjusted at run-time, all the saved tasks will be rescheduled.

4.1 Interface Navigator

partial interface Navigator {
  readonly attribute TaskScheduler taskScheduler;
}

The taskScheduler attribute provides the developer access to a TaskScheduler.

4.2 Interface TaskScheduler

The TaskScheduler interface exposes methods to get, set or remove scheduled tasks. ScheduledTasks are application specific, so there is no way to see the tasks scheduled by other applications nor to modify them. Developers should set a message handler for the task system message to listen for when scheduled tasks should be executed.

enum TimezoneDirective { "respectTimezone", "ignoreTimezone" };

interface TaskScheduler {
  Future getPendingTasks();
  Future add(Date date, TimezoneDirective timezoneDirective, optional any data);
  Future remove(DOMString taskId);
};

When invoked, the getPendingTasks() method must run the following steps:

1. Make a request to the system to retrieve the tasks that were registered by the current application and whose scheduled time is in the future.
2. Let future be a new Future object and resolver its associated resolver.
3. Return future.
4. If an error occurs, run these substeps and then terminate these steps:
   1. Let error be a new DOMError object whose name is "UnknownError".
   2. Call resolver's reject(value) method with error as value argument.
5. When the operation completes successfully, run these substeps:
   1. Let tasks be a new array containing the ScheduledTask objects that were retrieved.
   2. Call resolver's accept(value) method with tasks as value argument.

When invoked, the add(date, timezoneDirective[, data]) method must run the following steps:

1. Make a request to the system to schedule a new task for the current application that will trigger at the given date. Depending on the timezoneDirective argument, the system will honor the timezone information of that [ECMASCRIPT] Date object or not. The system must associate the JSON-serializable data with the task if provided.
2. Let future be a new Future object and resolver its associated resolver.
3. Return future.
4. If an error occurs, run these substeps and then terminate these steps:
   1. Let error be a new DOMError object whose name is "InvalidStateError" if the date argument is in the past, "QuotaExceededError" if the data argument exceeds an implementation-dependent size limit, and "UnknownError" otherwise.
   2. Call resolver's reject(value) method with error as value argument.
5. When the operation completes successfully, run these substeps:
   1. Let task be a new ScheduledTask object.
   2. Set task's id attribute to the unique identifier returned by the system for the newly registered task.
   3. Set task's date attribute to the date argument.
   4. Set task's timezoneDirective attribute to the timezoneDirective argument.
   5. Set task's data attribute to the data argument, if provided.
   6. Call resolver's accept(value) method with task as value argument.

When invoked, the remove(taskId) method must run the following steps:

1. Make a request to the system to unregister the task with the given unique taskId identifier.
2. Let future be a new Future object and resolver its associated resolver.
3. Return future.
4. If an error occurs, run these substeps and then terminate these steps:
   1. Let error be a new DOMError object whose name is "UnknownError".
   2. Call resolver's reject(value) method with error as value argument.
5. When the operation completes successfully, run these substeps:
   1. Let removed be a boolean value.
   2. Set removed to true if the task was removed, and to false if there was no task with the given identifier.
   3. Call resolver's accept(value) method with removed as value argument.

4.3 Interface ScheduledTask

The ScheduledTask interface captures the properties of a scheduled task.

interface ScheduledTask {
  readonly attribute DOMString id;
  readonly attribute Date date;
  readonly attribute TimezoneDirective timezoneDirective;
  readonly attribute any data;
};

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

The date attribute is a Date object representing when the task is scheduled to run.

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

The data attribute optionally represents the JSON-serializable data associated with the task.

4.4 The task system message

An task system message is fired when a scheduled task should be executed. This event is originated from the system and will wake up the application if it is not currently running.

The developer should set message handler for the task system message to listen for when scheduled tasks should be executed. The ScheduledTask that was went off will be passed in argument to the system message callback.

4.5 Timezones and daylight savings

This section is non-normative.

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.5.1 Crossing daylight savings time boundaries

This section is non-normative.

var time = new Date(2013, 2, 10, 2, 00, 00);
navigator.taskScheduler.add(time, "ignoreTimezone");

var time = new Date(2013, 10, 3, 1, 10, 00);
navigator.taskScheduler.add(time, "ignoreTimezone");

4.5.2 Crossing timezone boundaries

This section is non-normative.

// User is currently in Pacific Standard Time (PST)
var time = new Date(2013, 0, 21, 7, 0, 00);
navigator.taskScheduler.add(time, "ignoreTimezone"); 

// User is currently in Pacific Standard Time (PST)
var time = new Date(2013, 0, 21, 7, 0, 00); 
navigator.taskScheduler.add(time, "respectTimezone");

References

Acknowledgments

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].