com.webos.service.preferences
API Summary
Enables applications to manage system and application properties.
Note: This service must be used only if existing system applications are already using it. Else, use "com.webos.service.systemservice".
Overview of the API
Allows webOS applications to save and load custom settings. The methods accept settings as a JSON object.
The setting is specified as a pair of key - value. For example, {"filename" : "image.jpg"}.
Methods
appProperties/getAllAppProperties
Description
The getAllAppProperties gets all properties set to an application as an object array.
Note: If the getAllAppProperties method succeeds, there will be no returnValue and the returned object will only be an array of JSON objects containing key/value pairs.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| appId | Required | string | appId is the id of the application to fetch properties for. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Optional | boolean | Indicates the status of operation. Possible values are:
|
| errorText | Optional | string | Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details. |
| None | Optional | Object array | The array of application property objects. Each application property object contains a single element:
See the return example for details. Note: The name of the property 'None' indicates that the return value does not have a property name. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| None | no appId parameter found | appId parameter not specified. |
Example
Example for successful calls:
# luna-send -n 1 -f luna://com.webos.service.preferences/appProperties/getAllAppProperties '{"appId": "com.webos.service.preferences"}'
[
]
# luna-send -n 1 -f luna://com.webos.service.preferences/appProperties/getAllAppProperties '{"appId": "testApp"}'
[
{
"testKey": {
"testValueKey": "testValue"
}
}
]
Example for a failed call:
# luna-send -n 1 -f luna://com.webos.service.preferences/appProperties/getAllAppProperties '{}'
{
"returnValue": false,
"errorText": "no appId parameter found"
}
appProperties/getAllAppPropertiesObj
Description
The getAllAppPropertiesObj method gets all properties set to an application as an object.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| appId | Required | string | appId is the id of the application to fetch properties for. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | boolean | Indicates the status of operation. Possible values are:
|
| errorText | Optional | string | Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details. |
| values | Optional | Object array | values is an array of objects with key/value pairs that contain the individual application settings. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| None | no appId parameter found | appId parameter not specified |
Example
Example of a successful call:
#luna-send -n 1 -f luna://com.webos.service.preferences/appProperties/getAllAppPropertiesObj '{"appId": "com.webos.service.app.calendar"}'
{
"values": [
{
"aKey": {
"aValue": "lots"
}
},
{
"anotherKey": {
"anotherValue": "many"
}
},
{
"oneMoreKey": {
"anInt": 1,
"anotherInt": 2
}
}
],
"returnValue": true
}
Example of a failed call:
#luna-send -n 1 -f luna://com.webos.service.preferences/appProperties/getAllAppPropertiesObj '{"appId": "com.webos.service.foo"}'
{
"returnValue": false,
"errorText": "no appId parameter found"
}
appProperties/getAppKeys
Description
The getAppKeys method returns all property keys for an application as a string array.
Note: If the getAppKeys method succeeds, there will be no returnValue and the returned object will only be an array of strings.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| appId | Required | String | appId is the id of the application to fetch property keys for. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Optional | boolean | Indicates the status of operation. Possible values are:
|
| errorText | Optional | string | Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details. |
| None | Optional | String array | An array of property keys. Each array element is the property name. Note: The name of the property 'None' indicates that the return value does not have a property name. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| None | no appId parameter found | appId parameter not specified. |
Example
Example for a successful call:
# luna-send -n 1 -f luna://com.webos.service.preferences/appProperties/getAppKeys '{"appId": "com.webos.rdxd"}'
[
"reportIdNum"
]
Example for a failed call:
# luna-send -n 1 -f luna://com.webos.service.preferences/appProperties/getAppKeys '{}'
{
"returnValue": false,
"errorText": "no appId parameter found"
}
appProperties/getAppKeysObj
Description
The getAppKeys method returns all property keys for an application as a JSON object.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| appId | Required | string | appId is the id of the application to fetch property keys for. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | boolean | Indicates the status of operation. Possible values are:
|
| errorText | Optional | string | Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details. |
| values | Optional | string array | values is a an array containing the keys for the application settings. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| None | no appId parameter found | appId parameter not specified |
Example
Example for a successful call:
# luna-send -n 1 -f luna://com.webos.service.preferences/appProperties/getAppKeysObj '{"appId": "com.webos.rdxd"}'
{
"returnValue": true,
"values": [
"reportIdNum"
]
}
Example for a failed call:
# luna-send -n 1 -f luna://com.webos.service.preferences/appProperties/getAppKeysObj '{}'
{
"returnValue": false,
"errorText": "no appId parameter found"
}
appProperties/getAppProperty
Description
The getAppProperty method returns an application property for a specific key.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| appId | Required | string | appId is the id of the application to fetch properties for. |
| key | Required | string | key is the key of the property to be fetched. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | boolean | If the getAppProperty method succeeds, returnValue will contain true. If the getAppProperty method fails, returnValue will contain false. |
| errorText | Optional | string | Contains the error text if the getAppProperty method fails. The getAppProperty method will return errorText only if it fails. |
| key | Optional | object | Contains the value for the requested key. Note: The name of the property will be the same as the requested key, not the word 'key'. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| None | no such key | Specified key is not exists. |
| None | no appId or key parameter found | appId or key parameter is not specified at request. |
Example
Example for a successful call:
# luna-send -n 1 -f luna://com.webos.service.preferences/appProperties/getAppProperty '{"appId": "com.webos.rdxd", "key": "reportIdNum"}'
{
"returnValue": true,
"reportIdNum": [
"7"
]
}
Example for a failed call:
# luna-send -n 1 -f luna://com.webos.service.preferences/appProperties/getAppProperty '{"appId": "com.webos.rdxd", "key": "reportIdNum"}'
{
"returnValue": false,
"errorText": "no such key"
}
appProperties/removeAppProperty
Description
The getAppProperty method removes an application property.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| appId | Required | string | appId is the id of the application to fetch properties for. |
| key | Required | string | key is the key of the property to be removed. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | boolean | If the removeAppProperty method succeeds, returnValue will contain true. If the removeAppProperty method fails, returnValue will contain false. |
| errorText | Optional | string | Сontains the error text if the removeAppProperty method fails. The removeAppProperty method will return errorText only if it fails. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| None | no such key | Specified key is not exists. |
| None | 'appId'(string)/'key'(string) parameter is missing | appId or key parameter is not specified at request. |
Example
Example for a successful call:
# luna-send -n 1 -f luna://com.webos.service.preferences/appProperties/removeAppProperty '{"appId":"testApp", "key":"testKey"}'
{
"returnValue": true
}
Example for a failed call:
# luna-send -n 1 -f luna://com.webos.service.preferences/appProperties/removeAppProperty '{"appId":"testApp", "key":"testKey"}'
{
"returnValue": false,
"errorText": "no such key"
}
appProperties/setAppProperty
Description
Add or change an application property.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| appId | Required | string | appId is the id of the application to fetch properties for. |
| key | Required | string | key is the key of the property that is to be added or changed. |
| value | Required | object | value is the value that the property is to be set to. Must be a JSON object. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | boolean | If the setAppProperty method succeeds, returnValue will contain true. If the setAppProperty method fails, returnValue will contain false. |
| errorText | Optional | string | Сontains the error text if the setAppProperty method fails. The setAppProperty method will return errorText only if it fails. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| None | Missing required parameter 'appId'. | Missing required parameter appId. |
| None | Missing required parameter 'key'. | Missing required parameter key. |
| None | Missing required parameter 'value'. | Missing required parameter value. |
| None | illegal value (not a json document) | Illegal parameter value (not a json document). |
Example
Example for a successful call:
# luna-send -n 1 -f luna://com.webos.service.preferences/appProperties/setAppProperty '{"appId":"testApp", "key":"testKey", "value":{"testValueKey":"testValue"}}'
{
"returnValue": true
}
Example for failed calls:
# luna-send -n 1 -f luna://com.webos.service.preferences/appProperties/setAppProperty '{}'
{
"returnValue": false,
"errorText": "Missing required parameter 'appId'."
}
# luna-send -n 1 -f luna://com.webos.service.preferences/appProperties/setAppProperty '{"appId":"testApp", "key":"testKey", "value":"testValue"}'
{
"returnValue": false,
"errorText": "illegal value (not a json document)"
}
systemProperties/Get
Description
The systemProperties/Get method has been deprecated. Use systemProperties/getSysProperty instead.
Parameters
None
Example
systemProperties/getAllSysProperties
Description
The getAllSysProperties method returns all system properties as an object array.
Note: The call is always sucessful, except when an internal webOS error occurs (more details can be found in the syslog). If the call is successful, only an object array is returned. returnValue and errorText are returned only if the call fails.
Parameters
None
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Optional | boolean | If the getAllSysProperties method fails, returnValue will contain false. The getAllSysProperties method may fail because of:
or other system errors. |
| errorText | Optional | string | errorText contains the error text if the getAllSysProperties method fails. The getAllSysProperties method will return errorText only if it fails. |
| None | Optional | Object array | The array of system property objects. Each system property object contains a single element:
See the return example for details. Note: The name of the property 'None' indicates that the return value does not have a property name. |
Example
# luna-send -n 1 -f luna://com.webos.service.preferences/systemProperties/getAllSysProperties {}
[
{
"com.webos.service.properties.browserOsName": "Open webOS"
},
{
"com.webos.service.properties.deviceName": "Open webOS Device"
},
...
]
systemProperties/getAllSysPropertiesObj
Description
The getAllSysPropertiesObj method returns all system properties as an object.
Note: On a successful return, there will be no returnValue and the returned object will only be an array of JSON objects containing key/value pairs.
Parameters
None
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | boolean | If the getAllSysPropertiesObj method succeeds, returnValue will contain true. If the getAllSysPropertiesObj method fails, returnValue will contain false. |
| errorText | Optional | string | Сontains the error text if the getAllSysPropertiesObj method fails. The getAllSysPropertiesObj method will return errorText only if it fails. |
| values | Optional | preferences array | values is an array of objects with key/value pairs that contain the individual system settings. |
Example
# luna-send -n 1 -f luna://com.webos.service.preferences/systemProperties/getAllSysPropertiesObj {}
{
"returnValue": true,
"values": [
{
"com.webos.service.properties.browserOsName": "Open webOS"
},
{
"com.webos.service.properties.deviceName": "Open webOS Device"
},
...
]
}
systemProperties/getSomeSysProperties
Description
The getSomeSysProperties method takes an object array of property keys and returns an array of objects with key-value pairs for each of the keys. The getSomeSysProperties method returns the equivalent to what getSysProperty would have returned for each key. If one of the keys fails, an error is returned in that element of the array but the rest go through.
Note: On a successful return, there will be no returnValue and the returned object will only be an array of JSON objects containing key/value pairs.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| key | Required | String | A JSON array of keys for which the key-value pairs are returned. Note: The parameter is an array: ["k1", "k2"], and not an object: [{"key": "k1"}, {"key": "k2"}] |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| None | Optional | Object array | The array of system property objects. Each system property object contains a single element:
See the return example for details. Note: In case the method fails, the key will contain the errorText, and the value will contain a more detailed error message for that errorText. See the example below. Note: The name of the property 'None' indicates that the return value does not have a property name. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| None | general parameter error | The request parameters format is wrong. |
| None | missing 'key' parameter | The key parameter is not specified. |
Example
Example for a successful call:
# luna-send -n 1 -f luna://com.webos.service.preferences/systemProperties/getSomeSysProperties '[{"key": "com.webos.service.properties.browserOsName"}, {"key": "com.webos.service.properties.deviceName"}]'
[
{
"com.webos.service.properties.browserOsName": "Open webOS"
},
{
"com.webos.service.properties.deviceName": "Open webOS Device"
}
]
Example for a failed call:
# luna-send -n 1 -f luna://com.webos.service.preferences/systemProperties/getSomeSysProperties '["com.webos.service.properties.browserOsName"]'
[
{
"errorText": "missing 'key' parameter"
}
]
systemProperties/getSomeSysPropertiesObj
Description
The getSomeSysPropertiesObj method takes an object array of property keys and returns an object containing an array of objects with key-value pairs for each of the keys. The getSomeSysPropertiesObj method returns the equivalent to what getSysProperty would have returned for each key. If one of the keys fails, an error is returned in that element of the array but the rest go through.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| key | Required | String array | A JSON array of keys for which the key-value pairs are returned. Note: The parameter is an array: ["k1", "k2"], and not an object: [{"key": "k1"}, {"key": "k2"}] |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | boolean | If the getSomeSysPropertiesObj method succeeds, returnValue will contain true. If the getSomeSysPropertiesObj method fails, returnValue will contain false. |
| values | Optional | preferences array | values will contain an array of objects containing key/value pairs. Note: In case the method fails, the key will contain the errorText, and the value will contain a more detailed error message for that errorText. See the example below. Single or multiple errors can be reported. |
Example
Example for a successful calls:
# luna-send -n 1 -f luna://com.webos.service.preferences/systemProperties/getSomeSysPropertiesObj '[{"key": "com.webos.service.properties.browserOsName"}, {"key": "com.webos.service.properties.deviceName"}]'
{
"returnValue": true,
"values": [
{
"com.webos.service.properties.browserOsName": "Open webOS"
},
{
"com.webos.service.properties.deviceName": "Open webOS Device"
}
]
}
Example for failed calls:
# luna-send -n 1 -f luna://com.webos.service.preferences/systemProperties/getSomeSysPropertiesObj '[{"key": "testError"}, {"key": "com.webos.service.properties.deviceName"}]'
{
"returnValue": false,
"values": [
{
"errorText": "no such key"
},
{
"com.webos.service.properties.deviceName": "webOS TV Reference Device"
}
]
}
# luna-send -n 1 -f luna://com.webos.service.preferences/systemProperties/getSomeSysPropertiesObj '[{"key": "testError"}, {"key": "testError2"}]'
{
"returnValue": false,
"values": [
{
"errorText": "no such key"
},
{
"errorText": "no such key"
}
]
}
systemProperties/getSysKeys
Description
The getSysKeys method returns a the list of system property keys as a string array.
Note: This function does not return a JSON object.
This method is always successful, it never reports any errors.
Parameters
None
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| None | Optional | String array | An array of system property keys. Each array element has a key name. See the return example for details. Note: The name of the property 'None' indicates that the return value does not have a property name. |
Example
# luna-send -n 1 -f luna://com.webos.service.preferences/systemProperties/getSysKeys {}
[
"com.webos.service.properties.browserOsName",
"com.webos.service.properties.deviceName",
...
]
systemProperties/getSysKeysObj
Description
The getSysKeysObj method returns a the list of system property keys as a JSON object.
This method is always successful, it never reports any errors.
Parameters
None
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | boolean | returnValue will always contain true. |
| values | Optional | string array | values is an array of strings containing the system keys. The system keys may be different depending on the OS, build, device, etc. |
Example
# luna-send -n 1 -f luna://com.webos.service.preferences/systemProperties/getSysKeysObj {}
{
"returnValue": true,
"values": [
"com.webos.service.properties.browserOsName",
"com.webos.service.properties.deviceName",
...
]
}
systemProperties/getSysProperty
Description
The getSysProperty method returns a system property.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| key | Required | string | key is the key of the system property that is to be fetched. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | boolean | If the getSysProperty method succeeds, returnValue will contain true. If the getSysProperty method fails, returnValue will contain false. |
| errorText | Optional | string | Contains the error text if the getSysProperty method fails. The getSysProperty method will return errorText only if it fails. |
| key | Optional | object | Contains the value for the requested key. Note: The name of the property will be the same as the requested key, not the word 'key'. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| None | missing parameter key | Missing required parameter key. |
| None | no such key | Specified key is not exists. |
Example
Example for a successful call:
# luna-send -n 1 -f luna://com.webos.service.preferences/systemProperties/getSysProperty '{"key": "com.webos.service.properties.browserOsName"}'
{
"com.webos.service.properties.browserOsName": "Open webOS",
"returnValue": true
}
Example for a failed call:
# luna-send -n 1 -f luna://com.webos.service.preferences/systemProperties/getSysProperty '{"key": "testError"}'
{
"returnValue": false,
"errorText": "no such key"
}
backup/postRestore
Description
postRestore method restores the application/services preferences from lunaprefs_backup.db provided in the parameter.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| tempDir | Required | String | Directory path where lunaprefs_backup.db is present. |
| files | Required | String array | Array containing the backedup db names from which preferences data will be restored. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | If the backup/postRestore method succeeds, returnValue will contain true. If the backup/postRestore method fails, returnValue will contain false. |
| errorText | Optional | String | Contains the error text if the backup/postRestore method fails. The backup/postRestore method will return errorText only if it fails. |
| errorPayload | Optional | String | Will contain error payload of luna-send message if call fails. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| None | Cannot get payload | This message indicates that internal Luna Bus error occured. |
| None | Cannot parse payload | This message indicates that there is an error in the input parameters json object. |
| None | Required parameter "tempDir" is missing | This message indicates that there required parameter tempDir is not specified. |
| None | Parameter "tempDir" must have value type string | This message indicates that the Parameter tempDir does not have a string type. |
| None | Required parameter "files" is missing | This message indicates that there required parameter files is not specified. |
| None | Parameter "files" must have value type array | This message indicates that the Parameter files does not have a array type. |
| None | unable to restore preference db | This message indicates that an error occurred during restore. |
Example
Example for a successful call:
# luna-send -n 1 -f luna://com.webos.service.preferences/backup/postRestore '{"tempDir":"/var/","files":["/var/preferences/lunaprefs_backup.db"]}'
{
"returnValue": true
}
Example for failed calls:
# luna-send -n 1 -f luna://com.webos.service.preferences/backup/postRestore '{"files":["/var/preferences/lunaprefs_backup.db"]}'
{
"errorPayload": "{\"files\":[\"/var/preferences/lunaprefs_backup.db\"]}",
"returnValue": false,
"errorText": "Required parameter \"tempDir\" is missing"
}
# luna-send -n 1 -f luna://com.webos.service.preferences/backup/postRestore '{"tempDir":"/var/"}'
{
"errorPayload": "{\"tempDir\":\"/var/\"}",
"returnValue": false,
"errorText": "Required parameter \"files\" is missing"
}
backup/preBackup
Description
preBackup method takes backup of application/services preferences stored in "/var/preferences" path.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| tempDir | Optional | String | Path where backup database file is to be stored. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | If the backup/preBackup method succeeds, returnValue will contain true. If the backup/preBackup method fails, returnValue will contain false. |
| backupFile | Required | String | Full file name of backup database. |
| files | Optional | String array | Deprecated: Array of all backed-up db paths. |
| errorPayload | Optional | String | Will contain error payload of luna-send message if call fails (if tempDir is not of type String). |
| errorText | Optional | String | Contains the error text if the backup/preBackup method fails. The backup/preBackup method will return errorText only if it fails. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| None | Cannot get payload | This message indicates that internal Luna Bus error occured. |
| None | Cannot parse payload | This message indicates that there is an error in the input parameters json object. |
| None | Peyload must have type object | This message indicates that the input parameters json does not have a object type. |
| None | Parameter "tempDir" must have value type string | This message indicates that the Parameter tempDir does not have a string type. |
| None | Unable to create backup file | This message indicates that an error occurred during backup. |
Example
Example for successful calls:
# luna-send -n 1 -f luna://com.webos.service.preferences/backup/preBackup '{}'
{
"backupFile": "/var/preferences/lunaprefs_backup.db",
"files": [
"/var/preferences/lunaprefs_backup.db"
],
"returnValue": true
}
# luna-send -n 1 -f luna://com.webos.service.preferences/backup/preBackup '{"tempDir": "/tmp"}'
{
"backupFile": "/tmp/lunaprefs_backup.db",
"files": [
"/tmp/lunaprefs_backup.db"
],
"returnValue": true
}
Example for failed calls:
# luna-send -n 1 -f luna://com.webos.service.preferences/backup/preBackup '{"tempDir": "/tmp/nonexistent"}'
{
"backupFile": "/tmp/nonexistent/lunaprefs_backup.db",
"returnValue": false,
"errorText": "Unable to create backup file"
}
# luna-send -n 1 -f luna://com.webos.service.preferences/backup/preBackup '{"tempDir": ["/directory"]}'
{
"errorPayload": "{\"tempDir\": [\"/directory\"]}",
"returnValue": false,
"errorText": "Parameter \"tempDir\" must have value type string"
}
Objects
PreferenceValue
Returned value of a preference.
Name | Required | Type | Description |
|---|---|---|---|
| aValue | Required | Any | A value |