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

tempDirRequiredString

Directory to store temporarily generated files (files that are to be restored).

filesRequiredstring array

List of files to restore.

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

NoneRequired Arguments Missing.

Some of the arguments required for this method have not been provided.

NoneInvalid 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

incrementalKeyOptionalobject

This is used primarily for mojodb, backup service will handle other incremental backups.

maxTempBytesOptionalnumber

The allowed size of upload. It is currently set at 10MB.

tempDirOptionalString

Directory to store temporarily generated files.

Call Returns

Name

Required

Type

Description

descriptionRequiredString

Describes the backup.

 

versionRequiredString

Version of the backup.

 

filesRequiredstring 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

sourceOptionalString

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

manualOverrideOptionalBoolean
  1. 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).
  2. If useNetworkTime is set to false and manualOverride is set to true, get time specified in source parameter.
  3. 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.

fallbackOptionalString

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

returnValueRequiredBoolean

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
sourceRequiredString

Actual time source associated with result (either one specified in source or in fallback or manual if overridden).

utcOptionalNumber

Seconds since epoch for UTC.

offsetOptionalObject: TimeSourceOffset

Offset from some other time source (usually from system).

systemTimeSourceOptionalString

If system-wide system time is returned and this field is present, it will denote last time source used for system time synchronization.

priorityOptionalNumber

Priority of returned time source (with higher level overrides one with lower).

timestampOptionalObject: Timestamp

Monotonic timestamp.

errorCodeOptionalNumber

The error code for the failed operation.

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

NoneRequested clock is not registered

Time source is not among list of available ones ("timeSources").

NoneNo time available for that clock

Requested time source not yet available (ex. no Internet for "ntp").

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

utcRequiredNumber

Seconds since epoch in UTC time-zone. 

Note: Either utc field or available field is mandatory.

sourceOptionalString

Time source associated with time info update (default "manual").

Only those sources that are listed in the timeSources Preference key can be set.
 

availableRequiredBoolean

Availability flag. Set to false to specify that source is not available.

Note: Either available field or utc field is mandatory.

timestampOptionalObject: 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

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

. The clock/setTime method may fail because:

  • Requested clock is not registered.
errorTextOptionalString

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

errorCodeOptionalNumber

Error Code Number

Error Codes Reference

Error Code

Error Text

Error Description

NoneRequested clock is not registered

Time source is not among list of available ones ("timeSources").

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

parametersOptionalString 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_challangeOptionalString

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_typeOptionalString

Refers to the keyboard built into the device. Example: virtual

board_typeOptionalString

Board type.

product_idOptionalString

Product ID.

serial_numberOptionalString

Serial number.

installerOptionalString

Tool used to install the image.

Currently, the "not supported" value is always returned.

storage_sizeOptionalString

Storage size.

modem_presentOptionalString

Modem availability.

Note: This parameter is "not supported", even though the response shows this value as "N" to indicate modem is not present.

hardware_idOptionalString

Hardware ID.

ram_sizeOptionalString

RAM size.

hardware_revisionOptionalString

Hardware revision.

wired_addrOptionalString

Wired/Ethernet MAC address.

wifi_addrOptionalString

WiFi MAC address.

returnValueRequiredBoolean

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_typeOptionalString

Reason code for last reboot (may come from /proc/cmdline).

Currently, the "not supported" value is always returned.

radio_typeOptionalString

Internal ID code for the radio type.

Currently, the "not supported" value is always returned.

storage_freeOptionalString

Free storage size.

Currently, the "not supported" value is always returned.

battery_responseOptionalString

Battery response.

Currently, the "not supported" value is always returned.

device_nameOptionalString

Device name.

nduidOptionalString

NDUID.

bt_addrOptionalString

Bluetooth address.

device_idOptionalString

ID for uniquely identifying the device

errorCodeOptionalNumber

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

errorTextOptionalString

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

NoneInvalid 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"]

NoneInternal error. Can't initialize nyx

Failed to load nyx library.

NoneInternal error. Can't open nyx device

Nyx library error.

NoneInvalid 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

keyRequiredString

Key name to fetch preference values for.

Accepted key names:

  • locale
  • region
  • ringtone
  • useNetworkTime
  • useNetworkTimeZone
  • timeZone
  • timeFormat
  • wallpaper

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. 

The method can fail if the "key is not specified or is invalid".

errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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

[key name]OptionalAny array

Contains the set returned for the specified key name in command parameters.

syszonesOptionalAny array

Provides ZoneID with the respective time offset for different time zones.

mccInfoOptionalAny 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

1Could not validate json message against schema

The request data is invalid.

1Can't find handler for key: " + [key name]

The handler for the key specified in the error message cannot be found.

2Handler 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

subscribeOptionalBoolean

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

keysRequiredstring 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

subscribedOptionalBoolean

True if the subscription was successful

returnValueRequiredBoolean

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
errorCodeOptionalNumber

The error code for the failed operation.

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

Noneno keys specified

The keys property has not been provided to the method.

Noneno key array specified

The keys property provided is not an array.

Noneinvalid key array

The keys array does not have any values.

Noneinvalid value encoded in preference("did you escape your strings?")

Subset of requested values have preferences that contain invalid json representation.

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

parametersOptionalString 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_versionOptionalString

Core OS kernel version info

core_os_nameOptionalString

Core OS name

core_os_releaseOptionalString

Core OS release info

core_os_release_codenameOptionalString

Core OS release codename

webos_build_datetimeOptionalString

The UTC timestamp reflecting when the current image was built. The string is in the format "YYYYMMDDhhmmss".

webos_build_idOptionalString

webOS build ID

webos_imagenameOptionalString

webOS imagename

webos_nameOptionalString

webOS name

webos_prereleaseOptionalString

webOS prerelease info

webos_releaseOptionalString

webOS release info

webos_release_codenameOptionalString

webOS release codename

webos_manufacturing_versionOptionalString

webOS manufacting version

encryption_key_typeOptionalString

Encryption key type

returnValueRequiredBoolean

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
errorTextOptionalString

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.

NoneCan not initialize nyx

Internal error. Can't initialize nyx.

NoneInternal error. Can't open nyx device

Nyx API error

NoneCan'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.

NoneInvalid parameter: +

The <parameter name> specified in the error message is invalid.

NoneInvalid 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

filePathRequiredString

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

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

Noneinput 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)

Nonesource file name missing.

Can not find file at current path

NoneUnable to add ringtone.

Failed to copy ringtone to media partition.

NoneSource 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

filePathRequiredString

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

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

Nonefile doesn't exist

Specified file doesn't exist

Nonesource file name missing.

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

NoneUnable 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

param208OptionalObject

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

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

NoneSome 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

parametersOptionalString 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

returnValueRequiredBoolean

Indicates the status of the operation.

Possible values are:

  • true: Operation is successful.
  • false: Operation has failed. Check the 'errorCode' and 'errorText' fields.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

The reason for the failure of the operation. See the 'Error Codes' section of this method for details.

nodejs_versionsOptionalString array

Versions of nodejs that are available on the webOS device.

Error Codes Reference

Error Code

Error Text

Error Description

NoneInvalid 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.

NoneInvalid message payload

The request JSON payload contains invalid data.

NoneCould 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

dateRequiredString

Date to convert as a string in format: "Y-m-d H:M:S".

source_tzRequiredString

Source timezone.

dest_tzRequiredString

Destination timezone.

Call Returns

Name

Required

Type

Description

dateRequiredString

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

returnValueRequiredBoolean

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

NoneUnrecognized date format:

Date format is unrecognized.

Noneunrecognized characters in date:

Characters in date are unrecognized.

NoneTimezone 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

utcRequiredNumber

Seconds since epoch for UTC time-zone

localOptionalNumber

Seconds since epoch with offset according to broadcast regional offsets table

localtimeOptionalObject: LocalTime

Calendar representation of local time

timestampOptionalObject: Timestamp

Monotonic timestamp.

returnValueRequiredBoolean

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
errorCodeOptionalNumber

The error code for the failed operation.

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

-2No 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

localeRequiredString

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

timeZoneOptionalString

The timezone matching the given parameters.

returnValueRequiredBoolean

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

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

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

subscribeOptionalBoolean

Subscribe for notifications. Possible values are:

  • true - Get notifications
  • false - Notifications are not required

​Default value: false

Call Returns

Name

Required

Type

Description

subscribedOptionalBoolean

True if the subscription was successful.

adjustedUtcRequiredNumber

Seconds since epoch suitable for converting from UTC to local time which corresponds with appropriate broadcast regional offset table entry

localRequiredNumber

Seconds since epoch with offset according to broadcast regional offsets table

localtimeOptionalObject: LocalTime

Calendar representation of local time.

timestampOptionalObject: Timestamp

Monotonic timestamp

returnValueRequiredBoolean

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
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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

systemTimeSourceOptionalString

Time source used for last system time synchronization.

Note: This field is only provided when the systemTime feature is configured.

Subscription Returns

Name

Required

Type

Description

subscribedOptionalBoolean

True if the subscription was successful.

adjustedUtcRequiredNumber

Seconds since epoch suitable for converting from UTC to local time which corresponds with appropriate broadcast regional offset table entry

localRequiredNumber

Seconds since epoch with offset according to broadcast regional offsets table

localtimeOptionalObject: LocalTime

Calendar representation of local time.

timestampOptionalObject: Timestamp

Monotonic timestamp

returnValueRequiredBoolean

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
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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

systemTimeSourceOptionalString

Denotes last time source used for system time synchronization.
Note: The systemTimeSource field is only provided when the systemTime feature is configured.

Error Codes Reference

Error Code

Error Text

Error Description

-1Failed to get localtime

Failed to get localtime

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

utcOptionalNumber

Seconds since epoch for UTC time-zone

subscribedRequiredBoolean

subscribed will always contain false.

returnValueRequiredBoolean

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

NoneNTP 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

subscribeOptionalBoolean

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

errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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

isDSTOptionalBoolean

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.

localtimeRequiredObject: LocalTime

The object that contains information about the current system time.

offsetRequiredNumber

The number of minutes from UTC. This can be negative for time zones west of UTC, and positive for time zones east of UTC.

returnValueRequiredBoolean

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
subscribedOptionalBoolean

Indicates if subscribed to get notified.

  • true - Subscribed for changes
  • false - Not subscribed
timestampOptionalObject: Timestamp

Monotonic timestamp

timezoneRequiredString

 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 

timeZoneFileRequiredString

Linux zone information file for the currently set zone. For more information, see: http://linux.die.net/man/5/tzfile

TZRequiredString

 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.

utcRequiredNumber

The number of milliseconds since Epoch (midnight of January 1, 1970 UTC), also know as the Unix time.

systemTimeSourceRequiredString

 It will denote the time source used for system time synchronization.

Subscription Returns

Name

Required

Type

Description

utcRequiredNumber

The number of milliseconds since Epoch (midnight of January 1, 1970 UTC), also know as the Unix time.

localtimeRequiredObject: LocalTime

The object that contains information about the current system time.

offsetRequiredNumber

The number of minutes from UTC. This can be negative for time zones west of UTC, and positive for time zones east of UTC.

timezoneRequiredString

 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 

TZRequiredString

 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.

timeZoneFileRequiredString

Linux zone information file for the currently set zone. For more information, see: http://linux.die.net/man/5/tzfile

NITZValidTimeOptionalBoolean

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.

NITZValidZoneOptionalBoolean

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.

isDSTOptionalBoolean

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.

systemTimeSourceRequiredString

It will denote the time source used for system time synchronization.

Error Codes Reference

Error Code

Error Text

Error Description

1Could not get service unique name

Luna-service2 internal error: Can't retrieve unique service name from the message.

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

subscribedRequiredString

subscribed will always contain false.

timeZoneFileRequiredString

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

returnValueRequiredBoolean

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
errorCodeOptionalNumber

The error code for the failed operation.

It contains the POSIX errno value.

errorTextOptionalString

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

uptimeOptionalNumber

Number of seconds since last system boot.

Error Codes Reference

Error Code

Error Text

Error Description

14Bad 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

subscribedRequiredString

Always returns false.

returnValueRequiredBoolean

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

utcRequiredNumber

UTC time in seconds since epoch.

localRequiredNumber

Seconds since epoch with local time offset (according to broadcast regional offsets table).

timestampOptionalObject: 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

returnValueRequiredNumber

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
errorCodeOptionalNumber

The error code for the failed operation.

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

-2Failed to update broadcast time offsets

Failed to update broadcast time offsets

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

secRequiredString

GMT second.

minRequiredString

GMT minute.

hourRequiredString

GMT hour.

mdayRequiredString

Day of the month.

monRequiredString

Month of the year, 0 - 11.

yearRequiredString

Year calculated from 1900, for example 2012 - 1900 = 112.

offsetRequiredString

Offset from GMT time in minutes.

mccRequiredString

Country code.

mncRequiredString

Network code assign to carrier within a country

tzvalidRequiredBoolean

Is set to true of if timezone is valid. If false, mcc and offset are used to calculate time.

timevalidRequiredBoolean

Is time valid.

dstvalidRequiredBoolean

Is daylight saving time in use.

dstRequiredNumber (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).

timestampRequiredString

Timestamp of current time. Can be number of ticks from system boot. The number is used to calculate delay of message delivery

tilIgnoreRequiredBoolean

Set as true if you wish to test this service with a fake NITZ message.

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 the "errorCode" and "errorText" fields for details
errorCodeOptionalNumber

The error code for the failed operation.

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

Nonenitz message failed ...

Failed to handle this NITZ message at some stage

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

utcRequiredNumber

The number of milliseconds since Epoch (midnight of January 1, 1970 UTC), aka - Unix time.

timestampOptionalObject: 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

returnValueRequiredBoolean

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
errorCodeOptionalNumber

The error code for the failed operation.

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

FAILaccessing utc integer value failed

The utc key is missing.

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

appIdRequiredString

Application ID.

activeRequiredBoolean

If true, adds the application to the launch list. If false, the application is removed.

parametersRequiredObject

Launch parameters 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 the "errorCode" and "errorText" fields for details
errorCodeOptionalNumber

The error code for the failed operation.

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

Nonecannot deactivate an appId that isn't in the list

AppID is not in the list

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

returnValueRequiredBoolean

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

biasOptionalNumber

Number of minutes that the manual timezone is offset from Coordinated Universal Time (UTC).

standardDateOptionalObject: 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.

standardBiasOptionalNumber

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.

daylightDateOptionalObject: 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.

daylightBiasOptionalNumber

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

returnValueRequiredBoolean

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.
errorCodeOptionalNumber

The error code for the failed operation.

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

0DST duration is too short

DST duration is too short

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

biasRequiredNumber

Number of minutes that a time zone is offset from Coordinated Universal Time (UTC).

standardDateOptionalObject: 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.

standardBiasOptionalNumber

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.

daylightDateOptionalObject: 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.

daylightBiasOptionalNumber

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

timeZoneOptionalString

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

returnValueRequiredBoolean

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
errorCodeOptionalNumber

The error code for the failed operation.

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

NoneFailed to find timeZone preference

Failed to find timezone preference

NoneFailed to find any timezones with specified bias value

Failed to find any timezones with specified bias value

NoneFailed to find any timezones with specified parametes

Failed to find any timezones with specified parameters

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

tzRequiredString

The timezone for which to get information.

yearsOptionalNumber 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

resultsOptionalObject array: TimeZoneRule

Object array for the results.

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

0Cannot parse json payload. Json root needs to be an array

The request JSON data is invalid.

0Missing tz entry or entry is not a string

The request data is invalid.

0years entry is not array

The request data is invalid.

0entry 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

sourceRequiredString

 Path to the source file.

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

destTypeRequiredString

Type for the destination file. Can be jpg, png or bmp.

destOptionalString

Path for the destination file.

focusXOptionalNumber

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.

focusYOptionalNumber

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.

scaleOptionalNumber

Scale factor for the image, must be greater than zero.

Call Returns

Name

Required

Type

Description

conversionResultRequiredObject: ImageConversionResult

Object containing information of the converted image.

returnValueRequiredBoolean

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

Noneno destination file specified and couldn't create temp file

Destination file is missing

NoneCan't create destination folder

Can not create destination folder

Noneinvalid specification for input file (please use url format)

Invalid path for input file

Noneinput 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)

Noneinvalid specification for output file (please use url format)

Invalid specification for output file

Noneoutput 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)

NoneOne 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.

Nonecouldn't parse json

The request data is invalid.

Nonelunabus handler error; luna didn't pass a valid instance var to handler

Internal luna bus error.

NoneFile 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

wallpaperNameRequiredString

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

wallpaperOptionalObject: Wallpaper

A wallpaper object corresponding with the deleted wallpaper

returnValueRequiredBoolean

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
errorCodeOptionalNumber

The error code for the failed operation.

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

NoneInvalid 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.

1lunabus handler error; luna didn't pass a valid instance var to handler

Internal luna bus error.

1must specify wallpaperName

The wallpaper filename is not specified in the request.

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

targetRequiredString

Path to the image file.

focusXOptionalNumber

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.

focusYOptionalNumber

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.

scaleOptionalNumber

Scale parameter determines the new size of the image, must be greater than zero.

Call Returns

Name

Required

Type

Description

wallpaperOptionalObject: Wallpaper

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

returnValueRequiredBoolean

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

Noneempty input file path specified

Input file path should not be empty.

Noneinvalid specification for input file (please use url format)

Invalid specification for input file.

Noneinput 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.

Nonelunabus handler error; luna didn't pass a valid instance var to handler

Internal luna bus error.

Noneno input file specified

The input file is not specified in the request.

NonePath is missing

The path is not specified in the request.

NoneBoth path and file name are missing

The path and the filename are not specified in the request.

Nonefilename is missing

The name of the wallpaper file is not specified in the request.

Nonecouldn't create thumbnail

Failed to create a thumbnail from the wallpaper image.

NoneFile 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

wallpaperNameOptionalString

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

wallpaperFileOptionalString

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

wallpaperOptionalObject: Wallpaper

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

returnValueRequiredBoolean

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

Noneinvalid wallpaper name specified (perhaps it doesn't exist in the wallpaper dir; was it imported?)

Invalid wallpaper name specified.

NoneMust specify either the "wallpaperName" or the "wallpaperFile".

Must specify either the wallpaperName or the wallpaperFile.

Nonelunabus handler error; luna didn't pass a valid instance var to handler

Internal luna bus error.

Noneinvalid 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

returnValueRequiredBoolean

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

yearOptionalNumber

The year. Default value is current year

monthRequiredNumber

The month (1-12).

dayOfWeekRequiredNumber

Day of the week (0 - 6). 0 is for Sunday, 1 - for Monday and so on to 6 - for Saturday

dayRequiredNumber

Occurrence of the day of the week within the month (1 - 5).

hourRequiredNumber

The hour (0 - 23).

minuteOptionalNumber

The minute (0 - 59). Default value is 0

secondOptionalNumber

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

sourceOptionalString

Path to the original file.

destRequiredString

Path to the output file.

destTypeRequiredString

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

yearRequiredNumber

The year.

monthRequiredNumber

The month (1-12).

dayOfWeekOptionalNumber

Day of the week (0 - 6).

dayRequiredNumber

The day (1 - 31).

hourRequiredNumber

The hour (0 - 23).

minuteRequiredNumber

 The minute (0 - 59).

secondRequiredNumber

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

valueRequiredNumber

Offset in seconds from the time-source.

sourceRequiredString

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

yearOptionalNumber

The year

monthOptionalNumber

The month. Possible values are 1 - 12.

dayOfWeekOptionalNumber

Day of week. Possible values are 0 - 6, where 0 is Sunday and 6 is Saturday.

weekOptionalNumber

Week of the month. Possible values are 1 - 5, where 1 is the 1st week and 5 is the last or 5th week of month.

hourOptionalNumber

The hour. Possible values are 0 - 23.

minuteOptionalNumber

The minute (0-59)

secondOptionalNumber

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

tzOptionalString

The timezone.

yearOptionalNumber

The year.

hasDstChangeOptionalBoolean

True if daylight saving time is in use in this timezone.

utcOffsetRequiredNumber

Time difference from UTC time in seconds.

dstOffsetOptionalNumber

Time difference from UTC time in seconds during daylight saving time.

dstStartOptionalNumber

The time when daylight saving time starts during the year, presented in Unix time.

dstEndOptionalNumber

The time when daylight saving time ends during the year, presented in Unix time. 

Timestamp

Contains details of the timestamp.

Name

Required

Type

Description

sourceRequiredString

Source of the timestamp. For example monotonic, etc.

Note: currently only monotonic is used.

secRequiredNumber

Seconds for the timestamp

nsecRequiredNumber

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

wallpaperNameRequiredString

The wallpaperName that was passed to the wallpaper managing methods.

wallpaperFileOptionalString

Path to file with wallpaper image.

wallpaperThumbFileOptionalString

Path to file with wallpaper thumbnail.

Contents