alarms API

Hint

The alarms API is inherited from Firefox, and its primary documentation is maintained by Mozilla at MDN. Thunderbird implements only the subset of functions, events, and types listed here. The MDN pages may provide further details and examples, but they may also reference features that are not supported in Thunderbird.

Permissions

The following permissions influence the behavior of the API. Depending on which permissions are requested, additional methods might be available, or certain data may be included in responses.

Hint

Request permissions only when needed. Unnecessary requests may result in rejection during ATN review.

alarms



Grant access to some or all methods of the alarms API.

Note

The permission alarms is required to use messenger.alarms.*.

Functions

clear([name])

– [Added in TB 45]

Clears the alarm with the given name.

Parameters

name

[name]

(string, optional)



The name of the alarm to clear. Defaults to the empty string.

Return type (Promise)

_returns

boolean



Whether an alarm of the given name was found to clear.

Required permissions

alarms

clearAll()

– [Added in TB 45]

Clears all alarms.

Return type (Promise)

_returns

boolean



Whether any alarm was found to clear.

Required permissions

alarms

create([name], alarmInfo)

– [Added in TB 45]

Creates an alarm. After the delay is expired, 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.

Parameters

name

[name]

(string, optional)



Optional name to identify this alarm. Defaults to the empty string.

alarmInfo

alarmInfo

(object)



Details about the alarm. The alarm first fires either at ‘when’ milliseconds past the epoch (if ‘when’ is provided), after ‘delayInMinutes’ minutes from the current time (if ‘delayInMinutes’ is provided instead), or after ‘periodInMinutes’ minutes from the current time (if only ‘periodInMinutes’ is provided). Users should never provide both ‘when’ and ‘delayInMinutes’. If ‘periodInMinutes’ is provided, then the alarm recurs repeatedly after that many minutes.

delayInMinutes

[delayInMinutes]

(number, optional)



Number of minutes from the current time after which the alarm should first fire.

periodInMinutes

[periodInMinutes]

(number, optional)



Number of minutes after which the alarm should recur repeatedly.

when

[when]

(number, optional)



Time when the alarm is scheduled to first fire, in milliseconds past the epoch.

Required permissions

alarms

get([name])

– [Added in TB 45]

Retrieves details about the specified alarm.

Parameters

name

[name]

(string, optional)



The name of the alarm to get. Defaults to the empty string.

Return type (Promise)

_returns

Alarm



Required permissions

alarms

getAll()

– [Added in TB 45]

Gets an array of all the alarms.

Return type (Promise)

_returns

array of Alarm



Required permissions

alarms

Events

onAlarm

– [Added in TB 45]

Fired when an alarm has expired. Useful for transient background pages.

Parameters for onAlarm.addListener(listener)

listener(name)

listener(name)



A function that will be called when this event occurs.

Parameters passed to the listener function

name

name

(Alarm)



The alarm that has expired.

Required permissions

alarms

Types

Alarm

– [Added in TB 45]

object

name

name

(string)



Name of this alarm.

scheduledTime

scheduledTime

(number)



Time when the alarm is scheduled to fire, in milliseconds past the epoch.

periodInMinutes

[periodInMinutes]

(number, optional)



When present, signals that the alarm triggers periodically after so many minutes.