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

MethodDescriptionSubscription

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.

-

updateupdate 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

operationsRequiredObject array: batchOperation

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

subscribeOptionalBoolean

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

resultsRequiredarray

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.

subscribedOptionalBoolean

Indicates the current subscription status.

returnValueRequiredBoolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure

Subscription Returns

Name

Required

Type

Description

N/AOptionalString

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

categoryOptionalString

Category of settings

dimensionOptionalObject: dimension

Dimension information. It is used when setting by input, video mode, 3D mode.

keysRequiredString array

Keys to be deleted

app_idOptionalString

App ID. In case of app specific setting, app ID should be specified.

Call Returns

Name

Required

Type

Description

methodRequiredString

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

returnValueRequiredBoolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorTextOptionalString

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

categoryOptionalString

Category of settings. If omitted, it means the group that doesn't have category name.

dimensionOptionalObject: dimension

Dimension information. It is used when changing settings for a specific dimension. If omitted, the currently used dimension is used.

keysRequiredarray

Keys to be retrieved

subscribeOptionalBoolean

Indicates whether to subscribe for related events.

  • true: Subscribe
  • false: Do not subscribe (false)

Call Returns

Name

Required

Type

Description

settingsRequiredObject: settings

Objects that holds setting values.

categoryRequiredString

Category of settings. It is same with the value specified in category input parameter.

dimensionRequiredObject: dimension

In case there is a dimension property in settings category, it returns the corresponding value.

methodRequiredString

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

app_idRequiredString

Current foreground app ID

subscribedOptionalBoolean

Indicates the current subscription status.

returnValueRequiredBoolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorTextOptionalString

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

settingsRequiredObject

Objects that holds setting values.

categoryRequiredString

Category of settings. It is same with the value specified in category input parameter.

dimensionOptionalObject: dimension

In case there is a dimension property in settings category, it returns the corresponding value.

methodRequiredString

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

app_idRequiredString

In case of settings by app, it returns App ID.

returnValueRequiredBoolean

Indicates whether the execution succeeded.

errorTextOptionalString

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

NoneThere 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

categoryOptionalString

Category of settings

keysOptionalarray

Keys for retrieving setting values. One of the keys and key should be specified.

keyOptionalString

A key for retrieving setting value. One of keys and key should be specified.

app_idOptionalString

App ID. If target key is app specific setting, app ID should be specified.

current_appOptionalBoolean

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
subscribeOptionalBoolean

Indicates whether to subscribe for related events.

  • true: Subscribe
  • false: Do not subscribe (false)

Call Returns

Name

Required

Type

Description

categoryRequiredString

Category of settings. It is same with the value specified in category input parameter.

dbtypeRequiredString

Database type. One of the following values will be returned.

  • "G" : Global type
  • "S" : PerApp type
  • "M" : Mixed type
  • "E" : ExceptionApp type
dimensionRequiredObject: dimension

In case there is a dimension property in settings category, it returns the corresponding value.

keyRequiredString

Requested key

valueCheckRequiredBoolean

Indicates whether the validation check for the settings values is performed.

  • true: The validation check is performed
  • false: The validation check is not performed
volatileRequiredBoolean

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
uiRequiredObject: ui

Object for UI information containing active and visible flags as property.

vtypeRequiredString

Type of values object. One of the following value will be returned: array, arrayExt, range, callback, file

valuesRequiredObject: values

The valid range of the setting value. The properties of the values are determined according to vtype.

app_idOptionalString

If the result setting is app specific value, app ID will be returned.

returnValueRequiredBoolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorTextOptionalString

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

subscribedOptionalBoolean

Indicates the current subscription status.

Subscription Returns

Name

Required

Type

Description

categoryRequiredString

Category of settings. It is same with the value specified in category input parameter.

dbtypeRequiredString

Database type. One of the following values will be returned.

  • "G" : Global type
  • "S" : PerApp type
  • "M" : Mixed type
  • "E" : ExceptionApp type
dimensionRequiredObject: dimension

In case there is a dimension property in settings category, it returns the corresponding value.

keyRequiredString

Requested key

valueCheckRequiredBoolean

Indicates whether the validation check for the settings values is performed.

  • true: The validation check is performed
  • false: The validation check is not performed
volatileRequiredBoolean

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
uiRequiredObject: ui

Object for UI information containing active and visible flags as property.

vtypeRequiredString

Type of values object. One of the following value will be returned: array, arrayExt, range, callback, file

valuesRequiredObject: values

The valid range of the setting value. The properties of the values are determined according to vtype.

errorTextOptionalString

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

returnValueRequiredBoolean

Indicates whether the execution succeeded.

Error Codes Reference

Error Code

Error Text

Error Description

Noneno 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

categoryOptionalString

Category of settings

dimensionOptionalObject: dimension

Dimension information. It is used when setting by input, video mode, 3D mode.

keysOptionalString array

Keys to be retrieved. One of keys and key should be specified.

keyOptionalString

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_idOptionalString

App ID. In case of app specific setting, app ID should be specified.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorTextOptionalString

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

methodRequiredString

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

dimensionRequiredObject: dimension

In case there is a dimension property in settings category, it returns the corresponding value.

categoryRequiredString

Settings category name

settingsRequiredObject: settings

Object that holds setting values.

Error Codes Reference

Error Code

Error Text

Error Description

Noneno 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

categoryOptionalString

Category of settings

keyRequiredString

A key to be retrieved

app_idOptionalString

In case of setting by app, app ID needs to be specified.

subscribeOptionalBoolean

Indicates whether to subscribe for related events.

  • true: Subscribe
  • false: Do not subscribe (default)

Call Returns

Name

Required

Type

Description

methodRequiredString

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

vtypeRequiredString

Type of values object.

valuesRequiredObject: values

The valid range of the setting value. The properties of the values are determined according to vtype.

returnValueRequiredBoolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorTextOptionalString

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

subscribedRequiredBoolean

Indicates the current subscription status.

Subscription Returns

Name

Required

Type

Description

methodRequiredString

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

vtypeRequiredString

Type of values object.

valuesRequiredObject: values

The valid range of the setting value. The properties of the values are determined according to vtype.

returnValueRequiredBoolean

Indicates whether the execution succeeded.

subscribedRequiredBoolean

Indicates the current subscription status.

Error Codes Reference

Error Code

Error Text

Error Description

Noneno 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/AlocaleInfo

Locale info such as Menu, Audio

 

N/AeulaStatus

End-User License Agreement

captioncaptionEnable

Caption settings

 

optioncountry

Country settings (ISO 3166-1 alpha-3)

 

optionsmartServiceCountryCode2

Service country settings  (ISO 3166-1 alpha-2)

 

optionsmartServiceCountryCode3

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

categoryOptionalString

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.
dimensionOptionalObject: 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.

keysOptionalarray

Keys for retrieving setting values. One of keys and key should be specified.

keyOptionalString

A key for retrieving setting value. One of keys and key should be specified.

app_idOptionalString

App ID. If target key is app specific setting, app ID should be specified.

current_appOptionalBoolean

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
subscribeOptionalBoolean

Indicates whether to subscribe for related events.

  • true: Subscribe
  • false: Do not subscribe

Call Returns

Name

Required

Type

Description

settingsRequiredObject: settings

Objects that holds result setting values.

categoryRequiredString

Category name of the result settings. It is same with category parameter in method call.

dimensionRequiredObject: dimension

Dimension information of the result settings. In case the setting category has a dimension, it returns its value.

methodRequiredString

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

app_idOptionalString

If the result setting is app specific value, app ID will be returned.

subscribedOptionalBoolean

Indicates the current subscription status.

returnValueRequiredBoolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorTextOptionalString

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

settingsRequiredObject: settings

Objects that holds result setting values.

categoryRequiredString

Category name of the result settings. It is same with category parameter in method call.

dimensionRequiredObject: dimension

Dimension information of the result settings. In case the setting category has a dimension, it returns its value.

methodRequiredString

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

app_idOptionalString

If the result setting is app specific value, app ID will be returned.

returnValueOptionalString

Indicates whether the execution succeeded.

errorTextOptionalString

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

returnValueRequiredBoolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
subscriptionsRequiredObject array: subscription

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

errorTextOptionalString

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

Nonecannot run command or ls-monitor is running

ls-monitor has been already running or cannot run command

Nonecannot parse result or ls-monitor is running

Cannot parse the ls-monitor results

Nonememory 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

controlRequiredString

Information on internal method settings

paramsOptionalObject

The current app ID to be changed

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
instrumentStatusOptionalString

Instrument setting status

errorTextOptionalString

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/AError!! to insert request for internal category to task que

Fatal failure like OOM.

N/AUnexpected 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

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

categoryOptionalString

Category of settings

keysRequiredarray

Keys to be reset to the factory default value

app_idOptionalString

App ID. If target key is app specific setting, app ID should be specified.

Call Returns

Name

Required

Type

Description

methodRequiredString

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

returnValueRequiredBoolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorTextOptionalString

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

categoryOptionalString

Category of settings

dimensionOptionalObject: dimension

Dimension information. It is used when setting by input, video mode, 3D mode.

keysRequiredarray

Keys to be reset to the factory default value

app_idOptionalString

App ID. If target key is app specific setting, app ID should be specified.

resetAllOptionalBoolean

Indicates whether to reset the settings for all dimensions.

  • true: Reset
  • false: Do not reset (default)

Call Returns

Name

Required

Type

Description

methodRequiredString

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

returnValueRequiredBoolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorTextOptionalString

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

categoryOptionalString

Category of settings

keyRequiredString

A key to be set

app_idOptionalString

App ID. In case of app specific setting, app ID should be specified.

uiOptionalObject: ui

Object for UI information containing active and visible flags as property.

vtypeOptionalString

Type of values object. Possible values: array, arrayExt, range, callback, file.

valuesOptionalObject: values

Specify the properties of the values object according to vtype.

volatileOptionalBoolean

Indicates whether to initialize the setting when resetting the system.

  • true: Initialized 
  • false: Not initialized
valueCheckOptionalBoolean

Indicates whether to perform the validation check on the set values.

  • true: Do not perform
  • false: Perform
notifySelfOptionalBoolean

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
extOptionalObject: ext

reserved property

Call Returns

Name

Required

Type

Description

methodRequiredString

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

returnValueRequiredBoolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorTextOptionalString

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

NoneThe 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

categoryOptionalString

Category of settings

keyRequiredString

Setting key

app_idOptionalString

App ID. In case of app specific setting, app ID should be specified.

uiOptionalObject array: ui

Object for UI information containing active and visible flags as property.

vtypeOptionalString

Type of values object. 

valuesOptionalObject: values

Specify the properties of the values object according to vtype.

volatileOptionalBoolean

Indicates whether to initialize the setting when resetting the system.

  • true: Initialized 
  • false: Not initialized
valueCheckOptionalBoolean

Indicates whether to perform the validation check on the set values.

  • true: Do not perform
  • false: Perform
notifySelfOptionalBoolean

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
extOptionalObject: ext

reserved property

Call Returns

Name

Required

Type

Description

methodRequiredString

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

returnValueRequiredBoolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorTextOptionalString

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

NoneThe 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

categoryOptionalString

Category of settings

app_idOptionalString

App ID. In case of app specific setting, app ID should be specified.

dimensionOptionalObject: dimension

Dimension information. It is used when setting by input, video mode, 3D mode.

settingsRequiredObject: settings

Settings to be saved

setAllOptionalBoolean

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
countryOptionalString

Set to change settings of a specific country only

Call Returns

Name

Required

Type

Description

methodRequiredString

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

returnValueRequiredBoolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorTextOptionalString

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/AParsing Fail!

The payload isn't a correct JSON.

N/AUsed both setAll and dimension

Ambiguous parameters: either setAll or dimension can be specified in the request.

N/Ano 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/AERROR!! 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

categoryOptionalString

Category of settings

keyRequiredString

Setting key

valuesRequiredObject: values

Specify the properties of the values object according to vtype.

vtypeRequiredString

Type of values object. One of the following value will be returned: Array, ArrayExt, Range, Callback, File, Date

opRequiredString

Method of settings. One of the following values can be set: set, add, remove, update.

Call Returns

Name

Required

Type

Description

methodOptionalString

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

returnValueRequiredBoolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorTextOptionalString

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

NoneThe 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.)

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

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

categoryOptionalString

Category of settings

dimensionOptionalObject: dimension

It is used when setting by input, video mode, 3D mode.

settingsRequiredObject: settings

Settings to be saved

app_idOptionalString

App ID. In case of app specific setting, app ID should be specified.

notifySelfOptionalBoolean

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_appOptionalBoolean

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
setAllOptionalBoolean

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
notifyOptionalBoolean

Indicates whether to receive the subscription message.

  • true: The subscribe message will be sent
  • false: The subscribe message will not be sent
storeOptionalBoolean

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

methodRequiredString

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

returnValueRequiredBoolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorTextOptionalString

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

activeRequiredBoolean

If it's True, it means it is the value that users can select.

visibleRequiredBoolean

Only if it's True, it is displayed to the user as a selectable item.

valueRequiredString

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

methodRequiredString

Method name

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

inputOptionalString

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

_3dPatternOptionalString

You can use the following values:

2dto3d, 3d

_3dStatusOptionalString

You can use the following values:

2d, 3d

pictureModeOptionalString

You can use the following values:

vivid, normal, eco, cinema, game, sports, expert1, expert2

_3dModeOptionalString

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

intervalRequiredNumber (int32_t)

Interval between the values that the user can select in the integer range.

minRequiredNumber (int32_t)

Minimum value among the integer values that the user can select

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

messageRequiredObject

The original payload of the subscription request.

senderRequiredString

Service name of the subscriber

methodRequiredString

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

activeRequiredBoolean

If it's True, users can make a change.

visibleRequiredBoolean

If it's true, the menu that users can select is displayed.

displayNameRequiredString

The name of Settings menu that is displayed to users.

widgetRequiredString

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

arrayOptionalString array

Array of configurable strings

arrayExtOptionalObject array: arrayExt

Array of extended information of the configurable strings

rangeOptionalObject: range

Valid range in integer

callbackOptionalObject: callback

Validation check for external callback

dateOptionalObject: date

Format of date and time

fileOptionalString

Describes valid data on the external file

Contents