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

ACG: sleep.management

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

successRequiredBoolean

Always returns true

Example

Example scenario

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

 

Response:


  "success":true
}

shutdown/machineOff

ACG: sleep.management

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

Error Code

Error Text

Error Description

-1Invalid 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

ACG: sleep.management

Description

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

Error Code

Error Text

Error Description

-1Invalid 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

ACG: sleep.management

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

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

Error Code

Error Text

Error Description

-1Invalid 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

ACG: sleep.management

Description

Registers an application for the "shutdownApplications" signal. Returns 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 acknowledging 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 Codes Reference

Error Code

Error Text

Error Description

-1Invalid 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

ACG: sleep.management

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

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

Error Code

Error Text

Error Description

-1Invalid 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

ACG: sleep.management

Description

Registers an application for the "shutdownApplications" signal. Returns 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 acknowledging 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 Codes Reference

Error Code

Error Text

Error Description

-1Invalid 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

ACG: sleep.operation

Description

Handles a timeout/clear message and deletes 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

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

-1Malformed JSON object

Invalid JSON data

-1Invalid 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

ACG: sleep.operation

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

keyRequiredString

Unique key to identify individual alarms

atRequiredString

Absolute time for the alarm to be set to. Either this or the "in" parameter must be passed.

inRequiredString

Relative time for the alarm to be set to. Either this or the "at" parameter must be passed.

uriRequiredString

URI to be passed to the alarm

paramsRequiredString

Parameters for the URI.

wakeupOptionalBoolean

If a wakeup alarm needs to be set.

activity_idOptionalString

Activity ID

activity_duration_msOptionalNumber

Duration in milliseconds to keep the device ON. Needs to be provided only if activity_id is provided.

keep_existingOptionalBoolean

Set 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

kept_existingOptionalBoolean

If the existing alarms have been kept

errorTextOptionalString

Indicates the reason for the failure of the operation.

Error Codes Reference

Error Code

Error Text

Error Description

-1Malformed 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.

Contents