Documentation

Alarms

Real Time Clock (RTC) alarms signal the user at a preset time or at a specified interval from the current time. Alarms can wake up the device when the alarm activates, though by default, they do not. They are intended to wake applications (whether minimized or maximized) or to drive polling for Dashboard applications.

Alarm types:

Monotonic (in a certain period) - 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) - Causes the device to wake and activate an alarm at a specific calendar time. Calendar alarms do not have a 24 hours time limit.

To wake up your application, an alarm launches (or relaunches) it through the Application Manager service. The parameters to the Application Manager service call are passed thru to your application.

Callbacks in Mojo

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.

Callbacks in Enyo

In your Enyo app, create an onApplicationRelaunch application event handler that checks for the parameters passed from the Application Manager (see Enyo example).

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 wakeup 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 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 for information on activities.

Methods

set - Creates a new alarm with the provided alarm object
clear - Requests the named "key" timer to be cleared.

set

Creates a new alarm with the provided alarm object.

URI is palm://com.palm.power/timeout/set

Syntax

{
   at     : string,
   in     : string,
   key    : string,
   params : object,
   uri    : string,
   wakeup : boolean   
}

Parameters

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

Returns

{
   returnValue : boolean,
   key         : string,
   errorText   : string 
}

Attribute	Required	Type	Description
returnValue	Yes	boolean	`true` (success) or `false` (failure),
key	No	string	The key that was passed in.
errorText	No	string	Error message returned on failure. One of the following: Invalid format for "timeout/set". Malformed JSON. Could not set timeout.

Examples

Enyo

// Set alarm to call this app to launch browser in 10 seconds
enyo.kind({
   name : "enyo.alarms",
   kind : enyo.VFlexBox,
   components : [
     {kind: "ApplicationEvents", onApplicationRelaunch: "applicationRelaunchHandler"},   
     {flex : 1,
      kind : "Pane",
      components : [{
         flex : 1,
         kind : "Scroller",
         components : [
          {
             name: "setAlarm",
             kind: "PalmService",
             service: "palm://com.palm.power/timeout/",
             method: "set",
             onSuccess: "setAlarmSuccess",
             onFailure: "setAlarmFailure",
             subscribe: true
         },
         {
             name: "launchBrowser",
             kind: "PalmService",
             service: "palm://com.palm.applicationManager/",
             method: "launch",
             onSuccess: "launchSuccess",
             onFailure: "launchFailure",
             subscribe: true
         },
         {kind : "Button", name : "setAlarmButton", caption : "Set Alarm", onclick : "setAlarmClick"}
        ]
      }]
    }],
    applicationRelaunchHandler: function(inSender) {                                                                          
        var params = enyo.windowParams;           
        if (params.action !== undefined) {
            this.$.launchBrowser.call({"id": "com.palm.app.browser", "params":{"target": "http://www.google.com"}});                     
            return true;                      
        }                                                          
    }, 
    setAlarmClick: function(inSender, inResponse)  {
       // Call this app to launch browser in 10 seconds. Yes, you could launch the browser app directly from
       // the service, but this is for demo purposes.  
       this.$.setAlarm.call({"wakeup":true, "key":"myKey", "uri":"palm://com.palm.applicationManager/launch",
                      "params" : {"id":"com.palmdts.enyo.alarms","params":{"action":"alarmWakeup"}},
                      "in": "00:00:10"});
    },  
    setAlarmSuccess: function(inSender, inResponse) {   
        this.log("Set alarm success, results=" + enyo.json.stringify(inResponse));
    },
    setAlarmFailure: function(inSender, inError, inRequest) {
        this.log(enyo.json.stringify(inError));
    },
    launchSuccess: function(inSender, inResponse) {
        enyo.log("Launch browser success, results=" + enyo.json.stringify(inResponse));
    },
    launchFailure: function(inSender, inResponse) {
        enyo.log("Launch browser failure, results=" + enyo.json.stringify(inResponse));
    }
});

Mojo

this.controller.serviceRequest("palm://com.palm.power/timeout", {
    method: "set",
    parameters: {
        "wakeup" : true,
        "key"    : "myKeyName",
        "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.

URI is palm://com.palm.power/timeout/clear

Syntax

{
   key    : string
}

Parameters

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

Returns

{
   returnValue : boolean,
   key         : string,
   errorText   : string 
}

Attribute	Required	Type	Description
returnValue	Yes	boolean	`true` (success) or `false` (failure),
key	No	string	The key that was passed in.
errorText	No	string	Error message returned on failure. One of the following: Could not find key Malformed JSON

Examples

Mojo

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

Mojo Examples

This section shows example uses of the Alarms service for Mojo apps.

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's 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'}}"
    }  
});

Documentation

Alarms

Methods

set

Syntax

Parameters

Returns

Examples

clear

Syntax

Parameters

Returns

Examples

Mojo Examples

Set Calendar-Based Time

Set an Egg Timer to Activate 1 hr From Now

Remove Egg Timer

Schedule a News Fetch with a Twist

Why webOS

Getting Started

Videos

Stay up to date