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

(click to expand)

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


Open All


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

appIdRequiredstring

appId is the 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 References

Error Code

Error Text

Error Description

Noneno 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

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 References

Error Code

Error Text

Error Description

Noneno 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

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 References

Error Code

Error Text

Error Description

Noneno 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

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 References

Error Code

Error Text

Error Description

Noneno 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

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 References

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

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 References

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

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 References

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

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 References

Error Code

Error Text

Error Description

NoneCannot get payload

 This message indicates that internal luna bus error occured.

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

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

aValueRequiredAny

A value


Except as noted, this content is licensed under Creative Commons Attribution 4.0 and sample code is licensed under Apache License 2.0.