com.webos.service.preferences

Note
This API has been available since API level 11.

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

ACG: preferences.applicationpropertyquery
  • Added: API level 11

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

appIdRequiredString

ID of the application to fetch properties for.

Call Returns

Name

Required

Type

Description

returnValueOptionalBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "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.

NoneOptionalObject array

The array of application property objects.

Each application property object contains a single element:

  • key - the property name (string)
  • value - the property value (string)

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

Noneno appId parameter found

appId parameter not specified.

Example

Example code

# 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

ACG: preferences.applicationpropertyquery
  • Added: API level 11

Description

The getAllAppPropertiesObj method gets all properties set to an application as an object.

Parameters

Name

Required

Type

Description

appIdRequiredString

appId is the id of the application to fetch properties for.

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

valuesOptionalObject 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

Noneno appId parameter found

appId parameter not specified

Example

Example code

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

ACG: preferences.applicationpropertyquery
  • Added: API level 11

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

appIdRequiredString

appId is the id of the application to fetch property keys for.

Call Returns

Name

Required

Type

Description

returnValueOptionalBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "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.

NoneOptionalString 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

Noneno appId parameter found

appId parameter not specified.

Example

Example code

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

ACG: preferences.applicationpropertyquery
  • Added: API level 11

Description

The getAppKeys method returns all property keys for an application as a JSON object.

Parameters

Name

Required

Type

Description

appIdRequiredString

appId is the id of the application to fetch property keys for.

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

valuesOptionalstring array

values is a an array containing the keys for the application settings.

Error Codes Reference

Error Code

Error Text

Error Description

Noneno appId parameter found

appId parameter not specified

Example

Example code

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

ACG: preferences.applicationpropertyquery
  • Added: API level 11

Description

The getAppProperty method returns an application property for a specific key.

Parameters

Name

Required

Type

Description

appIdRequiredString

appId is the id of the application to fetch properties for.

keyRequiredString

key is the key of the property to be fetched.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

If the getAppProperty method succeeds, returnValue will contain true.

If the getAppProperty method fails, returnValue will contain false.

errorTextOptionalString

Contains the error text if the getAppProperty method fails. The getAppProperty method will return errorText only if it fails.

keyOptionalobject

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

Noneno such key

Specified key is not exists.

Noneno appId or key parameter found

appId or key parameter is not specified at request.

Example

Example code

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

ACG: preferences.operation
  • Added: API level 11

Description

The getAppProperty method removes an application property.

Parameters

Name

Required

Type

Description

appIdRequiredString

appId is the id of the application to fetch properties for.

keyRequiredString

key is the key of the property to be removed.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

If the removeAppProperty method succeeds, returnValue will contain true.

If the removeAppProperty method fails, returnValue will contain false

errorTextOptionalString

С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

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

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

ACG: preferences.operation
  • Added: API level 11

Description

Add or change an application property.

Parameters

Name

Required

Type

Description

appIdRequiredString

appId is the id of the application to fetch properties for.

keyRequiredString

key is the key of the property that is to be added or changed.

valueRequiredobject

value is the value that the property is to be set to. Must be a JSON object.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

If the setAppProperty method succeeds, returnValue will contain true.

If the setAppProperty method fails, returnValue will contain false

errorTextOptionalString

С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

NoneMissing required parameter 'appId'.

Missing required parameter appId.

NoneMissing required parameter 'key'.

Missing required parameter key.

NoneMissing required parameter 'value'.

Missing required parameter value.

Noneillegal value (not a json document)

Illegal parameter value (not a json document).

Example

Example code

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

}

backup/postRestore

ACG: preferences.management
  • Added: API level 11

Description

postRestore method restores the application/services preferences from lunaprefs_backup.db provided in the parameter.

Parameters

Name

Required

Type

Description

tempDirRequiredString

Directory path where lunaprefs_backup.db is present.

filesRequiredString array

Array containing the backedup db names from which preferences data will be restored.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

If the backup/postRestore method succeeds, returnValue will contain true

If the backup/postRestore method fails, returnValue will contain false.

errorTextOptionalString

Contains the error text if the backup/postRestore method fails. The backup/postRestore method will return errorText only if it fails.

errorPayloadOptionalString

Will contain error payload of luna-send message if call fails.

Error Codes Reference

Error Code

Error Text

Error Description

NoneCannot get payload

This message indicates that internal Luna bus error occurred.

NoneCannot parse payload

This message indicates that there is an error in the input parameters json object.

NoneRequired parameter "tempDir" is missing

This message indicates that there required parameter tempDir is not specified.

NoneParameter "tempDir" must have value type string

This message indicates that the Parameter tempDir does not have a string type.

NoneRequired parameter "files" is missing

This message indicates that there required parameter files is not specified.

NoneParameter "files" must have value type array

This message indicates that the Parameter files does not have a array type.

Noneunable to restore preference db

This message indicates that an error occurred during restore.

Example

Example code

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

ACG: preferences.management
  • Added: API level 11

Description

preBackup method takes backup of application/services preferences stored in "/var/preferences" path.

Parameters

Name

Required

Type

Description

tempDirOptionalString

Path where backup database file is to be stored.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

If the backup/preBackup method succeeds, returnValue will contain true

If the backup/preBackup method fails, returnValue will contain false.

backupFileRequiredString

Full file name of backup database. 

filesOptionalString array

Deprecated: Array of all backed-up db paths.

errorPayloadOptionalString

Will contain error payload of luna-send message if call fails (if tempDir is not of type String).

errorTextOptionalString

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

NoneCannot get payload

This message indicates that internal Luna bus error occurred.

NoneCannot parse payload

This message indicates that there is an error in the input parameters json object.

NonePeyload must have type object

This message indicates that the input parameters json does not have a object type.

NoneParameter "tempDir" must have value type string

This message indicates that the Parameter tempDir does not have a string type.

NoneUnable to create backup file

This message indicates that an error occurred during backup.

Example

Example code

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"

}

systemProperties/Get

ACG: preferences.systempropertyquery
Deprecated
  • Added: API level 11
  • Deprecated: API level 21

Description

The systemProperties/Get method has been deprecated. Use systemProperties/getSysProperty instead.

Parameters

None

Example

None

systemProperties/getAllSysProperties

ACG: preferences.systempropertyquery
Deprecated
  • Added: API level 11
  • Deprecated: API level 21

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

returnValueOptionalBoolean

If the getAllSysProperties method fails, returnValue will contain false

The getAllSysProperties method may fail because of:

  • memory overflow
  • storage hardware failure

or other system errors.

errorTextOptionalString

errorText contains the error text if the getAllSysProperties method fails. The getAllSysProperties method will return errorText only if it fails.

NoneOptionalObject array

The array of system property objects.

Each system property object contains a single element:

  • key - the property name (string)
  • value - the property value (string)

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

Example code

# 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

ACG: preferences.systempropertyquery
Deprecated
  • Added: API level 11
  • Deprecated: API level 21

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

returnValueRequiredBoolean

If the getAllSysPropertiesObj method succeeds, returnValue will contain true

If the getAllSysPropertiesObj method fails, returnValue will contain false.

errorTextOptionalString

Сontains the error text if the getAllSysPropertiesObj method fails. The getAllSysPropertiesObj method will return errorText only if it fails.

valuesOptionalpreferences array

values is an array of objects with key/value pairs that contain the individual system settings. 

Example

Example code

# 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

ACG: preferences.systempropertyquery
Deprecated
  • Added: API level 11
  • Deprecated: API level 21

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

keyRequiredString

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

NoneOptionalObject array

The array of system property objects.

Each system property object contains a single element:

  • key - the property name (string)
  • value - the property value (string)

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

Nonegeneral parameter error

The request parameters format is wrong.

Nonemissing 'key' parameter

The key parameter is not specified.

Example

Example code

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

ACG: preferences.systempropertyquery
Deprecated
  • Added: API level 11
  • Deprecated: API level 21

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

keyRequiredString 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

returnValueRequiredBoolean

If the getSomeSysPropertiesObj method succeeds, returnValue will contain true

If the getSomeSysPropertiesObj method fails, returnValue will contain false.

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

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

ACG: preferences.systempropertyquery
Deprecated
  • Added: API level 11
  • Deprecated: API level 21

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

NoneOptionalString 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

Example code

# luna-send -n 1 -f luna://com.webos.service.preferences/systemProperties/getSysKeys {}

[

"com.webos.service.properties.browserOsName",

"com.webos.service.properties.deviceName",

...

]

systemProperties/getSysKeysObj

ACG: preferences.systempropertyquery
Deprecated
  • Added: API level 11
  • Deprecated: API level 21

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

returnValueRequiredBoolean

returnValue will always contain true

valuesOptionalstring 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

Example code

# 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

ACG: preferences.systempropertyquery
Deprecated
  • Added: API level 11
  • Deprecated: API level 21

Description

The getSysProperty method returns a system property.

Parameters

Name

Required

Type

Description

keyRequiredString

key is the key of the system property that is to be fetched.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

If the getSysProperty method succeeds, returnValue will contain true

If the getSysProperty method fails, returnValue will contain false.

errorTextOptionalString

Contains the error text if the getSysProperty method fails. The getSysProperty method will return errorText only if it fails.

keyOptionalobject

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

Nonemissing parameter key

Missing required parameter key.

Noneno such key

Specified key is not exists.

Example

Example code

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"

}

Contents