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

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.

-

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

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 value: false

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.

  • true: Subscription is ON
  • false: Subscription is OFF
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

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

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

returnValue will always contain true.

Error Codes Reference

Error Code

Error Text

Error Description

N/AN/A

It is OK to delete non-existent keys. It doesn't return any error.

Example

Run luna-send command:

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

 

Example response for a successful call:

{

"method": "deleteSystemSettings",

"returnValue": true

}

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

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
  • default value: 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.

  • true: Subscription is ON
  • false: Subscription is OFF
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.

  • 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

NoneThere is no matched result from DB

Requested keys are undefined.

Example

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

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
  • default value: 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.

  • true: Subscription is ON
  • false: Subscription is OFF

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.

  • true: Success
  • false: Failure

Error Codes Reference

Error Code

Error Text

Error Description

Noneno result in DB

An undefined key is requested.

Example

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

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

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.

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

  • true: Subscription is ON
  • false: Subscription is OFF
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.

  • 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

N/AThere is no matched result from DB

Requested keys are undefined.

Example

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

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 value: false

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.

  • true: Subscription is ON
  • false: Subscription is OFF

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.

  • true: Success
  • false: Failure

Error Codes Reference

Error Code

Error Text

Error Description

Noneno result in DB

An undefined key is requested.

Example

Run luna-send command:

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

 

Example response for a successful call:

{

"method": "getSystemSettingValues",

"returnValue": true,

"vtype": "Range",

"values": {

"range": {

"interval": 1,

"max": 100,

"min": 0

}

}

}

 

Example 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

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

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

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

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

Fatal failure like OOM.

Example

Run luna-send command: (Create log)

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

 

Example response for a successful call:

{

"instrumentStatus": "started",

"returnValue": true

}

 

Example response for a failed call:

{

"returnValue": false,

"errorText": "unexpected request on PrefsInternalCategory::handleMethodInstrument"

}

 

Run luna-send command:(Change current app)

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

 

Example response for a successful call:

{

"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

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

returnValue will always contain true.

Error Codes Reference

Error Code

Error Text

Error Description

N/AN/A

Always succeed. Even though undefined keys are requested, error will not be returned.

Example

Run luna-send command:

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

 

Example response for a successful call:

{

"returnValue": true

}

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

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 value: false

Call Returns

Name

Required

Type

Description

methodRequiredstring

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

returnValueRequiredboolean

returnValue will always contain true.

Error Codes Reference

Error Code

Error Text

Error Description

N/AN/A

Always succeed. Even though undefined keys are requested, error will not be returned.

Example

Run luna-send command:

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

 

Example response for a successful call:

{

"returnValue": true

}

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

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

      }

    }

  • file

    {

      "file": string

    }

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

Run luna-send command:

# 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"
               }
}'

 

Example response for a successful call:

{

"returnValue": true

}

 

Example 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

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

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

 

Example response for a successful call:

{

"returnValue": true

}

 

Example 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'"

}

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

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

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

Run luna-send command:

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

 

Example response for a successful call:

{

"method": "setSystemSettingFactoryValue",

"returnValue": true

}

 

Example 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'"

}

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.

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

returnValue will always contain true.

Error Codes Reference

Error Code

Error Text

Error Description

N/AN/A

Always succeed. Even though undefined keys are requested, error will not be returned.

Example

Run luna-send command:

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

 

Example response for a successful call:

{

"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

categoryOptionalstring

Category of settings

keyRequiredstring

Setting key

valuesRequiredObject: values

Specify the properties of the values object according to vtype. 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

        }

      }

    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

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

    Noneno result in DB

    An undefined key is requested.

    Example

    Run luna-send command:

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

     

    Example response for a successful call:

    {

    "returnValue": true

    }

     

    Example 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'"

    }

    Objects

    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

    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

    activeRequiredBoolean

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

    visibleRequiredBoolean

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

    displayNmaeRequiredString

    The name of Settings menu that is displayed to users.

    widgetRequiredString

    UI Component information like Combo Box and List. (currently not in use)

    values

    It is the information that is used for the validation of configurable values.

    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

    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

    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.

    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

    date

    Reserved. Not implemented.

    callback

    Reserved. Not implemented.

    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.

    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

    messageRequiredObject

    The original payload of the subscription request.

    senderRequiredString

    Service name of the subscriber

    methodRequiredString

    Method name that subscriber called to create the subscription.

    Contents