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
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 with an acknowledgement (ACK) using the "shutdown/shutdownApplicationsAck" method. As soon as all clients respond 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 with an ACK using the "shutdown/shutdownServicesAck" method. As soon as all clients respond 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. It sends 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 |
|---|---|---|---|
| success | Required | Boolean | Always returns true |
Example
Example scenario
# 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 |
|---|---|---|---|
| reason | Required | string | Reason for the shutdown. Possible reasons are:
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| 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" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -1 | Invalid parameters | The reason parameter was not provided. |
Example
Example scenario
# luna-send -n 1 luna://com.webos.service.sleep/shutdown/machineOff '{"reason":"remoteKey"}'
Response:
{
"returnValue":true
}
shutdown/machineReboot
Description
Reboots the machine forcefully by calling "reboot".
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| reason | Required | string | The reason why caller wants to reboot the system. Possible reasons are:
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| 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" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -1 | Invalid parameters | The reason parameter was not provided |
Example
Example scenario
# luna-send -n 1 luna://com.webos.service.sleep/shutdown/machineReboot '{"reason":"reset"}'
Response:
{
"returnValue":true
}
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 exceeds total number of clients, it can proceed to the next state.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| clientId | Required | string | The unique token for this client which was generated in a previous shutdownApplicationsRegister call. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| 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" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -1 | Invalid parameters | The clientId parameter was not provided |
Example
Example scenario
# luna-send -n 1 luna://com.webos.service.sleep/shutdown/shutdownApplicationsAck '{"clientId":"/var/run/ls2/T4fb64.4"}'
Response:
{
"returnValue":true
}
shutdown/shutdownApplicationsRegister
Description
Registers an application for the "shutdownApplications" signal. Returns the client ID of the client.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| clientName | Required | string | A unique name which the caller decides for the application. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| clientId | Required | String | 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. |
| errorText | Optional | String | 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 |
|---|---|---|
| -1 | Invalid parameters | The clientName parameter was not provided |
Example
Example scenario
# 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
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 exceeds total number of clients, it can proceed to the next state.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| clientId | Required | string | The unique token for this client which was generated in a previous shutdownServicesRegister call. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| 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" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -1 | Invalid parameters | The clientId parameter was not provided |
Example
Example scenario
# luna-send -n 1 luna://com.webos.service.sleep/shutdown/shutdownServicesAck '{"clientId":"/var/run/ls2/T4fb64.5"}'
Response:
{
"returnValue":true
}
shutdown/shutdownServicesRegister
Description
Registers an application for the "shutdownApplications" signal. Returns the client ID of the client added.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| clientName | Required | string | A unique name which the caller decides for the application |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| clientId | Required | String | 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. |
| errorText | Optional | String | 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 |
|---|---|---|
| -1 | Invalid parameters | The clientName parameter was not provided |
Example
Example scenario
# 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
Handles a timeout/clear message and deletes a timeout by its key.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| key | Required | string | Unique identifier for the alarm |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| key | Optional | String | Unique identifier for the alarm |
| errorText | Optional | String | 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 |
|---|---|---|
| -1 | Malformed JSON object | Invalid JSON data |
| -1 | Invalid parameters | Invalid parameters data received |
Example
Example scenario
# 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
Handles a timeout/set message and adds 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 |
|---|---|---|---|
| key | Required | String | Unique key to identify individual alarms |
| at | Required | String | Absolute time for the alarm to be set to. Either this or the "in" parameter must be passed. |
| in | Required | String | Relative time for the alarm to be set to. Either this or the "at" parameter must be passed. |
| uri | Required | String | URI to be passed to the alarm |
| params | Required | String | Parameters for the URI. |
| wakeup | Optional | Boolean | If a wakeup alarm needs to be set. |
| activity_id | Optional | String | Activity ID |
| activity_duration_ms | Optional | Number | Duration in milliseconds to keep the device ON. Needs to be provided only if activity_id is provided. |
| keep_existing | Optional | Boolean | Set to true to keep existing alarms with the same key |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| key | Required | String | Unique key used to identify the alarm |
| kept_existing | Optional | Boolean | If the existing alarms have been kept |
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -1 | Malformed JSON object | Invalid JSON data |
Example
Example scenario
# 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"
}
Signals/Events
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.