Menu

Reference

com.webos.service.alarm

API Summary

The com.webos.service.alarm API enables webOS daemons or apps to call webOS API methods with specific parameters in a specified time interval. 

Overview of the API

About webOS alarms

  • A webOS alarm is 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-wake up alarm. 

Parameters

Name

Required

Type

Description

keyRequiredString

Unique key to identify individual alarms.

atRequiredString

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.

inRequiredString

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.

uriRequiredString

The webOS API method that should be called when the alarm fires.

Example: luna//com.webos.service.test/alarmFired

paramsRequiredObject

Parameters that need to be passed with the uri when the alarm fires.

Example: {"param1":"abc","param2":"xyz"}

wakeupOptionalBoolean

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_existingOptionalBoolean
  • 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

keyOptionalString

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

returnValueRequiredBoolean

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
errorTextOptionalString

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

Noneactivity_duration_ms less than 5000 ms

The activity set for the alarm is less than 5 seconds.

NoneCould not set timeout

Due to some unknown error, the system could not set the timeout.

NoneInvalid 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

keyRequiredString

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

keyOptionalString

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

returnValueRequiredBoolean

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
errorTextOptionalString

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

NoneCould 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

wakeupRequiredBoolean

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
expiryRequiredString

Expiry time when the alarm will be expired. It is returned as a string in a format: MM/DD/YYYY HH:MM:SS.

uriRequiredString

webOS API method that should be called when the alarm fires.

Example: luna://com.webos.display/control/setState

paramsOptionalObject

Parameters that need to be passed with the uri when the alarm fires.

Example: {"param1":"abc","param2":"xyz"}

keyRequiredString

Unique key to identify individual alarms.

calendarOptionalBoolean

Indicates whether the alarm is calendar alarm or relative alarm.

  • true: calendar alarm
  • false: relative alarm
appidOptionalString

Application ID

API Error Codes Reference

Error Code

Error Text

Error Description

NoneJson parse error

Json parse error

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 and sample code is licensed under the Apache License 2.0.

Contents