com.webos.service.alarm
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
set
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:
Default value: false. |
| keep_existing | Optional | Boolean |
|
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:
|
| 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 for a successful call:
# luna-send -n 1 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
}'
Returns:
{
"returnValue": true,
"key": "test"
}
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 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"
}
Example for a failed call: key input parameter is not specified
# luna-send -n 1 luna://com.webos.service.alarm/set '{
"at":"08/11/2014 09:26:05",
"params":{\"state\":\"on\"},
"uri":"luna://com.webos.display/control/setState",
"wakeup":true
}'
Returns:
{
"errorCode":-1,
"returnValue":false,
"errorText":"Invalid format for timeout/set"
}
clear
Description
Deletes an existing alarm. Apps or daemons can identify the 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:
|
| 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
# luna-send -n 1 luna://com.webos.service.alarm/clear '{"key":"test"}'
{
"key": "test",
"returnValue": true
}
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.
|
| 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.
|
| appid | Optional | String | Application ID |
API Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| None | Json parse error | Json parse error |