com.webos.service.systemservice

Note
This API has been available since API level 11.

API Summary

Provides access to the webOS system settings such as:

Backup options
Getting device information
Getting and modifying the date and time settings
Setting ringtones
Wallpaper
Local formats

Overview of the API

This service must be used when an application needs to read or modify system settings. It should not be used to implement any business functionality, such as saving business data through backup procedures. It is often used by UI applications.

This service provides a group of system utilities:

backup - backs up the systemprefs database
clock - manage clock settings
deviceInfo - query device information
erase - options to erase specified partition
osInfo - query OS information
softwareInfo - query software information
time - manage time settings
ringtone - options to add or delete ringtones
wallpaper - manage wallpaper settings
preferences - options to store and load preferences

Preferences

These values represent system settings which can be queried or modified. Some of them are read-only or write-only, some values are hardware specific(like ringtone). A list of system preference values:

locale
timeSources
region
ringtone
useNetworkTime
useNetworkTimeZone
timeZone
timeFormat
timeChangeLaunch - list of ls2 uris to launch when time is changed
timeDriftPeriodHr - time refresh period
wallpaper

User can set their own values, these values will be stored permanently. Custom values can be used to save program settings.

There are three functions to manage preference values:

getPreferences - get system/custom preference values
setPreferences - set system/custom preferences values
getPreferenceValues - get vaild values for system preferences

Methods

backup/postRestore

ACG: systemsettings.management

Added: API level 11

Description

Restores the platform-specific environment settings from the dump file, previously created by the preBackup method call.

Call this method after executing the restore procedure in order to restore platform-specific settings.

The dump files are saved into the directory specified by the temp_dir parameter.

This method is internal, only system applications can use it. It is not available to third-party applications.

Parameters

Name	Required	Type	Description
tempDir	Required	String	Directory to store temporarily generated files (files that are to be restored).
files	Required	string array	List of files to restore.

Call Returns

Name	Required	Type	Description
returnValue	Required	boolean	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
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Name

Required

Type

Description

returnValue

Required

boolean

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

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
None	Required Arguments Missing.	Some of the arguments required for this method have not been provided.
None	Invalid arguments.	Some of the arguments provided to the method have invalid values.

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.systemservice/backup/postRestore '{
"tempDir": "/tmp/",
"files": ["/var/luna/preferences/systemprefs_backup.db"]
}'

Response:

{
"returnValue": true
}

backup/preBackup

ACG: systemsettings.management

Added: API level 11

Description

The preBackup method creates dump files containing platform-specific environment settings. Call this method before executing the backup procedure in order to save these settings.

The dump files are saved into the directory specified by the temp_dir parameter or '${localstatedir}/preferences'.

The list of the platform-specific settings that are saved in the dump file is specified in the sysservice-backupkeys.json file. Below is an example of this file:

[
   "useNetworkTime",
   "useNetworkTimeZone",
   "timeZone",
   "timeChangeLaunch",
   "showcontactmatch",
"x_webos_virtualkeyboard_prefs"
]

If any of the method parameters is not specified or specified incorrectly, the method will use the default values.

This method is internal, only system applications can use it. It is not available to third-party applications.

Parameters

Name	Required	Type	Description
incrementalKey	Optional	object	This is used primarily for mojodb, backup service will handle other incremental backups.
maxTempBytes	Optional	number	The allowed size of upload. It is currently set at 10MB.
tempDir	Optional	string	Directory to store temporarily generated files.

Call Returns

Name	Required	Type	Description
description	Required	string	Describes the backup.
version	Required	string	Version of the backup.
files	Required	string array	List of files included in the backup.

Name

Required

Type

Description

description

Required

string

Describes the backup.

version

Required

string

Version of the backup.

files

Required

string array

List of files included in the backup.

Example

Example code

Example response for a successful call:

# luna-send -n 1 -f luna://com.webos.service.systemservice/backup/preBackup '{}'

{

"description": "Backup of LunaSysService, containing the systemprefs sqlite3 database",

"version": "1.0",

"files": [

"\/var\/luna\/preferences\/systemprefs_backup.db"

]

}

clock/getTime

ACG: time.query

Added: API level 11

Description

The getTime method gets the current time for a specific time source.

There are several time data sources on the system: Linux system time, user time, network-broadcast time and more. When calling this method, you can specify the desired time data source in the source parameter. The complete list of the data sources is listed in the source parameter description below.

Any application can use this method.

Parameters

Name	Required	Type	Description
source	Optional	String	Time-source to access (default "system") Supported sources: system - Linux system-wide time (always available) manual - Last time set manually by user sdp - time received with session initialization to server (ex. device membership registration) ntp - time periodically or by request received from NTP (Network Time Protocol) service nitz - time received over NITZ (Network Identity and Time Zone) from cellular network provider (ex. GSM operator) (Not Available in Auto) broadcast - time received through broadcast signal broadcast-adjusted - same as broadcast but adjusted in a way to represent time with offset from broadcast regional offset table after applying Linux system-wide time-zone Note: Some platforms may have different subsets of mentioned time sources according to the value of preference timeSources
manualOverride	Optional	Boolean	If manualOverride set to false means that source shouldn't be overriden by manual time when useNetworkTime is turned to false (use the time user specified manually). If useNetworkTime is set to false and manualOverride is set to true, get time specified in source parameter. If useNetworkTime is set to false and manualOverride is set to false, ignore the time in the source parameter and get the time from manual time. The default value of manualOverride is true and gets the time from the source parameter system. Note: useNetworkTime is a preference that is set by the setPreferences, getPreferences, and getPreferenceValues methods. The values for these preferences depend on the app or product that is being used.
fallback	Optional	String	Fall-back time source to use when requested one is missing. If not set and time-source specified in "source" is missing request will fail (unless overridden by manual time).

Name

Required

Type

Description

source

Optional

String

Time-source to access (default "system")
Supported sources:

system - Linux system-wide time (always available)
manual - Last time set manually by user
sdp - time received with session initialization to server (ex. device membership registration)
ntp - time periodically or by request received from NTP (Network Time Protocol) service
nitz - time received over NITZ (Network Identity and Time Zone) from cellular network provider (ex. GSM operator) (Not Available in Auto)
broadcast - time received through broadcast signal
broadcast-adjusted - same as broadcast but adjusted in a way to represent time with offset from broadcast regional offset table after applying Linux system-wide time-zone

Note: Some platforms may have different subsets of mentioned time sources according to the value of preference timeSources

manualOverride

Optional

Boolean

If manualOverride set to false means that source shouldn't be overriden by manual time when useNetworkTime is turned to false (use the time user specified manually).
If useNetworkTime is set to false and manualOverride is set to true, get time specified in source parameter.
If useNetworkTime is set to false and manualOverride is set to false, ignore the time in the source parameter and get the time from manual time.

The default value of manualOverride is true and gets the time from the source parameter system.

Note: useNetworkTime is a preference that is set by the setPreferences, getPreferences, and getPreferenceValues methods. The values for these preferences depend on the app or product that is being used.

fallback

Optional

String

Fall-back time source to use when requested one is missing. If not set and time-source specified in "source" is missing request will fail (unless overridden by manual time).

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
source	Required	String	Actual time source associated with result (either one specified in source or in fallback or manual if overridden).
utc	Optional	Number	Seconds since epoch for UTC.
offset	Optional	Object: TimeSourceOffset	Offset from some other time source (usually from system).
systemTimeSource	Optional	String	If system-wide system time is returned and this field is present, it will denote last time source used for system time synchronization.
priority	Optional	Number	Priority of returned time source (with higher level overrides one with lower).
timestamp	Optional	Object: Timestamp	Monotonic timestamp.
errorCode	Optional	Number	The error code for the failed operation.
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
None	Requested clock is not registered	Time source is not among list of available ones ("timeSources").
None	No time available for that clock	Requested time source not yet available (ex. no Internet for "ntp").
1	Could not validate json message against schema	The request data is invalid.

Example

Example code

Example of a successful call:

# luna-send -n 1 -f luna://com.webos.service.systemservice/clock/getTime '{}'

{

"source": "system",

"offset": {

"source": "system",

"value": 0

"systemTimeSource": "sdp",

"timestamp": {

"source": "monotonic",

"sec": 94528,

"nsec": 612100095

"returnValue": true,

"utc": 1448556831

}

clock/setTime

ACG: time.management,systemsettings.management

Added: API level 11

Description

The setTime method is used to set the time. By calling this method you can update any time data source, including Linux system time, network-broadcasted time, user time and others.

Any application can use this method.

After this method is called, the system services receives a notification about the time update.

Parameters

Name	Required	Type	Description
utc	Required	Number	Seconds since epoch in UTC time-zone. Note: Either utc field or available field is mandatory.
source	Optional	String	Time source associated with time info update (default "manual"). Only those sources that are listed in the timeSources Preference key can be set.
available	Required	Boolean	Availability flag. Set to false to specify that source is not available. Note: Either available field or utc field is mandatory.
timestamp	Optional	Object: Timestamp	Monotonic timestamp. If set, will be used to calculate a delay between sending and receipt of this request over luna-bus and add that to utc field.

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	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 . The clock/setTime method may fail because: Requested clock is not registered.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.
errorCode	Optional	Number	Error Code Number

Name

Required

Type

Description

returnValue

Required

Boolean

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

. The clock/setTime method may fail because:

Requested clock is not registered.

errorText

Optional

String

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

errorCode

Optional

Number

Error Code Number

Error Codes Reference

Error Code	Error Text	Error Description
None	Requested clock is not registered	Time source is not among list of available ones ("timeSources").
1	Could not validate json message against schema	The request data is invalid.

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.systemservice/clock/setTime '{"utc":1448556562}'

deviceInfo/query

ACG: systemsettings.query

Added: API level 11

Description

The query method to get the device system information such as product Id, system number, hardware information, Wi-FI address, battery status and others. Please refer to the return values table below for a complete list of the system parameters.

Note: This method must not be used by 3rd-party applications.

Parameters

Name	Required	Type	Description
parameters	Optional	String array	List of requested parameters. If not specified, all available parameters wiil be returned. Accepted parameters: battery_challange keyboard_type board_type product_id serial_number installer storage_size modem_present hardware_id ram_size hardware_revision wired_addr wifi_addr last_reset_type radio_type storage_free battery_response device_name nduid bt_addr device_id

Name

Required

Type

Description

parameters

Optional

String array

List of requested parameters. If not specified, all available parameters wiil be returned.

Accepted parameters:

battery_challange
keyboard_type
board_type
product_id
serial_number
installer
storage_size
modem_present
hardware_id
ram_size
hardware_revision
wired_addr
wifi_addr
last_reset_type
radio_type
storage_free
battery_response
device_name
nduid
bt_addr
device_id

Call Returns

Name	Required	Type	Description
battery_challange	Optional	String	Battery challenge. Currently, the "not supported" value is always returned. Note: There is a typo in the parameter name. Use the spelling as given in this table.
keyboard_type	Optional	String	Refers to the keyboard built into the device. Example: virtual
board_type	Optional	String	Board type.
product_id	Optional	String	Product ID.
serial_number	Optional	String	Serial number.
installer	Optional	String	Tool used to install the image. Currently, the "not supported" value is always returned.
storage_size	Optional	String	Storage size.
modem_present	Optional	String	Modem availability. Note: This parameter is "not supported", even though the response shows this value as "N" to indicate modem is not present.
hardware_id	Optional	String	Hardware ID.
ram_size	Optional	String	RAM size.
hardware_revision	Optional	String	Hardware revision.
wired_addr	Optional	String	Wired/Ethernet MAC address.
wifi_addr	Optional	String	WiFi MAC address.
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
last_reset_type	Optional	String	Reason code for last reboot (may come from /proc/cmdline). Currently, the "not supported" value is always returned.
radio_type	Optional	String	Internal ID code for the radio type. Currently, the "not supported" value is always returned.
storage_free	Optional	String	Free storage size. Currently, the "not supported" value is always returned.
battery_response	Optional	String	Battery response. Currently, the "not supported" value is always returned.
device_name	Optional	String	Device name.
nduid	Optional	String	NDUID.
bt_addr	Optional	String	Bluetooth address.
device_id	Optional	String	ID for uniquely identifying the device
errorCode	Optional	Number	The error code for the failed operation. Note:If the method fails, the errorText is always returned but the errorCode is returned only for specific errors..
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details.

Error Codes Reference

Error Code	Error Text	Error Description
None	Invalid message payload	JSON format is not valid
None	'parameters' needs to be an array	parameters field should be a JSON string array e.g. ["param1", "param2"]
None	Internal error. Can't initialize nyx	Failed to load nyx library.
None	Internal error. Can't open nyx device	Nyx library error.
None	Invalid parameter: + [parameter name]	The parameter mentioned in the error message is invalid.

Example

Example : General invocation

# luna-send -n 1 -f luna://com.webos.service.systemservice/deviceInfo/query '{}'

getPreferenceValues

ACG: systemsettings.query

Added: API level 11

Description

Retrieves a list of valid values for the specified key. If the key is of a type that takes one of a discrete set of valid values, it returns that set. Otherwise, it returns nothing for the key.

Parameters

Name	Required	Type	Description
key	Required	string	Key name to fetch preference values for. Accepted key names: locale region ringtone useNetworkTime useNetworkTimeZone timeZone timeFormat wallpaper

Name

Required

Type

Description

key

Required

string

Key name to fetch preference values for.

Accepted key names:

locale
region
ringtone
useNetworkTime
useNetworkTimeZone
timeZone
timeFormat
wallpaper

Call Returns

Name	Required	Type	Description
returnValue	Required	boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. The method can fail if the "key is not specified or is invalid".
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.
[key name]	Optional	Any array	Contains the set returned for the specified key name in command parameters.
syszones	Optional	Any array	Provides ZoneID with the respective time offset for different time zones.
mccInfo	Optional	Any array	Provides a 3 digit mobile country code [mcc], which signifies details of the region. Example: "mcc" : 460.

Error Codes Reference

Error Code	Error Text	Error Description
1	Could not validate json message against schema	The request data is invalid.
1	Can't find handler for key: " + [key name]	The handler for the key specified in the error message cannot be found.
2	Handler doesn't have values for key: " + [key name]	The handler countains no values for the key specified in the error message.

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.systemservice/getPreferenceValues '{"key": "useNetworkTime" }'

Response:

{
"useNetworkTime":[
true,
false
],
"returnValue":true
}

Example scenario

# luna-send -n 1 -f luna://com.webos.service.systemservice/getPreferenceValues '{ "key": "timeFormat" }'

Response:

{
"timeFormat":[
"HH12",
"HH24"
],
"returnValue":true
}

getPreferences

ACG: systemsettings.query

Added: API level 11

Description

The getPreferences method retrieves the values for keys specified in a passed array. If subscribe is set to true, then getPreferences sends an update if the key values change. This method queries system preference values and custom user values.

Parameters

Name	Required	Type	Description
subscribe	Optional	boolean	If subscribe is set to true, then getPreferences sends an update if the key values have changed.
keys	Required	string array	An array of key names. A key is a system preference or custom user key (see overview of this API for details). Accepted key names: locale region ringtone useNetworkTime useNetworkTimeZone timeZone timeFormat timeChangeLaunch timeDriftPeriodHr wallpaper

Name

Required

Type

Description

Optional

boolean

If subscribe is set to true, then getPreferences sends an update if the key values have changed.

keys

Required

string array

An array of key names. A key is a system preference or custom user key (see overview of this API for details).

Accepted key names:

locale
region
ringtone
useNetworkTime
useNetworkTimeZone
timeZone
timeFormat
timeChangeLaunch
timeDriftPeriodHr
wallpaper

Call Returns

Name	Required	Type	Description
subscribed	Optional	boolean	True if the subscription was successful
returnValue	Required	boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
errorCode	Optional	Number	The error code for the failed operation.
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
None	no keys specified	The keys property has not been provided to the method.
None	no key array specified	The keys property provided is not an array.
None	invalid key array	The keys array does not have any values.
None	invalid value encoded in preference("did you escape your strings?")	Subset of requested values have preferences that contain invalid json representation.
1	Could not validate json message against schema	The request data is invalid.

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.systemservice/getPreferences '{"keys": ["locale"]}'

Response:

{
   "subscribed":false,
   "locale":{
      "languageCode":"en",
      "phoneRegion":{
         "countryName":"United States",
         "countryCode":"us"
      },
      "countryCode":"us"
   },
   "returnValue":true
}

osInfo/query

ACG: systemsettings.query

Added: API level 11

Description

The query method returns operating system information. This method may be used to display the operating system version, API version, build name and date and so on.

This method is available for both internal and third-party applications.

Parameters

Name	Required	Type	Description
parameters	Optional	String array	List of requested parameters. If not specified, all available parameters will be returned. The available parameters are those listed under the Name column under the Return section below (with the exception of errorCode and errorText).

Name

Required

Type

Description

parameters

Optional

String array

List of requested parameters. If not specified, all available parameters will be returned.

The available parameters are those listed under the Name column under the Return section below (with the exception of errorCode and errorText).

Call Returns

Name	Required	Type	Description
core_os_kernel_version	Optional	String	Core OS kernel version info
core_os_name	Optional	String	Core OS name
core_os_release	Optional	String	Core OS release info
core_os_release_codename	Optional	String	Core OS release codename
webos_build_datetime	Optional	String	The UTC timestamp reflecting when the current image was built. The string is in the format "YYYYMMDDhhmmss".
webos_build_id	Optional	String	webOS build ID
webos_imagename	Optional	String	webOS imagename
webos_name	Optional	String	webOS name
webos_prerelease	Optional	String	webOS prerelease info
webos_release	Optional	String	webOS release info
webos_release_codename	Optional	String	webOS release codename
webos_manufacturing_version	Optional	String	webOS manufacting version
encryption_key_type	Optional	String	Encryption key type
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details.

Error Codes Reference

Error Code	Error Text	Error Description
None	'parameters' needs to be an array	The parameters parameter must be an array.
None	Can not initialize nyx	Internal error. Can't initialize nyx.
None	Internal error. Can't open nyx device	Nyx API error
None	Can't get OS parameter:	Failed to retrieve information for <parameter> where<parameter> is the name of one of the requested parameters passed to this method.
None	Invalid parameter: +	The <parameter name> specified in the error message is invalid.
None	Invalid message payload	The request JSON payload contains invalid data.

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.systemservice/osInfo/query '{
"parameters":[
  "webos_name",
  "webos_release",
  "webos_build_id"
]
}'

Response:

{
   "webos_release":"1.0.p",
   "webos_build_id":"4",
   "webos_name":"webOS OSE",
   "returnValue":true
}

ringtone/addRingtone

ACG: systemsettings.management

Added: API level 11

Description

Adds a new ringtone on devices that use ringtones.

Note: This method is public. It can be used both by the system and third-party applications.

Parameters

Name	Required	Type	Description
filePath	Required	String	Absolute path to the ringtone file. Note: The ringtone file needs to be copied manually to the target prior to using this API

Name

Required

Type

Description

filePath

Required

String

Absolute path to the ringtone file.

Note: The ringtone file needs to be copied manually to the target prior to using this API

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	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
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Name

Required

Type

Description

returnValue

Required

Boolean

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

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
None	invalid specification for source file (please use url format)	File path in wrong format should be (file:://path/to/file)
None	input file specification doesn't support non-local files (use file:///path/file or /path/file format	input file specification does not support non-local files (use file:///path/file or /path/file format)
None	source file name missing.	Can not find file at current path
None	Unable to add ringtone.	Failed to copy ringtone to media partition.
None	Source file doesn't exist	Note: The ringtone file needs to be copied manually to the target first. Note: #cp <local_directory>/ringtone.mp3 /usr/palm/sounds/ The file could not be found by the specified filepath.

Example

Example : Copy the ringtone file (.mp3) to desired location, for example (/usr/palm/sounds/)

# luna-send -n 1 -f luna://com.webos.service.systemservice/ringtone/addRingtone '{"filePath": "/usr/palm/sounds/ringtone.mp3" }'

Response:

{
"returnValue": true
}

ringtone/deleteRingtone

ACG: systemsettings.management

Added: API level 11

Description

Deletes a ringtone.

Note: This method is public. It can be used both by the system and third-party applications.

Parameters

Name	Required	Type	Description
filePath	Required	String	Absolute path to the ringtone file. The directory must be given only as "/media/internal/ringtones/" Note: The ringtone file needs to be added via addRingtone API prior to using this API.

Name

Required

Type

Description

filePath

Required

String

Absolute path to the ringtone file. The directory must be given only as "/media/internal/ringtones/"

Note: The ringtone file needs to be added via addRingtone API prior to using this API.

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	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
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Name

Required

Type

Description

returnValue

Required

Boolean

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

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
None	file doesn't exist	Specified file doesn't exist
None	source file name missing.	specified file to path does not contain the name of file (for example "foo/bar/" but not "foo/bar.mp3")
None	Unable to delete ringtone.	Note: The ringtone file must be present in the location Unable to delete ringtone.

Error Code

Error Text

Error Description

None

file doesn't exist

Specified file doesn't exist

None

source file name missing.

specified file to path does not contain the name of file (for example "foo/bar/" but not "foo/bar.mp3")

None

Unable to delete ringtone.

Note: The ringtone file must be present in the location

Unable to delete ringtone.

Example

Example code

// The ringtone file must be present in "/media/internal/ringtones/"

# luna-send -n 1 -f luna://com.webos.service.systemservice/ringtone/deleteRingtone '{"filePath": "/media/internal/ringtones/ringtone.mp3" }'

Response:

{
"returnValue": true
}

setPreferences

ACG: systemsettings.management

Added: API level 11

Description

The setPreferences method sets preference keys to specified values. The values are specified by pair: key - value in JSON format. See the example below.

Note: This method is public. It can be used both by the system and third-party applications.

Parameters

Name	Required	Type	Description
param208	Optional	Object	Each such param represents a key-value pair of preference name and its value. Existing key values are: locale region ringtone useNetworkTime useNetworkTimeZone timeZone timeFormat timeDriftPeriodHr wallpaper New key will be created if any other key is specified.

Name

Required

Type

Description

param208

Optional

Object

Each such param represents a key-value pair of preference name and its value.

Existing key values are:

locale
region
ringtone
useNetworkTime
useNetworkTimeZone
timeZone
timeFormat
timeDriftPeriodHr
wallpaper

New key will be created if any other key is specified.

Call Returns

Name	Required	Type	Description
returnValue	Required	boolean	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
errorText	Optional	string	Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Name

Required

Type

Description

returnValue

Required

boolean

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

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
None	Some settings could not be saved	Some settings could not be saved

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.systemservice/setPreferences '{ "timeZone": {"ZoneID":"Europe/Kiev"}, "timeFormat": "HH12" }'

softwareInfo/query

ACG: software.query

Added: API level 15

Description

Returns details of software deployed on the webOS device.

Note: Currently, returns only the nodejs version.

Parameters

Name	Required	Type	Description
parameters	Optional	String array	List of requested parameters. Possible values: nodejs_versions Note: If no value is specified, all available parameters are returned:

Name

Required

Type

Description

parameters

Optional

String array

List of requested parameters.

Possible values:

nodejs_versions

Note: If no value is specified, all available parameters are returned:

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Operation is successful. false: Operation has failed. Check the 'errorCode' and 'errorText' fields.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	The reason for the failure of the operation. See the 'Error Codes' section of this method for details.
nodejs_versions	Optional	String array	Versions of nodejs that are available on the webOS device.

Error Codes Reference

Error Code	Error Text	Error Description
None	Invalid parameter: +	The <parameter name> specified in the request is invalid.
None	'parameters' needs to be an array	The 'parameters' parameter must be provided as an array.
None	Invalid message payload	The request JSON payload contains invalid data.
None	Could not validate json message against schema	Anything other than parameters is passed.

Example

Example : Querying the nodejs version

# luna-send -n 1 -f luna://com.webos.service.systemservice/softwareInfo/query '{
"parameters":[
"nodejs_versions"
]
}'

Response:

{
"returnValue": true,
"nodejs_versions": [
"v8.17.0",
"v6.17.1"
]
}

time/convertDate

ACG: time.management

Added: API level 11

Description

The convertDate method converts the given date from one timezone to another.

Parameters

Name	Required	Type	Description
date	Required	String	Date to convert as a string in format: "Y-m-d H:M:S".
source_tz	Required	String	Source timezone.
dest_tz	Required	String	Destination timezone.

Call Returns

Name	Required	Type	Description
date	Required	String	The date in the destination timezone if the call was successful.
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorText" field for details
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Name

Required

Type

Description

date

Required

String

The date in the destination timezone if the call was successful.

returnValue

Required

Boolean

Indicates the status of operation. Possible values are:

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

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
None	Unrecognized date format:	Date format is unrecognized.
None	unrecognized characters in date:	Characters in date are unrecognized.
None	Timezone not found:	Timezone with the specified name is not found. Depending on which time zone is not recognized, either source timezone or detination time zone name will be specified in the error message.

Example

Example code

Example of a successful call:

# luna-send -n 1 -f luna://com.webos.service.systemservice/time/convertDate '{
  "date": "1982-12-06 17:25:33",
  "source_tz": "America/Los_Angeles",
  "dest_tz":"America/New_York"
}'

{

"returnValue": true,

"date": "Mon Dec 6 19:25:33 1982"

}

Example of a failed call:

# luna-send -n 1 -f luna://com.webos.service.systemservice/time/convertDate '{
  "date": "1982-12-06 17:25:33",
  "source_tz": "America/Los_Angeles",
  "dest_tz":"America/New_York1"
}'

{

"returnValue": false,

"errorText": "timezone not found: 'America/New_York1'"

}

time/getBroadcastTime

ACG: time.query

Added: API level 11

Description

The getBroadcastTime method returns the broadcast time.

Parameters

None

Call Returns

Name	Required	Type	Description
utc	Required	Number	Seconds since epoch for UTC time-zone
local	Optional	Number	Seconds since epoch with offset according to broadcast regional offsets table
localtime	Optional	Object: LocalTime	Calendar representation of local time
timestamp	Optional	Object: Timestamp	Monotonic timestamp.
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
errorCode	Optional	Number	The error code for the failed operation.
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
-2	No information available	No broadcast time information available since boot

Example

Example code

Example of a successful call:

# luna-send -n 1 -f luna://com.webos.service.systemservice/time/getBroadcastTime '{}'

{

"utc": 1418745993,

"localtime": {

"month": 12,

"day": 16,

"hour": 11,

"minute": 0,

"year": 2014,

"second": 41

"local": 1418727641,

"timestamp": {

"source": "monotonic",

"sec": 94707,

"nsec": 141357576

"returnValue": true

}

time/getCurrentTimeZoneByLocale

ACG: time.query

Added: API level 11

Description

Returns the locale info matching the requested locale settings. In particular, the name of the city is returned on the language for which the code is specified in the locale request parameter.

Parameters

Name	Required	Type	Description
locale	Required	String	The requested locale code. For example: "en" - English, "de" - German, "ko" - Korean. If the wrong locale code is specified, the method will return the default time zone locale data.

Name

Required

Type

Description

locale

Required

String

The requested locale code. For example: "en" - English, "de" - German, "ko" - Korean.

If the wrong locale code is specified, the method will return the default time zone locale data.

Call Returns

Name	Required	Type	Description
timeZone	Optional	String	The timezone matching the given parameters.
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorText" field for details
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Name

Required

Type

Description

timeZone

Optional

String

The timezone matching the given parameters.

returnValue

Required

Boolean

Indicates the status of operation. Possible values are:

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

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
None	'locale' parameter missing	The locale parameter is not specified in the request. You must specify the locale (e.g. "en" for English, "de" for German) in the request.

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.systemservice/time/getCurrentTimeZoneByLocale '{"locale":"ko"}'

Response:

{
"timeZone":{
"supportDST":0,
"offsetFromUTC":-480,
"City":"로스앤젤레스",
"CountryCode":"US",
"Description":"Pacific Time",
"Country":"United States of America",
"ZoneID":"America/Los_Angeles",
"preferred":true
},
"returnValue":true
}

time/getEffectiveBroadcastTime

ACG: time.query

Added: API level 11

Description

The getEffectiveBroadcastTime method returns the effective broadcast time. If no broadcast time info update has been received since boot, the Linux system-wide time is returned.

Parameters

Name	Required	Type	Description
subscribe	Optional	Boolean	Subscribe for notifications. Possible values are: true - Get notifications false - Notifications are not required Default value: false

Name

Required

Type

Description

Optional

Boolean

Subscribe for notifications. Possible values are:

true - Get notifications
false - Notifications are not required

Default value: false

Call Returns

Name	Required	Type	Description
subscribed	Optional	Boolean	True if the subscription was successful.
adjustedUtc	Required	Number	Seconds since epoch suitable for converting from UTC to local time which corresponds with appropriate broadcast regional offset table entry
local	Required	Number	Seconds since epoch with offset according to broadcast regional offsets table
localtime	Optional	Object: LocalTime	Calendar representation of local time.
timestamp	Optional	Object: Timestamp	Monotonic timestamp
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
errorCode	Optional	Number	The error code for the failed operation.
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	Failed to get localtime	Failed to get localtime
1	Could not validate json message against schema	The request data is invalid.

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.systemservice/time/getEffectiveBroadcastTime '{}'

Response:

{
   "timestamp":{
      "source":"monotonic",
      "sec":94707,
      "nsec":141357576
   },
   "localtime":{
      "month":11,
      "day":26,
      "hour":8,
      "minute":56,
      "year":2015,
      "second":49
   },
   "adjustedUtc":1448557009,
   "local":1448528209,
   "returnValue":true,
   "systemTimeSource":"sdp"
}

time/getNTPTime

ACG: time.query

Added: API level 11

Description

The getNTPTime returns the fresh NTP time (the time data transferred by the Network Time Protocol).

Parameters

None

Call Returns

Name	Required	Type	Description
utc	Optional	Number	Seconds since epoch for UTC time-zone
subscribed	Required	Boolean	subscribed will always contain false.
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
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
None	NTP requests are prohibited at the moment	NTP requests are prohibited at the moment

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.systemservice/time/getNTPTime '{ }'

time/getSystemTime

ACG: time.query

Added: API level 11

Description

The time/getSystemTime method gets the system time and time zone information. Apps can susbcribe to this method and receive notifications when the time zone changes and/or the system time changes by a significant amount (currently 5 min.).

This method does not generate errors, however if the LSSubscriptionAdd method, which is used inside the getSystemTime method, returns an error, this error is reported.

Parameters

Name	Required	Type	Description
subscribe	Optional	Boolean	If the app wants to receive notifications when the time zone changes and/or the system time changes by a system-defined threshold, it should set subscribe to true. The current system-defined threshold is 5 minutes. If the app does not wish to receive notifications of change in time zone and/or the system time changes, it should set subscribe to false.

Name

Required

Type

Description

Optional

Boolean

If the app wants to receive notifications when the time zone changes and/or the system time changes by a system-defined threshold, it should set subscribe to true. The current system-defined threshold is 5 minutes.

If the app does not wish to receive notifications of change in time zone and/or the system time changes, it should set subscribe to false.

Call Returns

Name	Required	Type	Description
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.
isDST	Optional	Boolean	Indicates whether the system is currently using Daylight Saving Time (DST). The possible values: True - System is using DST False - System is not using DST Note: This field is not provided if the DST information is not available.
localtime	Required	Object: LocalTime	The object that contains information about the current system time.
offset	Required	Number	The number of minutes from UTC. This can be negative for time zones west of UTC, and positive for time zones east of UTC.
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
subscribed	Optional	Boolean	Indicates if subscribed to get notified. true - Subscribed for changes false - Not subscribed
timestamp	Optional	Object: Timestamp	Monotonic timestamp
timezone	Required	String	The current system time zone. It has the same format as the TZ environment variable. For information, see http://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html
timeZoneFile	Required	String	Linux zone information file for the currently set zone. For more information, see: http://linux.die.net/man/5/tzfile
TZ	Required	String	Contains the time zone abbreviation in the standard Unix format, for example PDT (which stands for Pacific Daylight Time). The time zone corresponds to the current time zone of the system.
utc	Required	Number	The number of milliseconds since Epoch (midnight of January 1, 1970 UTC), also know as the Unix time.
systemTimeSource	Required	String	It will denote the time source used for system time synchronization.

Subscription Returns

Name	Required	Type	Description
utc	Required	Number	The number of milliseconds since Epoch (midnight of January 1, 1970 UTC), also know as the Unix time.
localtime	Required	Object: LocalTime	The object that contains information about the current system time.
offset	Required	Number	The number of minutes from UTC. This can be negative for time zones west of UTC, and positive for time zones east of UTC.
timezone	Required	String	The current system time zone. It has the same format as the TZ environment variable. For information, see http://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html
TZ	Required	String	Contains the time zone abbreviation in the standard Unix format, for example PDT (which stands for Pacific Daylight Time). The time zone corresponds to the current time zone of the system.
timeZoneFile	Required	String	Linux zone information file for the currently set zone. For more information, see: http://linux.die.net/man/5/tzfile
NITZValidTime	Optional	Boolean	The NITZValidTime property indicaltes that a valid time was correctly set using NITZ. This value is needed because sometimes the time-zone may be received ahead of the time.
NITZValidZone	Optional	Boolean	The NITZValidZone property indicates that a valid time-zone was correctly set using NITZ. This value is needed because sometimes the time may be received ahead of the time-zone.
isDST	Optional	Boolean	A flag that indicates whether daylight saving time (DST) is in effect at the time described. The value is true if DST is in effect, false if it is not, and absent if the information is not available.
systemTimeSource	Required	String	It will denote the time source used for system time synchronization.

Error Codes Reference

Error Code	Error Text	Error Description
1	Could not get service unique name	Luna-service2 internal error: Can't retrieve unique service name from the message.
1	Could not get unique token	Luna-service2 internal error: Can't retrieve unique token from the message

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.systemservice/time/getSystemTime '{}'

Response:

{
   "timezone":"America/Los_Angeles",
   "returnValue":true,
   "utc":1448556823,
   "localtime":{
      "month":11,
      "day":26,
      "hour":8,
      "minute":53,
      "year":2015,
      "second":43
   },
   "TZ":"PST",
   "systemTimeSource":"sdp",
   "timestamp":{
      "source":"monotonic",
      "sec":94520,
      "nsec":767897750
   },
   "timeZoneFile":"/var/luna/preferences/localtime",
   "offset":-480,
   "isDST":true
}

time/getSystemTimezoneFile

ACG: time.query

Added: API level 11

Description

Returns the path to Linux time-zone information file for the currently set zone. This file contains the list of rules that define switching to and from daylight saving time. In particular, the time-zone information file defines when the time shift occurs in each particular year.

Note: A call to this method always succeeds. This method does not return returnValue.

Parameters

None

Call Returns

Name	Required	Type	Description
subscribed	Required	String	subscribed will always contain false.
timeZoneFile	Required	String	Path to the system timezone file.

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.systemservice/time/getSystemTimezoneFile '{}'

Response:

{
   "subscribed":false,
   "timeZoneFile":"/var/luna/preferences/localtime"
}

time/getSystemUptime

ACG: time.query

Added: API level 11

Description

Returns the number of seconds since the last system boot. This method uses the Linux-specific sysinfo function.

Parameters

None

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
errorCode	Optional	Number	The error code for the failed operation. It contains the POSIX errno value.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.
uptime	Optional	Number	Number of seconds since last system boot.

Error Codes Reference

Error Code	Error Text	Error Description
14	Bad address	Internal error: Invalid sysinfo parameter.

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.systemservice/time/getSystemUptime '{}'

Response:

{
"returnValue": true,
"uptime": 5185
}

time/launchTimeChangeApps

ACG: time.management

Added: API level 11

Description

Executes all methods listed in the timeChangeLaunch list (value of the timeChangeLaunch preference).

The timeChangeLaunch list contains all applications that must be executed when the switching to/from the daylight saving time occurs. These applications are executed automatically, you should not call the launchTimeChangeApps method. However, if for some reason you need to execute these applications apart from the schedule, you can call the the launchTimeChangeApps method.

Note: This method call always succeeds.

Parameters

None

Call Returns

Name	Required	Type	Description
subscribed	Required	String	Always returns false.
returnValue	Required	Boolean	Always returns true.

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.systemservice/time/launchTimeChangeApps '{}'

Response:

{
   "subscribed":false,
   "returnValue":true
}

time/setBroadcastTime

ACG: time.management

Added: API level 11

Description

Sets the broadcast time which is in the broadcast signal. The system service will be notified that the broadcast time must be changed.

Parameters

Name	Required	Type	Description
utc	Required	Number	UTC time in seconds since epoch.
local	Required	Number	Seconds since epoch with local time offset (according to broadcast regional offsets table).
timestamp	Optional	Object: Timestamp	Monotonic timestamp. If set, will be used to calculate a delay between sending and receipt of this request over luna-bus and add that to utc field.

Call Returns

Name

Required

Type

Description

returnValue

Required

Number

Indicates the status of operation. Possible values are:

true - Indicates that the operation was successful.
false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details

errorCode

Optional

Number

The error code for the failed operation.

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
-2	Failed to update broadcast time offsets	Failed to update broadcast time offsets
1	Could not validate json message against schema	The request data is invalid.

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.systemservice/time/setBroadcastTime '{"utc": 1418745990, "local": 1418727638 }'

time/setSystemNetworkTime

ACG: time.management

Added: API level 11

Description

The setSystemNetworkTime method is used to send a NITZ messages to Luna System Service. A NITZ message contains the local time and date, time zone and DST offset, as well as network provider identity. NITZ can be used to update the system clock of network devices.

This method is called by the service, which receives the time data from the service provider.

Parameters

Name	Required	Type	Description
sec	Required	String	GMT second.
min	Required	String	GMT minute.
hour	Required	String	GMT hour.
mday	Required	String	Day of the month.
mon	Required	String	Month of the year, 0 - 11.
year	Required	String	Year calculated from 1900, for example 2012 - 1900 = 112.
offset	Required	String	Offset from GMT time in minutes.
mcc	Required	String	Country code.
mnc	Required	String	Network code assign to carrier within a country
tzvalid	Required	Boolean	Is set to true of if timezone is valid. If false, mcc and offset are used to calculate time.
timevalid	Required	Boolean	Is time valid.
dstvalid	Required	Boolean	Is daylight saving time in use.
dst	Required	Number (int32_t)	If this is 1, month needs to be set within the timeframe of DaylightSavingTime (~April - ~Septermber). If this is 0, months needs to be specified outside of DaylightSavingTime ( ~November - February).
timestamp	Required	String	Timestamp of current time. Can be number of ticks from system boot. The number is used to calculate delay of message delivery
tilIgnore	Required	Boolean	Set as true if you wish to test this service with a fake NITZ message.

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates the status of operation. Possible values are:

true - Indicates that the operation was successful.
false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details

errorCode

Optional

Number

The error code for the failed operation.

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
None	nitz message failed ...	Failed to handle this NITZ message at some stage
1	Could not validate json message against schema	The request data is invalid.

Example

Example code

Example of a successful call:

# luna-send -f -n 1 luna://com.webos.service.systemservice/time/setSystemNetworkTime '{
  "sec":"30",
  "min":"15",
  "offset":"-480",
"hour":"2",
"dst":1,
  "tzvalid":true,
  "dstvalid":true,
  "mon":"6",
  "year":"111",
  "timevalid":true,
  "mday":"1",
  "mcc":"310",
  "mnc":"26",
  "tilIgnore":true,
"timestamp":"123"
}'

{

"returnValue": true

}

time/setSystemTime

ACG: time.management

Added: API level 11

Description

The setSystemTime method sets the Linux system-wide time effectively overriding any previous synchronization with any time source.

Note: this API might not change system time returned by getSystemTime. It depends on manualOverride and useNetworkTime preferences.

Parameters

Name	Required	Type	Description
utc	Required	Number	The number of milliseconds since Epoch (midnight of January 1, 1970 UTC), aka - Unix time.
timestamp	Optional	Object: Timestamp	Monotonic timestamp. If set, will be used to calculate a delay between sending and receipt of this request over luna-bus and add that to the utc field.

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates the status of operation. Possible values are:

true - Indicates that the operation was successful.
false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details

errorCode

Optional

Number

The error code for the failed operation.

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
FAIL	accessing utc integer value failed	The utc key is missing.
1	Could not validate json message against schema	The request data is invalid.

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.systemservice/time/setSystemTime '{"utc": 1418745990 }'

time/setTimeChangeLaunch

ACG: time.management

Added: API level 11

Description

The setTimeChangeLaunch method adds an application to, or removes it from the timeChangeLaunch list.

The timeChangeLaunch list contains the applications that are automatically executed by the system when the switch to or from the daylight saving time occurs.

Parameters

Name	Required	Type	Description
appId	Required	String	Application ID.
active	Required	Boolean	If true, adds the application to the launch list. If false, the application is removed.
parameters	Required	Object	Launch parameters for the application.

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates the status of operation. Possible values are:

true - Indicates that the operation was successful.
false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details

errorCode

Optional

Number

The error code for the failed operation.

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
None	cannot deactivate an appId that isn't in the list	AppID is not in the list
1	Could not validate json message against schema	The request data is invalid.

Example

Example code

Example of a successful call:

# luna-send -n 1 -f luna://com.webos.service.systemservice/time/setTimeChangeLaunch '{
  "appId": "com.webos.app.someApp",
  "active": true,
  "parameters": { "param1": "foo", "param2": "bar" }
}'

{

"subscribed": false,

"returnValue": true

}

time/setTimeWithNTP

ACG: time.management

Added: API level 11

Description

The setTimeWithNTP methods synchronizes the system time with the NTP.

Note: This method call always succeeds.

Parameters

None

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Always true

Example

Example code

Example of a successful call:

# luna-send -n 1 -f luna://com.webos.service.systemservice/time/setTimeWithNTP '{}'

{

"returnValue": true

}

timezone/createTimeZoneFromEasData

ACG: time.management

Added: API level 11

Description

Create a manual timezone named "Etc/Manual" and specify details of this timezone.

After creating the timezone, enable it by using the following command:

luna-send -n 1 -f luna://com.webos.service.systemservice/setPreferences '{"timeZone": {"ZoneID": "Etc/Manual"}}'

Parameters

Name	Required	Type	Description
bias	Optional	Number	Number of minutes that the manual timezone is offset from Coordinated Universal Time (UTC).
standardDate	Optional	Object: TimeZoneEasRule	Date and local time when Daylight Saving Time (DST) transitions to standard time. Note: This field must be specified in combination with the daylightDate parameter. If either of these parameters is not specified, both the fields are ignored.
standardBias	Optional	Number	The bias value to be used during local time translations that occur during standard time. This value is added to the value of the bias parameter to form the bias used during standard time. Default value: 0 (in most time zones this value is 0) Note: This parameter is ignored if the standardDate parameter is not specified.
daylightDate	Optional	Object: TimeZoneEasRule	Date and local time when standard time transitions to Daylight Saving Time (DST). Note: This field must be specified in combination with the standardDate parameter. If either of these parameters is not specified, both fields are ignored.
daylightBias	Optional	Number	The bias value to be used during local time translations that occur during daylight saving time. This value is added to the value of the bias parameter to form the bias used during daylight saving time. Default value: -60 (in most time zones this value is -60) Note: This parameter is ignored if the daylightDate parameter is not specified.

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates the status of operation. Possible values are:

true - Indicates that the operation was successful.
false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.

errorCode

Optional

Number

The error code for the failed operation.

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
0	DST duration is too short	DST duration is too short
1	Could not validate json message against schema	The request data is invalid

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.systemservice/timezone/createTimeZoneFromEasData '{
"standardDate":
{
"month": 10,
"dayOfWeek": 0,
"week": 3,
"hour": 2
},
"daylightDate":
{
  "month": 7,
  "dayOfWeek": 0,
  "week": 1,
  "hour": 0
}
}'

timezone/getTimeZoneFromEasData

ACG: time.query

Added: API level 11

Description

Gets the time-zone that matches the provided EAS data. This method enables you to determine the time zone by the specified time stamp.

Parameters

Name	Required	Type	Description
bias	Required	Number	Number of minutes that a time zone is offset from Coordinated Universal Time (UTC).
standardDate	Optional	Object: EasLocalTime	Object containing date and time information in standard time. If any of the fields for EasLocalTime structure are missing or out of range, this field is ignored as not specified. This field should be specified in combination with daylightDate. If either standardDate or daylightDate is not specified, both fields are ignored as not specified.
standardBias	Optional	Number	The standardBias is the bias value to be used for local time translations that occur during standard time. This value is added to the value of the bias member to form the bias used during standard time. In most time zones, the value is zero. This field is not used in calculations for the moment.
daylightDate	Optional	Object: EasLocalTime	The daylightDate is an object containing the date and time information in daylight saving time. If any of the fields for EasLocalTime structure are missing or out of range, this field is ignored as not specified. This field should be specified in combination with standardDate. If either standardDate or daylightDate is not specified, both are ignored as not specified.
daylightBias	Optional	Number	The dayLightBias is the bias value to be used for local time translations that occur during daylight saving time. This value is added to the value of the bias member to form the bias used during daylight saving time. In most time zones, the value is –60. This field is not used in calculations for the moment.

Call Returns

Name	Required	Type	Description
timeZone	Optional	String	The timezone matching the given parameters. Note: When there are multiple locations that match the specified "bias", the entry that first appears in the preferences is returned. For example, Gibraltar and Brussles, both have offset from UTC as 60. So, if bias is given as "-60", the API returns timezone as "Gibraltar" since it appears before "Brussels". This order can be checked in the output of the following command: # luna-send -n 1 -f luna://com.webos.service.systemservice/getPreferenceValues '{"key": "timeZone" }'
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
errorCode	Optional	Number	The error code for the failed operation.
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
None	Failed to find timeZone preference	Failed to find timezone preference
None	Failed to find any timezones with specified bias value	Failed to find any timezones with specified bias value
None	Failed to find any timezones with specified parametes	Failed to find any timezones with specified parameters
1	Could not validate json message against schema	The request data is invalid.

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.systemservice/timezone/getTimeZoneFromEasData '{ "bias": 0 }'

timezone/getTimeZoneRules

ACG: time.query

Added: API level 11

Description

The getTimeZoneRules method requests rules for specific time-zone for the specified years. By calling this method you can get the rules of when and how the daylight time switching occurs at the specified year.

Parameters

Name	Required	Type	Description
tz	Required	String	The timezone for which to get information.
years	Optional	Number array	Array of years for which to get information. If not specified, information for the current year is returned.

Call Returns

Name

Required

Type

Description

results

Optional

Object array: TimeZoneRule

Object array for the results.

returnValue

Required

Boolean

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

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
0	Cannot parse json payload. Json root needs to be an array	The request JSON data is invalid.
0	Missing tz entry or entry is not a string	The request data is invalid.
0	years entry is not array	The request data is invalid.
0	entry in years array is not integer	The request data is invalid.

Example

Example code

Example of a successful call:

# luna-send -n 1 -f luna://com.webos.service.systemservice/timezone/getTimeZoneRules '[ {"tz": "Europe/Helsinki", "years": [2012, 2010]} ]'

{

"returnValue": true,

"results": [

{

"tz": "Europe/Helsinki",

"dstOffset": 10800,

"dstStart": 1332637200,

"dstEnd": 1351386000,

"utcOffset": 7200,

"year": 2012,

"hasDstChange": true

{

"tz": "Europe/Helsinki",

"dstOffset": 10800,

"dstStart": 1269738000,

"dstEnd": 1288486800,

"utcOffset": 7200,

"year": 2010,

"hasDstChange": true

}

]

}

wallpaper/convert

ACG: systemsettings.management

Added: API level 11

Description

The convert method converts an image. The type, scaling and centering of the image may be changed. If the resulting image is smaller than the original, black is added to the edges so that the resulting image is the same size as the original. If the resulting image would be bigger than the original, the image is cropped.

JPG, PNG and BMP files are supported.

Parameters

Name	Required	Type	Description
source	Required	String	Path to the source file. Note: The wallpaper file needs to be copied manually to the target prior to using this API
destType	Required	String	Type for the destination file. Can be jpg, png or bmp.
dest	Optional	String	Path for the destination file.
focusX	Optional	Number	The horizontal coordinate of the new center of the image, from 0.0 (left edge) to 1.0 (right edge). A value of 0.5 preserves the current horizontal center of the image.
focusY	Optional	Number	The vertical coordinate of the new center of the image, from 0.0 (top edge) to 1.0 (bottom edge). A value of 0.5 preserves the current vertical center of the image.
scale	Optional	Number	Scale factor for the image, must be greater than zero.

Call Returns

Name

Required

Type

Description

conversionResult

Required

Object: ImageConversionResult

Object containing information of the converted image.

returnValue

Required

Boolean

Indicates the status of operation. Possible values are:

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

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
None	no destination file specified and couldn't create temp file	Destination file is missing
None	Can't create destination folder	Can not create destination folder
None	invalid specification for input file (please use url format)	Invalid path for input file
None	input file specification doesn't support non-local files (use file:///path/file or /path/file format)	input file specification doesn't support non-local files (use file:///path/file or /path/file format)
None	invalid specification for output file (please use url format)	Invalid specification for output file
None	output file specification doesn't support non-local files (use file:///path/file or /path/file format	output file specification doesn't support non-local files (use file:///path/file or /path/file format)
None	One of the standard Linux error messages	System errors related to memory allocation or file operations such as "Resource temporary unavailable" or "Cannot allocate memory". See errno(3) and strerror(3) for details.
None	couldn't parse json	The request data is invalid.
None	lunabus handler error; luna didn't pass a valid instance var to handler	Internal luna bus error.
None	File not found.	File not found.

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.systemservice/wallpaper/convert '{
  "source": "/var/rootdirs/home/root/Capture.PNG",
  "dest":"/var/rootdirs/home/root/test.jpg",
  "destType" : "jpg"
}'

Response:

{
"returnValue": true,
"conversionResult": {
  "dest": "//var/rootdirs/home/root/test.jpg",
  "source": "//var/rootdirs/home/root/Capture.PNG",
  "destType": "jpg"
}
}

wallpaper/deleteWallpaper

ACG: systemsettings.management

Added: API level 11

Description

The deleteWallpaper method deletes the specified wallpaper from the list of available wallpapers on the device.

Parameters

Name

Required

Type

Description

wallpaperName

Required

String

The wallpaperName attribute of the wallpaper object to delete.

Note: The wallpaper file should have been copied and imported in the target prior to using this API

Call Returns

Name	Required	Type	Description
wallpaper	Optional	Object: Wallpaper	A wallpaper object corresponding with the deleted wallpaper
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
errorCode	Optional	Number	The error code for the failed operation.
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
None	Invalid wallpaper name specified.	Invalid wallpaper name specified (perhaps it doesn't exist in the wallpaper directory).
1	"Could not validate json message against schema	The request data is invalid.
1	lunabus handler error; luna didn't pass a valid instance var to handler	Internal luna bus error.
1	must specify wallpaperName	The wallpaper filename is not specified in the request.
1	Could not validate json message against schema	The request data is invalid.

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.systemservice/wallpaper/deleteWallpaper '{ "wallpaperName": "record-large.png" }'

Response:

{
"returnValue": true,
"wallpaper": {
"wallpaperName": "record-large.png"
}
}

wallpaper/importWallpaper

ACG: systemsettings.management

Added: API level 11

Description

The importWallpaper method is used to convert the specified image into a device wallpaper. To convert into a wallpaper the image is either re-centered and cropped, or scaled. Once the image has been converted, the wallpaper is stored in the internal list of wallpapers on the device, and is available until deleted using deleteWallpaper method.

Focus Parameter	Scale Parameter	Conversion Method
Yes	No	The image is re-centered at the point specified by the focus parameters and cropped. Gaps are filled with Black color if the image does not reach the edge of the screen.
No	Yes	The image is scaled and then cropped
Yes	Yes	The image is first scaled and then re-centered and cropped
No	No	Scales the image to fill the screen

Parameters

Name	Required	Type	Description
target	Required	String	Path to the image file.
focusX	Optional	Number	Represents the horizontal coordinates of the new center of the image from 0.0 (left edge) to 1.0 (right edge). A value of 0.5 preserves the current horizontal center of the image.
focusY	Optional	Number	The vertical coordinate of the new center of the image, from 0.0 (top edge) to 1.0 (bottom edge). A value of 0.5 preserves the current vertical center of the image.
scale	Optional	Number	Scale parameter determines the new size of the image, must be greater than zero.

Call Returns

Name

Required

Type

Description

wallpaper

Optional

Object: Wallpaper

A wallpaper object. This object can be passed to setPreferences to set the wallpaper key.

returnValue

Required

Boolean

Indicates the status of operation. Possible values are:

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

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
None	empty input file path specified	Input file path should not be empty.
None	invalid specification for input file (please use url format)	Invalid specification for input file.
None	input file specification doesn't support non-local files (use file:///path/file or /path/file format	Input file specification does not support the non-local files.
None	lunabus handler error; luna didn't pass a valid instance var to handler	Internal luna bus error.
None	no input file specified	The input file is not specified in the request.
None	Path is missing	The path is not specified in the request.
None	Both path and file name are missing	The path and the filename are not specified in the request.
None	filename is missing	The name of the wallpaper file is not specified in the request.
None	couldn't create thumbnail	Failed to create a thumbnail from the wallpaper image.
None	File not found	The wallpaper image file is not found.

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.systemservice/wallpaper/importWallpaper '{ "target": "/media/internal/.wallpapers/flowers.png" }'

{

"returnValue": true,

"wallpaper": {

"wallpaperName": "flowers.png",

"wallpaperFile": "\/media\/internal\/.wallpapers\/flowers.png",

"wallpaperThumbFile": "\/media\/internal\/.wallpapers\/thumbs\/flowers.png"

}

wallpaper/info

ACG: systemsettings.management

Added: API level 11

Description

The info method retrieves a wallpaper object using either the wallpaperName or wallpaperFile parameter.

Parameters

Name

Required

Type

Description

wallpaperName

Optional

String

Wallpaper name. Either this, or wallpaperFile is required.

Note: The wallpaper file needs to be copied manually to the target prior to using this API

wallpaperFile

Optional

String

Wallpaper's full path including the file name. Either this, or wallpaperName is required.

Note: The wallpaper file needs to be copied manually to the target prior to using this API

Call Returns

Name

Required

Type

Description

wallpaper

Optional

Object: Wallpaper

A wallpaper object. This object can be passed to setPreferences to set the wallpaper key.

returnValue

Required

Boolean

Indicates the status of operation. Possible values are:

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

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
None	invalid wallpaper name specified (perhaps it doesn't exist in the wallpaper dir; was it imported?)	Invalid wallpaper name specified.
None	Must specify either the "wallpaperName" or the "wallpaperFile".	Must specify either the wallpaperName or the wallpaperFile.
None	lunabus handler error; luna didn't pass a valid instance var to handler	Internal luna bus error.
None	invalid wallpaper file specified (perhaps it doesn't exist in the wallpaper dir; was it imported?)	Invalid wallpaper name specified.

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.systemservice/wallpaper/info '{ "wallpaperFile": "/media/internal/.wallpapers/flowers.png" }'

{

"returnValue": true,

"wallpaper": {

"wallpaperName": "flowers.png",

"wallpaperFile": "\/media\/internal\/.wallpapers\/flowers.png",

"wallpaperThumbFile": "\/media\/internal\/.wallpapers\/thumbs\/flowers.png"

}

wallpaper/refresh

ACG: systemsettings.management

Added: API level 11

Description

The refresh method refreshes the internal list of available wallpapers. Under normal circumstances, there is no need to call refresh directly.

Note: This method call always succeeds.

Parameters

None

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	returnValue will always contain true.

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.systemservice/wallpaper/refresh '{}'

Objects

EasLocalTime

This object provides details of the EAS time structure.

Example

"standardDate": {
    "month": 12,
    "day": 3,
    "dayOfWeek": 2,
    "hour": 11,
    "minute": 0,
    "year": 2014,
    "second": 38
}

Name	Required	Type	Description
year	Optional	Number	The year. Default value is current year
month	Required	Number	The month (1-12).
dayOfWeek	Required	Number	Day of the week (0 - 6). 0 is for Sunday, 1 - for Monday and so on to 6 - for Saturday
day	Required	Number	Occurrence of the day of the week within the month (1 - 5).
hour	Required	Number	The hour (0 - 23).
minute	Optional	Number	The minute (0 - 59). Default value is 0
second	Optional	Number	The second (0 - 59). Default value is 0

ImageConversionResult

Contains details of the converted image.

Example

{
    "src": "/usr/lib/luna/system/luna-systemui/images/opensearch-small-icon.png",
    "dest": "/tmp/convertedimage.png",
    "destType": "jpg"
}

Name	Required	Type	Description
source	Optional	String	Path to the original file.
dest	Required	String	Path to the output file.
destType	Required	String	Type of the output file: jpg, png or bmp.

LocalTime

This object provides details of the current system time.

Example

"localtime": {
    "month": 12,
    "day": 16,
    "hour": 11,
    "minute": 0,
    "year": 2014,
    "second": 38
}

Name	Required	Type	Description
year	Required	Number	The year.
month	Required	Number	The month (1-12).
dayOfWeek	Optional	Number	Day of the week (0 - 6).
day	Required	Number	The day (1 - 31).
hour	Required	Number	The hour (0 - 23).
minute	Required	Number	The minute (0 - 59).
second	Required	Number	The second (0 - 59 or 60 for leap seconds).

TimeSourceOffset

Details about the offset from one of the time-sources.

Example

"offset": {
"source": "system",
"value": 0
}

Name	Required	Type	Description
value	Required	Number	Offset in seconds from the time-source.
source	Required	String	Time source identifier (for example system, manual, etc). Only system is returned for the moment.

TimeZoneEasRule

Provides details of structure for creating a timezone rule.

Example

{
    "year": 2016,
    "month": 10,
    "dayOfWeek": 0,
    "week": 3,
    "hour": 2
}

Name	Required	Type	Description
year	Optional	Number	The year
month	Optional	Number	The month. Possible values are 1 - 12.
dayOfWeek	Optional	Number	Day of week. Possible values are 0 - 6, where 0 is Sunday and 6 is Saturday.
week	Optional	Number	Week of the month. Possible values are 1 - 5, where 1 is the 1^st week and 5 is the last or 5^th week of month.
hour	Optional	Number	The hour. Possible values are 0 - 23.
minute	Optional	Number	The minute (0-59)
second	Optional	Number	The second (0-59). Default value is 0

TimeZoneRule

Contains the rule to be used when DST(daylight saving time) is enabled for a particular zone.

Example

{
    "tz": "Europe/Helsinki",
    "dstOffset": 10800,
    "dstStart": 1332637200,
    "dstEnd": 1351386000,
    "utcOffset": 7200,
    "year": 2012,
    "hasDstChange": true
}

Name	Required	Type	Description
tz	Optional	String	The timezone.
year	Optional	Number	The year.
hasDstChange	Optional	Boolean	True if daylight saving time is in use in this timezone.
utcOffset	Required	Number	Time difference from UTC time in seconds.
dstOffset	Optional	Number	Time difference from UTC time in seconds during daylight saving time.
dstStart	Optional	Number	The time when daylight saving time starts during the year, presented in Unix time.
dstEnd	Optional	Number	The time when daylight saving time ends during the year, presented in Unix time.

Timestamp

Contains details of the timestamp.

Name

Required

Type

Description

source

Required

String

Source of the timestamp. For example monotonic, etc.

Note: currently only monotonic is used.

sec

Required

Number

Seconds for the timestamp

nsec

Required

Number

Nanoseconds for the timestamp

Wallpaper

Contains wallpaper details.

Example

"wallpaper": {
    "wallpaperName": "flowers.png",
    "wallpaperFile": "\/media\/internal\/.wallpapers\/flowers.png",
    "wallpaperThumbFile": "\/media\/internal\/.wallpapers\/thumbs\/flowers.png"
}

Name	Required	Type	Description
wallpaperName	Required	String	The wallpaperName that was passed to the wallpaper managing methods.
wallpaperFile	Optional	String	Path to file with wallpaper image.
wallpaperThumbFile	Optional	String	Path to file with wallpaper thumbnail.