Re: Alarm API Draft

http://sysapps.github.com/sysapps/proposals/alarm/Overview.html

This document, as with the Contacts document suffers from a lack of
Use Cases (an actual document should be provided). What follows are
examples of early text in the document showing how the document
suffers from lack of UCs and a lack of an explanation of how the API
would help satisfy those (absent) UCs.

Actually, I've included other problems in this message too...

> This specification defines a System Level API to provide access to the device alarm settings,

How does this API fulfill this? I don't see it doing this at all.

> which can schedule a notification or for an application to be started at a specific time.

How does this API fulfill this? I don't see it doing this either.

There's no sign of a way to ask the system to start an "application".

If this API is only meant for a single process (the app launcher
process), then there's very little need to standardize it, that app
can have its own internal datastore, and use timers however to do what
it needs.

Similarly, I'm not sure how this API helps with Notifications. There's
already an API for creating a timer (setTimeout) and an API for
Notifications.

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

I don't understand how this API provides something beyond setTimeout()
[and yes, I'm aware that setTimeout is ugly].

> Example use of the Alarm API for adding, getting and removing and listening to alarms in the device:
> How to listen to the "alarm" event with a callback function which will run whem [sic] an alarm goes off?
>  navigator.alarms.addEventListener("alarm", function (message) { alert("alarm fired: " + JSON.stringify(message)); }, false);

This is a terrible example.

https://developer.mozilla.org/en-US/docs/DOM/element.addEventListener

> listener The object that receives a notification when an event of the specified type occurs. This must be an object implementing the EventListener interface, or simply a JavaScript function.

http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-EventListener

> // Introduced in DOM Level 2:
> interface EventListener {
>  void               handleEvent(in Event evt);
> };

Note that the name of the argument for an event handler is generally
something like "event" or "evt" or "e" and not "message".

>  attribute Function? onsuccess;
>  attribute Function? onerror;
> 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.


`onsuccess` and `onerror` look like functions, and not events. What
arguments are passed to `onsuccess` / `onerro` when they are called
(and not fired, since they aren't events/eventhandlers!)?

If I do:

 function successhandler(...) {}

Nothing in your document normatively explains how successhandler
should be written.

>  request.onsuccess = function (e) { alarmId2 = e.target.result; };

The example makes it look like onsuccess is in fact an EventHandler
and not a Function.

Note that `fired` should be used in a linkified form if you mean
dom-level-3-fired, and you should have sufficient documentation that
one can determine where in [micro-]task-state the system is when the
event will be dispatched (if it's an event) or the function is called
(if it's just a function).

> When this happens, the user agent must queue a task to fire an event with the name alarm,

`alarm` here is in orange, but isn't a link, I can't tell if you mean
[literal] "alarm", or Alarm.id.valueOf(), or if you mean an event with
an attribute alarm, or an AlarmEvent, or if you mean an AlarmEvent
with an Event.type="alarm" or ... !?

-- 
Sent from my mobile device

Received on Monday, 19 November 2012 21:20:32 UTC