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

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 acknowledgement (ACK) or negative acknowledgement (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.

Methods

shutdown/initiate

Description

Starts the shutdown process by sending the shutdownApplications and shutdownServices signals to all the registered apps/services.

Returns "true" once the shutdown process is complete and the system decides that it can shutdown.

Note: This call does not do the actual shutdown; instead use the 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 Codes Reference

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":"localKey"}'
 

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 Codes Reference

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":"ota"}'
 

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 acknowledging 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 Codes Reference

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

Sets 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 Codes Reference

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"}'

 

Response:


  "returnValue":true
}

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 acknowledging 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 Codes Reference

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

Sets 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 Codes Reference

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

suspend/suspendRequest

Informs registered clients that the system thinks it is the right time to suspend, and wants to get the client response. Client should respond via the suspendRequestAck whether it is ready for a suspend at this moment.

suspend/prepareSuspend

Informs registered clients that the system is about to suspend so it is the last chance for them to stop it. Client should respond via the prepareSuspendAck method indicating whether or not it is able to suspend at this moment.

suspend/resume

Informs clients that the system has resumed operation from a previous suspend. The signal is sent if any client NACKs to the prepareSuspend signal, indicating the suspend has been aborted.

Call Returns

Name

Required

Type

Description

resumetypeRequiredString

The reason for resume can be following types:

  • 0 - System woke up from sleep normally
  • 1 - System did not really sleep but had to prevent the sleep because an activity was active
  • 2 - System did not suspend but had to prevent the suspend because one or more client(s) responded with NACK for prepareSuspend signal sent from sleepd

suspend/suspended

Informs clients that the system is just making the kernel call to suspend the system.

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.

Contents