com.webos.service.alarm

Note
This API has been available since API level 13.

API Summary

Enables webOS daemons or apps to call webOS API methods with specific parameters in a specified time interval.

Overview of the API

About webOS alarm:

A timer that causes a webOS API method to be called after a specified time interval.
webOS manages a list of alarms in a SQL database.
Each webOS app or daemon can have its unique set of alarms.
webOS app can request all alrams present in alarms database.
webOS app can request next wakeup alarm present in database.

Using the com.webos.service.alarm

Any webOS app or daemon can use the com.webos.service.alarm API.

Wake up vs. non-wake up

An important decision that you need to make when using the com.webos.service.alarm is whether the alarm wakes up the system or not.

IMPORTANT: Waking up only applies to webOS devices that can go into a suspend state.

In order to save power, systems typically go into a suspend state. When a system is in a suspend state, none of the processes on the system are running, and the system goes into a very low power mode.

Wake up alarm - When an alarm is set as a wake up alarm, the alarm is guaranteed to be delivered at the requested time, whether the system is awake or suspended at the requested time. If the system is suspended, system will be woken up to deliver the alarm. As one would expect, if the system is awake, the alarm is delivered normally. The wake up alarm is the most significant advantage of the alarm API over other operating system provided alarms.
Non-wake up alarm - When an alarm is set as a non-wake up alarm, the alarm is delivered at requested time only if the system is awake at that time. If the system is suspended at the requested time, the alarm will be delivered after the system is woken up, for example, by a user action.

Wake up or non-wake up is determined by wakeup parameter in the set method.

Methods

clear

ACG: alarm.operation

Added: API level 13

Description

Deletes an existing alarm. Apps or daemons can identify their alarm to be deleted by specifying its key.

Parameters

Name	Required	Type	Description
key	Required	String	key of the alarm that you wish to delete. This is the same key that was specified when the alarm was created the set method.

Call Returns

Name	Required	Type	Description
key	Optional	String	The same unique identifier is returned if the alarm was deleted successfully.
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorText" field for details
errorText	Optional	String	Indicates the reason for the failure of the operation. See the Error Codes Reference and API Error Codes Reference of this method for more details.

Name

Required

Type

Description

key

Optional

String

The same unique identifier is returned if the alarm was deleted successfully.

returnValue

Required

Boolean

Indicates the status of operation. Possible values are:

true - Indicates that the operation was successful.
false - Indicates that the operation failed. Check the "errorText" field for details

errorText

Optional

String

Indicates the reason for the failure of the operation. See the Error Codes Reference and API Error Codes Reference of this method for more details.

Error Codes Reference

Error Code	Error Text	Error Description
None	Could not find key	The supplied key does not exist.

Example

Example scenario

# luna-send -n 1 -a com.webos.app.test luna://com.webos.service.alarm/clear '{"key":"test"}'

Response:

{
"key": "test",
"returnValue": true
}

set

ACG: alarm.operation

Added: API level 13

Description

Creates a new alarm for an absolute time or a relative time. By using the "wakeup" parameter you can define it as a wake-up or a non-wakeup alarm.

Parameters

Name	Required	Type	Description
key	Required	String	Unique key to identify individual alarms.
at	Required	String	The at parameter sets the absolute time, and must be in the format mm/dd/yyyy HH:MM:SS to be passed. Note: Either this, or in is required.
in	Required	String	The in parameter sets the relative time and must be in the format HH:MM:SS to be passed. Note: Either this, or at is required.
uri	Required	String	The webOS API method that should be called when the alarm fires. Example: luna//com.webos.service.test/alarmFired
params	Required	Object	Parameters that need to be passed with the uri when the alarm fires. Example: {"param1":"abc","param2":"xyz"}
wakeup	Optional	Boolean	Specifies if the alarm is a wake-up alarm. Possible values are: true - Create a wake-up alarm, false - Create a non-wake up alarm Default value: false.
keep_existing	Optional	Boolean	If there is an existing alarm with the same key, and you don't want to delete it, set keep_existing to true. To clear existing alarms with the same key, set keep_existing to false. The default value of keep_existing is false.

Call Returns

Name	Required	Type	Description
key	Optional	String	If the alarm was created successfully, the set method will return the key of the alarm that it created.
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorText" field for details
errorText	Optional	String	Indicates the reason for the failure of the operation. See the Error Codes Reference and API Error Codes Reference of this method for more details.

Name

Required

Type

Description

key

Optional

String

If the alarm was created successfully, the set method will return the key of the alarm that it created.

returnValue

Required

Boolean

Indicates the status of operation. Possible values are:

true - Indicates that the operation was successful.
false - Indicates that the operation failed. Check the "errorText" field for details

errorText

Optional

String

Indicates the reason for the failure of the operation. See the Error Codes Reference and API Error Codes Reference of this method for more details.

Error Codes Reference

Error Code	Error Text	Error Description
None	activity_duration_ms less than 5000 ms	The activity set for the alarm is less than 5 seconds.
None	Could not set timeout	Due to some unknown error, the system could not set the timeout.
None	Invalid format for timeout/set	The values provided for at or in did not match the required format - mm/dd/yyyy HH:MM:SS for at and HH:MM:SS for in.

Example

Example scenario

# luna-send -n 1 -a com.webos.app.test luna://com.webos.service.alarm/set '{
"key":"test",
"uri":"luna://com.webos.service.testsleepd/firealarm",
"params":{},
"at":"09/24/2014 04:40:00",
"wakeup":true
}'

Response:

{
"returnValue": true,
"key": "test"
}

Example scenario

Example for a successful call: params input parameter is used to pass parameters to alarm client; in this case "com.webos.display" will receive "state : on" and take respective action

# luna-send -n 1 -a com.webos.app.test luna://com.webos.service.alarm/set '{
"at":"08/11/2014 09:26:05",
"key":"test_alarm",
"params":{\"state\": \"on\"},
"uri":"luna://com.webos.display/control/setState",
"wakeup":true
}'

Returns:

{
"returnValue":true,
"key":"test_alarm"
}

Objects

alarmObject

Object contains information about the alarms.

Name	Required	Type	Description
wakeup	Required	Boolean	Indicates whether the alarm can wakeup the device from suspend state or not. true: can wakeup the device from suspend state false: cannot wakeup the device from suspend state
expiry	Required	String	Expiry time when the alarm will be expired. It is returned as a string in a format: MM/DD/YYYY HH:MM:SS.
uri	Required	String	webOS API method that should be called when the alarm fires. Example: luna://com.webos.display/control/setState
params	Optional	Object	Parameters that need to be passed with the uri when the alarm fires. Example: {"param1":"abc","param2":"xyz"}
key	Required	String	Unique key to identify individual alarms.
calendar	Optional	Boolean	Indicates whether the alarm is calendar alarm or relative alarm. true: calendar alarm false: relative alarm
appid	Optional	String	Application ID

API Error Codes Reference

Error Code	Error Text	Error Description
None	Invalid parameters	Json parse error