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:

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:

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