Do we need an Alarm API?

[Mounir Lamouri]

Hi,

The recent discussion about Time/Clock API pointed out that we might
need an Alarm API but I was wondering which use cases this API would be
fulfilling and how it would actually work.

I see two use cases for which we could need something like an Alarm API:
- Alarm Clock App;
- Calendar App / or any kind of reminder.

Basically, an app that wants to get something done later regardless of
the state of the app (active, inactive, killed).
The API could be as easy as:
var alarmId = navigator.alarm.add(date, callback);
and:
navigator.alarm.remove(alarmId);

However, there is the issue of timezone agnostic or not. In other words,
an Alarm Clock should be timezone agnostic in the sens that you want to
wake up at [pick a number] every morning even if you are not in the same
country. However, the meeting planned at 8pm CST will be at 11am PST and
you want the alarm to change appropriately.
To fix that, we could add an unaesthetic boolean argument to the |add|
method.

When the alarm will occur, the platform would be responsible on
resurrecting the app if needed and send an event to |navigator.alarm|.

This said, I think we could prevent adding this API to the platform and
simply rely on the good old setInterval which is very close to what we
want here: every X seconds, a check will be done to see if an alarm have
to be fired.
To be able to do that, there are three requirements:
1. being able to run JS when in background, but that is also something
that will be required by the API because you don't want to show the
Calendar App when you have a reminder, you only want a notification and
a sound coming from a background app;
2. being sure that the app will not be killed while in the background;
3. running the app from the startup.

In my opinion, those two questions should be solved by the background
app/service discussion and we should consider alarm as a use case to be
fulfilled.

So, if the background app/service discussion allows an application to
ask to stay alive, be run from startup and run some js code in
background, does someone see a reason to still require an Alarm API?
I know Jonas is really fond of that API and I would love to hear is
opinion on that matter.

Thanks,
--
Mounir

[SUN Haitao]

> Basically, an app that wants to get something done later regardless of
> the state of the app (active, inactive, killed).
> The API could be as easy as:
>  var alarmId = navigator.alarm.add(date, callback);
> and:
>  navigator.alarm.remove(alarmId);

> However, there is the issue of timezone agnostic or not. In other words,
> an Alarm Clock should be timezone agnostic in the sens that you want to
> wake up at [pick a number] every morning even if you are not in the same
> country. However, the meeting planned at 8pm CST will be at 11am PST and
> you want the alarm to change appropriately.
> To fix that, we could add an unaesthetic boolean argument to the |add|
> method.

Maybe a parameter to indicate timezone (using null for agnostic cases)
will be more aesthetic than a boolean flag?

Maybe we could introduce a parent type of Date (or extend Date
objects) to represent timezone-agnostic date-time. But this solution
requires much more works.

> So, if the background app/service discussion allows an application to
> ask to stay alive, be run from startup and run some js code in
> background, does someone see a reason to still require an Alarm API?
> I know Jonas is really fond of that API and I would love to hear is
> opinion on that matter.

I think an Alarm API (or system service) will still be helpful. It
seems that keeping all time-checking works in one place could save
some resources when there are many apps that want to do something in
some particular time.

[Matthew Phillips]

This seems overly specific to me. Maybe this is just a nit on the name but
what you need is a scheduler or cron equivalent. This can be really simple.
Load my app at this URL and I'll handle the rest with pop state.

> _______________________________________________
> dev-webapi mailing list
> dev-w...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-webapi
>

[Mounir Lamouri]

On 04/18/2012 03:04 PM, Matthew Phillips wrote:
> This seems overly specific to me. Maybe this is just a nit on the name but
> what you need is a scheduler or cron equivalent. This can be really simple.
> Load my app at this URL and I'll handle the rest with pop state.

What would be the use case that can't be handled by background apps? or
where using a background would be really too much?

--
Mounir

[Vivien]

On 13/04/2012 13:10, Mounir Lamouri wrote:
>
> This said, I think we could prevent adding this API to the platform and
> simply rely on the good old setInterval which is very close to what we
> want here: every X seconds, a check will be done to see if an alarm have
> to be fired.
> To be able to do that, there are three requirements:
> 1. being able to run JS when in background, but that is also something
> that will be required by the API because you don't want to show the
> Calendar App when you have a reminder, you only want a notification and
> a sound coming from a background app;
> 2. being sure that the app will not be killed while in the background;
> 3. running the app from the startup.
>
> In my opinion, those two questions should be solved by the background
> app/service discussion and we should consider alarm as a use case to be
> fulfilled.
>

> So, if the background app/service discussion allows an application to
> ask to stay alive, be run from startup and run some js code in
> background, does someone see a reason to still require an Alarm API?

It worth experimenting on Gaia but it sounds like everything can be
tackle by setInterval.

[Matthew Phillips]

Is setInterval adjusted if I change time zones?

> ______________________________**_________________
> dev-webapi mailing list
> dev-w...@lists.mozilla.org
> https://lists.mozilla.org/**listinfo/dev-webapi<https://lists.mozilla.org/listinfo/dev-webapi>
>

[KanRu Chen]

Does setInterval still fire event when the device is suspended?

[Andreas Gal]

Waking up every X seconds is horrible for battery life.

Andreas

Sent from Mobile.

On Apr 18, 2012, at 7:34 PM, KanRu Chen <kc...@mozilla.com> wrote:

> Does setInterval still fire event when the device is suspended?

> _______________________________________________
> dev-webapi mailing list
> dev-w...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-webapi

[Vivien]

On 19/04/2012 04:41, Andreas Gal wrote:
> Waking up every X seconds is horrible for battery life.
>

Well I said setInterval but doing a setTimeout(..., delta) where delta
is the time between now and the future alarm you want to set should be
enough. Does it change anything?

>
> On Apr 18, 2012, at 7:34 PM, KanRu Chen <kc...@mozilla.com> wrote:
>
>>

>> It worth experimenting on Gaia but it sounds like everything can be
>> tackle by setInterval.

>> Does setInterval still fire event when the device is suspended?
>> _______________________________________________
>>

I guess it depends what you mean by suspended.
If suspended == turned off, obviously it doesn't but this is not a
problem since the different alarms can be stored into a DB and an alarm
service can activate them back at start up.
If suspended == something else, it probably depends on the limitations
on this mode.

[Vivien]

On 18/04/2012 21:18, Matthew Phillips wrote:
>
> Is setInterval adjusted if I change time zones?
>

Not that I know but this is the role of the Time API iirc (or
mozSettings) and it should fire an event when it happens. The alarm
app/service can listen those changes and update the alarms based on that.

[KanRu Chen]

Vivien <2...@vingtetun.org> writes:

>> On Apr 18, 2012, at 7:34 PM, KanRu Chen <kc...@mozilla.com> wrote:
>>
>>>
>>> It worth experimenting on Gaia but it sounds like everything can be
>>> tackle by setInterval.
>>> Does setInterval still fire event when the device is suspended?
>>> _______________________________________________
>>>
>
> I guess it depends what you mean by suspended.
> If suspended == turned off, obviously it doesn't but this is not a
> problem since the different alarms can be stored into a DB and an
> alarm service can activate them back at start up.
> If suspended == something else, it probably depends on the limitations
> on this mode.

Yeah, I mean when the device is off or partially off, it might need RTC
to wakeup. Some alarm event cannot be deferred to later "start up",
otherwise the user might be late for work or miss the flight, etc.

Kanru

[Vivien]

On 19/04/2012 11:20, KanRu Chen wrote:

> Vivien <2...@vingtetun.org> writes:
>
>>> On Apr 18, 2012, at 7:34 PM, KanRu Chen <kc...@mozilla.com> wrote:
>>>
>>>> It worth experimenting on Gaia but it sounds like everything can be
>>>> tackle by setInterval.
>>>> Does setInterval still fire event when the device is suspended?
>>>> _______________________________________________
>>>>
>> I guess it depends what you mean by suspended.
>> If suspended == turned off, obviously it doesn't but this is not a
>> problem since the different alarms can be stored into a DB and an
>> alarm service can activate them back at start up.
>> If suspended == something else, it probably depends on the limitations
>> on this mode.

> Yeah, I mean when the device is off or partially off, it might need RTC
> to wakeup. Some alarm event cannot be deferred to later "start up",
> otherwise the user might be late for work or miss the flight, etc.

I normally agree with you but from an other discussion on the Time/Clock
API on this mailing list what I have understood that it is not an
expected behavior to wake up the phone if it is turned off.
See
http://groups.google.com/group/mozilla.dev.webapi/browse_thread/thread/f382abb068abd4c5

[KanRu Chen]

Ah, I mean when the phone is in the low power state. On iOS and Android
I think it is called sleep mode. The main CPU is off but the modem is
still on so it can wakeup the system when there is incoming call. The
AlarmManager[1] in Android allows the app to schedule a event to run at
a specific time even the CPU is off and the app is not running.

I don't think we can implement the Alarm Clock app without this API.

[1]: http://developer.android.com/reference/android/app/AlarmManager.html

[Vivien]

> Ah, I mean when the phone is in the low power state. On iOS and Android
> I think it is called sleep mode. The main CPU is off but the modem is
> still on so it can wakeup the system when there is incoming call. The
> AlarmManager[1] in Android allows the app to schedule a event to run at
> a specific time even the CPU is off and the app is not running.

Thanks for the explanation. I didn't know about that.
Does b2g know how to enter sleep mode at the moment?

> I don't think we can implement the Alarm Clock app without this API.

Assuming there is sleep mode I agree.

[JOSE MANUEL CANTERA FONSECA]

El 24/04/12 13:02, "KanRu Chen" <kc...@mozilla.com> escribió:

>
>
>I don't think we can implement the Alarm Clock app without this API.
>

>[1]: http://developer.android.com/reference/android/app/AlarmManager.html


Having an Alarm API has the advantage of providing more flexibility and
possibilities for future evolution, for instance if the OEM decides to
support a RTC and wake-ups even if the phone is off. In addition the
Platform-Level implementation could take care of all the Timezone burdens.

For Telephony and SMS, CJones has suggested to use System Intents to allow
the Dialer / SMS to be started once a new incoming call is received or
when a new SMS arrives. Maybe we can have another kind of system intent
for Alarms.

Using this approach the Clock App would only need to call the Alarm API to
register for an Alarm. When the time to wake-up has come the B2G Platform
will raise a System Intent that will be resolved by the Clock App. The
advantage of this approach is that probably the Clock App does not need to
be in background, thus saving memory.

>_______________________________________________
>dev-webapi mailing list
>dev-w...@lists.mozilla.org
>https://lists.mozilla.org/listinfo/dev-webapi
>

Este mensaje se dirige exclusivamente a su destinatario. Puede consultar nuestra política de envío y recepción de correo electrónico en el enlace situado más abajo.
This message is intended exclusively for its addressee. We only send and receive email on the basis of the terms set out at
http://www.tid.es/ES/PAGINAS/disclaimer.aspx

[KanRu Chen]

Yes, when the screen is turned off it will enter sleep mode as soon as possible.

[KanRu Chen]

Hi,

This is a followup of Mounir's inquiry about the Alarm API. To
summarize, the potential users of this API is any Apps that want to get

something done later regardless of the state of the app (active,
inactive, killed).

I think the API needs to be able to:

- Set alarm time
- Set repeat interval
- Pass data for later use
- Wakeup the device from sleep mode if needed.

The API will looks like:

interface Alarm : EventTarget
{
long add(options, data);
void remove(long id);

attribute Function? onalarm;
}

interface AlarmEvent : Event
{
readonly attribute any data;
}

To add a new alarm:

var alarmId = navigator.alarm.add(options, data);

and to remove a alarm:

navigator.alarm.remove(alarmId);

Where the options object has these properties:

- when: a Date object
- interval: "yearly", "weekly", "daily", "hourly", or number of
seconds
- *exact: should be fired at exact time or not
- *timezone: boolean indicating whether the alarm is timezone aware
- *wakeup: wakeup the device from sleep mode or not

When the alarm fires, it can use System Intent or something like that to
bring up the App and fire the AlarmEvent. Given the current web intent
status is not clear, the alarm event is limited to the registering App
for now.

Any thoughts?

Thanks,
Kanru

[JOSE MANUEL CANTERA FONSECA]

El 27/04/12 13:12, "KanRu Chen" <kc...@mozilla.com> escribió:

>Hi,
>
>This is a followup of Mounir's inquiry about the Alarm API. To
>summarize, the potential users of this API is any Apps that want to get
>something done later regardless of the state of the app (active,
>inactive, killed).
>
>I think the API needs to be able to:
>
> - Set alarm time
> - Set repeat interval
> - Pass data for later use
> - Wakeup the device from sleep mode if needed.
>
>The API will looks like:
>
> interface Alarm : EventTarget
> {
> long add(options, data);
> void remove(long id);
>
> attribute Function? onalarm;
> }
>
> interface AlarmEvent : Event
> {
> readonly attribute any data;
> }

Maybe something also to list alarms
What's the use case for data?

>
>To add a new alarm:
>
> var alarmId = navigator.alarm.add(options, data);
>
>and to remove a alarm:
>
> navigator.alarm.remove(alarmId);
>
>Where the options object has these properties:
>
> - when: a Date object
> - interval: "yearly", "weekly", "daily", "hourly", or number of

> Seconds

You need the day of the week and also the number of repetitions and the
time between repetitions

> - *exact: should be fired at exact time or not
> - *timezone: boolean indicating whether the alarm is timezone aware
> - *wakeup: wakeup the device from sleep mode or not
>
>When the alarm fires, it can use System Intent or something like that to
>bring up the App and fire the AlarmEvent. Given the current web intent
>status is not clear, the alarm event is limited to the registering App
>for now.
>
>Any thoughts?
>
>Thanks,
>Kanru

[Reuben Morais]

On Apr 27, 2012 8:13 AM, "KanRu Chen" <kc...@mozilla.com> wrote:
> - when: a Date object
> - interval: "yearly", "weekly", "daily", "hourly", or number of

> seconds

What about custom repetition patterns? Something like ["mon", "wed",
"sat"]. A simple use case: I don't have classes on Friday
so no need to wake up early :)

Google Calendar, iCal and Android's alarm app all support this.

-- reuben

[Jim Straus]

Or Monthly. The 15th of each month (bill reminders). Or 1st Monday of each month (MozCorp meeting)?

[Andreas Gal]

I am working on an iCal parser right now. Flexible repeat pattern declaration is _extremely_ complex. Every 2nd Friday a month except if its the 7th week of the year or there is a Holiday the week prior in the local time zone. You do not want to go this route. Allow setting an alarm at a specific time. Let the web app wake up and reset the alarm.

Andreas

[Jim Straus]

If that's the case, why have reaeats at all? Set the alarm. Once it goes off, the app can reset it for the next occurrence. But yes, complex repeats are very hard. Even non-repeats can be difficult, as in: Set an alarm for 7am and then move timezones or daylight savings occurs during the night. When does it go off? If we have notification of time changes and notifications of alarms going off, we can foist this all off on the apps.
It doesn't make Andreas' problems any easier, and it makes life for simple alarm clock developers harder, but it makes the API easier. If desired, we could also publish some code to do the simple cases to make the developers life less complex.

[Andreas Gal]

Yes, I would avoid repeats altogether.

For individual alarms, there should be two options (again, borrowing from iCal). You set a timezone, which means the alarm goes off exactly at that time. Or if you don't set a timezone, its a floating alarm that goes off according to the local timezone (e.g. noon-get lunch!).

Andreas

[JOSE MANUEL CANTERA FONSECA]

El 27/04/12 18:41, "Andreas Gal" <g...@mozilla.com> escribió:

>
>I am working on an iCal parser right now. Flexible repeat pattern
>declaration is _extremely_ complex. Every 2nd Friday a month except if
>its the 7th week of the year or there is a Holiday the week prior in the
>local time zone. You do not want to go this route. Allow setting an alarm
>at a specific time. Let the web app wake up and reset the alarm.

The API could support common and simple repeat patterns

[Gene]

Hi all,

A Bugzilla entry is created at https://bugzilla.mozilla.org/show_bug.cgi?id=749551
to address this issue.

Thanks,
Gene

[KanRu Chen]

JOSE MANUEL CANTERA FONSECA <jm...@tid.es> writes:

> El 27/04/12 13:12, "KanRu Chen" <kc...@mozilla.com> escribió:
>
>>Hi,
>>
>>This is a followup of Mounir's inquiry about the Alarm API. To
>>summarize, the potential users of this API is any Apps that want to get
>>something done later regardless of the state of the app (active,
>>inactive, killed).
>>
>>I think the API needs to be able to:
>>
>> - Set alarm time
>> - Set repeat interval
>> - Pass data for later use
>> - Wakeup the device from sleep mode if needed.
>>
>>The API will looks like:
>>
>> interface Alarm : EventTarget
>> {
>> long add(options, data);
>> void remove(long id);
>>
>> attribute Function? onalarm;
>> }
>>
>> interface AlarmEvent : Event
>> {
>> readonly attribute any data;
>> }
>
> Maybe something also to list alarms

Right, so we should separate the Alarm interface and the AlarmManager
interface and model the interface after Contacts:

interface AlarmManager : EventTarget
{
DOMRequest clear();
DOMRequest save(in Alarm alarm);
DOMRequest remove(in Alarm alarm);

// Array of all alarms for this app
readonly attribute jsval alarms;

attribute Function onalarm;
}

interface Alarm
{
readonly attribute DOMString id;

attribute Date date;
attribute DOMString timezone;
attribute boolean exact;
attribute boolean wakeup;

}

> What's the use case for data?

To save the environment for later "callback" use. We cannot store
function object in the DB but we can save the needed variables. It is
convenient for developers to need not to setup extra db to store the
associated data.

[Mounir Lamouri]

On 04/30/2012 05:08 AM, KanRu Chen wrote:
> JOSE MANUEL CANTERA FONSECA <jm...@tid.es> writes:
>

>> El 27/04/12 13:12, "KanRu Chen" <kc...@mozilla.com> escribió:
>>
>>> Hi,
>>>
>>> This is a followup of Mounir's inquiry about the Alarm API. To
>>> summarize, the potential users of this API is any Apps that want to get
>>> something done later regardless of the state of the app (active,
>>> inactive, killed).
>>>
>>> I think the API needs to be able to:
>>>
>>> - Set alarm time
>>> - Set repeat interval
>>> - Pass data for later use
>>> - Wakeup the device from sleep mode if needed.
>>>
>>> The API will looks like:
>>>
>>> interface Alarm : EventTarget
>>> {
>>> long add(options, data);
>>> void remove(long id);
>>>
>>> attribute Function? onalarm;
>>> }
>>>
>>> interface AlarmEvent : Event
>>> {
>>> readonly attribute any data;
>>> }
>>
>> Maybe something also to list alarms
>

> Right, so we should separate the Alarm interface and the AlarmManager
> interface and model the interface after Contacts:
>
> interface AlarmManager : EventTarget
> {
> DOMRequest clear();

I'm not sure we need .clear(). One can just get all alarms and remove them.

> DOMRequest save(in Alarm alarm);
> DOMRequest remove(in Alarm alarm);
>
> // Array of all alarms for this app
> readonly attribute jsval alarms;
>
> attribute Function onalarm;
> }
>
> interface Alarm
> {
> readonly attribute DOMString id;
>
> attribute Date date;
> attribute DOMString timezone;

Date already has a TZ information. We should have a |boolean
respectTimezone;| instead.

> attribute boolean exact;

What's the meaning of that?

> attribute boolean wakeup;

If we don't wake up, don't we already have the tools to do that in the
web platform?

> }
>
>> What's the use case for data?
>

> To save the environment for later "callback" use. We cannot store
> function object in the DB but we can save the needed variables. It is
> convenient for developers to need not to setup extra db to store the
> associated data.

Do you have any use case for that?

I would propose an API like that:

interface AlarmsManager : EventTarget {
DOMRequest get();
attribute Function? onalarm;
};

interface NavigatorAlarm {
readonly attribute AlarmsManager alarms;
};

Navigator implements NavigatorAlarm;

interface Alarm {
readonly attribute long id;
attribute Date date;
attribute boolean respectTimezone;

// Two propositions, depending on if we really care about
// the async and the chances or errors.
// A:
attribute boolean set;
// B:
boolean isSet();
DOMRequest set();
DOMRequest unset();
};

interface AlarmEvent : Event {
readonly attribute Alarm alarm;
};

How does that sound?

Cheers,
--
Mounir

[Gene]

Mounir,

You're right we could probably remove the "exact" since your suggested
"respectTimezone" already implies the same meaning. Also, the "wakeup"
can be removed since the alarm should always wake the device up in any
way when it goes off. I'd like to have some quick questions based on
your suggested interfaces:

1. I don't quite understand how to associate a new-added alarm with
the AlarmsManager if we don't want to use navigator.alarm.save(new
Alarm()) as Kanru originally suggested? Could you please elaborate
more on this with a quick example in the JavaScript layer?

2. What is the AlarmEvent used for? Is it just used for the
association between AlarmsManager and Alarm addressed in #1?

3. Do the isSet()/set()/unset() functions within Alarm mean the
current alarm is already attached to the AlarmsManager? Or all the
created Alarm must be attached to the AlarmsManager by default and the
"set" functions here mean if the attached alarm is enabled for go-off?

4. What is the expected return when calling navigator.alarms.get()?

Thanks,
Gene

[Kan-Ru Chen]

Mounir Lamouri <mou...@lamouri.fr> writes:

> On 04/30/2012 05:08 AM, KanRu Chen wrote:
>> Right, so we should separate the Alarm interface and the AlarmManager
>> interface and model the interface after Contacts:
>>
>> interface AlarmManager : EventTarget
>> {
>> DOMRequest clear();
>
> I'm not sure we need .clear(). One can just get all alarms and remove them.

Yeah, we can get rid of this.

>> DOMRequest save(in Alarm alarm);
>> DOMRequest remove(in Alarm alarm);
>>
>> // Array of all alarms for this app
>> readonly attribute jsval alarms;
>>
>> attribute Function onalarm;
>> }
>>
>> interface Alarm
>> {
>> readonly attribute DOMString id;
>>
>> attribute Date date;
>> attribute DOMString timezone;
>
> Date already has a TZ information. We should have a |boolean
> respectTimezone;| instead.

Ah, sure.

>> attribute boolean exact;
>
> What's the meaning of that?

Should the alarm be fired at the exact time requested or let the system
group the alarms that have close expire time. This is the strategy used
by Android to prevent frequent wake up of the device.

>> attribute boolean wakeup;
>
> If we don't wake up, don't we already have the tools to do that in the
> web platform?

Not the ability to fire a system intent if the application isn't already
running.

>> }
>>
>>> What's the use case for data?
>>
>> To save the environment for later "callback" use. We cannot store
>> function object in the DB but we can save the needed variables. It is
>> convenient for developers to need not to setup extra db to store the
>> associated data.
>
> Do you have any use case for that?

To carry the calendar information etc. But it could be managed by the
application self and use the alarm id to associate the information so I
removed the data field from the second proposal.

> I would propose an API like that:
>
> interface AlarmsManager : EventTarget {
> DOMRequest get();
> attribute Function? onalarm;
> };
>
> interface NavigatorAlarm {
> readonly attribute AlarmsManager alarms;
> };
>
> Navigator implements NavigatorAlarm;
>
> interface Alarm {
> readonly attribute long id;
> attribute Date date;
> attribute boolean respectTimezone;
>
> // Two propositions, depending on if we really care about
> // the async and the chances or errors.
> // A:
> attribute boolean set;
> // B:
> boolean isSet();
> DOMRequest set();
> DOMRequest unset();
> };
>
> interface AlarmEvent : Event {
> readonly attribute Alarm alarm;
> };
>
> How does that sound?

Looks good to me, but please consider the issue I addressed above.

Kanru

[Mounir Lamouri]

On 05/07/2012 08:22 AM, Gene wrote:
> Mounir,
>
> You're right we could probably remove the "exact" since your suggested
> "respectTimezone" already implies the same meaning. Also, the "wakeup"
> can be removed since the alarm should always wake the device up in any
> way when it goes off. I'd like to have some quick questions based on
> your suggested interfaces:
>
> 1. I don't quite understand how to associate a new-added alarm with
> the AlarmsManager if we don't want to use navigator.alarm.save(new
> Alarm()) as Kanru originally suggested? Could you please elaborate
> more on this with a quick example in the JavaScript layer?

navigator.alarms.get(); // returns no alarm.

var a = new Alarm(/* set a date here */);
a.set();

navigator.alarms.get(); // returns |a| now.

> 2. What is the AlarmEvent used for? Is it just used for the
> association between AlarmsManager and Alarm addressed in #1?

It's to prevent the developers to keep a reference to the alarm objects
created. Actually, it might or might not be useful to get the alarm
object when the alarm is fired. It would probably be more useful if we
have a |data| attribute on |Alarm|.

> 3. Do the isSet()/set()/unset() functions within Alarm mean the
> current alarm is already attached to the AlarmsManager? Or all the
> created Alarm must be attached to the AlarmsManager by default and the
> "set" functions here mean if the attached alarm is enabled for go-off?

Alarms are not attached by default and set() (or .set = true;) should be
used to make it attached.

> 4. What is the expected return when calling navigator.alarms.get()?

A DOMRequest object with |.result| containing whether an iterator or a
|Alarm[]|.

--
Mounir

[JOSE MANUEL CANTERA FONSECA]

El 04/05/12 20:15, "Mounir Lamouri" <mou...@lamouri.fr> escribió:

>I would propose an API like that:
>
>interface AlarmsManager : EventTarget {
> DOMRequest get();
> attribute Function? onalarm;
>};

Does this mean that an application can get a reference to all the Alarms,
including those created by other apps?

It is a bit strange that the 'onalarm' event handler is on the global
manager object and not on the 'Alarm' object itself. Another idea could be
that the 'set' method incorporates another parameter with a callback
function to be invoked when the alarm goes off.

On the other hand a mechanism is needed to deal with the problem of
awaking the concerned app when the alarm goes off and the app is not
already running.

>
>interface NavigatorAlarm {
> readonly attribute AlarmsManager alarms;
>};
>
>Navigator implements NavigatorAlarm;
>
>interface Alarm {
> readonly attribute long id;
> attribute Date date;
> attribute boolean respectTimezone;
>
> // Two propositions, depending on if we really care about
> // the async and the chances or errors.
> // A:
> attribute boolean set;
> // B:
> boolean isSet();
> DOMRequest set();
> DOMRequest unset();
>};
>
>interface AlarmEvent : Event {
> readonly attribute Alarm alarm;
>};
>
>How does that sound?
>

>Cheers,
>--
>Mounir

[Kan-Ru Chen]

JOSE MANUEL CANTERA FONSECA <jm...@tid.es> writes:

> El 04/05/12 20:15, "Mounir Lamouri" <mou...@lamouri.fr> escribió:
>
>>I would propose an API like that:
>>
>>interface AlarmsManager : EventTarget {
>> DOMRequest get();
>> attribute Function? onalarm;
>>};
>
> Does this mean that an application can get a reference to all the Alarms,
> including those created by other apps?

I think the application only gets the alarms they registered.

> It is a bit strange that the 'onalarm' event handler is on the global
> manager object and not on the 'Alarm' object itself.

Like I said before, we need to fire the event even if the application is
not running. The flow as I understand is like:

Alarm expired -> Fire system intent -> App started -> the App binds
the alarm handler to AlarmManager -> Fire alarm event

If we put the onalarm event handler on each alarm object then the App
would have to query and bind the event handler each time it starts.

> Another idea could be that the 'set' method incorporates another
> parameter with a callback function to be invoked when the alarm goes
> off.

Callback function does not work cross App shutdown/startup.

> On the other hand a mechanism is needed to deal with the problem of
> awaking the concerned app when the alarm goes off and the app is not
> already running.

Exactly.

Kanru

[Jonas Sicking]

Hi everyone,

Today Mounir and I worked on this and a few related APIs. The
resulting suggestions are below.

On Mon, May 7, 2012 at 12:00 PM, Kan-Ru Chen <kc...@mozilla.com> wrote:
>> It is a bit strange that the 'onalarm' event handler is on the global
>> manager object and not on the 'Alarm' object itself.
>

> Like I said before, we need to fire the event even if the application is
> not running. The flow as I understand is like:
>
>  Alarm expired -> Fire system intent -> App started -> the App binds
>  the alarm handler to AlarmManager -> Fire alarm event

The problem with this approach is that it means that we can't fire the
alarm until the page is "fully loaded". However defining "fully
loaded" is a bit tricky on the web. We could fire the alarm event
sometime after DOMContentLoaded has fired. This generally means after
the whole DOM has been parsed and most of the <script>s have executed.

However not all <script>s have executed when DOMContentLoaded fires.
For example any <script>s with the async attribute set might not have
loaded. Also, it's very common today on the web to use various script
loaders which asynchronously load scripts using
createElement("script") and setting .src. Such scripts might also not
have loaded and so haven't had time to register alarm event listeners.

So we could wait until the "load" event is fired on the page. That
will ensure that <script>s with the async attribute set will have
loaded and have executed. But again, scripts loading using script
loaders might not even be started until the "load" event fires.

Additionally, waiting for "load" or DOMContentLoaded firing could in
many cases be waiting too long. An app can have been rendering for a
long time by the time that DOMContentLoaded fires. This could result
in a bad user experience where the app loads and renders in its
default state, and then suddenly changes once the alarm event fires.
Users likely expect the app to render in the correct state right away.

We had exactly this problem when designing the pushState API and ended
up having to do a last-minute change of the API and move away from
delivering data to a loading page using an event. There simply was no
good way to make events work as a delivery mechanism.

Instead we propose that we expand the capabilities of "system intents"
such that when an app is opened using a system event, the app can
request to get information about why it was started right away. I.e.
at any point during the loading of an app can the app state to the
platform that it is ready to receive events. That way it can ensure to
render in the right state right away.

So if it was started due to an alarm, the app gets the information
about this alarm using not using an event, but using the messaging
mechanism of system intents.

I'll start a separate thread about how these "system intents" will be
used to start applications and deliver messages to them.

But assuming that we remove the actual notifying part from the API,
here is the API that I suggest we use for the Alarm API:

partial interface Navigator {
readonly attribute AlarmsManager alarms;
};

interface AlarmsManager {
DOMRequest get();
long add(Date date, optional DOMString ignoreTimezone, optional any data);
void remove(long);
};

The 'add' function returns an id for the alarm. This id is used to
unregister alarms that the application is no longer interested in
receiving.

The 'remove' function simply unregisters a previously registered alarm.

The 'get' function asynchronously returns an array of all registered
alarms for that application. The array is basically a JSON object
which looks like:

[{ id: 1, date: <dateObject>, ignoreTimezone: true, data: ... },
{ id: 2, date: <dateObject>, ignoreTimezone: false, data: null },
...]

To register alarm callbacks you'd do something like:

id1 = navigator.alarms.add(new Date("2012-08-30"), "honorTimezone", {
mydata: "foo" });
id2 = navigator.alarms.add(new Date("2012-08-31"), "ignoreTimezone");

Again, since "system intents" is a somewhat orthogonal discussion,
i'll start a separate thread on how the delivery mechanism will work.

/ Jonas

[JOSE MANUEL CANTERA FONSECA]

El 09/05/12 08:11, "Jonas Sicking" <jo...@sicking.cc> escribió:

>
>partial interface Navigator {
> readonly attribute AlarmsManager alarms;
>};
>
>interface AlarmsManager {
> DOMRequest get();
> long add(Date date, optional DOMString ignoreTimezone, optional any
>data);
> void remove(long);
>};
>
>The 'add' function returns an id for the alarm. This id is used to
>unregister alarms that the application is no longer interested in
>receiving.

Once the alarm is added, is it activated? If so, what would happen if I
add an alarm and set the date to Date.now() ?

If I want to support in an Alarm Clock App repetition patterns, does this
mean that I have to add multiple alarms? I don't see how with this API it
can be supported the use case of awaking the user all days at certain
time.

Furthermore, I'm not sure if a Date object semantically is valid for these
use cases. Maybe we don't need a Date object, but Time or Date strings as
specified by HTML5.

It is a bit strange that add is a synchronous operation

>
>The 'remove' function simply unregisters a previously registered alarm.
>
>The 'get' function asynchronously returns an array of all registered
>alarms for that application. The array is basically a JSON object
>which looks like:
>
>[{ id: 1, date: <dateObject>, ignoreTimezone: true, data: ... },
> { id: 2, date: <dateObject>, ignoreTimezone: false, data: null },
> ...]

Probably this has to be implemented through the DOMIterator proposal I made

>
>To register alarm callbacks you'd do something like:
>
>id1 = navigator.alarms.add(new Date("2012-08-30"), "honorTimezone", {
>mydata: "foo" });
>id2 = navigator.alarms.add(new Date("2012-08-31"), "ignoreTimezone");

See my concerns above regarding the suitability of the Date object. If I
want to have Alarms Timezone agnostic, probably is better to use
DOMTimeStamp and not Date objects.

>
>Again, since "system intents" is a somewhat orthogonal discussion,
>i'll start a separate thread on how the delivery mechanism will work.

I'm looking forward to discussing on it

>
>/ Jonas

[Jonas Sicking]

On Wed, May 9, 2012 at 9:47 AM, JOSE MANUEL CANTERA FONSECA <jm...@tid.es> wrote:
> El 09/05/12 08:11, "Jonas Sicking" <jo...@sicking.cc> escribió:
>
>>
>>partial interface Navigator {
>> readonly attribute AlarmsManager alarms;
>>};
>>
>>interface AlarmsManager {
>> DOMRequest get();
>> long add(Date date, optional DOMString ignoreTimezone, optional any
>>data);
>> void remove(long);
>>};
>>
>>The 'add' function returns an id for the alarm. This id is used to
>>unregister alarms that the application is no longer interested in
>>receiving.
>
> Once the alarm is added, is it activated? If so, what would happen if I
> add an alarm and set the date to Date.now() ?

If you set an alarm for Date.now() or earlier the alarm will be fired
immediately. We could also throw, but that seems more error prone.

> If I want to support in an Alarm Clock App repetition patterns, does this
> mean that I have to add multiple alarms? I don't see how with this API it
> can be supported the use case of awaking the user all days at certain
> time.

You set an alarm for the next time the alarm should fire. Once it
fires you schedule an alarm for the next time you want it to fire.

We could add support for basic repeating alarms. But like Andreas
pointed out, the way things can repeat is very complex (consider
alarms for every easter, or every mothers/fathers day).

> Furthermore, I'm not sure if a Date object semantically is valid for these
> use cases.

Why?

> It is a bit strange that add is a synchronous operation

Synchronous is always better than async when we can do it. I don't see
a reason we couldn't here.

>>The 'remove' function simply unregisters a previously registered alarm.
>>
>>The 'get' function asynchronously returns an array of all registered
>>alarms for that application. The array is basically a JSON object
>>which looks like:
>>
>>[{ id: 1, date: <dateObject>, ignoreTimezone: true, data: ... },
>> { id: 2, date: <dateObject>, ignoreTimezone: false, data: null },
>> ...]
>
> Probably this has to be implemented through the DOMIterator proposal I made

I don't think applications will have enough alarms that we need to
worry about loading them all into memory.

/ Jonas

[Mounir Lamouri]

On 05/09/2012 01:39 PM, Gene wrote:
> One question: since it seems that the system intent can only support
> us wake up the specific AlarmsManager application, how to specify the
> target alarm that was fired? Can we save the alarm ID or any other
> customized data in the system intent?

The callback will have in argument an alarm object in JSON format.

Cheers,
--
Mounir

[Jonas Sicking]

On Wed, May 9, 2012 at 1:39 PM, Gene <cl...@mozilla.com> wrote:
> Jonas,

>
> One question: since it seems that the system intent can only support
> us wake up the specific AlarmsManager application, how to specify the
> target alarm that was fired? Can we save the alarm ID or any other
> customized data in the system intent?
>

> I'll be working out a very first version that implements the latest
> API you suggested by the weekend (discarding the usage of event
> things), and continue on the system intent part when it is available.
> Please see: https://bugzilla.mozilla.org/show_bug.cgi?id=749551

I just sent the proposal for how messages are delivered to
applications. Please see the "System Intents" thread.

I'm not sure I understand how your patch is going to work without
using the system intents support. What happens if the application
isn't running when we want to fire the Alarm?

/ Jonas

[Gene]

On May 10, 5:20 am, Jonas Sicking <jo...@sicking.cc> wrote:
> On Wed, May 9, 2012 at 1:39 PM, Gene <cl...@mozilla.com> wrote:
> > Jonas,
>
> > One question: since it seems that the system intent can only support
> > us wake up the specific AlarmsManager application, how to specify the

> > targetalarmthat was fired? Can we save thealarmID or any other

> > customized data in the system intent?
>
> > I'll be working out a very first version that implements the latest

> >APIyou suggested by the weekend (discarding the usage of event

> > things), and continue on the system intent part when it is available.
> > Please see:https://bugzilla.mozilla.org/show_bug.cgi?id=749551
>
> I just sent the proposal for how messages are delivered to
> applications. Please see the "System Intents" thread.
>
> I'm not sure I understand how your patch is going to work without
> using the system intents support. What happens if the application
> isn't running when we want to fire theAlarm?
>
> / Jonas

Jonas,

Yeap... it didn't work at all. We must use system intent in any way to
wake up the app before sending an event to it.

Gene

[Jonas Sicking]

On Wed, May 9, 2012 at 2:47 PM, Gene <cl...@mozilla.com> wrote:
> On May 10, 5:20 am, Jonas Sicking <jo...@sicking.cc> wrote:

>> On Wed, May 9, 2012 at 1:39 PM, Gene <cl...@mozilla.com> wrote:
>> > Jonas,
>>
>> > One question: since it seems that the system intent can only support
>> > us wake up the specific AlarmsManager application, how to specify the

>> > targetalarmthat was fired? Can we save thealarmID or any other

>> > customized data in the system intent?
>>
>> > I'll be working out a very first version that implements the latest

>> >APIyou suggested by the weekend (discarding the usage of event

>> > things), and continue on the system intent part when it is available.
>> > Please see:https://bugzilla.mozilla.org/show_bug.cgi?id=749551
>>
>> I just sent the proposal for how messages are delivered to
>> applications. Please see the "System Intents" thread.
>>
>> I'm not sure I understand how your patch is going to work without
>> using the system intents support. What happens if the application

>> isn't running when we want to fire theAlarm?
>>
>> / Jonas
>
> Jonas,
>
> Yeap... it didn't work at all. We must use system intent in any way to
> wake up the app before sending an event to it.

Does it add any functionality over what setTimeout already supplies then?

/ Jonas

[JOSE MANUEL CANTERA FONSECA]

El 09/05/12 19:35, "Jonas Sicking" <jo...@sicking.cc> escribió:

That will not work if the alarm deadline happens while the device is off.

>
>We could add support for basic repeating alarms. But like Andreas
>pointed out, the way things can repeat is very complex (consider
>alarms for every easter, or every mothers/fathers day).

That's something which could done through the Calendar App + Notifications

>
>> Furthermore, I'm not sure if a Date object semantically is valid for
>>these
>> use cases.
>
>Why?

Because date represents a Date and a time. But If we for example allow
something like

navigator.mozAlarms.add('12:00') it would be pretty straightforward to
support simple use cases like awake me all days at 12:00 AM

>
>> It is a bit strange that add is a synchronous operation
>
>Synchronous is always better than async when we can do it. I don't see
>a reason we couldn't here.

My understanding that the alarm setting will persist

>
>>>The 'remove' function simply unregisters a previously registered alarm.
>>>
>>>The 'get' function asynchronously returns an array of all registered
>>>alarms for that application. The array is basically a JSON object
>>>which looks like:
>>>
>>>[{ id: 1, date: <dateObject>, ignoreTimezone: true, data: ... },
>>> { id: 2, date: <dateObject>, ignoreTimezone: false, data: null },
>>> ...]
>>
>> Probably this has to be implemented through the DOMIterator proposal I
>>made
>
>I don't think applications will have enough alarms that we need to
>worry about loading them all into memory.
>
>/ Jonas
>

[Gene]

On May 10, 6:07 am, Jonas Sicking <jo...@sicking.cc> wrote:
> > Jonas,
>
> > Yeap... it didn't work at all. We must use system intent in any way to
> > wake up the app before sending an event to it.
>
> Does it add any functionality over what setTimeout already supplies then?
>
> / Jonas

Jonas,

I mean the previous interface still needs system intent to wake up the
app even if the event thing is used. All in all, the alarm API
absolutely depends on the system intent.

Gene

[Jonas Sicking]

To keep things simple, the idea is that this is an API to simply allow
applications to scheduled to be woken up at a specific date+time.

If the device is turned off at that date+time, the application will be
woken up as soon as the device is started.

So my proposal is that we *don't* allow any type of repeating alarms.
I.e. the API doesn't allow things like "wake me up as 12am every day"
or "wake me up every monday/wednesday/friday at 7pm"

However, since the API will wake up the application even if the device
is turned off as soon as the device is restarted, that means that you
can use this API to build any sorts of reoccurring notifications. You
just have to have a little bit of code.

We certainly could build something which has built-in support for
repetition, however it's very hard to draw the line for which types of
repetition to include. I think for example that most alarm-clock apps
which allow repeating alarms, uses more advanced repetitions than
"every day at 12am". Most of them at least let you choose which days
of the week the repetition should happen.

It seems simpler to me to always leave it up to the web application to
implement repetition.

/ Jonas

[JOSE MANUEL CANTERA FONSECA]

El 10/05/12 02:22, "Jonas Sicking" <jo...@sicking.cc> escribió:

That can be done without creating an API, so I don't see the advantage

>
>If the device is turned off at that date+time, the application will be
>woken up as soon as the device is started.

That seems to be a waste of resources, imagine I have 10 apps that have
pending alarms, would you run the ten at the same time while the device
has just restarted?

>
>So my proposal is that we *don't* allow any type of repeating alarms.
>I.e. the API doesn't allow things like "wake me up as 12am every day"
>or "wake me up every monday/wednesday/friday at 7pm"
>
>However, since the API will wake up the application even if the device
>is turned off as soon as the device is restarted, that means that you
>can use this API to build any sorts of reoccurring notifications. You
>just have to have a little bit of code.

Yes, but as I said before what's the point of creating an API if it does
not solve the problem?

>
>We certainly could build something which has built-in support for
>repetition, however it's very hard to draw the line for which types of
>repetition to include.

I think the principle is to make simple things easy and complex things
possible. With the current approach it seems none of them are met.

>
>It seems simpler to me to always leave it up to the web application to
>implement repetition.

For the API implementor sure, but for the app developer is just the
opposite

[Gene]

> On May 11, 12:18 am, JOSE MANUEL CANTERA FONSECA <j...@tid.es> wrote:
> >If the device is turned off at that date+time, the application will be
> >woken up as soon as the device is started.
>
> That seems to be a waste of resources, imagine I have 10 apps that have
> pending alarms, would you run the ten at the same time while the device
> has just restarted?

Just a thought: I think we don't need to wake up the app if its
pending alarms are no longer valid. For example, if the alarms of an
alarm-clock app are all expired after the device is restarted, there
is no need to wake up the app. Right? However, for other apps like
calendar or auto-update, we probably need to wake them up to notify
users the attached alarms have already been expired. To achieve this,
we need to use indexedDB to save/access the alarm settings.

Gene

[Mounir Lamouri]

On 05/10/2012 07:04 PM, Gene wrote:
>> On May 11, 12:18 am, JOSE MANUEL CANTERA FONSECA <j...@tid.es> wrote:

>>> If the device is turned off at that date+time, the application will be
>>> woken up as soon as the device is started.
>>
>> That seems to be a waste of resources, imagine I have 10 apps that have
>> pending alarms, would you run the ten at the same time while the device
>> has just restarted?
>

> Just a thought: I think we don't need to wake up the app if its
> pending alarms are no longer valid. For example, if the alarms of an
> alarm-clock app are all expired after the device is restarted, there
> is no need to wake up the app. Right? However, for other apps like
> calendar or auto-update, we probably need to wake them up to notify
> users the attached alarms have already been expired. To achieve this,
> we need to use indexedDB to save/access the alarm settings.

I think we should still wake up the app otherwise recurrence might be
broken. For example, if I have an alarm clock at 7am and I shutdown my
phone at 8pm and start it the day after at 9pm before going to sleep. If
the alarm doesn't wake up the app, I will not be woken up in the morning
because the alarm was for the previous day but I clearly expect to be
waken up in the morning.

Cheers,
--
Mounir

[Gene]

>On 5月15日, 下午7時02分, Mounir Lamouri <mou...@lamouri.fr> wrote:
>I think we should still wake up the app otherwise recurrence might be

>broken. For example, if I have analarmclock at 7am and I shutdown my

>phone at 8pm and start it the day after at 9pm before going to sleep. If

>thealarmdoesn't wake up the app, I will not be woken up in the morning
>because thealarmwas for the previous day but I clearly expect to be

>waken up in the morning.
>
>Cheers,
>--
>Mounir

Sounds good! Mounir :)

Some updates to let you know waht I'm doing regarding the indexedDB
things. I'm going to construct a database containing the followoing
columns. Note that a record will be created after the app calls
add(date, repectTimeZone, data) as mentioned in the previous
discussion.

1. id (key)
2. date
3. respectTimezone
4. appId
5. data

Unique *id* is internally generated and will be exposed to app for
removing the alarm (i.e. remove(id)) and for matching the correct
pending intents. *date* and *respectTimeZone* are saved for reset the
lower-level dev/alarm through IO control whenever the device is
rebooted. *appId* is used for system intent to know which app is going
to be waken up so that system can send intents toward that app. *data*
saves the customized JSON data. All in all, we need such an off-line
database to restore all the registered alarm info to avoid losing data
after the device shuts down.

Please feel free to let me know if anything doesn't sound good to you.

Thanks,
Gene

[Gene Lian]

An wikipage was created at: https://wiki.mozilla.org/WebAPI/AlarmAPI
Please feel free to edit it yourself if you see anything wrong or improper.

Thanks,
Gene

[Jonas Sicking]

On Thu, May 31, 2012 at 8:55 PM, Gene Lian <cl...@mozilla.com> wrote:
> An wikipage was created at: https://wiki.mozilla.org/WebAPI/AlarmAPI
> Please feel free to edit it yourself if you see anything wrong or improper.

I renamed 'get' to 'getAll' to make it more clear that the function
doesn't just return a single alarm.

The other part that I'm somewhat concerned about is the fact that .add
synchronously returns an identifier. If we can do that then that's
great. But if not I think it would be ok to return a DOMRequest.

/ Jonas

[Gene Lian]

Jonas Sicking於 2012年6月4日星期一UTC+8下午2時29分30秒寫道：

Jonas,

I think it would be OK to return a DOMRequest for both add() and remove(). I can have these changes as well.

Thanks,
Gene

[Gene Lian]

Hi guys,

One thing needs to be clarified about the use of "honorTimezone" of add(). I'm afraid I kind of misunderstood its purpose. Supposing we're setting the following time at Tokyo:

navigator.mozAlarms.add(new Date("May 15, 2012 17:00:00"), "honorTimezone");

If user is located at New York, the alarm will go off at 17:00:00 respect to New York's local time instead of the Tokyo's local time. Right?

If so, the system must be able to dynamically adjust the alarm time according to the timezone change, since the alarm UTC time is not fixed and can vary by timezone.

Do you think we need to expose another DOM like setHonorTimezone("NewYork") for the app to dynamically reset the expected honorTimezone?

Thanks,
Gene

[Jonas Sicking]

The idea is as follows:

All Javascript Date objects consist of date+time+timezone. This is
already the case and has been part of javascript since its original
release.

So when someone calls

navigator.mozAlarms.add(dateobject, "honorTimezone");

they implicitly specify a timezone for the alarm. When "honorTimezone"
is passed as second argument, 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.

navigator.mozAlarms.add(dateobject, "ignoreTimezone");

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

Does this make sense?

An alternative to having a second respectTimeZone argument, we could
have two separate add functions: addRespectTimezone and
addIgnoreTimezone (or some other shorter names).

/ Jonas

[Gene Lian]

Jonas,

Thanks for your clarifications :) It seems I misunderstand the respectTimeZone argument as an opposite way. Both the "ignoreTimezone" and "honorTimezone" are interpreted respect to the dateobject's timezone.

> navigator.mozAlarms.add(dateobject, "ignoreTimezone");
>
> then 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.

Regarding the "ignoreTimezone", I still have the same concern that I pointed out in the previous comment. Supposing a user is setting 7:00pm with "ignoreTimezone", its actual UTC time can be very different based on where the timezone the user is located. Unfortunately, the system alarm can only be programmed by UTC time, which means we need to dynamically adjust the setting time when there is a timezone change. So do we need to provide an DOM exposed to app to flexibly change the alarm timezone like setUserTimezoneForIgnoreTimezone("NewYork") (just a psudo name)?

Another minor question is: since the respectTimeZone argument is optional. Which one is preferred as default ("ignoreTimezone" or "honorTimezone")?

Thanks,
Gene

[Jonas Sicking]

On Tue, Jun 5, 2012 at 1:16 AM, Gene Lian <cl...@mozilla.com> wrote:
> Jonas,
>
> Thanks for your clarifications :) It seems I misunderstand the respectTimeZone argument as an opposite way. Both the "ignoreTimezone" and "honorTimezone" are interpreted respect to the dateobject's timezone.
>

>> navigator.mozAlarms.add(dateobject, "ignoreTimezone");
>>
>> then 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.
>

> Regarding the "ignoreTimezone", I still have the same concern that I pointed out in the previous comment. Supposing a user is setting 7:00pm with "ignoreTimezone", its actual UTC time can be very different based on where the timezone the user is located. Unfortunately, the system alarm can only be programmed by UTC time, which means we need to dynamically adjust the setting time when there is a timezone change. So do we need to provide an DOM exposed to app to flexibly change the alarm timezone like setUserTimezoneForIgnoreTimezone("NewYork") (just a psudo name)?

It would be somewhat annoying for all applications that want to use
"ignoreTimezone" to have to observe the "timezone change" event and
immediately call setUserTimezoneForIgnoreTimezone(currentTimeZone).
This is especially a problem since the timezone-change event is
currently just a plain DOM event and thus won't be fired if the user
changes timezone while the app isn't running.

We could fix that and use a system message ("system intent") to
deliver the timezone-change event. However it still seems silly for
all apps that want to use "ignoreTimezone" to have to all listen to
timezone changes and then do exactly the same thing when the timezone
changes. In fact, if they had to do that then "ignoreTimezone" doesn't
really provide much functionality since they could just use
"respectTimezone" and reschedule all alarms as needed when the
timezone changes.

Instead the alarm API backend implementation should listen for
timezone changes and when they occur, reschedule all alarms registered
with "ignoreTimezone". That way it will "just work".

> Another minor question is: since the respectTimeZone argument is optional. Which one is preferred as default ("ignoreTimezone" or "honorTimezone")?

Good question. The answer seems non-obvious enough that making the
argument required might be better?

/ Jonas

[Mounir Lamouri]

I agree. Making the argument required seems to be the best approach. We
could later make it optional if we happen to find a good default value
trough feedback.

--
Mounir

[Gene Lian]

> Instead the alarm API backend implementation should listen for
> timezone changes and when they occur, reschedule all alarms registered
> with "ignoreTimezone". That way it will "just work".

Jonas,

You're right we should watch the timezone change in the backend, which seems to be more reasonable. I found the bug 714358 (https://bugzilla.mozilla.org/show_bug.cgi?id=714358) exactly supports what we want and seems to be available soon.

Gene

[Gene Lian]

Mounir Lamouri於 2012年6月6日星期三UTC+8上午12時50分15秒寫道：

Sounds good! I'll include this change in the next patch. The final interface would be like the following one. Note that eventually I don't let remove() have a DOMRequest return since it doesn't need to return anything at all. Please let me know if we can do anything better.

interface AlarmsManager
{
DOMRequest getAll();
DOMRequest add(in jsval date, in DOMString respectTimezone, [optional] in jsval data);
void remove(in unsigned long id);
};


Another issue I'd like to address here is: after some experiments I found the Date object cannot really save the timezone when it was created. Instead, it ALWAYS returns the current system's timezone. For example,

date = new Date();

The above function will return "Wed Jun 06 2012 10:59:24 GMT+0800 (CST)"

date.getTimezoneOffset();

The above function will return -480 because of GMT+0800.

However, the weird thing is if I re-assign the date with another different timezone (ex, GMT+0600 (CST)):

date = new Date("Wed Jun 06 2012 10:59:24 GMT+0600 (CST)");

The above function will return "Wed Jun 06 2012 12:59:24 GMT+0800 (CST)", which would automatically be adjusted respect to the current system timezone!

date.getTimezoneOffset();

Again, this will return -480, which is not expected as -360.

If so, I think we need to save the timezone info apart from the Date object in the back-end when it was being added by add(), so that we can adjust the alarm UTC time (for "ignoreTimezone") by calculating the difference between the original timezone and the current system timezone.

Does it sound reasonable to you guys? Or I misunderstood the usage of Date object?

Thanks,
Gene

[Jonas Sicking]

On Tue, Jun 5, 2012 at 7:27 PM, Gene Lian <cl...@mozilla.com> wrote:
> Mounir Lamouri於 2012年6月6日星期三UTC+8上午12時50分15秒寫道：

> Sounds good! I'll include this change in the next patch. The final interface would be like the following one. Note that eventually I don't let remove() have a DOMRequest return since it doesn't need to return anything at all. Please let me know if we can do anything better.
>
> interface AlarmsManager
> {
> DOMRequest getAll();
> DOMRequest add(in jsval date, in DOMString respectTimezone, [optional] in jsval data);
> void remove(in unsigned long id);
> };
>
>
> Another issue I'd like to address here is: after some experiments I found the Date object cannot really save the timezone when it was created. Instead, it ALWAYS returns the current system's timezone. For example,
>
> date = new Date();
>
> The above function will return "Wed Jun 06 2012 10:59:24 GMT+0800 (CST)"
>
> date.getTimezoneOffset();
>
> The above function will return -480 because of GMT+0800.
>
> However, the weird thing is if I re-assign the date with another different timezone (ex, GMT+0600 (CST)):
>
> date = new Date("Wed Jun 06 2012 10:59:24 GMT+0600 (CST)");
>
> The above function will return "Wed Jun 06 2012 12:59:24 GMT+0800 (CST)", which would automatically be adjusted respect to the current system timezone!
>
> date.getTimezoneOffset();
>
> Again, this will return -480, which is not expected as -360.

Crap, I did not know this. That is indeed very annoying.

> If so, I think we need to save the timezone info apart from the Date object in the back-end when it was being added by add(), so that we can adjust the alarm UTC time (for "ignoreTimezone") by calculating the difference between the original timezone and the current system timezone.
>
> Does it sound reasonable to you guys?

Yes, that sounds correct.

/ Jonas

[Mounir Lamouri]

On 06/06/2012 09:01 AM, Jonas Sicking wrote:
> On Tue, Jun 5, 2012 at 7:27 PM, Gene Lian <cl...@mozilla.com> wrote:
>> Mounir Lamouri於 2012年6月6日星期三UTC+8上午12時50分15秒寫道：

>> Sounds good! I'll include this change in the next patch. The final interface would be like the following one. Note that eventually I don't let remove() have a DOMRequest return since it doesn't need to return anything at all. Please let me know if we can do anything better.
>>
>> interface AlarmsManager
>> {
>> DOMRequest getAll();
>> DOMRequest add(in jsval date, in DOMString respectTimezone, [optional] in jsval data);
>> void remove(in unsigned long id);
>> };
>>
>>
>> Another issue I'd like to address here is: after some experiments I found the Date object cannot really save the timezone when it was created. Instead, it ALWAYS returns the current system's timezone. For example,
>>
>> date = new Date();
>>
>> The above function will return "Wed Jun 06 2012 10:59:24 GMT+0800 (CST)"
>>
>> date.getTimezoneOffset();
>>
>> The above function will return -480 because of GMT+0800.
>>
>> However, the weird thing is if I re-assign the date with another different timezone (ex, GMT+0600 (CST)):
>>
>> date = new Date("Wed Jun 06 2012 10:59:24 GMT+0600 (CST)");
>>
>> The above function will return "Wed Jun 06 2012 12:59:24 GMT+0800 (CST)", which would automatically be adjusted respect to the current system timezone!
>>
>> date.getTimezoneOffset();
>>
>> Again, this will return -480, which is not expected as -360.
>
> Crap, I did not know this. That is indeed very annoying.

I wonder why it is not allowed to set a Date object TZ. It seems that
might be a nice addition for various APIs. Can't we request that change
to ECMAScript?

>> If so, I think we need to save the timezone info apart from the Date object in the back-end when it was being added by add(), so that we can adjust the alarm UTC time (for "ignoreTimezone") by calculating the difference between the original timezone and the current system timezone.
>>
>> Does it sound reasonable to you guys?
>
> Yes, that sounds correct.

How would you pass the timezone information? Would you pass a string
that defines the timezone or an integer that defines the difference from
UTC? I think a string would be more appropriate but it's quite harder to
handle because the backend has to make sure the value is correct and
needs to handle UTC offset changes for the same string (that's why
passing an UTC offset isn't a good solution).
If we pass a timezone information, we could consider |null| as "no
timezone specified" thus removing the "ignoreTimezon" string. Though,
that would force callers to get the current timezone information from
somewhere and you can't get that from the Date object for understandable
fingerprinting reasons (I guess).

--
Mounir

[Jonas Sicking]

On Wed, Jun 6, 2012 at 4:55 AM, Mounir Lamouri <mou...@lamouri.fr> wrote:
> On 06/06/2012 09:01 AM, Jonas Sicking wrote:
>> On Tue, Jun 5, 2012 at 7:27 PM, Gene Lian <cl...@mozilla.com> wrote:
>>> Mounir Lamouri於 2012年6月6日星期三UTC+8上午12時50分15秒寫道：

>>> Sounds good! I'll include this change in the next patch. The final interface would be like the following one. Note that eventually I don't let remove() have a DOMRequest return since it doesn't need to return anything at all. Please let me know if we can do anything better.
>>>
>>> interface AlarmsManager
>>> {
>>> DOMRequest getAll();
>>> DOMRequest add(in jsval date, in DOMString respectTimezone, [optional] in jsval data);
>>> void remove(in unsigned long id);
>>> };
>>>
>>>
>>> Another issue I'd like to address here is: after some experiments I found the Date object cannot really save the timezone when it was created. Instead, it ALWAYS returns the current system's timezone. For example,
>>>
>>> date = new Date();
>>>
>>> The above function will return "Wed Jun 06 2012 10:59:24 GMT+0800 (CST)"
>>>
>>> date.getTimezoneOffset();
>>>
>>> The above function will return -480 because of GMT+0800.
>>>
>>> However, the weird thing is if I re-assign the date with another different timezone (ex, GMT+0600 (CST)):
>>>
>>> date = new Date("Wed Jun 06 2012 10:59:24 GMT+0600 (CST)");
>>>
>>> The above function will return "Wed Jun 06 2012 12:59:24 GMT+0800 (CST)", which would automatically be adjusted respect to the current system timezone!
>>>
>>> date.getTimezoneOffset();
>>>
>>> Again, this will return -480, which is not expected as -360.
>>
>> Crap, I did not know this. That is indeed very annoying.
>
> I wonder why it is not allowed to set a Date object TZ. It seems that
> might be a nice addition for various APIs. Can't we request that change
> to ECMAScript?

We sure can, but the ECMAScript committee runs slowly. If this doesn't
make ES6 (which there's a high risk it wouldn't) it'll be years until
it's in the spec.

>>> If so, I think we need to save the timezone info apart from the Date object in the back-end when it was being added by add(), so that we can adjust the alarm UTC time (for "ignoreTimezone") by calculating the difference between the original timezone and the current system timezone.
>>>
>>> Does it sound reasonable to you guys?
>>
>> Yes, that sounds correct.
>
> How would you pass the timezone information? Would you pass a string
> that defines the timezone or an integer that defines the difference from
> UTC? I think a string would be more appropriate but it's quite harder to
> handle because the backend has to make sure the value is correct and
> needs to handle UTC offset changes for the same string (that's why
> passing an UTC offset isn't a good solution).
> If we pass a timezone information, we could consider |null| as "no
> timezone specified" thus removing the "ignoreTimezon" string. Though,
> that would force callers to get the current timezone information from
> somewhere and you can't get that from the Date object for understandable
> fingerprinting reasons (I guess).

Why do you need to pass a timezone? For "honorTimezone" alarms it
doesn't matter what the timezone is, all that matters is the UTC time.
For "ignoreTimezone" alarms it'll be trickier indeed since you have to
make sure that the passed in time is the right time in the current
timezone. But that's what you'll get by default anyway.

/ Jonas

[Gene Lian]

> Why do you need to pass a timezone? For "honorTimezone" alarms it
> doesn't matter what the timezone is, all that matters is the UTC time.
> For "ignoreTimezone" alarms it'll be trickier indeed since you have to
> make sure that the passed in time is the right time in the current
> timezone. But that's what you'll get by default anyway.
>
> / Jonas

Jonas and Mounir,

What I'm actually doing now is just like Jonas' comments. We don't need to care about the timezone effect for "honorTimezone" alarms since they will be added as UTC time in anyway.

Regarding the "ignoreTimezone" alarms, we must additionally save their timezone (= the system timezone when they were being added); otherwise, their original timezone info will be disappeared because of the annoying Date object effect. The following pseudo codes shows how we can adjust the alarm UTC time for the "ignoreTimezone" alarms:

alarmUTCTime += (currentSystemTimezoneOffset - alarmOriginalTimezoneOffset) * 60000;

Another similar concern is I think the back-end also needs to return the original timezone info when the Apps calls getAll(), so that they can know a way to restore the correct alarm time for displaying purpose. Right? For example,

[{ id: 1, date: <dateObject>, ignoreTimezone: true, timezoneOffset: -480, data: ... },
{ id: 2, date: <dateObject>, ignoreTimezone: false, timezoneOffset: -480, data: ... }]

Note that the number -480 here is following the same type returned by the Date object's getTimezoneOffset() (i.e. by minutes). Does that sound reasonable to you guys?

Thanks,
Gene

[Mounir Lamouri]

On 06/07/2012 04:50 AM, Gene Lian wrote:
>> Why do you need to pass a timezone? For "honorTimezone" alarms it
>> doesn't matter what the timezone is, all that matters is the UTC time.
>> For "ignoreTimezone" alarms it'll be trickier indeed since you have to
>> make sure that the passed in time is the right time in the current
>> timezone. But that's what you'll get by default anyway.
>>
>> / Jonas
>

> Jonas and Mounir,
>
> What I'm actually doing now is just like Jonas' comments. We don't need to care about the timezone effect for "honorTimezone" alarms since they will be added as UTC time in anyway.

I don't think it is as easy as that in all situations.

> Regarding the "ignoreTimezone" alarms, we must additionally save their timezone (= the system timezone when they were being added); otherwise, their original timezone info will be disappeared because of the annoying Date object effect. The following pseudo codes shows how we can adjust the alarm UTC time for the "ignoreTimezone" alarms:
>
> alarmUTCTime += (currentSystemTimezoneOffset - alarmOriginalTimezoneOffset) * 60000;
>
> Another similar concern is I think the back-end also needs to return the original timezone info when the Apps calls getAll(), so that they can know a way to restore the correct alarm time for displaying purpose. Right? For example,
>
> [{ id: 1, date: <dateObject>, ignoreTimezone: true, timezoneOffset: -480, data: ... },
> { id: 2, date: <dateObject>, ignoreTimezone: false, timezoneOffset: -480, data: ... }]
>

> Note that the number -480 here is following the same type returned by the Date object's getTimezoneOffset() (i.e. by minutes). Does that sound reasonable to you guys?

My concerns was exactly with using |getTimezoneOffset()|. If you do so,
how do you handle situations where I put an alarm for 15:00 CEST in a
specific day but it happens that in the mean time, my country moves to
CET. The alarm would have been saved as 13:00 UTC with an offset of 120.
So it will fire at 13:00 UTC which will be 14:00 CET. However, saving
the alarm at 15:00 CEST or 15:00 CET should make no difference for the user.

One problem I see is that the Date object doesn't seem to carry the TZ
information, only the offset and this is the least interesting
information. The solution would be to make sure the Date object and the
system timezone are in sync. In that case, we could just get the date
from the object and the timezone information from the system. However,
it feels to me that this would weaken the API.
FWIW, I guess we might need to fix bug 285615 for the implementation.

--
Mounir

[Jonas Sicking]

On Fri, Jun 8, 2012 at 3:35 AM, Mounir Lamouri <mou...@lamouri.fr> wrote:
> On 06/07/2012 04:50 AM, Gene Lian wrote:

>>> Why do you need to pass a timezone? For "honorTimezone" alarms it
>>> doesn't matter what the timezone is, all that matters is the UTC time.
>>> For "ignoreTimezone" alarms it'll be trickier indeed since you have to
>>> make sure that the passed in time is the right time in the current
>>> timezone. But that's what you'll get by default anyway.
>>>
>>> / Jonas
>>

>> Jonas and Mounir,
>>
>> What I'm actually doing now is just like Jonas' comments. We don't need to care about the timezone effect for "honorTimezone" alarms since they will be added as UTC time in anyway.
>
> I don't think it is as easy as that in all situations.
>
>> Regarding the "ignoreTimezone" alarms, we must additionally save their timezone (= the system timezone when they were being added); otherwise, their original timezone info will be disappeared because of the annoying Date object effect. The following pseudo codes shows how we can adjust the alarm UTC time for the "ignoreTimezone" alarms:
>>
>> alarmUTCTime += (currentSystemTimezoneOffset - alarmOriginalTimezoneOffset) * 60000;
>>
>> Another similar concern is I think the back-end also needs to return the original timezone info when the Apps calls getAll(), so that they can know a way to restore the correct alarm time for displaying purpose. Right? For example,
>>
>> [{ id: 1, date: <dateObject>, ignoreTimezone: true, timezoneOffset: -480, data: ... },
>>  { id: 2, date: <dateObject>, ignoreTimezone: false, timezoneOffset: -480, data: ... }]
>>
>> Note that the number -480 here is following the same type returned by the Date object's getTimezoneOffset() (i.e. by minutes). Does that sound reasonable to you guys?
>
> My concerns was exactly with using |getTimezoneOffset()|. If you do so,
> how do you handle situations where I put an alarm for 15:00 CEST in a
> specific day but it happens that in the mean time, my country moves to
> CET. The alarm would have been saved as 13:00 UTC with an offset of 120.
> So it will fire at 13:00 UTC which will be 14:00 CET. However, saving
> the alarm at 15:00 CEST or 15:00 CET should make no difference for the user.
>
> One problem I see is that the Date object doesn't seem to carry the TZ
> information, only the offset and this is the least interesting
> information. The solution would be to make sure the Date object and the
> system timezone are in sync. In that case, we could just get the date
> from the object and the timezone information from the system. However,
> it feels to me that this would weaken the API.
> FWIW, I guess we might need to fix bug 285615 for the implementation.

I don't understand the concerns here.

There are two types of alarms. "honorTimezone" and "ignoreTimezone".

For "honorTimezone" alarms, we need to save the the time expressed in
UTC time. It doesn't really matter what timezone the date was
originally expressed in, or if we store that information, the alarm
represents a very specific point in time when the alarm should fire,
no matter which timezone you use to express that point in time. These
alarms are also easy to schedule using the propose Alarm API since
when creating the Date object it doesn't matter which timezone you
express it in as the point in time is what matters, not any particular
timezone.

For "ignoreTimezone" alarms, we need to save a time+date. I.e.
something like "17:03 May 1st 2013". This is the important
information. We don't really need to save a timezone since we want to
fire the alarm when the time is the specified time+date in whatever
timezone the user happens to be in. Any time the user changes
timezone, the alarm API implementation need to schedule callbacks with
the internal hardware for the specified time+date in the timezone that
the user is now in.

These alarms are trickier to schedule using the proposed alarm API
since a Date object expresses a time+date+timezone, which means that
we have to drop the timezone information in a safe way somehow. The
easiest way to do this is to simply convert the Date to the local
timezone and then drop the timezone part. The reason this works fairly
well is that the Date API in javascript always converts Date objects
to the local timezone. So all methods for reading/writing the various
components of the Date (including when creating a Date using a string
containing just a time+date) operate in the local timezone. That means
that if a page does operations which doesn't specify timezones at all
things will "just work" as long as we interpret that Date in the local
timezone when the alarm is scheduled using the .add function.

/ Jonas

[Tim Guan-tin Chien]

Hi Jonas,

From your post, I guess *internally* the Date object does save data in
time+date+timezone (I never know that coz it's not expose to
Javascript!). In Javascript, there are no way to specify the timezone,
nor the timezone offset of a Date object. It would cause some problems
for us:

1) There will be exceptions. Daylight changes and time zone changes will
eat a specific calendar moment, for example, if one stay in US, 2 :10 am
March 10, 2013 local time exist because at 1:59:59 the clocks will jump
to 3am for the next second. How would a Alarm set at the specific time
work? Also, how would the alarm work on the date DL time ends?

2) I will not be able to schedule an alarm for an event on another
timezone -- Say I want to be notified for Gaia meeting at 9am Tuesday
Pacific time. I can only create a Date object that points to 12am
Wednesday Taipei Time and have Alarm API to strip the timezone part, but
the calculation would fail on Nov 4 when the DST ends -- I will be
notified on 8am PST.

3) It would be problematic for Javascript to specify a datetime w/o
putting an assumption of the timezone. A date object created by |new
Date(timestamp)| will be assumed by Alarm API that the datetime
specified by the timestamp is relative to the current system timezone
offset, not, and cannot be, anything else. For this reason, we probably
need to put a note on spec that we advice passing a |new Date(year,
month, day [, hour, minute, second, millisecond ])| date object into
"ignoreTimezone" Alarms, and a |new Date(timestamp)| is ambiguous due to
above reason.

I do think allowing Alarm API to handle timezone is essential for
applications, but I do think it's chaotic when we are using Date object
to pass the information. We are essentially creating an Alarm API that
will fire NOT on the Unix time specified by the Date object!

For now, I could live with (3) (with the note), and not to worry about
(2) which is considered an extreme case. But for a more robust API this
should be revised.

--
Tim Guan-tin Chien, Front-end Dev, Mozilla Corp. (Taipei)

[Jonas Sicking]

On Sun, Jun 10, 2012 at 12:00 PM, Tim Guan-tin Chien
<timd...@mozilla.com> wrote:
> Hi Jonas,
>
> From your post, I guess *internally* the Date object does save data in
> time+date+timezone (I never know that coz it's not expose to Javascript!).
> In Javascript, there are no way to specify the timezone, nor the timezone
> offset of a Date object. It would cause some problems for us:

I actually don't think the Date object keeps a timezone internally.
Instead it just stores the time in UTC, but maps that time to the
local timezone for the purposes of all API calls. But whether it
stores the timezone internally or not I guess is largely academic
since there's no way to get to it, neither from javascript or from
JSAPI :-)

> 1) There will be exceptions. Daylight changes and time zone changes will eat
> a specific calendar moment, for example, if one stay in US, 2 :10 am March
> 10, 2013 local time exist because at 1:59:59 the clocks will jump to 3am for
> the next second. How would a Alarm set at the specific time work? Also, how
> would the alarm work on the date DL time ends?

This is a problem no matter if we use Date objects or something else
to define an alarm, no? I.e. say that we used strings for the two
parts "time", "date", if someone scheduled an alarm for "2:10am" on
"10-March-2013" we will have the exact same problem as far as I can
tell.

The way I think we should deal with this problem is that we should
fire the alarm any time we detect that the local time is past the
scheduled time. So once the clock hits 3am on March 10th 2013, we
detect that this is past 2:10am and fire the alarm.

We need to do this anyway in order to handle situations when the phone
is off when the alarm is supposed to fire. In that situation we should
fire the alarm as soon as the phone is turned on. Note that this
doesn't mean that the Alarm App will play the "wake-up" sound as soon
as you turn on the phone. It just means that we'll notify the Alarm
App and then it's up to it to take appropriate action.

> 2) I will not be able to schedule an alarm for an event on another timezone
> -- Say I want to be notified for Gaia meeting at 9am Tuesday Pacific time. I
> can only create a Date object that points to 12am Wednesday Taipei Time and
> have Alarm API to strip the timezone part, but the calculation would fail on
> Nov 4 when the DST ends -- I will be notified on 8am PST.

This isn't correct. While the Date object doesn't store a specific
timezone internally, you can still create a Date object using any
timezone.

If you want to schedule an alarm for a 9am Tuesday June 12th Pacific
Time, all you need to do is something like:

navigator.alarms.add(new Date("June 12, 2012 09:00:00 GMT-0800"),
"honorTimezone");

> 3) It would be problematic for Javascript to specify a datetime w/o putting
> an assumption of the timezone. A date object created by |new
> Date(timestamp)| will be assumed by Alarm API that the datetime specified by
> the timestamp is relative to the current system timezone offset, not, and
> cannot be, anything else. For this reason, we probably need to put a note on
> spec that we advice passing a |new Date(year, month, day [, hour, minute,
> second, millisecond ])| date object into "ignoreTimezone" Alarms, and a |new
> Date(timestamp)| is ambiguous due to above reason.

See above, this isn't correct if you simply pass in an explicit
timezone when calling |new Date(...)|.

I definitely agree that the Date object has a lot of shortcomings when
it comes to timezones. However this appears to have been a shortcoming
that the web has learned to live with. I'd love to add more explicit
functions to manage timezones on Date objects, but I don't think we
need to block on that. And I suspect there are JS libraries out there
that can help bridge the gap.

/ Jonas

[Tim Guan-tin Chien]

Jonas,

My specific point on the previous post was that for the "ignoreTimezone"
alarms, we are essentially creating an Alarm API that will fire NOT on
the Unix time specified by the Date object.

Wrapping a date time string into Date or pass the string itself *is*
different -- although you cannot compare it with ==, for all intent and
purposes,

new Date("June 12, 2012 09:00:00 GMT-0800") [1]

is the same as

new Date('Wed Jun 13 2012 01:00:00 GMT+0800') [2]

because they have the same Unix timestamp (1339520400000) in the space-time continuum. So, for Alarm API to work correctly and "strip" the "timezone part" of the date object, on my computer, which sets +0800 as the timezone, it would have to always make the assumption that the date object was created with [2] but not [1], in order to extract "Wed Jun 13 2012 01:00:00" and not "June 12, 2012 09:00:00" so the alarm won't fire 16hr earlier than it was intended to.

Thanks for the explanation, I understand why it is designed this way now, just that such assumption works but not pretty.

[Gene Lian]

On Friday, June 8, 2012 6:35:56 PM UTC+8, Mounir Lamouri wrote:
> My concerns was exactly with using |getTimezoneOffset()|. If you do so,
> how do you handle situations where I put an alarm for 15:00 CEST in a
> specific day but it happens that in the mean time, my country moves to
> CET. The alarm would have been saved as 13:00 UTC with an offset of 120.
> So it will fire at 13:00 UTC which will be 14:00 CET. However, saving
> the alarm at 15:00 CEST or 15:00 CET should make no difference for the user.

Mounir,

That's why we must save its original timezone offset when the alarm has been added, which will be used to adjust the alarm time when the user is relocated at a different timezone.

Let me keep tacking your example here :) If you add a 15:00 CEST alarm (UTC time = 13:00 and timezoneOffest = -120). When you move to CET (timezoneOffest = -60), the back-end logic can adjust the alarm time based on the formulation I posted before:

adjuestedAlarmTime += (currentSystemTimezoneOffset - alarmOriginalTimezoneOffset) * 60000;

Since the original CEST timezone offset (-120) has been saved, when moving to CET (-60), the new alarm time can be adjusted to be:

adjustedAlarmTime += (-60 - (-120)) * 60000;

You can see here~ the alarm will go off "lately" because of a plus! :) This is expected as what we want because the adjusted alarm time is equivalent to "setting an alarm at 15:00 at CET", which is one-hour later in a real world to "setting an alarm at 15:00 at CEST". Therefore, we can achieve the "ignoreTimezone" feature.

Does this sound reasonable to you?

> One problem I see is that the Date object doesn't seem to carry the TZ
> information, only the offset and this is the least interesting
> information. The solution would be to make sure the Date object and the
> system timezone are in sync. In that case, we could just get the date
> from the object and the timezone information from the system. However,
> it feels to me that this would weaken the API.
> FWIW, I guess we might need to fix bug 285615 for the implementation.

Thanks for the info ;) This is kind of bad if we cannot use getTimezoneOffset() to get the correct timezone at any time, because I planed to use it to get the current system timezone information when the timezone is changed. Not sure if we can have other similar alternatives to do this. Note that I'll also rely on the timezone-changed observer done by Steve at bug 714358.

Thanks,
Gene

[Gene Lian]

On Saturday, June 9, 2012 2:29:26 AM UTC+8, Jonas Sicking wrote:
> For "ignoreTimezone" alarms, we need to save a time+date. I.e.
> something like "17:03 May 1st 2013". This is the important
> information. We don't really need to save a timezone since we want to
> fire the alarm when the time is the specified time+date in whatever
> timezone the user happens to be in. Any time the user changes
> timezone, the alarm API implementation need to schedule callbacks with
> the internal hardware for the specified time+date in the timezone that
> the user is now in.

Jonas,

Regarding the "ignoreTimezone", I'd prefer saving the Date object with an additional timezone offset in the back-end, instead of only the "date+time" literal string, because:

1. Parsing the "date+time" part could be difficult since the Date API can allow lots of different "date+time+timezone" expressions.

2. We can return the original timezone offset to app (when calling .getAll()) if the app needs to know this info as well.

3. Using an existing architecture like Date would be more convenient in the back-end, since we can therefore have more Date APIs to use, like date.getTime().

4. We can easily use the original timezone and the current system timezone to calculate the adjusted alarm time, where you can find a formulation/example in my previous response to Mounir. If we simply save "date+time" string, we need to combine the "date+time" and the "timezone" strings first and then convert it to a Date object again (why not just saving it as a Date object in the first place?).

Not sure if you can catch my point :) The date/timezone calculation and cases could be hard to explain clearly. Please let me know if you have any other suggestions or questions.

Thanks,
Gene

[Mounir Lamouri]

On 06/11/2012 05:53 AM, Gene Lian wrote:
> On Friday, June 8, 2012 6:35:56 PM UTC+8, Mounir Lamouri wrote:

>> My concerns was exactly with using |getTimezoneOffset()|. If you do so,
>> how do you handle situations where I put an alarm for 15:00 CEST in a
>> specific day but it happens that in the mean time, my country moves to
>> CET. The alarm would have been saved as 13:00 UTC with an offset of 120.
>> So it will fire at 13:00 UTC which will be 14:00 CET. However, saving
>> the alarm at 15:00 CEST or 15:00 CET should make no difference for the user.
>

> Mounir,
>
> That's why we must save its original timezone offset when the alarm has been added, which will be used to adjust the alarm time when the user is relocated at a different timezone.
>
> Let me keep tacking your example here :) If you add a 15:00 CEST alarm (UTC time = 13:00 and timezoneOffest = -120). When you move to CET (timezoneOffest = -60), the back-end logic can adjust the alarm time based on the formulation I posted before:
>
> adjuestedAlarmTime += (currentSystemTimezoneOffset - alarmOriginalTimezoneOffset) * 60000;
>
> Since the original CEST timezone offset (-120) has been saved, when moving to CET (-60), the new alarm time can be adjusted to be:
>
> adjustedAlarmTime += (-60 - (-120)) * 60000;
>
> You can see here~ the alarm will go off "lately" because of a plus! :) This is expected as what we want because the adjusted alarm time is equivalent to "setting an alarm at 15:00 at CET", which is one-hour later in a real world to "setting an alarm at 15:00 at CEST". Therefore, we can achieve the "ignoreTimezone" feature.
>
> Does this sound reasonable to you?

Yes. But my concern wasn't about "ignoreTimezone" but "honorTimezone".
More details in my coming reply to Jonas.

Cheers,
--
Mounir

[Mounir Lamouri]

On 06/08/2012 08:29 PM, Jonas Sicking wrote:

> On Fri, Jun 8, 2012 at 3:35 AM, Mounir Lamouri <mou...@lamouri.fr> wrote:
>> My concerns was exactly with using |getTimezoneOffset()|. If you do so,
>> how do you handle situations where I put an alarm for 15:00 CEST in a
>> specific day but it happens that in the mean time, my country moves to
>> CET. The alarm would have been saved as 13:00 UTC with an offset of 120.
>> So it will fire at 13:00 UTC which will be 14:00 CET. However, saving
>> the alarm at 15:00 CEST or 15:00 CET should make no difference for the user.
>>

>> One problem I see is that the Date object doesn't seem to carry the TZ
>> information, only the offset and this is the least interesting
>> information. The solution would be to make sure the Date object and the
>> system timezone are in sync. In that case, we could just get the date
>> from the object and the timezone information from the system. However,
>> it feels to me that this would weaken the API.
>> FWIW, I guess we might need to fix bug 285615 for the implementation.
>

> I don't understand the concerns here.
>
> There are two types of alarms. "honorTimezone" and "ignoreTimezone".
>
> For "honorTimezone" alarms, we need to save the the time expressed in
> UTC time. It doesn't really matter what timezone the date was
> originally expressed in, or if we store that information, the alarm
> represents a very specific point in time when the alarm should fire,
> no matter which timezone you use to express that point in time. These
> alarms are also easy to schedule using the propose Alarm API since
> when creating the Date object it doesn't matter which timezone you
> express it in as the point in time is what matters, not any particular
> timezone.

Saving the timezone in UTC isn't enough when you want to honor timezone
because you will not take into account daylight saving changes.

One example to illustrate that:
The user takes an appointment with his dentist. The appointment is taken
in August for 14:00 21st of November. The user is currently in CEST so
14:00 means 12:00 UTC but the 21st of November will actually be in CET
so 12:00 UTC will be 13:00 in local time. The user will arrive 1 hour
earlier to his appointment.

We can solve that without touching the API but we would need to know in
which timezone as in "Europe/Paris", "US/Pacific" the user currently is
so when setting an alarm, we would know if daylight saving apply or not
at the given time. IOW, we can't simply use the current UTC offset, we
need to know the UTC offset of the date.

Hope I am more clear now.

Cheers,
--
Mounir

[Justin Lebar]

> We can solve that without touching the API but we would need to know in
> which timezone as in "Europe/Paris", "US/Pacific" the user currently is
> so when setting an alarm, we would know if daylight saving apply or not
> at the given time. IOW, we can't simply use the current UTC offset, we
> need to know the UTC offset of the date.

Actually, you can't really do that, either.

DST policies change over time. If the US decided to change the DST
date (again), we could push an update, but we'd be unable to tell
update your alarm times, if all we had was a UTC time.

[Mounir Lamouri]

Indeed. The implementation could save the timezone and update the alarm
time if DST policies change.

--
Mounir

[Gene Lian]

On Wednesday, June 20, 2012 10:42:57 PM UTC+8, Mounir Lamouri wrote:
> Saving the timezone in UTC isn't enough when you want to honor timezone
> because you will not take into account daylight saving changes.
>
> One example to illustrate that:
> The user takes an appointment with his dentist. The appointment is taken
> in August for 14:00 21st of November. The user is currently in CEST so
> 14:00 means 12:00 UTC but the 21st of November will actually be in CET
> so 12:00 UTC will be 13:00 in local time. The user will arrive 1 hour
> earlier to his appointment.

Ah! Good point! This is indeed a possible case. However, to handle that, I think the clients are still able to specify a given timezone when adding alarm. Taking your example here, the callers can do:

navigator.mozAlarms.add(new Date("November 21, 2012 14:00:00 CET"), "honorTimezone");

If the user doesn't want to specify the timezone, the Alarm API will consider it respecting to the current system timezone. For example, the following statement can make the wrong alarm as you mentioned, because it is treated as CEST where the user is currently located.

navigator.mozAlarms.add(new Date("November 21, 2012 14:00:00"), "honorTimezone");

Anyway, users can still use "ignoreTimezone" to avoid this above-mentioned error, if they don't know the expected timezone on November 21 or cannot predict the government's DST policy in the future.

navigator.mozAlarms.add(new Date("November 21, 2012 14:00:00"), "ignoreTimezone");

Does the above-mentioned sound a reasonable solution to you guys?

Thanks,
Gene

[Justin Lebar]

> One example to illustrate that:
> The user takes an appointment with his dentist. The appointment is taken
> in August for 14:00 21st of November. The user is currently in CEST so
> 14:00 means 12:00 UTC but the 21st of November will actually be in CET
> so 12:00 UTC will be 13:00 in local time. The user will arrive 1 hour
> earlier to his appointment.

and

> Anyway, users can still use "ignoreTimezone" to avoid this above-mentioned error, if they don't know the expected timezone on November 21 or cannot predict the government's DST policy in the future.

The time zone does not change when DST happens.

The caller definitely should not have to predict when DST is going to
happen. That adds a huge amount of complexity to the caller that they
should not have to deal with.

Note that "ignoreTimezone" is not a sufficient work-around for this
issue, because "ignoreTimezone" means "use whatever time zone I happen
to be in at the moment", which is not the same as "use whatever DST
settings Eastern Time happens to have at the moment."

On Thu, Jun 21, 2012 at 4:26 AM, Gene Lian <cl...@mozilla.com> wrote:
> On Wednesday, June 20, 2012 10:42:57 PM UTC+8, Mounir Lamouri wrote:

>> Saving the timezone in UTC isn't enough when you want to honor timezone
>> because you will not take into account daylight saving changes.
>>
>> One example to illustrate that:
>> The user takes an appointment with his dentist. The appointment is taken
>> in August for 14:00 21st of November. The user is currently in CEST so
>> 14:00 means 12:00 UTC but the 21st of November will actually be in CET
>> so 12:00 UTC will be 13:00 in local time. The user will arrive 1 hour
>> earlier to his appointment.
>

> Ah! Good point! This is indeed a possible case. However, to handle that, I think the clients are still able to specify a given timezone when adding alarm. Taking your example here, the callers can do:
>
> navigator.mozAlarms.add(new Date("November 21, 2012 14:00:00 CET"), "honorTimezone");
>
> If the user doesn't want to specify the timezone, the Alarm API will consider it respecting to the current system timezone. For example, the following statement can make the wrong alarm as you mentioned, because it is treated as CEST where the user is currently located.
>
> navigator.mozAlarms.add(new Date("November 21, 2012 14:00:00"), "honorTimezone");
>
> Anyway, users can still use "ignoreTimezone" to avoid this above-mentioned error, if they don't know the expected timezone on November 21 or cannot predict the government's DST policy in the future.
>
> navigator.mozAlarms.add(new Date("November 21, 2012 14:00:00"), "ignoreTimezone");
>
> Does the above-mentioned sound a reasonable solution to you guys?
>
> Thanks,
> Gene

> _______________________________________________
> dev-webapi mailing list
> dev-w...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-webapi

[Gervase Markham]

On 21/06/12 09:26, Gene Lian wrote:
> navigator.mozAlarms.add(new Date("November 21, 2012 14:00:00 CET"),
> "honorTimezone");

You should definitely not create an API where timezone information is
passed as a 3-letter string (e.g. CET). Such strings are not unique. The
only unique string-based timezone identifiers are those from the Olson
database.

APIs and functions involving time are tricky. Why are we attempting to
design one from scratch? Are there not existing popular APIs we could
copy and adapt? They would, no doubt, have thought of all these things.

Gerv

[Gene Lian]

On Friday, June 22, 2012 6:02:56 PM UTC+8, Gervase Markham wrote:
> On 21/06/12 09:26, Gene Lian wrote:
> > navigator.mozAlarms.add(new Date("November 21, 2012 14:00:00 CET"),
> > "honorTimezone");
>
> You should definitely not create an API where timezone information is
> passed as a 3-letter string (e.g. CET). Such strings are not unique. The
> only unique string-based timezone identifiers are those from the Olson
> database.

Gerv,

I didn't create a new API :) Note that I'm using the existing JS Date object to set the alarm time, which is very powerful for parsing the various time strings, including the timezone information.

[Gene Lian]

On Thursday, June 21, 2012 11:22:18 PM UTC+8, Justin Lebar wrote:
> > Anyway, users can still use "ignoreTimezone" to avoid this above-mentioned error, if they don't know the expected timezone on November 21 or cannot predict the government's DST policy in the future.
>
> The time zone does not change when DST happens.
>
> The caller definitely should not have to predict when DST is going to
> happen. That adds a huge amount of complexity to the caller that they
> should not have to deal with.
>
> Note that "ignoreTimezone" is not a sufficient work-around for this
> issue, because "ignoreTimezone" means "use whatever time zone I happen
> to be in at the moment", which is not the same as "use whatever DST
> settings Eastern Time happens to have at the moment."

Justin,

Got it! I'll try to put this logic in the back-end implementation. This is indeed a very tricky case when users are located at a location that can have different timezones because of the DST effect. I believe there must be some existing functions in NSPR supporting us to do the calculations.

Thanks for your suggestions :)
Gene

[Gene Lian]

On Wednesday, June 20, 2012 10:42:57 PM UTC+8, Mounir Lamouri wrote:

> Saving the timezone in UTC isn't enough when you want to honor timezone
> because you will not take into account daylight saving changes.

After some discussions and tests with Jonas and Mounir, we eventually concluded the Date object can automatically take the DST effect into account when calculating UTC time, so don't need to worry about this case!

Gene

[Gene Lian]

Hi Jonas, Mounir and Vivien,

After the recent integration work with Gaia member (Ian), some interesting API behavior issues are collected and need to be further confirmed:

1. Can the .getAll() return the alarms that are not added by this app? For example, if the Alarm-Clock app calls the .getAll(), will the alarms added by Calendar app return as well? Or just only the ones added by Alarm-Clock?

2. Similarly, how about .remove()? Can an app delete the alarms added by other apps?

3. Supposing an alarm is set at 8:00am, but the device shuts down from 7:00am to 9:00am. Should the Alarm API fire a system message for that when the device powers up next time? Or just skip it?

4. Does the .getAll() need to return the alarms that have already been fired? Or the back-end should keep them before the .remove() is explicitly called to delete them?

Some API behaviors are ambiguous to be defined because they could be reasonably handled either on the Gecko or Gaia sides. Need your suggestions when you're available. :)

Thanks,
Gene

[Vivien]

I let Jonas and Mounir answers APIs questions but IMHO:
1. I think this question should be answered by keeping in mind the
fact that you don't want the calendar app to be opened by a an alarm set
by the clock app. System messages have the mechanism for it. I tend to
think that the Alarm API should take that into account too.

2. This question would be obvious once 1. is answered.

3. I really don't know. I can imagine some cases where I still want my
calendar app to pops up for the meeting I have missed. I would say this
belongs to Gaia to decide for the moment.

4. If the alarm won't be fired anymore it should be removed by the backend.

As I said above this is just my 2 cents. Jonas/Mounir may have a very
different opinion :)

Regards,
Vivien.

[Jonas Sicking]

Sorry, replied to the wrong address.

---------- Forwarded message ----------
From: Jonas Sicking <jo...@sicking.cc>
Date: Tue, Jul 24, 2012 at 5:13 PM
Subject: Re: Alarm API proposals
To: Gene Lian <cl...@mozilla.com>
Cc: mozilla.d...@googlegroups.com, mounir....@mozilla.com,
timd...@mozilla.com, il...@mozilla.com, vnic...@mozilla.com

On Mon, Jul 23, 2012 at 3:23 AM, Gene Lian <cl...@mozilla.com> wrote:
> Hi Jonas, Mounir and Vivien,
>
> After the recent integration work with Gaia member (Ian), some interesting API behavior issues are collected and need to be further confirmed:
>
> 1. Can the .getAll() return the alarms that are not added by this app? For example, if the Alarm-Clock app calls the .getAll(), will the alarms added by Calendar app return as well? Or just only the ones added by Alarm-Clock?

No, .getAll only returns the alarms scheduled by the app.

> 2. Similarly, how about .remove()? Can an app delete the alarms added by other apps?

No. You can only interact with alarms scheduled by the same app.

> 3. Supposing an alarm is set at 8:00am, but the device shuts down from 7:00am to 9:00am. Should the Alarm API fire a system message for that when the device powers up next time? Or just skip it?

It should fire as soon as the device powers up.

> 4. Does the .getAll() need to return the alarms that have already been fired? Or the back-end should keep them before the .remove() is explicitly called to delete them?

Only alarms that have not fired should be returned.

> Some API behaviors are ambiguous to be defined because they could be reasonably handled either on the Gecko or Gaia sides. Need your suggestions when you're available. :)

Hope that answers your questions?

/ Jonas

[Gene Lian]

----- Original Message -----
> From: "Jonas Sicking" <jo...@sicking.cc>
> To: "dev-webapi" <dev-w...@lists.mozilla.org>
> Sent: Wednesday, July 25, 2012 8:14:49 AM
> Subject: Fwd: Alarm API proposals
>
> <skipped>

>
> Hope that answers your questions?

Thanks Jonas! Everything sounds clear and reasonable to me. I'll fire another bug to have these logics checked in and put some descriptions on the Wiki to clarify the API behaviors.

Gene

[Mounir Lamouri]

On 07/25/2012 02:14 AM, Jonas Sicking wrote:
> Sorry, replied to the wrong address.
>
> ---------- Forwarded message ----------
> From: Jonas Sicking <jo...@sicking.cc>
> Date: Tue, Jul 24, 2012 at 5:13 PM
> Subject: Re: Alarm API proposals
> To: Gene Lian <cl...@mozilla.com>
> Cc: mozilla.d...@googlegroups.com, mounir....@mozilla.com,
> timd...@mozilla.com, il...@mozilla.com, vnic...@mozilla.com
>
>
> On Mon, Jul 23, 2012 at 3:23 AM, Gene Lian <cl...@mozilla.com> wrote:
>> Hi Jonas, Mounir and Vivien,
>>
>> After the recent integration work with Gaia member (Ian), some interesting API behavior issues are collected and need to be further confirmed:
>>
>> 1. Can the .getAll() return the alarms that are not added by this app? For example, if the Alarm-Clock app calls the .getAll(), will the alarms added by Calendar app return as well? Or just only the ones added by Alarm-Clock?
>
> No, .getAll only returns the alarms scheduled by the app.
>
>> 2. Similarly, how about .remove()? Can an app delete the alarms added by other apps?
>
> No. You can only interact with alarms scheduled by the same app.

Points 1 and 2 are blockers. They are security/privacy issues if app can
read/write alarms from any other app.

>> 3. Supposing an alarm is set at 8:00am, but the device shuts down from 7:00am to 9:00am. Should the Alarm API fire a system message for that when the device powers up next time? Or just skip it?
>
> It should fire as soon as the device powers up.
>
>> 4. Does the .getAll() need to return the alarms that have already been fired? Or the back-end should keep them before the .remove() is explicitly called to delete them?
>
> Only alarms that have not fired should be returned.

Those two are bugs that we should fix.

--
Mounir

[Gene Lian]

I think we can simply compare if the manifestURL is matched or not to decide if .getAll()/.remove() can return/delete the alarms, since the manifestURL of an app has been saved to identify the app when adding alarms (for system message purpose).

>
> >> 3. Supposing an alarm is set at 8:00am, but the device shuts down
> >> from 7:00am to 9:00am. Should the Alarm API fire a system message
> >> for that when the device powers up next time? Or just skip it?
> >
> > It should fire as soon as the device powers up.
> >
> >> 4. Does the .getAll() need to return the alarms that have already
> >> been fired? Or the back-end should keep them before the .remove()
> >> is explicitly called to delete them?
> >
> > Only alarms that have not fired should be returned.
>
> Those two are bugs that we should fix.

Got it! All these changes should be easy. Just some fine-tunes of the logic. I'll come back with them ASAP.

>
> --
> Mounir

[Gene Lian]

Hi Jonas,

One more question (hoping it's the last tricky case ;P): what happened if the app attempts to add an alarm which has a past time?

1. The backend needs to return an error event through .add.onerror. That is, fail to add it.
2. Add the alarm and return a valid ID through .add.onsuccess. If so, should it be immediately fired with system message (since it has already been expired)?

Which one is the preferred behavior? Thanks for your confirmation in advance!

Gene