# Alarms

Real Time Clock (RTC) alarms are timers that signal the user at a preset time or at a certain interval from the current time. Alarms can wake up the device when the alarm activates, though by default, they do not. RTC alarm functionality is provided as a Service through a service request. They are intended to wake applications (whether minimized or maximized) or to drive polling for Dashboard applications.

There are two types of alarms:

- Monotonic (in a certain period): A monotonic-time alarm causes the device to wake and activate an alarm at a fixed time interval in the future. This is independent of clock time changes. The maximum period for monotonic alarms is 24 hours.
- Calendar (at a certain time and date): A calendar alarm causes the device to wake and activate an alarm at a specific calendar time. Calendar alarms do not have the 24 hours time limit.

An alarm wakes up your application by launching (or relaunching) it through the Application Manager service. The parameters to the applicationManager service call pass to your application during the creation of its stage assistant.

To receive an alarm callback, your application assistant requires a handleLaunch() method that handles parameters passed from the application manager, and then calls stageController.activate() to bring your application to the foreground.

Notes:

- Setting an alarm timeout with the same key from the same application overwrites the existing alarm timeout with the new parameters.
- By default, the event does not wake up the device. If the timeout expires while the device is asleep, the timer activates when the device next wakes. To create an alarm timeout that does wake up the device, set the wakeup parameter to true.
- Alarms are preserved across a reboot. If an alarm expired while the device was shutdown, the alarm activates when the device restarts.
- Alarms are coarse-grained. An alarm may activate up to 2 seconds off from the intended time.
- When an alarm fires (if "wakeup" is set to true), webOS starts or restarts an activity to keep the device awake long enough for the client code to do something useful. This is a fixed, 5-second activity with the name "com.palm.power.timeout_fired".
- See Power Management Service for information on activities.

## URI

The URI is as follows:

> palm://com.palm.power/timeout

## Methods

This section describes the following methods:

- set
- clear

### set

Creates a new alarm with the provided alarm object.

Required parameters:

- key
- Either in or at
- URI
- params

#### Parameters

Parameter | Type | Description
--- | --- | ---
at | string | Creates a calendar-based alarm in GMT (i.e., UTC). Either at or in is required. Format is "mm/dd/yyyy hh:mm:ss".
in | string | Creates a relative alarm (minimum alarm time is "00:05:00" 5 minutes). Either at or in is required. Format is "hh:mm:ss".
key | object | The identifier for timeout. Format is "com.X.X.timer".
params | object | Payload of the message that is sent when the timeout expires. The format of the payload depends on the key (service) used.
uri | string | URI of the message that is sent when the timeout expires. Format is "palm://com.X.X/method".
wakeup | boolean | Wakes up the device when the timeout expires. Default is false.

#### Return Handling

onSuccess

An object is returned with the following attributes:

Attribute | Type | Description
--- | --- | ---
key | string | The key that was passed in.
returnValue | boolean | true

onFailure

An object is returned with the following attributes:

Attribute | Type | Description
--- | --- | ---
errorText | string | A string representing the error for display if needed. One of the following: Timeout value for "in" less than 5 minutes. Invalid format for "timeout/set". Malformed JSON. Could not set timeout.
returnValue | boolean | false

#### Example

>     this.controller.serviceRequest("palm://com.palm.power/timeout", {
>       method: "set",
>       parameters: {
>           "wakeup": true,
>           "key": "yourKeyName",
>           "uri": "palm://com.palm.applicationManager/launch",
>           "params": '{"id":"com.YourDomain.YourApp","params":{"action":"setTimeout"}}',
>               "at": "01/01/2009 17:45:00"
>       },
>       onSuccess: myCallback,
>       onFailure: myFailureCallback
>     });

### clear

Requests the named "key" timer to be cleared.

Required parameter:

- key

#### Parameters

Parameter | Type | Description
--- | --- | ---
key | string | Identifier of the timeout to remove. Format is "com.X.X.timer".

#### Return Handling

onSuccess

An object is returned with the following attributes:

Attribute | Type | Description
--- | --- | ---
key | string | The key that was passed in.
returnValue | boolean | true

onFailure

An object is returned with the following attributes:

Attribute | Type | Description
--- | --- | ---
errorText | string | A string representing the error for display if needed. One of the following: Could not find key. Malformed JSON.
returnValue | boolean | false

#### Example

>     this.schedulerSetRequest = new Mojo.Service.Request(
>       "palm://com.palm.power/timeout", {
>           method: "clear",
>           parameters: {"key": "yourKeyName"},
>           onSuccess: myCallback,
>           onFailure: myFailureCallback
>       }
>     );

## Examples

This section shows example uses of the Alarms service.

### Set Calendar-Based Time

Set a calendar event to activate at 04-03-2009 at 21:35:00 GMT (UTC).

>     this.controller.serviceRequest("palm://com.palm.power/timeout", {
>       method: "set",
>       parameters: {
>           "wakeup": true,
>           "key": "calendarEvent",
>           "uri": "palm://com.palm.applicationManager/open",
>           "params" : "{'id': 'com.palm.calendarEvent','params': {}}","at": "04/03/2009 21:35:00"
>       },
>       onSuccess: myCallback,
>       onFailure: myFailureCallback
>     });

### Set an Egg Timer to Activate 1 hr From Now

>     this.controller.serviceRequest("palm://com.palm.power/timeout", {
>       method: "set",
>       parameters: {
>           "wakeup" : true,
>           "key" : "egg1",
>           "uri": "palm://com.palm.applicationManager/open",
>           "in" : "01:00:00",
>           "params" : "{'id':'com.palm.eggtimer','params': {'alarm': 'egg1'}}"
>       }
>     });

### Remove Egg Timer

>     this.controller.serviceRequest('palm://com.palm.power/timeout', {
>       method: "clear",
>       parameters: {"key" : "eggtime"}
>     });

### Schedule a News Fetch with a Twist

Schedule a news fetch in 30 minutes, but only activate if the device is already awake. If the timeout expires when the device is asleep, the timeout activates the next time the device wakes.

This is an opportunistic way of using the timer and helps save battery power. This is especially useful when the request is not urgent or needs the user immediate attention.

>     this.controller.serviceRequest('palm://com.palm.power/timeout', {
>       method: "set",
>       parameters: {
>           "key": "news_fetch",
>           "in": "00:30:00",
>           "wakeup": false,
>           "uri": "palm://com.palm.applicationManager/open",
>           "params": "{'id':'com.palm.news','params':{'action': 'fetch'}}"
>       }
>     });