Time/Clock API

240 views
Skip to first unread message

Mounir Lamouri

unread,
Mar 30, 2012, 6:19:47 PM3/30/12
to dev-w...@lists.mozilla.org
Hi,

Following bug 714357 and bug 714358 discussions, I would like to propose
an API for Time/Clock (we should keep one word I guess).

There are six things we want to handle:
1. set time
2. get time
3. set timezone
4. get timezone
5. be informed when time is changed
6. be informed when timezone changes

1. Set time
We can have a navigator.time.set() method that will either take a double
that will be the number of milliseconds since epoch in the current
timezone or a Date object. The system time will then be replaced.

ISSUES:
I can think of two questions: should we take the epoch double in UTC
timezone (I guess not but better to ask) and how should we behave if the
Date object isn't in the same timezone the system currently is? Could
that actually happen unless the timezone has been changed in the
meantime? If not, we could just throw/ignore. Otherwise, we should
define a behavior.

2. Get time
Use Date.

3/4. Set/Get Timezone
We should use the Settings API to do that.

5. Time change
We should fire a change event to navigator.time.
That event should fire if the timezone has been changed or the time has
been changed manually. It should not be fired every ms ;)

6. Timezone change
The settings API should allow you to listen to changes.

The API would look like that:

interface TimeManager {
void set(Date time);
void set(double time);

attribute Function? onchange;
};

interface NavigatorTime {
readonly attribute TimeManager time;
};

interface Navigator implements NavigatorTime;

Any feedback?

Thanks,
--
Mounir

David Ascher

unread,
Mar 30, 2012, 6:26:52 PM3/30/12
to Mounir Lamouri, dev-w...@lists.mozilla.org
On Mar 30 '12 3:19 PM, Mounir Lamouri wrote:
> Hi,
>
> Following bug 714357 and bug 714358 discussions, I would like to propose
> an API for Time/Clock (we should keep one word I guess).
>
> Any feedback?
>

I recently ran into a weird problem w/ an iOS device with a dying
battery, and I learned that iOS doesn't have an NTP client and expects
to have the time drift corrected by syncing w/ iTunes. It made me wish
that iOS had a "set-time" API.

I doubt it's a P1, but figuring out who gets to set the time turned out
surprising.

--da

Mounir Lamouri

unread,
Mar 30, 2012, 6:46:24 PM3/30/12
to dev-w...@lists.mozilla.org
Luckily, iOS isn't a target. But in general, I believe we should return
undefined if TimeManager isn't implemented for the currenty system.
On Android we could implement that [1] (but that would require
permissions we are not going to ask) and we could easily implement that
for B2G too. I guess changing the system time and timezone would be
doable in major desktop OSes (Windows, MacOS and GNU/Linux) but I'm not
sure the change event would be easily implementable.

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

--
Mounir

Fabien Cazenave

unread,
Mar 31, 2012, 3:56:54 AM3/31/12
to Mounir Lamouri, dev-w...@lists.mozilla.org
Le 31/03/2012 00:19, Mounir Lamouri a écrit :
> Hi,
>
> Following bug 714357 and bug 714358 discussions, I would like to propose
> an API for Time/Clock (we should keep one word I guess).
>
> There are six things we want to handle:
> 1. set time
> 2. get time
> 3. set timezone
> 4. get timezone
> 5. be informed when time is changed
> 6. be informed when timezone changes
>

My 2¢: let’s call it “Clock API” and add an “alarm” object to it.

At the moment we don’t have any proper way (afaik) to set an alarm in
b2g/gaia… last time I checked we were using a setTimeout() for that.
I think it’d be nice to handle an array of alarms and attach callbacks
to each alarm.

:kazé

Fabien Cazenave

unread,
Mar 31, 2012, 3:56:54 AM3/31/12
to Mounir Lamouri, dev-w...@lists.mozilla.org
Le 31/03/2012 00:19, Mounir Lamouri a écrit :
> Hi,
>
> Following bug 714357 and bug 714358 discussions, I would like to propose
> an API for Time/Clock (we should keep one word I guess).
>
> There are six things we want to handle:
> 1. set time
> 2. get time
> 3. set timezone
> 4. get timezone
> 5. be informed when time is changed
> 6. be informed when timezone changes
>

Fabien Cazenave

unread,
Mar 31, 2012, 3:56:54 AM3/31/12
to Mounir Lamouri, dev-w...@lists.mozilla.org
Le 31/03/2012 00:19, Mounir Lamouri a écrit :
> Hi,
>
> Following bug 714357 and bug 714358 discussions, I would like to propose
> an API for Time/Clock (we should keep one word I guess).
>
> There are six things we want to handle:
> 1. set time
> 2. get time
> 3. set timezone
> 4. get timezone
> 5. be informed when time is changed
> 6. be informed when timezone changes
>

Ian Bicking

unread,
Mar 31, 2012, 12:25:39 AM3/31/12
to Mounir Lamouri, dev-w...@lists.mozilla.org
On Mar 30, 2012 5:20 PM, "Mounir Lamouri" <mou...@lamouri.fr> wrote:
> 5. Time change
> We should fire a change event to navigator.time.
> That event should fire if the timezone has been changed or the time has
> been changed manually. It should not be fired every ms ;)

Would this fire if the time is changed due to ntp or done other sync event?
If so, would there also be a threshold? E.g., if the adjustment is less
than a couple milliseconds would that count as no change?

Ian

Robert Kaiser

unread,
Apr 2, 2012, 3:04:11 PM4/2/12
to mozilla-d...@lists.mozilla.org
Fabien Cazenave schrieb:
> My 2¢: let’s call it “Clock API” and add an “alarm” object to it.

+1


Reason: "Clock" as a word makes it easier to connect it with the system
clock (RTC) being managed through it, while "Time" is easily twisted
with the existing Date object. Also, there's usually ways for the
system's RTC to save and trigger alarms, so the "alarm" stuff fits onto
a "Clock" object very well.

Robert Kaiser

JOSE MANUEL CANTERA FONSECA

unread,
Apr 3, 2012, 4:08:12 AM4/3/12
to Mounir Lamouri, dev-w...@lists.mozilla.org


El 31/03/12 00:19, "Mounir Lamouri" <mou...@lamouri.fr> escribió:

>Hi,
>
>Following bug 714357 and bug 714358 discussions, I would like to propose
>an API for Time/Clock (we should keep one word I guess).
>
>There are six things we want to handle:
>1. set time
>2. get time
>3. set timezone
>4. get timezone

Probably timezone is part of a setting

>5. be informed when time is changed
>6. be informed when timezone changes
>
>1. Set time
>We can have a navigator.time.set() method that will either take a double
>that will be the number of milliseconds since epoch in the current
>timezone or a Date object. The system time will then be replaced.

Wouldn't it be good to have also nanosecond precision?

On the other hand according to the Ecmascript Spec the number of
milliseconds since the epoch are always independent of the timezone ...
See the getTime method of Date or Date.now()

>
>ISSUES:
>I can think of two questions: should we take the epoch double in UTC
>timezone (I guess not but better to ask) and how should we behave if the
>Date object isn't in the same timezone the system currently is?

I think it is not a good idea to use Date objects for setting time

>Could
>that actually happen unless the timezone has been changed in the
>meantime? If not, we could just throw/ignore. Otherwise, we should
>define a behavior.
>
>2. Get time
>Use Date.
>
>3/4. Set/Get Timezone
>We should use the Settings API to do that.

Yes

>
>5. Time change
>We should fire a change event to navigator.time.
>That event should fire if the timezone has been changed or the time has
>been changed manually. It should not be fired every ms ;)

If timezone changes this can be detected through the Settings API

A time change is worth informing if an alarm is set and the target time
has elapsed

>
>6. Timezone change
>The settings API should allow you to listen to changes.

Yes
>
>The API would look like that:
>
>interface TimeManager {
> void set(Date time);
> void set(double time);
>
> attribute Function? onchange;
>};
>
>interface NavigatorTime {
> readonly attribute TimeManager time;
>};
>
>interface Navigator implements NavigatorTime;
>
>Any feedback?

I don't see setting the time by passing a Date object which to some extent
has some bindings to the timezone. So I would only use the double

>
>Thanks,
>--
>Mounir
>_______________________________________________
>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

Andreas Gal

unread,
Apr 3, 2012, 4:12:57 AM4/3/12
to JOSE MANUEL CANTERA FONSECA, dev-w...@lists.mozilla.org, Mounir Lamouri

>> There are six things we want to handle:
>> 1. set time
>> 2. get time
>> 3. set timezone
>> 4. get timezone

Shouldn't this be something we delegate to the UA? The radio layer usually supplies time and timezone information. If not the radio layer, the web does (NTP). If there is no radio and no web, we probably are ok with whatever time is on the device (the user has bigger problems at that point that setting the time).

> 5. be informed when time is changed
> 6. be informed when timezone changes

These seem useful.

Andreas

Mounir Lamouri

unread,
Apr 3, 2012, 10:24:43 AM4/3/12
to dev-w...@lists.mozilla.org
On 03/31/2012 06:25 AM, Ian Bicking wrote:
> Would this fire if the time is changed due to ntp or done other sync event?

Yes.

> If so, would there also be a threshold? E.g., if the adjustment is less
> than a couple milliseconds would that count as no change?

I think that could be up to the implementation. It seems silly to send
an event for a few microseconds time change but specifying that might
hard because choosing an arbitrary value wouldn't be a good idea.

--
Mounir

Mounir Lamouri

unread,
Apr 3, 2012, 10:48:21 AM4/3/12
to dev-w...@lists.mozilla.org
On 04/03/2012 10:08 AM, JOSE MANUEL CANTERA FONSECA wrote:
>> I can think of two questions: should we take the epoch double in UTC
>> timezone (I guess not but better to ask) and how should we behave if the
>> Date object isn't in the same timezone the system currently is?
>
> I think it is not a good idea to use Date objects for setting time

Wouldn't that be easier to manipulate dates with Date objects?

--
Mounir

Mounir Lamouri

unread,
Apr 3, 2012, 10:55:48 AM4/3/12
to dev-w...@lists.mozilla.org
On 04/03/2012 10:12 AM, Andreas Gal wrote:
>>> There are six things we want to handle:
>>> 1. set time
>>> 2. get time
>>> 3. set timezone
>>> 4. get timezone
>
> Shouldn't this be something we delegate to the UA? The radio layer usually supplies time and timezone information.

Indeed but usually phones allow you to disable that. Personally, I've
always found that feature quite flaky especially while traveling and I
tend to disable it.

> If not the radio layer, the web does (NTP).

That I do not understand. If someone writes an NTP client for B2G,
he/she will need the WebSocket API and the Clock API, right?

> If there is no radio and no web, we probably are ok with whatever time is on the device (the user has bigger problems at that point that setting the time).

So, given that I'm not sure what you meant by "the web does (NTP)", I'm
really sure how to reply here but as I said, my phones have radio layer
time information disabled which means I'm setting the timezone manually
(and sometimes update the time but it tends to be rare).
In addition, even if I had an NTP server set up, I want to be able to
change my timezone (and time) information while I'm offline. Typically,
when I board a plan, I change the timezone to match the timezone
destination. How could I do that if I have to rely on radio layer or NTP
client?

Cheers,
--
Mounir

Mounir Lamouri

unread,
Apr 3, 2012, 11:02:17 AM4/3/12
to dev-w...@lists.mozilla.org
On 03/31/2012 09:56 AM, Fabien Cazenave wrote:
> My 2¢: let’s call it “Clock API” and add an “alarm” object to it.
>
> At the moment we don’t have any proper way (afaik) to set an alarm in
> b2g/gaia… last time I checked we were using a setTimeout() for that.
> I think it’d be nice to handle an array of alarms and attach callbacks
> to each alarm.

An Alarm API is in the list of WebAPIs we will have to work on [1].
Maybe it could be merged with the Clock API. However, I would prefer to
wait and see what happens with the background apps topic before going
forward with an alarm api; maybe we could simply make the alarm clock
app staying alive in the background? Though, it might be nice to have an
API that gives a time and a callback so the callback is called at the
appropriate time. I'm just worried that the only use case would be an
Alarm Clock app. A Calendar app might use a similar API but the Alarm
Clock app likely doesn't care about timezones while the Calendar app
does... This is a different topic anyhow ;)

[1] https://wiki.mozilla.org/WebAPI#APIs

Cheers,
--
Mounir

Robert Kaiser

unread,
Apr 3, 2012, 1:17:47 PM4/3/12
to mozilla-d...@lists.mozilla.org
Mounir Lamouri schrieb:
> However, I would prefer to
> wait and see what happens with the background apps topic before going
> forward with an alarm api; maybe we could simply make the alarm clock
> app staying alive in the background?

Actually, I expect that we'll need to support the case where you set an
alarm and turn off your phone (yes, some people conserve battery power
and avoid disturbances while they sleep and turn off this life-important
device). And for that, we probably need to set some kind of system RTC
alarm that wakes the whole OS at the specified time, as I doubt there
are any background apps running when the device is turned off.

Robert Kaiser

Justin Lebar

unread,
Apr 3, 2012, 1:23:47 PM4/3/12
to Robert Kaiser, mozilla-d...@lists.mozilla.org
> Actually, I expect that we'll need to support the case where you set an
> alarm and turn off your phone (yes, some people conserve battery power and
> avoid disturbances while they sleep and turn off this life-important
> device).

Other people expect that turning off your phone entirely will silence
any alarms.  For example this guy [1].

I'm totally OK with our v1 phone not ringing alarms when it's powered off.

[1] http://www.nytimes.com/2012/01/13/nyregion/ringing-finally-stopped-but-concertgoers-alarm-persists.html

On Tue, Apr 3, 2012 at 1:17 PM, Robert Kaiser <ka...@kairo.at> wrote:
> Mounir Lamouri schrieb:
>
>> However, I would prefer to
>> wait and see what happens with the background apps topic before going
>> forward with an alarm api; maybe we could simply make the alarm clock
>> app staying alive in the background?
>
>
> Actually, I expect that we'll need to support the case where you set an
> alarm and turn off your phone (yes, some people conserve battery power and
> avoid disturbances while they sleep and turn off this life-important
> device). And for that, we probably need to set some kind of system RTC alarm
> that wakes the whole OS at the specified time, as I doubt there are any
> background apps running when the device is turned off.
>
> Robert Kaiser
>

Jason Miller

unread,
Apr 3, 2012, 10:51:12 PM4/3/12
to Justin Lebar, Robert Kaiser, mozilla-d...@lists.mozilla.org
I don't know anyone who turns off their phone expecting it to wake them in
the morning. It's not a logical assumption to make, and unless someone
were to explicitly prove to the user that it could be done, there is a
trust issue.

This is also the main purpose of having separate volume controls for phone,
alarm and media.

@Justin, I was thinking of the same article. Though it appears in that
particular instance the man had only set his ringer to vibrate, not
realizing the alarm has its own volume control.


Jason Miller
519.872.0797 // developIT <http://developit.ca/> // Jason Miller
Design<http://jasonmillerdesign.com/>
*Developer of amoebaOS <https://amoebaos.com/>,
Shutterborg<http://shutterb.org/> &
more

*



On Tue, Apr 3, 2012 at 1:23 PM, Justin Lebar <justin...@gmail.com> wrote:

> > Actually, I expect that we'll need to support the case where you set an
> > alarm and turn off your phone (yes, some people conserve battery power
> and
> > avoid disturbances while they sleep and turn off this life-important
> > device).
>
> Other people expect that turning off your phone entirely will silence
> any alarms. For example this guy [1].
>
> I'm totally OK with our v1 phone not ringing alarms when it's powered off.
>
> [1]
> http://www.nytimes.com/2012/01/13/nyregion/ringing-finally-stopped-but-concertgoers-alarm-persists.html
>
> On Tue, Apr 3, 2012 at 1:17 PM, Robert Kaiser <ka...@kairo.at> wrote:
> > Mounir Lamouri schrieb:
> >
> >> However, I would prefer to
> >> wait and see what happens with the background apps topic before going
> >> forward with an alarm api; maybe we could simply make the alarm clock
> >> app staying alive in the background?
> >
> >

Justin Lebar

unread,
Apr 4, 2012, 1:40:57 AM4/4/12
to Jason Miller, Robert Kaiser, mozilla-d...@lists.mozilla.org
> @Justin, I was thinking of the same article. Though it appears in that
> particular instance the man had only set his ringer to vibrate, not
> realizing the alarm has its own volume control.

His solution now is to power off his phone when he goes to concerts.
Imagine how he'd be thwarted by our alarm! :)

As another example, imagine your phone alarm going off in an airplane
during takeoff or landing. You did everything right, powering it off,
but it powered itself up.

On Tue, Apr 3, 2012 at 10:51 PM, Jason Miller <ja...@developit.ca> wrote:
>
> I don't know anyone who turns off their phone expecting it to wake them in
> the morning.  It's not a logical assumption to make, and unless someone were
> to explicitly prove to the user that it could be done, there is a trust
> issue.
>
> This is also the main purpose of having separate volume controls for
> phone, alarm and media.
>
> @Justin, I was thinking of the same article.  Though it appears in that
> particular instance the man had only set his ringer to vibrate, not
> realizing the alarm has its own volume control.
>
>
> Jason Miller
> 519.872.0797 // developIT // Jason Miller Design
> Developer of amoebaOS, Shutterborg & more
>
>
>
>
> On Tue, Apr 3, 2012 at 1:23 PM, Justin Lebar <justin...@gmail.com>
> wrote:
>>
>> > Actually, I expect that we'll need to support the case where you set an
>> > alarm and turn off your phone (yes, some people conserve battery power
>> > and
>> > avoid disturbances while they sleep and turn off this life-important
>> > device).
>>
>> Other people expect that turning off your phone entirely will silence
>> any alarms.  For example this guy [1].
>>
>> I'm totally OK with our v1 phone not ringing alarms when it's powered
>> off.
>>
>> [1]
>> http://www.nytimes.com/2012/01/13/nyregion/ringing-finally-stopped-but-concertgoers-alarm-persists.html
>>
>> On Tue, Apr 3, 2012 at 1:17 PM, Robert Kaiser <ka...@kairo.at> wrote:
>> > Mounir Lamouri schrieb:
>> >
>> >> However, I would prefer to
>> >> wait and see what happens with the background apps topic before going
>> >> forward with an alarm api; maybe we could simply make the alarm clock
>> >> app staying alive in the background?
>> >
>> >

Gervase Markham

unread,
Apr 4, 2012, 5:37:32 AM4/4/12
to mozilla-d...@lists.mozilla.org
On 03/04/12 15:55, Mounir Lamouri wrote:
> Indeed but usually phones allow you to disable that. Personally, I've
> always found that feature quite flaky especially while traveling and I
> tend to disable it.

Yes; O2 in the UK, at least, gets this wrong with Android.

Gerv

Mounir Lamouri

unread,
Apr 4, 2012, 10:43:08 AM4/4/12
to dev-w...@lists.mozilla.org
On 04/03/2012 07:17 PM, Robert Kaiser wrote:
> Actually, I expect that we'll need to support the case where you set an
> alarm and turn off your phone (yes, some people conserve battery power
> and avoid disturbances while they sleep and turn off this life-important
> device). And for that, we probably need to set some kind of system RTC
> alarm that wakes the whole OS at the specified time, as I doubt there
> are any background apps running when the device is turned off.

That's a feature I actually used in the past when I was using
feature-phones from a well-known Finish company. However, I wonder if
that is still working with current smartphones. FWIW, it doesn't seem to
work with my Nexus S.

Practically, that's the kind of feature people will have a hard time to
find and will require some low level work (we have to be able to boot
the phone because of the alarm and boot in a special mode were only the
alarm shows up). However, we could keep that in mind for the API design
but I don't see us implementing such a feature for a v1.

Cheers,
--
Mounir

Andreas Gal

unread,
Apr 4, 2012, 10:46:22 AM4/4/12
to Mounir Lamouri, dev-w...@lists.mozilla.org

On Apr 4, 2012, at 7:43 AM, Mounir Lamouri wrote:

> On 04/03/2012 07:17 PM, Robert Kaiser wrote:
>> Actually, I expect that we'll need to support the case where you set an
>> alarm and turn off your phone (yes, some people conserve battery power
>> and avoid disturbances while they sleep and turn off this life-important
>> device). And for that, we probably need to set some kind of system RTC
>> alarm that wakes the whole OS at the specified time, as I doubt there
>> are any background apps running when the device is turned off.
>
> That's a feature I actually used in the past when I was using
> feature-phones from a well-known Finish company. However, I wonder if
> that is still working with current smartphones. FWIW, it doesn't seem to
> work with my Nexus S.

Smart phones are usually constantly connected to the network to wait for push notifications. I don't think we will see RTC-driven hardware wakeup any time soon on the roadmap.

Andreas

Robert Kaiser

unread,
Apr 4, 2012, 12:20:05 PM4/4/12
to mozilla-d...@lists.mozilla.org
Justin Lebar schrieb:
> His solution now is to power off his phone when he goes to concerts.
> Imagine how he'd be thwarted by our alarm! :)
>
> As another example, imagine your phone alarm going off in an airplane
> during takeoff or landing. You did everything right, powering it off,
> but it powered itself up.

Those are both not issues, because you as a user won't set an alarm to
go off at a time where you know you won't want to get an alarm.

Anyhow, I know a lot of people who are used to this behavior, including
myself when traveling (esp. when I'm e.g. in the US I want to turn off
the phone when sleeping because I don't want to get *any* disturbance
from Europeans thinking they call me during daytime when it's night,
etc. - but of course, I want to be woken by an alarm in the morning.

In any case, I just wanted to give the example of what an alarm on the
Clock API would be useful for, I didn't mean to say it has to be
implemented immediately. ;-)

Robert Kaiser
Reply all
Reply to author
Forward
0 new messages