com.webos.service.settings
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
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.
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.
|
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
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.
|
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
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.
|
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.
|
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
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.
|
subscribe | Optional | boolean | Indicates whether to subscribe for related events.
|
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.
|
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.
|
volatile | Required | boolean | Indicates whether to initialize with the factory default value when resetting the system (device is rebooted).
|
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.
|
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.
|
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.
|
volatile | Required | Boolean | Indicates whether to initialize with the factory default value when resetting the system (device is rebooted).
|
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
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.
|
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"
}
getSystemSettings
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
|
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.
|
subscribe | Optional | boolean | Indicates whether to subscribe for related events.
|
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.
|
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
}
getSystemSettingValues
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.
|
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.
|
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
}
internal/getCurrentSubscriptions
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.
|
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
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.
|
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 |
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
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.
|
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
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.
|
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.
|
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
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.
|
valueCheck | Optional | boolean | Indicates whether to perform the validation check on the set values.
|
notifySelf | Optional | boolean | Indicates whether to receive the subscription message.
|
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.
|
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
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.
|
valueCheck | Optional | boolean | Indicates whether to perform the validation check on the set values.
|
notifySelf | Optional | boolean | Indicates whether to receive the subscription message.
|
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.
|
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
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.
|
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.
|
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
}
setSystemSettings
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.
|
current_app | Optional | boolean | Indicates whether to return the settings of the current foreground app
|
setAll | Optional | boolean | Indicates whether to set the settings of all dimensions.
|
notify | Optional | boolean | Indicates whether to receive the subscription message.
|
store | Optional | boolean | Indicates whether to store the subscription message in DB
|
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.
|
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
}
setSystemSettingValues
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.
|
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
}
Objects
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 |
settings
It is the Object that has the setting property. No specific format to follow.
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 |
ext
It is defined for future expansion. Not in use now.
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. |
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 |
date
Reserved. Not implemented.
callback
Reserved. Not implemented.
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. |
params
This object has the corresponding parameters to the methods described in the batch method's operations as property. No specific format needed.
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. |