com.webos.service.power

API Summary

The com.webos.service.power service is provided by the sleep daemon (sleepd), and allows applications to interact with (e.g. defer or prevent) the system suspend/resume cycle.

Overview of the API

(click to expand)

Sleep/Wake Process:

The sleep daemon (sleepd) transitions the system (and ultimately the device) from "On" to "Sleep" (and back).  Clients that wish to be notified of these transitions and optionally defer or prevent them must first register with sleepd using the "suspend/identify" method.  Clients may unregister using the "suspend/clientCancelByName" method.

When sleepd determines that the device is idle and could be suspended, it will transition to the "suspendRequest" state.

In the "suspendRequest" state, sleepd will broadcast the "suspendRequest" signal to all clients which have registered for this signal using the "suspend/suspendRequestRegister" method and will wait a maximum of 30 seconds for all responses. Each registered client should respond back with an ACK or NACK using the "suspend/suspendRequestAck" method. If any client responds with a NACK, sleepd will simply return to the "On" state. However, if all clients respond back with an ACK, or the "SuspendRequest" timeout expires, sleepd will transition to the "PrepareSuspend" state.

In the "prepareSuspend" state, sleepd will broadcast the "prepareSuspend" signal to all clients which have registered for this signal using the "suspend/prepareSuspendRegister" method and will wait a maximum of five seconds for all responses. Each registered client should respond back with an ACK or NACK using the "suspend/prepareSuspendAck" method. If any client responds with a NACK, sleepd will broadcast the "Resume" signal and return to the "On" state. However, if all clients respond back with an ACK, or the "prepareSuspend" timeout expires, sleepd will transition to the "Sleep" state.

In the "Sleep" state, sleepd will broadcast the "Suspended" signal to all clients and then check for activities which have been registered using the "suspend/activityStart" method. If sleepd finds a registered activity that is active, it will broadcast the "Resume" signal and return to the "On" state.  Otherwise, it will let the device go to sleep.  After the device wakes from sleep, sleepd will broadcast the "Resume" signal and return to the "On" state.

Clients may cancel a previously registered activity using the "suspend/activityEnd" method.

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 true

Example

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

Response:

{ "success":true }

 


shutdown/machineOff

Description

Shuts down the system forcefully

Parameters

Name

Required

Type

Description

reasonRequiredString

The reason why caller wants to shutdown the system

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

returnValueOptionalBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check  "errorText" fields 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.power/shutdown/machineOff '{"reason":"power off"}'

Response:

{ "returnValue":true }


shutdown/machineReboot

Description

Reboots the system forcefully.

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" fields 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.power/shutdown/machineReboot '{"reason":"none"}'

Response:

{ "returnValue":true }


shutdown/shutdownApplicationsRegister

Description

Register an application for the "shutdownApplications" signal. The caller provides a unique name for the application with this method.

Parameters

Name

Required

Type

Description

clientNameRequiredString

A unique name which the caller decides for the application

Call Returns

Name

Required

Type

Description

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.

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check  "errorText" fields 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 clientName parameter was not provided

Example

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

Response:

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


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 is equal to the 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" fields 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.power/shutdown/shutdownApplicationsAck '{"clientId":"/var/run/ls2/T4fb64.4"}'

shutdown/shutdownServicesRegister

Description

Register an application for the "shutdownServices" signal. The caller provides a unique name for the application with this method.

Parameters

Name

Required

Type

Description

clientNameRequiredString

A unique name which the caller decides for the application

Call Returns

Name

Required

Type

Description

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.

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check  "errorText" fields 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 clientName parameter was not provided

Example

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

Response:

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


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 is equal to the 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" fields 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.power/shutdown/shutdownServicesAck '{"clientId":"/var/run/ls2/T4fb64.5"}'

Response:

{ "returnValue":true }


Signals/Events

shutdown/shutdownApplications

This is the signal sent out by the sleepd daemon 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 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.