RE: Alarm API Draft

Chritophe wrote:
> We have uploaded an initial draft proposal of the Alarm API to:
> http://sysapps.github.com/sysapps/proposals/alarm/Overview.html


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

I wonder how the system defines an "application"?

If I uninstall an application and reinstall it, are the alarms persisted?

If I install version 2 of an application and I had alarms in version
1, are the alarms persisted?

Please note that this API doesn't match how the proposed Contacts API
works at all. Contacts aren't Application specific.

> enum TimezoneDirective { "honorTimezone", "ignoreTimezone" };

Please avoid using words where the spelling in en-us and en-gb differ.
"honor" v. "honour". The odds of someone trying to use
"honourTimezone" are unfortunately quite high.

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

"a an" [sic]

>  AlarmRequest add(Date date, TimezoneDirective respectTimezone, optional Object data);
> The add(alarm, respectTimezone[, data]) method is used to register a an alarm.

These do not agree.

> 1.The first argument date can be passed by a Date object.

This statement is confusing on its own, but the confusion stems from
the previous confusion.

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

Assuming that the user is in a timezone which has DST and assuming the
alarm recurs across a DST border, you haven't defined what happens
there.

Labeling something as "US Pacific Time" or "US Eastern Time" should be
your first clue that your API is broken as neither such time exists.

There's Pacific Daylight Time and Pacific Standard Time, there is no
"Pacific Time" nor is there an "Eastern Time" (although there *is* an
Easter Time, and that does move around some).

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

Oddly, it should be "a unique" as it's really "a youtube" not "an ootube"

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

Note that you didn't use "an unique" here, that's good, except for the
lack of consistency within a line (that's bad).

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

Origin should be linked to something. Note that "origin" conflicts
with the earlier statement that it was "per application", if the
answer to my previous question is "per origin" then the previous text
should be adjusted to say "per origin" instead of "per application".

> The alarm event is fired when an alarm goes off.

Where does an alarm go off? ("not bubble; not cancelable" isn't a
place, nor is "at an alarm manager", does the system / UA manage it?
Does it apply to multiple instances of an application? Does a
suspended instance get an alarm?)

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

How many AlarmManagers can there be, and why?


> References

If most of your API is stolen from Boot-to-Gecko then you should at
least have a non-normative reference to that origin. Lack of
references especially for source material is really inappropriate,
just because stuff is "open source" doesn't mean you're free to skip
attribution.

-- 
Sent from my mobile device

Received on Monday, 19 November 2012 20:55:00 UTC