com.webos.service.sleep

API Summary

This service registers itself as com.webos.service.power and as com.webos.service.alarm and is provided by the sleep daemon (sleepd). It allows applications to interact with (e.g. defer or prevent) the system suspend/resume cycle.

Overview of the API

(click to expand)

Shutdown Process:

The sleep daemon (sleepd) also transitions the system (and ultimately the device) from "On" to "Off". Clients that wish to be notified of this transition and optionally defer or prevent it must first register with sleepd using the "shutdown/shutdownApplicationsRegister" or "shutdown/ShutdownServicesRegister" method.

When sleepd receives a "shutdown/initiate" request, it will transition to the "ShutdownApplications" state.

In the "ShutdownApplications" state, sleepd will broadcast the "ShutdownApplications" signal to all clients which have registered for this signal using the "shutdown/shutdownApplicationsRegister" method, and will wait a maximum of 15 seconds for all responses. Each registered client should respond back with an ACK using the "shutdown/shutdownApplicationsAck" method. As soon as all clients respond back with an ACK, or the "ShutdownApplications" timeout expires, sleepd will transition to the "ShutdownServices" state.

In the "ShutdownServices" state, sleepd will broadcast the "ShutdownServices" signal to all clients which have registered for this signal using the "shutdown/shutdownServicesRegister" method, and will wait a maximum of 15 seconds for all responses. Each registered client should respond back with an ACK using the "shutdown/shutdownServicesAck" method. As soon as all clients respond back with an ACK, or the "ShutdownServices" timeout expires, sleepd will reply to the caller of the "shutdown/initiate" request.

After receiving the reply to the "shutdown/initiate" request, the caller should then call "shutdown/machineOff" or "shutdown/machineReboot" to forcefully shut down or reboot the device, respectively.


Open All


shutdown/initiate

Description

The initiate method starts the shutdown process - sending the shutdownApplications and shutdownServices signals to all the registered apps/services. Once the shutdown process completes and the system decides it can shutdown, this call returns.

Please note: This call does not do the actual shutdown , for that you need to call machineOff method.

Parameters

None

Call Returns

Name

Required

Type

Description

successRequiredBoolean

Always returns true

Example

luna-send -n 1 luna://com.webos.service.sleep/shutdown/initiate '{}'

Response:

{ "success":true }


shutdown/machineOff

Description

Shuts down the machine forcefully

Parameters

Name

Required

Type

Description

reasonRequiredstring

Reason for the shutdown. Possible reasons are:

  • remoteKey - Power off using remote control
  • offTimer - Power off using OFF timer
  • localKey - Power off using using the devices hardware power on/off key

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

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

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

-1Invalid parameters

The reason parameter was not provided

Example

luna-send -n 1 luna://com.webos.service.sleep/shutdown/machineOff '{"reason":"power off"}'

Response:

{ "returnValue":true }


shutdown/machineReboot

Description

Reboot the machine forcefully by calling "reboot"

Parameters

Name

Required

Type

Description

reasonRequiredstring

The reason why caller wants to reboot the system. Possible reasons are:

  • reset - Reboot after device was reset
  • ota - Reboot after OTA update completion
  • SwDownload - Reboot after software download

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

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

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

-1Invalid parameters

The reason parameter was not provided

Example

luna-send -n 1 luna://com.webos.service.sleep/shutdown/machineReboot '{"reason":"none"}'

Response:

{ "returnValue":true }


shutdown/shutdownApplicationsAck

Description

This method will set the client's response as ACK for the "shutdownApplications" signal and trigger the dispatcher for the shutdown state machine, so that if the total client ACK count exceeds total number of clients, it can proceed to the next state.

Parameters

Name

Required

Type

Description

clientIdRequiredstring

The unique token for this client which was generated in a previous shutdownApplicationsRegister call.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

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

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

-1Invalid parameters

The clientId parameter was not provided

Example

luna-send -n 1 luna://com.webos.service.sleep/shutdown/shutdownApplicationsAck '{"clientId":"/var/run/ls2/T4fb64.4"}'


shutdown/shutdownApplicationsRegister

Description

Register an application for the "shutdownApplications" signal. Send the client id of the client.

Parameters

Name

Required

Type

Description

clientNameRequiredstring

A unique name which the caller decides for the application

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

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

This is a unique token generated for this client by this method, which should be used by the caller for acking the shutdownApplications signal later.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

-1Invalid parameters

The clientName parameter was not provided

Example

luna-send -n 1 luna://com.webos.service.sleep/shutdown/shutdownApplicationsRegister '{"clientName":"facebook app"}'

Response:

{ "returnValue":true, "clientId":"/var/run/ls2/T4fb64.4" }


shutdown/shutdownServicesAck

Description

This method will set the client's response as ACK for the "shutdownServices" signal and trigger the dispatcher for the shutdown state machine, so that if the total client ACK count exceeds total number of clients, it can proceed to the next state.

Parameters

Name

Required

Type

Description

clientIDRequiredstring

The unique token for this client which was generated in a previous shutdownServicesRegister call.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

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

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

-1Invalid parameters

The clientId parameter was not provided

Example

luna-send -n 1 luna://com.webos.service.sleep/shutdown/shutdownServicesAck '{"clientId":"/var/run/ls2/T4fb64.5"}'

Response:

{ "returnValue":true }


shutdown/shutdownServicesRegister

Description

Register an application for the "shutdownApplications" signal. Send the client id of the client added.

Parameters

Name

Required

Type

Description

clientNameRequiredstring

A unique name which the caller decides for the application

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

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

This is a unique token generated for this client by this method, which should be used by the caller for acking the shutdownApplications signal later.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

-1Invalid parameters

The clientName parameter was not provided

Example

luna-send -n 1 luna://com.webos.service.sleep/shutdown/shutdownServicesRegister '{"clientName":"facebook service"}'

Response:

{ "returnValue":true, "clientId":"/var/run/ls2/T4fb64.5" }


timeout/clear

Description

Handle a timeout/clear message and delete a timeout by its key.

Parameters

Name

Required

Type

Description

keyRequiredstring

Unique identifier for the alarm

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. 
keyOptionalString

Unique identifier for the alarm

Example

luna-send -n 1 luna://com.webos.service.sleep/timeout/clear

'{

    "key":"com.webos.service.activitymanager.wakeup"

}'

Response:

{

    "returnValue":true,

    "key":"com.webos.service.activitymanager.wakeup"

}


timeout/set

Description

Handle a timeout/set message and add a new power timeout. Relative timeouts can be set by passing the "in" parameter. Absolute timeouts can be set by passing the "at" parameter.

Parameters

Name

Required

Type

Description

keyRequiredstringunique key to identify individual alarms
atRequiredstringAbsolute time for the alarm to be set to. Either this or the "in" parameter must be passed.
inRequiredstringRelative time for the alarm to be set to. Either this or the "at" parameter must be passed.
uriRequiredstringUri to be passed to the alarm
paramsRequiredstringparameters for the uri
wakeupRequiredbooleanif a wakeup alarm needs to be set.
activity_idOptionalstringActivity ID
activity_duration_msOptionalnumberDescription here
keep_existingOptionalbooleanset to true to keep existing alarms with the same key

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. 
keyRequiredString

Unique key used to identify the alarm

Example

luna-send -n 1 luna://com.webos.service.sleep/timeout/set

'{

    "at":"03/12/2014 06:26:46",

    "key":"com.webos.service.activitymanager.wakeup",

    "params":{},

    "uri":"luna://com.webos.service.activitymanager/callback/scheduledwakeup",

    "wakeup":true

}'

Response:

{

    "returnValue":true,

    "key":"com.webos.service.activitymanager.wakeup"

}


Objects

CallReturn

Default object returned by methods.

Name

Required

Type

Description

returnValueRequiredString

If the method succeeds returnValue will contain true.

If the method fails, returnValue will contain false​ and an error code and error message in the errorCode and errorText fields respectively.

errorCodeOptionalNumber

If the method fails, it will return an error code number in errorCode

errorTextOptionalString

If the method fails, it will return an error message describing the reason for failure in errorText

IdRequiredString

Pipeline Id

identifyReturn

Object returned by the identify method.

Name

Required

Type

Description

clientIdOptionalStringid of the client
returnValueOptionalBooleanreturn true if success
errorTextOptionalStringerror message if call fails
subscribedOptionalBooleantrue if subscribed

shutdownApplicationsRegisterReturn

Object returned by shutdownApplicationsRegister.

Name

Required

Type

Description

clientIdRequiredNumberClient ID.

shutdownServicesRegisterReturn

Object returned by shutdownServicesRegister

Name

Required

Type

Description

clientIdRequiredBooleanClient ID.

alarmAddReturn

Object returned by alarmAdd.

Name

Required

Type

Description

subscribedOptionalBooleanif subscription is successful
alarmIdOptionalNumberalarmId if the alarm was successfully added
returnValueRequiredBooleantrue if the call was successful
errorTextOptionalStringError message on failure

alarmAddSubscriptionReturn

Object returned when alarmAdd is called with subscribe set as true.

Name

Required

Type

Description

alarmIdRequiredNumberid of the alarm that was added
firedRequiredBooleantrue if the alarm has fired

alarmAddCalendarReturn

Object returned by alarmAddCalendar.

Name

Required

Type

Description

subscribedOptionalBooleanif subscription has been successful
alarmIdOptionalNumberid of the alarm when successfully created
returnValueRequiredBooleanif the call was successful
errorTextOptionalStringerror message when the call fails
serviceNameOptionalStringName of the service for which add alarm failed.

alarmAddCalendarSubscriptionReturn

Object returned by the alarmAddCalendar method when subscribed.

Name

Required

Type

Description

alarmIdRequiredNumberid of the alarm
firedRequiredBooleanif the alarm has been fired

alarmQueryReturn

Object returned by the alarmQuery method.

Name

Required

Type

Description

alarmsOptionalObject array[alarm]
returnValueRequiredBooleantrue if call is successful
errorTextOptionalStringError message if call fails

clearReturn

Object returned by the clear method.

Name

Required

Type

Description

returnValueRequiredBooleantrue if successful
errorTextOptionalStringreturned if failure
keyOptionalStringkey of the alarm that was cleared, returned if successful

setReturn

Object returned by the set method.

Name

Required

Type

Description

returnValueRequiredBooleantrue if success
keyOptionalStringDescription here
kept_existingOptionalBooleanIf the existing alarms have been kept
errorTextOptionalStringWill be sent only when there is an error.

Signals/Events

prepareSuspend

Provide a detailed description of the API signal. Do not include any code samples here.

suspendRequest

Provide a detailed description of the API signal. Do not include any code samples here.

shutdown/shutdownApplications

This is the signal sent out by the sleepd daemon to the applications when the shutdown process starts. The daemon expects to get a response from all the registered applications if they are ready for the system shutdown.

shutdown/shutdownServices

This is the signal sent out by the sleepd daemon to the services when the shutdown process starts. The daemon expects to get a response from all the registered services if they are ready for the system shutdown.


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