com.webos.service.settings

Note
This API has been available since API level 11.

API Summary

Settings Service manages the settings used in webOS and provides the setting information (descriptions) such as Set, Get functions to setting values, the valid range of data that can be set, and whether UI is exposed or not. Subscription option is supported for all settings.

Settings Service manages different values according to dimension, such as country and external input, under the same setting. When the dimension has changed, it sends a necessary subscription message.

Overview of the API

Method	Description	Subscription
batch	It is used when processing multiple methods as one Luna call.	Support
deleteSystemSettings	Delete settings.	-
getCurrentSettings	Return foreground app related settings.	Support
getSystemSettingDesc	Return settings info (Description).	Support
getSystemSettings	Return settings value.	Support
getSystemSettingFactoryValue	Return default value.	-
getSystemSettingValues	Return the info of valid range of the possible setting value.	Support
resetSystemSettings	Initialize setting value and switch to default value.	-
resetSystemSettingDesc	Change settings info (Description) to default value.	-
setSystemSettingDesc	Modify settings info (Description).	-
setSystemSettingFactoryDesc	Modify default value of the settings info (Description).
setSystemSettingFactoryValue	Change default value.	-
setSystemSettings	Change settings.	-
setSystemSettingValues	Modify the info of the valid range of the possible setting value.	-
update	update customized settings forcefully	-
internal/instrument	Generate log for debug and change current app.
internal/getCurrentSubscriptions	Return the information of currently subscribed service.

Methods

batch

ACG: settings.management

Added: API level 11

Description

Runs more than one Settings Service method at once.

Remarks
- Subscription is supported only when all the methods in operations input parameter support subscription.
Exception
- Atomicity is not supported.

Parameters

Name	Required	Type	Description
operations	Required	Object array: batchOperation	A set of objects containing method name and the method's parameters as properties.
subscribe	Optional	boolean	Indicates whether to subscribe for related events. true: Subscribe false: Do not subscribe (default) Should be set to true if any of the batchOperation`s params have a 'subscribe' option set to true

Name

Required

Type

Description

operations

Required

Object array: batchOperation

A set of objects containing method name and the method's parameters as properties.

Optional

boolean

Indicates whether to subscribe for related events.

true: Subscribe
false: Do not subscribe (default)

Should be set to true if any of the batchOperation`s params have a 'subscribe' option set to true

Call Returns

Name	Required	Type	Description
results	Required	array	It contains method property and the result of each method that matches passed operations. method property contains name of the method. It is used to clarify which method is called from the many responses returned from batch.
subscribed	Optional	boolean	Indicates the current subscription status.
returnValue	Required	Boolean	Indicates whether the execution succeeded. true: Success false: Failure

Name

Required

Type

Description

results

Required

array

It contains method property and the result of each method that matches passed operations.

method property contains name of the method. It is used to clarify which method is called from the many responses returned from batch.

subscribed

Optional

boolean

Indicates the current subscription status.

returnValue

Required

Boolean

Indicates whether the execution succeeded.

true: Success
false: Failure

Subscription Returns

Name	Required	Type	Description
N/A	Optional	String	Although the first response includes all methods' responses, in the subscription response, only necessary method responses are included. The subscription form is determined according to each method described in operations parameter.

Error Codes Reference

Error Code	Error Text	Error Description
N/A	N/A	The errors of each method included in the batch method are described in results.

Example

Example code

Run luna-send command:

# luna-send -n 1 luna://com.webos.service.settings/batch '{
"operations": [
{
   "method": "getSystemSettings",
   "params": {
  "category": "picture",
   "keys": [
"brightness"
],
"subscribe":true
}
},
{
"method": "getSystemSettingDesc",
"params": {
"category": "picture",
    "keys": [
  "brightness"
],
"subscribe":true
   }
}
],
  "subscribe": true
}'

Example response for a successful call:

{

"returnValue": true,

"results": [

{

"method":"getSystemSettigns",

"settings": {

"brightness": "50"

"category": "picture",

"dimension": {

"input": "comp1",

"pictureMode": "normal",

"_3dStatus": "2d"

"returnValue": true

{

"method":"getSystemSettingDesc",

"returnValue": true,

"results": [

{

"category": "picture",

"dimension": [

"input",

"pictureMode",

"_3dStatus"

"key": "brightness",

"ui": {

"active": true,

"displayName": "brightness",

"visible": true,

"widget": "None"

"valueCheck": true,

"values": {

"range": {

"interval": 1,

"max": 100,

"min": 0

}

"volatile": false,

"vtype": "Range"

}

]

}

]

}

Example response for a failed call

{

"returnValue": true,

"results": [

{

"errorText": "no result from DB",

"category": "picture",

"dimension": {},

"method": "getSystemSettings",

"returnValue": false

{

"returnValue": false,

"error": "no result in DB",

"subscribed": false,

"method": "getSystemSettingDesc"

}

]

}

deleteSystemSettings

ACG: settings.management

Added: API level 11

Description

Deletes settings item(s). Factory default value is also deleted.

Remarks
- In case there is a subscriber for the deleted item, error text will be sent.
Exception
- Errors occur when using undefined dimension.

Parameters

Name	Required	Type	Description
category	Optional	string	Category of settings
dimension	Optional	Object: dimension	Dimension information. It is used when setting by input, video mode, 3D mode.
keys	Required	String array	Keys to be deleted
app_id	Optional	string	App ID. In case of app specific setting, app ID should be specified.

Call Returns

Name	Required	Type	Description
method	Required	string	Method name. It is used to clarify which method is called from the many responses returned from batch.
returnValue	Required	boolean	Indicates whether the execution succeeded. true: Success false: Failure
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details.

Name

Required

Type

Description

method

Required

string

Method name. It is used to clarify which method is called from the many responses returned from batch.

returnValue

Required

boolean

Indicates whether the execution succeeded.

true: Success
false: Failure

errorText

Optional

String

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

Error Codes Reference

Error Code	Error Text	Error Description
N/A	invalid key array	It throws error for invalid key or empty key as invalid key array

Example

Example code

# luna-send -n 1 luna://com.webos.service.settings/deleteSystemSettings '{
"category": "option",
"keys": [
"zipcode"
]
}' -f

Response:

{
"method": "deleteSystemSettings",
"returnValue": true

}

Example of the failed case:

# luna-send -n 1 luna://com.webos.service.settings/deleteSystemSettings '{ "category": "option", "keys": [ ]}' -f

{

"returnValue": false,

"errorText": "invalid key array",

"method": "deleteSystemSettings"

}

getCurrentSettings

ACG: settings.query

Added: API level 11

Description

Looks up the settings item, and returns the settings for the current foreground app only unlike the setSystemSettings method.

Remarks
- Even though the foreground app is converted, the subscription message for the changed app settings will not be sent.
Exception
- Errors occur when using undefined dimensions.

Parameters

Name	Required	Type	Description
category	Optional	string	Category of settings. If omitted, it means the group that doesn't have category name.
dimension	Optional	Object: dimension	Dimension information. It is used when changing settings for a specific dimension. If omitted, the currently used dimension is used.
keys	Required	array	Keys to be retrieved
subscribe	Optional	boolean	Indicates whether to subscribe for related events. true: Subscribe false: Do not subscribe (false)

Call Returns

Name	Required	Type	Description
settings	Required	Object: settings	Objects that holds setting values.
category	Required	string	Category of settings. It is same with the value specified in category input parameter.
dimension	Required	Object: dimension	In case there is a dimension property in settings category, it returns the corresponding value.
method	Required	string	Method name. It is used to clarify which method is called from the many responses returned from batch.
app_id	Required	string	Current foreground app ID
subscribed	Optional	boolean	Indicates the current subscription status.
returnValue	Required	boolean	Indicates whether the execution succeeded. true: Success false: Failure
errorText	Optional	string	Describes the error. The method will return errorText only if it fails. See the Error Codes Reference for more details.

Subscription Returns

Name	Required	Type	Description
settings	Required	Object	Objects that holds setting values.
category	Required	String	Category of settings. It is same with the value specified in category input parameter.
dimension	Optional	Object: dimension	In case there is a dimension property in settings category, it returns the corresponding value.
method	Required	String	Method name. It is used to clarify which method is called from the many responses returned from batch.
app_id	Required	String	In case of settings by app, it returns App ID.
returnValue	Required	Boolean	Indicates whether the execution succeeded.
errorText	Optional	String	Describes the error. The method will return errorText only if it fails. See the Error Codes Reference for more details.

Error Codes Reference

Error Code	Error Text	Error Description
None	There is no matched result from DB	Requested keys are undefined.

Example

Example code

Run luna-send command:

# luna-send -n 1 luna://com.webos.service.settings/getCurrentSettings '{
"category": "lock",
"keys": [
"applockPerApp"
]
}'

Example response for a successful call:

{

"settings": {

"applockPerApp": false

"app_id": "com.webos.app.live",

"category": "lock",

"method": "getSystemSettings",

"returnValue": true

}

Example response for a failed call:

{

"errorText": "There is no matched result from DB",

"app_id": "com.webos.app.live",

"category": "lock",

"method": "getSystemSettings",

"returnValue": false

}

getSystemSettingDesc

ACG: settings.query

Added: API level 11

Description

Retrieves detailed information on the settings.

Exception
- The request for nonexistent keys will be processed as an error.

Parameters

Name	Required	Type	Description
category	Optional	string	Category of settings
keys	Optional	array	Keys for retrieving setting values. One of the keys and key should be specified.
key	Optional	string	A key for retrieving setting value. One of keys and key should be specified.
app_id	Optional	String	App ID. If target key is app specific setting, app ID should be specified.
current_app	Optional	Boolean	If app ID isn't specified, use current foreground app ID. If app ID is explicitly given, this parameter is ignored. true: Use current foreground app ID false: Don't use app ID default value: false
subscribe	Optional	boolean	Indicates whether to subscribe for related events. true: Subscribe false: Do not subscribe (false)

Call Returns

Name	Required	Type	Description
category	Required	String	Category of settings. It is same with the value specified in category input parameter.
dbtype	Required	String	Database type. One of the following values will be returned. "G" : Global type "S" : PerApp type "M" : Mixed type "E" : ExceptionApp type
dimension	Required	Object: dimension	In case there is a dimension property in settings category, it returns the corresponding value.
key	Required	String	Requested key
valueCheck	Required	boolean	Indicates whether the validation check for the settings values is performed. true: The validation check is performed false: The validation check is not performed
volatile	Required	boolean	Indicates whether to initialize with the factory default value when resetting the system (device is rebooted). true: Initialized with the factory default value false: Not initialized with the factory default value
ui	Required	Object: ui	Object for UI information containing active and visible flags as property.
vtype	Required	String	Type of values object. One of the following value will be returned: array, arrayExt, range, callback, file
values	Required	Object: values	The valid range of the setting value. The properties of the values are determined according to vtype.
app_id	Optional	String	If the result setting is app specific value, app ID will be returned.
returnValue	Required	Boolean	Indicates whether the execution succeeded. true: Success false: Failure
errorText	Optional	String	Describes the error. The method will return errorText only if it fails. See the Error Codes Reference for more details.
subscribed	Optional	Boolean	Indicates the current subscription status.

Subscription Returns

Name	Required	Type	Description
category	Required	String	Category of settings. It is same with the value specified in category input parameter.
dbtype	Required	String	Database type. One of the following values will be returned. "G" : Global type "S" : PerApp type "M" : Mixed type "E" : ExceptionApp type
dimension	Required	Object: dimension	In case there is a dimension property in settings category, it returns the corresponding value.
key	Required	String	Requested key
valueCheck	Required	Boolean	Indicates whether the validation check for the settings values is performed. true: The validation check is performed false: The validation check is not performed
volatile	Required	Boolean	Indicates whether to initialize with the factory default value when resetting the system (device is rebooted). true: Initialized with the factory default value false: Not initialized with the factory default value
ui	Required	Object: ui	Object for UI information containing active and visible flags as property.
vtype	Required	String	Type of values object. One of the following value will be returned: array, arrayExt, range, callback, file
values	Required	Object: values	The valid range of the setting value. The properties of the values are determined according to vtype.
errorText	Optional	String	Describes the error. The method will return errorText only if it fails. See the Error Codes Reference for more details.
returnValue	Required	Boolean	Indicates whether the execution succeeded.

Error Codes Reference

Error Code	Error Text	Error Description
None	no result in DB	An undefined key is requested.

Example

Example code

Run luna-send command:

# luna-send -n 1 luna://com.webos.service.settings/getSystemSettingDesc '{"category":"picture", "keys":["brightness"]}' -f

Example response for a successful call:

{

"method": "getSystemSettingDesc",

"returnValue": true,

"results": [

{

"vtype": "Range",

"dbtype": "G",

"ui": {

"active": true,

"displayName": "brightness",

"visible": true,

"widget": "None"

"values": {

"range": {

"interval": 1,

"max": 100,

"min": 0

}

"volatile": false,

"valueCheck": true,

"category": "picture",

"dimension": [

"input",

"pictureMode",

"_3dStatus"

"key": "brightness"

}

]

}

Example response for a failed call:

{

"error": "no result in DB",

"method": "getSystemSettingDesc",

"returnValue": false

}

getSystemSettingFactoryValue

ACG: settings.query

Added: API level 11

Description

Retrieves the factory default value of the setting item. Method of use is the same as getSystemSettings.

Remarks
- Dimension is applied in the same way as getSystemSettings.
- Subscription is not supported.
Exception
- If undefined dimension is used, errors will occur.

Parameters

Name	Required	Type	Description
category	Optional	String	Category of settings
dimension	Optional	Object: dimension	Dimension information. It is used when setting by input, video mode, 3D mode.
keys	Optional	String array	Keys to be retrieved. One of keys and key should be specified.
key	Optional	String	A key to be retrieved. In case there is one key to be retrieved, directly input the strings. One of keys and key should be specified.
app_id	Optional	String	App ID. In case of app specific setting, app ID should be specified.

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates whether the execution succeeded. true: Success false: Failure
errorText	Optional	String	Describes the error. The method will return errorText only if it fails. See the Error Codes Reference for more details.
method	Required	String	Method name. It is used to clarify which method is called from the many responses returned from batch.
dimension	Required	Object: dimension	In case there is a dimension property in settings category, it returns the corresponding value.
category	Required	String	Settings category name
settings	Required	Object: settings	Object that holds setting values.

Error Codes Reference

Error Code	Error Text	Error Description
None	no result in DB	An undefined key is requested.

Example

Example code

Run luna-send command:

# luna-send -n 1 luna://com.webos.service.settings/getSystemSettingFactoryValue '{"category":"picture", "key":"brightness"}' -f

Example response for a successful call:

{

"dimension": {

"pictureMode": "eco",

"input": "comp1",

"_3dStatus": "2d"

"category": "picture",

"method": "getSystemSettingFactoryValue",

"settings": {

"brightness": "50"

"returnValue": true

}

Example response for a failed call:

{

"dimension": {

"category": "picture",

"method": "getSystemSettingFactoryValue",

"returnValue": false,

"errorText": "no result from DB"

}

getSystemSettingValues

ACG: settings.query

Added: API level 11

Description

Retrives possible items to be set

Remarks
- The return type varies depending on the keys.
- Use getSystemSettingDesc method for the retrieval of additional info other than configurable valid conditions
Exception
- Errors will occur when retrieving the undefined keys.

Parameters

Name	Required	Type	Description
category	Optional	String	Category of settings
key	Required	String	A key to be retrieved
app_id	Optional	String	In case of setting by app, app ID needs to be specified.
subscribe	Optional	boolean	Indicates whether to subscribe for related events. true: Subscribe false: Do not subscribe (default)

Call Returns

Name	Required	Type	Description
method	Required	String	Method name. It is used to clarify which method is called from the many responses returned from batch.
vtype	Required	String	Type of values object.
values	Required	Object: values	The valid range of the setting value. The properties of the values are determined according to vtype.
returnValue	Required	boolean	Indicates whether the execution succeeded. true: Success false: Failure
errorText	Optional	string	Describes the error. The method will return errorText only if it fails. See the Error Codes Reference for more details.
subscribed	Required	Boolean	Indicates the current subscription status.

Subscription Returns

Name	Required	Type	Description
method	Required	String	Method name. It is used to clarify which method is called from the many responses returned from batch.
vtype	Required	String	Type of values object.
values	Required	Object: values	The valid range of the setting value. The properties of the values are determined according to vtype.
returnValue	Required	Boolean	Indicates whether the execution succeeded.
subscribed	Required	Boolean	Indicates the current subscription status.

Error Codes Reference

Error Code	Error Text	Error Description
None	no result in DB	An undefined key is requested.

Example

Example code

# luna-send -n 1 luna://com.webos.service.settings/getSystemSettingValues '{"category":"picture", "key":"brightness"}' -f

Response for a successful call:

{
"method": "getSystemSettingValues",
"subscribed": true,
"returnValue": true,
"vtype": "Range",
"values": {
"range": {
"interval": 1,
"max": 100,
"min": 0
}
}
}

Response for a failed call:

{
"error": "no result in DB",
"method": "getSystemSettingValues",
"returnValue": false
}

getSystemSettings

ACG: settings.query

Added: API level 11

Description

Retrieves values from system settings with keys or category which are specified in array as parameter. Following keys are available in public bus.

Category	Key	Remarks
N/A	localeInfo	Locale info such as Menu, Audio
N/A	eulaStatus	End-User License Agreement
caption	captionEnable	Caption settings
option	country	Country settings (ISO 3166-1 alpha-3)
option	smartServiceCountryCode2	Service country settings (ISO 3166-1 alpha-2)
option	smartServiceCountryCode3	Service country settings (ISO 3166-1 alpha-3)

Remarks
- There is additional feature named 'Dimension'. We can store different settings values with a KEY using different dimension. Imagine array. Using dimension, we can keep different settings values simultaneously, and categorize settings into some groups. Dimension is index by other keys settingsservice has. For example, Brightness key has 3 dimensions, input, 3dmode, and pictureMode. You can store different brightness value according to 3 different settings, input, 3dmode, and pictureMode.
Exception
- If getSystemSettings is called with undefined category and key, it will return error.

Parameters

Name	Required	Type	Description
category	Optional	string	Category of settings If the specified keys (key) has a category, you must specify this property. If you only use this property without keys or key, this method will return all values which are in the specified category.
dimension	Optional	Object: dimension	Specify dimension information for special key (e.g. brightness has 3 dimensions, input, _3dMode, pictureMode). Current dimensions is applied if dimension is not specified.
keys	Optional	array	Keys for retrieving setting values. One of keys and key should be specified.
key	Optional	string	A key for retrieving setting value. One of keys and key should be specified.
app_id	Optional	string	App ID. If target key is app specific setting, app ID should be specified.
current_app	Optional	boolean	Indicates whether to use current foreground app ID instead of specific app ID. true: Use current foreground app ID false: Use specific app ID default value: false
subscribe	Optional	boolean	Indicates whether to subscribe for related events. true: Subscribe false: Do not subscribe

Call Returns

Name	Required	Type	Description
settings	Required	Object: settings	Objects that holds result setting values.
category	Required	string	Category name of the result settings. It is same with category parameter in method call.
dimension	Required	Object: dimension	Dimension information of the result settings. In case the setting category has a dimension, it returns its value.
method	Required	string	Method name that is used for clarify which method is called in subscription messages.
app_id	Optional	string	If the result setting is app specific value, app ID will be returned.
subscribed	Optional	boolean	Indicates the current subscription status.
returnValue	Required	boolean	Indicates whether the execution succeeded. true: Success false: Failure
errorText	Optional	string	Describes the error. The method will return errorText only if it fails. See the Error Codes Reference for more details.

Subscription Returns

Name	Required	Type	Description
settings	Required	Object: settings	Objects that holds result setting values.
category	Required	String	Category name of the result settings. It is same with category parameter in method call.
dimension	Required	Object: dimension	Dimension information of the result settings. In case the setting category has a dimension, it returns its value.
method	Required	String	Method name that is used for clarify which method is called in subscription messages.
app_id	Optional	String	If the result setting is app specific value, app ID will be returned.
returnValue	Optional	String	Indicates whether the execution succeeded.
errorText	Optional	String	Describes the error. The method will return errorText only if it fails. See the Error Codes Reference for more details.

Error Codes Reference

Error Code	Error Text	Error Description
N/A	There is no matched result from DB	Requested keys are undefined.

Example

Example code

Example 1:

# luna-send -f -n 1 luna://com.webos.service.settings/getSystemSettings '{
"category":"option",
"keys":["country", "smartServiceCountryCode2"]
}'

Response:

{
  "category": "option",
  "method": "getSystemSettings",
  "settings": {
"smartServiceCountryCode2": "GB",
"country": "FRA"
  },
  "returnValue": true
}

Example 2:

# luna-send -f -n 1 luna://com.webos.service.settings/getSystemSettings '{"keys":["localeInfo"]}'

Response:

{
  "method": "getSystemSettings",
  "settings": {
  "localeInfo": {
  "locales": {
  "UI": "en-GB",
  "TV": "en-GB",
  "FMT": "en-GB",
  "NLP": "en-GB",
"STT": "fr-FR",
"AUD2": "en-GB"
  },
  "clock": "locale",
"keyboards": ["en"],
  "timezone": ""
  }
  },
  "returnValue": true
}

internal/getCurrentSubscriptions

ACG: settings.devutility

Added: API level 11

Description

Returns the information of the services which currently subscribe to the Settings Service.

Parameters

None

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates whether the execution succeeded.

true: Success
false: Failure

subscriptions

Required

Object array: subscription

The list of the services (e.g., message, sender, method) which are currently subscribing to the Settings Service.

errorText

Optional

String

Describes the error. The method will return errorText only if it fails. See the Error Codes Reference for more details.

Error Codes Reference

Error Code	Error Text	Error Description
None	cannot run command or ls-monitor is running	ls-monitor has been already running or cannot run command
None	cannot parse result or ls-monitor is running	Cannot parse the ls-monitor results
None	memory allocation error	Memory related errors

Example

Example code

Run luna-send command: (Create log)

# luna-send -n 1 -f luna://com.webos.service.settings/internal/getCurrentSubscriptions '{}'

Example response for a successful call:

{

"returnValue": true,

"subscriptions": [

{

"message": "{ \"category\": \"option\", \"keys\": [ \"country\" ], \"subscribe\": true }",

"sender": "com.webos.service.update",

"method": "getSystemSettings"

}

]

}

internal/instrument

ACG: settings.devutility

Added: API level 11

Description

Generates log for debug and changes current app.

Remarks
- Generates logs for every luna call
- Changes current app id

Parameters

Name	Required	Type	Description
control	Required	String	Information on internal method settings
params	Optional	Object	The current app ID to be changed

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates whether the execution succeeded.

true: Success
false: Failure

instrumentStatus

Optional

String

Instrument setting status

errorText

Optional

String

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

Error Codes Reference

Error Code	Error Text	Error Description
N/A	Error!! to insert request for internal category to task que	Fatal failure like OOM.
N/A	Unexpected request on PrefsInternalCategory::handleMethodInstrument	Unexpected request on PrefsInternalCategory::handleMethodInstrument

Error Code

Error Text

Error Description

N/A

Error!! to insert request for internal category to task que

Fatal failure like OOM.

N/A

Unexpected request on PrefsInternalCategory::handleMethodInstrument

Example

Example : Create log

# luna-send -n 1 -f luna://com.webos.service.settings/internal/instrument '{"control":"start"}'

Response for a successful call:

{
"instrumentStatus": "started",
"returnValue": true
}

Response for a failed call:

{
"returnValue": false,
"errorText": "unexpected request on PrefsInternalCategory::handleMethodInstrument"
}

Example : Change current app

# luna-send -n 1 -f luna://com.webos.service.settings/internal/instrument '{"control":"changeApp","params":{"app_id":"com.webos.app.live"}}'

Response:

{
"returnValue": true
}

resetSystemSettingDesc

ACG: settings.management

Added: API level 11

Description

Initializes the settings item information to the factory default value.

Exception
- Error occurs when requesting to delete nonexistent keys.

Parameters

Name	Required	Type	Description
category	Optional	string	Category of settings
keys	Required	array	Keys to be reset to the factory default value
app_id	Optional	String	App ID. If target key is app specific setting, app ID should be specified.

Call Returns

Name	Required	Type	Description
method	Required	string	Method name. It is used to clarify which method is called from the many responses returned from batch.
returnValue	Required	boolean	Indicates whether the execution succeeded. true: Success false: Failure
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details.

Name

Required

Type

Description

method

Required

string

Method name. It is used to clarify which method is called from the many responses returned from batch.

returnValue

Required

boolean

Indicates whether the execution succeeded.

true: Success
false: Failure

errorText

Optional

String

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

Error Codes Reference

Error Code	Error Text	Error Description
N/A	no keys specified	It will throw error for failed cases as no keys specified

Example

Example code

# luna-send -n 1 -a com.webos.setting luna://com.webos.service.settings/resetSystemSettingDesc '{"category":"support"}'

Response:

{
"method": "resetSystemSettingDesc"
"returnValue": true
}

Example of failed case

luna-send -f -n 1 -a com.webos.setting luna://com.webos.service.settings/resetSystemSettingDesc '{"category":"support"}'

{

"returnValue": false,

"errorText": "no keys specified",

"method": "resetSystemSettingDesc"

}

resetSystemSettings

ACG: settings.management

Added: API level 11

Description

Initializes the setting items to the factory default values.

Remarks
- For the given category, when changing setting items, other items can be initialized according to the dimension.
- For the key with 'E' dbtype, the values of ExceptionApp list will be equally changed.
Exception
- Error occurs when using undefined dimension.

Parameters

Name	Required	Type	Description
category	Optional	string	Category of settings
dimension	Optional	Object: dimension	Dimension information. It is used when setting by input, video mode, 3D mode.
keys	Required	array	Keys to be reset to the factory default value
app_id	Optional	string	App ID. If target key is app specific setting, app ID should be specified.
resetAll	Optional	boolean	Indicates whether to reset the settings for all dimensions. true: Reset false: Do not reset (default)

Call Returns

Name	Required	Type	Description
method	Required	string	Method name that is used for clarify which method is called in subscription messages.
returnValue	Required	boolean	Indicates whether the execution succeeded. true: Success false: Failure
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details.

Name

Required

Type

Description

method

Required

string

Method name that is used for clarify which method is called in subscription messages.

returnValue

Required

boolean

Indicates whether the execution succeeded.

true: Success
false: Failure

errorText

Optional

String

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

Error Codes Reference

Error Code	Error Text	Error Description
N/A	invalid key array	It throws error for invalid key as invalid key array

Example

Example code

# luna-send -n 1 -a com.webos.setting luna://com.webos.service.settings/resetSystemSettings '{"category":"support", "keys":["automaticUpdate"]}'

Response:

{
"returnValue": true
}

Example of failed call

luna-send -f -n 1 -a com.webos.setting luna://com.webos.service.settings/resetSystemSettings '{"category":"support", "keys":[]}'

{

"returnValue": false,

"errorText": "invalid key array",

"method": "resetSystemSettings"

}

setSystemSettingDesc

ACG: settings.management

Added: API level 11

Description

Changes detailed information of the settings.

Exception
- Category, key, dimension, dbtype, volatile attributes cannot be changed during runtime.

Parameters

Name	Required	Type	Description
category	Optional	string	Category of settings
key	Required	string	A key to be set
app_id	Optional	String	App ID. In case of app specific setting, app ID should be specified.
ui	Optional	Object: ui	Object for UI information containing active and visible flags as property.
vtype	Optional	string	Type of values object. Possible values: array, arrayExt, range, callback, file.
values	Optional	Object: values	Specify the properties of the values object according to vtype.
volatile	Optional	boolean	Indicates whether to initialize the setting when resetting the system. true: Initialized false: Not initialized
valueCheck	Optional	boolean	Indicates whether to perform the validation check on the set values. true: Do not perform false: Perform
notifySelf	Optional	boolean	Indicates whether to receive the subscription message. true: The subscribe message will be sent to self false: The subscribe message will not be sent to self
ext	Optional	Object: ext	reserved property

Call Returns

Name	Required	Type	Description
method	Required	string	Method name that is used for clarify which method is called in subscription messages.
returnValue	Required	boolean	Indicates whether the execution succeeded. true: Success false: Failure
errorText	Optional	string	Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details.

Name

Required

Type

Description

method

Required

string

Method name that is used for clarify which method is called in subscription messages.

returnValue

Required

boolean

Indicates whether the execution succeeded.

true: Success
false: Failure

errorText

Optional

string

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

Error Codes Reference

Error Code	Error Text	Error Description
None	The format of value is wrong	vtype and the combination of values do not match. (e.g. In case vtype is arrayExt, there must exist arrayExt in values object.)

Example

Example code

# luna-send -f -n 1 -a com.webos.service.settings luna://com.webos.service.settings/setSystemSettingDesc '{
"key": "brightness",
"ui": {
"visible": false,
"displayName": "brightness",
"active": true,
"widget": "None"
}
}'

Response for a successful call:

{
"method": "setSystemSettingDesc",
"returnValue": true
}

Response for a failed call:

{
"method": "setSystemSettingDesc",
"returnValue": false,
"errorText": "The format of value is wrong. 'value':{$ref:'VaildValues'}. $ref is one of 'array', 'range', or 'date'"
}

setSystemSettingFactoryDesc

ACG: settings.management

Added: API level 11

Description

Sets the default value when reset by resetSystemSettingDesc.

It is the same type as setSystemSettingDesc method, and it can change the factory default values of the settings info.

Remarks
- Settings item info is in JSON type, and includes the following.
Exception
- Category, key, dimension, dbtype, volatile attributes cannot be changed during runtime.

Parameters

Name	Required	Type	Description
category	Optional	string	Category of settings
key	Required	string	Setting key
app_id	Optional	String	App ID. In case of app specific setting, app ID should be specified.
ui	Optional	Object array: ui	Object for UI information containing active and visible flags as property.
vtype	Optional	string	Type of values object.
values	Optional	Object: values	Specify the properties of the values object according to vtype.
volatile	Optional	boolean	Indicates whether to initialize the setting when resetting the system. true: Initialized false: Not initialized
valueCheck	Optional	boolean	Indicates whether to perform the validation check on the set values. true: Do not perform false: Perform
notifySelf	Optional	boolean	Indicates whether to receive the subscription message. true: The subscribe message will be sent to self false: The subscribe message will not be sent to self
ext	Optional	Object: ext	reserved property

Call Returns

Name	Required	Type	Description
method	Required	string	Method name that is used for clarify which method is called in subscription messages.
returnValue	Required	boolean	Indicates whether the execution succeeded. true: Success false: Failure
errorText	Optional	string	Describes the error. The method will return errorText only if it fails. See the Error Codes Reference for more details.

Name

Required

Type

Description

method

Required

string

Method name that is used for clarify which method is called in subscription messages.

returnValue

Required

boolean

Indicates whether the execution succeeded.

true: Success
false: Failure

errorText

Optional

string

Describes the error. The method will return errorText only if it fails. See the Error Codes Reference for more details.

Error Codes Reference

Error Code	Error Text	Error Description
None	The format of value is wrong	vtype and the combination of values do not match. (e.g. In case vtype is arrayExt, there must exist arrayExt in values object.)

Example

Example code

Run luna-send command:

# luna-send -f -n 1 -a com.webos.service.settings luna://com.webos.service.settings/setSystemSettingFactoryDesc '{
"key": "brightness",
"ui": {
"visible": false,
"displayName": "brightness",
"active": true,
"widget": "None"
}
}'

Response for a successful call:

{
"returnValue": true,
"method": "setSystemSettingFactoryDesc"
}

Response for a failed call:

{
"method": "setSystemSettingFactoryDesc",
"returnValue": false,
"errorText": "The format of value is wrong. 'value':{$ref:'VaildValues'}. $ref is one of 'array', 'range', or 'date'"
}

setSystemSettingFactoryValue

ACG: settings.management

Added: API level 11

Description

Changes the factory default of the setting item. The using method is same as setSystemSettings method.

It can set the default value when resetSystemSettings method is called.

Remarks
- In case of the following specific categories, when changing settings, it can store different values according to conditions such as dimension.
Exception
- When using undefined dimension, errors will occur.

Parameters

Name	Required	Type	Description
category	Optional	string	Category of settings
app_id	Optional	String	App ID. In case of app specific setting, app ID should be specified.
dimension	Optional	Object: dimension	Dimension information. It is used when setting by input, video mode, 3D mode.
settings	Required	Object: settings	Settings to be saved
setAll	Optional	boolean	Indicates whether to set the settings for all dimensions. Either dimension or setAll can be specified. true: Set the settings for all dimensions false: Set the settings for the given dimension only default value: false
country	Optional	string	Set to change settings of a specific country only

Call Returns

Name	Required	Type	Description
method	Required	string	Method name that is used for clarify which method is called in subscription messages.
returnValue	Required	boolean	Indicates whether the execution succeeded. true: Success false: Failure
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details.

Name

Required

Type

Description

method

Required

string

Method name that is used for clarify which method is called in subscription messages.

returnValue

Required

boolean

Indicates whether the execution succeeded.

true: Success
false: Failure

errorText

Optional

String

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

Error Codes Reference

Error Code	Error Text	Error Description
N/A	Parsing Fail!	The payload isn't a correct JSON.
N/A	Used both setAll and dimension	Ambiguous parameters: either setAll or dimension can be specified in the request.
N/A	no settings specified	Parameter validation failure: settings should be specified.
N/A	'settings' should be set json_object type	Parameter validation: settings isn't a JSON object
N/A	'Key' shouldn't be NULL	Parameter validation: settings shouldn't be empty.
N/A	ERROR!! send a request to DB	Failed to send a request to the DB.

Example

Example code

# luna-send -f -n 1 luna://com.webos.service.settings/setSystemSettingFactoryValue '{
"category":"picture",
"dimension":{"input":"hdmi2", "pictureMode":"vivid", "_3dStatus":"2d"},
"settings":{"brightness":30, "contrast":44}
}'

Response for a successful call:

{
"method": "setSystemSettingFactoryValue",
"returnValue": true
}

setSystemSettingValues

ACG: settings.management

Added: API level 11

Description

Changes the formats of the configurable values. It can change detailed information using setSystemSettingDesc method.

Exception
- When undefined keys are requested to change settings, errors will occur.

Parameters

Name	Required	Type	Description
category	Optional	string	Category of settings
key	Required	string	Setting key
values	Required	Object: values	Specify the properties of the values object according to vtype.
vtype	Required	string	Type of values object. One of the following value will be returned: Array, ArrayExt, Range, Callback, File, Date
op	Required	string	Method of settings. One of the following values can be set: set, add, remove, update.

Call Returns

Name	Required	Type	Description
method	Optional	string	Method name that is used for clarify which method is called in subscription messages.
returnValue	Required	boolean	Indicates whether the execution succeeded. true: Success false: Failure
errorText	Optional	string	Describes the error. The method will return errorText only if it fails. See the Error Codes Reference for more details.

Name

Required

Type

Description

method

Optional

string

Method name that is used for clarify which method is called in subscription messages.

returnValue

Required

boolean

Indicates whether the execution succeeded.

true: Success
false: Failure

errorText

Optional

string

Describes the error. The method will return errorText only if it fails. See the Error Codes Reference for more details.

Error Codes Reference

Error Code	Error Text	Error Description
None	The format of value is wrong	vtype and the combination of values do not match. (e.g. In case vtype is arrayExt, there must exist arrayExt in values object.)
None	no result in DB	An undefined key is requested.

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.settings/setSystemSettingValues '{
"category":"sampleCategory",
"key":"sampleKey",
"op":"set",
"vtype":"ArrayExt",
"values":{
"arrayExt":[
{
"value":"expert1",
"visible":false,
"active":false
}
]
}
}'

Response:

{
"method": "setSystemSettingValues",
"returnValue": true
}

setSystemSettings

ACG: settings.management

Added: API level 11

Description

Changes settings. It is available only for the keys open to public when called through Public Luna bus. The permission setting is as follow.

Category	Key	Remarks
caption	captionEnable	Caption setting

Remarks
- In case of the following specific categories, when changing settings, it can store different values according to the dimension.
- For the keys with 'E' dbtype, the values of ExceptionApp list will be equally changed.
Exception
- When an undefined dimension is used, errors will occur.

Parameters

Name	Required	Type	Description
category	Optional	string	Category of settings
dimension	Optional	Object: dimension	It is used when setting by input, video mode, 3D mode.
settings	Required	Object: settings	Settings to be saved
app_id	Optional	string	App ID. In case of app specific setting, app ID should be specified.
notifySelf	Optional	boolean	Indicates whether to receive the subscription message. true: The subscribe message will be sent to self false: The subscribe message will not be sent to self
current_app	Optional	boolean	Indicates whether to return the settings of the current foreground app true: the settings of the current foreground app gets returned false: use app ID specified in the perameter app_id default value: false
setAll	Optional	boolean	Indicates whether to set the settings of all dimensions. true: Set the settings for all dimensions false: Set the settings for the dimension specified in the parameter dimension default value: false
notify	Optional	boolean	Indicates whether to receive the subscription message. true: The subscribe message will be sent false: The subscribe message will not be sent
store	Optional	boolean	Indicates whether to store the subscription message in DB true: Store in DB false: Do not tore in DB. Only subscription message will be sent. default value: true

Call Returns

Name

Required

Type

Description

method

Required

string

Method name that is used for clarify which method is called in subscription messages.

returnValue

Required

boolean

Indicates whether the execution succeeded.

true: Success
false: Failure

errorText

Optional

String

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

Error Codes Reference

Error Code	Error Text	Error Description
N/A	'Key' shouldn't be NULL"	Parameter validation: settings shouldn't be empty.
N/A	Error checking access rights	When the Sender or SenderServiceName is empty or NULL

Example

Example code

# luna-send \-n 1 luna://com.webos.service.settings/setSystemSettings '{
"category":"picture",
"dimension":{"input":"hdmi2", "pictureMode":"vivid", "_3dStatus":"2d"},
"settings":{"brightness":30, "contrast":44}
}'

Response:

{
"method": "setSystemSettings",
"returnValue": true
}

Objects

arrayExt

This object describes the strings among the selectable value type.

Name	Required	Type	Description
active	Required	Boolean	If it's True, it means it is the value that users can select.
visible	Required	Boolean	Only if it's True, it is displayed to the user as a selectable item.
value	Required	String	Defines the value that is stored when the user makes a selection.

batchOperation

This object describes the methods to be executed in batch method.

Name	Required	Type	Description
method	Required	String	Method name
params	Required	Object: params	The object that includes the parameters defined by method.

callback

Reserved. Not implemented.

date

Reserved. Not implemented.

dimension

Settings Service can set many different values under the same setting according to dimension.

Name	Required	Type	Description
input	Optional	String	You can use the following values: av1, av2, pictest, comp1, comp2, comp3, rgb, hdmi1, hdmi2, hdmi3, hdmi4, hdmi1_pc, hdmi2_pc, hdmi3_pc, hdmi4_pc, movie, photo, default, scart
_3dPattern	Optional	String	You can use the following values: 2dto3d, 3d
_3dStatus	Optional	String	You can use the following values: 2d, 3d
pictureMode	Optional	String	You can use the following values: vivid, normal, eco, cinema, game, sports, expert1, expert2
_3dMode	Optional	String	You can use the following values: standard, sports, cinema, extreme, manual, auto

ext

It is defined for future expansion. Not in use now.

params

This object has the corresponding parameters to the methods described in the batch method's operations as property. No specific format needed.

range

It is used when describing the user-configurable data in the integer range.

Name	Required	Type	Description
interval	Required	Number (int32_t)	Interval between the values that the user can select in the integer range.
min	Required	Number (int32_t)	Minimum value among the integer values that the user can select
max	Required	Number (int32_t)	Maximum value among the integer values that the user can select

settings

It is the Object that has the setting property. No specific format to follow.

subscription

This object describes an active subscription to the settings service.

Name	Required	Type	Description
message	Required	Object	The original payload of the subscription request.
sender	Required	String	Service name of the subscriber
method	Required	String	Method name that subscriber called to create the subscription.

ui

It is the object to be referred to when creating user UI like Settings App.

Name	Required	Type	Description
active	Required	Boolean	If it's True, users can make a change.
visible	Required	Boolean	If it's true, the menu that users can select is displayed.
displayName	Required	String	The name of Settings menu that is displayed to users.
widget	Required	String	UI Component information like Combo Box and List. (currently not in use)

values

Specify the properties of the values object according to vtype. It is the information that is used for the validation of configurable values.

The format for the value of each vtype is:

array
{
array: [ string, string, ...]
}
arrayExt
{
arrayExt: [ object, object, ...]
}
Object Syntax:
{
   visible: boolean
   active: boolean
   value: string
}
range
{
range: {
    max: integer
    min: integer
    interval: integer
}
}

Name	Required	Type	Description
array	Optional	String array	Array of configurable strings
arrayExt	Optional	Object array: arrayExt	Array of extended information of the configurable strings
range	Optional	Object: range	Valid range in integer
callback	Optional	Object: callback	Validation check for external callback
date	Optional	Object: date	Format of date and time
file	Optional	String	Describes valid data on the external file