whale.alarms
| Description: | Use the whale.alarms API to schedule code to run periodically or at a specified time in the future. |
|---|---|
| Availability: | Since Chrome 22. |
| Permissions: | "alarms" |
| Learn More: | Event Pages |
## Types
### Alarm
| properties |
|---|
| string | name |
Name of this alarm.
|
| double | scheduledTime |
Time at which this alarm was scheduled to fire, in milliseconds past the epoch (e.g. `Date.now() + n`). For performance reasons, the alarm may have been delayed an arbitrary amount beyond this.
|
| double | (optional) periodInMinutes |
If not null, the alarm is a repeating alarm and will fire again in periodInMinutes minutes.
|
## Methods
### create
`whale.alarms.create(string name, object alarmInfo)`
Creates an alarm. Near the time(s) specified by alarmInfo, the `onAlarm` event is fired. If there is another alarm with the same name (or no name if none is specified), it will be cancelled and replaced by this alarm.
In order to reduce the load on the user's machine, Chrome limits alarms to at most once every 1 minute but may delay them an arbitrary amount more. That is, setting `delayInMinutes` or `periodInMinutes` to less than `1` will not be honored and will cause a warning. `when` can be set to less than 1 minute after "now" without warning but won't actually cause the alarm to fire for at least 1 minute.
To help you debug your app or extension, when you've loaded it unpacked, there's no limit to how often the alarm can fire.
| Parameters |
|---|
| string | (optional) name |
Optional name to identify this alarm. Defaults to the empty string.
|
| object | alarmInfo |
Describes when the alarm should fire. The initial time must be specified by either when or delayInMinutes (but not both). If periodInMinutes is set, the alarm will repeat every periodInMinutes minutes after the initial event. If neither when or delayInMinutes is set for a repeating alarm, periodInMinutes is used as the default for delayInMinutes.
| double | (optional) when |
|---|---|
Time at which the alarm should fire, in milliseconds past the epoch (e.g. `Date.now() + n`).
|
| double | (optional) delayInMinutes |
Length of time in minutes after which the `onAlarm` event should fire.
|
| double | (optional) periodInMinutes |
If set, the onAlarm event should fire every periodInMinutes minutes after the initial event specified by when or delayInMinutes. If not set, the alarm will only fire once.
|
|
### get
`whale.alarms.get(string name, function callback)`
Retrieves details about the specified alarm.
| Parameters |
|---|
| string | (optional) name |
The name of the alarm to get. Defaults to the empty string.
|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function( [Alarm](/extensions/alarms#type-Alarm) alarm) {...};`
| [Alarm](/extensions/alarms#type-Alarm) | (optional) alarm | |
|---|---|---|
|
### getAll
`whale.alarms.getAll(function callback)`
Gets an array of all the alarms.
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function(array of [Alarm](/extensions/alarms#type-Alarm) alarms) {...};`
| array of [Alarm](/extensions/alarms#type-Alarm) | alarms | |
|---|---|---|
|
### clear
`whale.alarms.clear(string name, function callback)`
Clears the alarm with the given name.
| Parameters |
|---|
| string | (optional) name |
The name of the alarm to clear. Defaults to the empty string.
|
| function | (optional) callback |
If you specify the _callback_ parameter, it should be a function that looks like this:
`function(boolean wasCleared) {...};`
| boolean | wasCleared | |
|---|---|---|
|
### clearAll
## Events
`whale.alarms.clearAll(function callback)`
Clears all alarms.
| Parameters |
|---|
| function | (optional) callback |
If you specify the _callback_ parameter, it should be a function that looks like this:
`function(boolean wasCleared) {...};`
| boolean | wasCleared | |
|---|---|---|
|
### onAlarm
Fired when an alarm has elapsed. Useful for event pages.
#### addListener
`whale.alarms.onAlarm.addListener(function callback)`
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function( [Alarm](/extensions/alarms#type-Alarm) alarm) {...};`
| [Alarm](/extensions/alarms#type-Alarm) | alarm |
|---|---|
The alarm that has elapsed.
|
|