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).
|
in | string |
Creates a relative alarm (minimum alarm time is "00:05:00" 5 minutes).
|
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:
|
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:
|
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'}}" } });