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

(click to expand)
Method Description Subscription

batch

It is used when processing multiple methods as one Luna call

Support

deleteSystemSettings

Delete settings

-

getCurrentSettings

Return foreground app related settings

Support

getSystemSettingDesc

Return settings info (Description)

Support

getSystemSettings

Return settings value

Support

getSystemSettingFactoryValue

Return default value

-

getSystemSettingValues

Return the info of valid range of the possible setting value

Support

resetSystemSettings

Initialize setting value and switch to default value

-

resetSystemSettingDesc

Change settings info (Description) to default value

-

setSystemSettingDesc

Modify settings info (Description)

-

setSystemSettingFactoryDesc

Modify default value of the settings info (Description)

 

setSystemSettingFactoryValue

Change default value

-

setSystemSettings

Change settings

-

setSystemSettingValues

Modify the info of the valid range of the possible setting value

-

internal/instrument

Generate log for debug and change current app

 
internal/getCurrentSubscriptions

Return the information of currently subscribed service

 

 


Open All


batch

Description

Runs more than one Settings Service method at once.

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

Parameters

Name

Required

Type

Description

operations Required Object array: batchOperation

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

subscribe Optional boolean

Indicates whether to subscribe for related events.

  • 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

results Required array

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

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

subscribed Optional boolean

Indicates the current subscription status.

  • true: Subscription is ON
  • false: Subscription is OFF
returnValue Required Boolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure

Subscription Returns

Name

Required

Type

Description

N/A Optional String

Although the first response includes all methods' responses, in the subscription response, only necessary method responses are included. The subscription form is determined according to each method described in operations parameter.

Error References

Error Code

Error Text

Error Description

N/A N/A

The errors of each method included in the batch method are described in results.

Example

Run luna-send command:

luna-send -n 1 luna://com.webos.service.settings/batch

'{

"operations": [

{

"method": "getSystemSettings",

"params": {

"category": "picture",

"keys": [

"brightness"

],

"subscribe":true

}

},

{

"method": "getSystemSettingDesc",

"params": {

"category": "picture",

"keys": [

"brightness"

],

"subscribe":true

}

}

],

"subscribe": true

}'

 

Example response for a successful call:

{

"returnValue": true,

"results": [

{

"method":"getSystemSettigns",

"settings": {

"brightness": "50"

},

"category": "picture",

"dimension": {

"input": "comp1",

"pictureMode": "normal",

"_3dStatus": "2d"

},

"returnValue": true

},

{

"method":"getSystemSettingDesc",

"returnValue": true,

"results": [

{

"category": "picture",

"dimension": [

"input",

"pictureMode",

"_3dStatus"

],

"key": "brightness",

"ui": {

"active": true,

"displayName": "brightness",

"visible": true,

"widget": "None"

},

"valueCheck": true,

"values": {

"range": {

"interval": 1,

"max": 100,

"min": 0

}

},

"volatile": false,

"vtype": "Range"

}

]

}

]

}

 

Example response for a failed call

{

"returnValue": true,

"results": [

{

"errorText": "no result from DB",

"category": "picture",

"dimension": {},

"method": "getSystemSettings",

"returnValue": false

},

{

"returnValue": false,

"error": "no result in DB",

"subscribed": false,

"method": "getSystemSettingDesc"

}

]

}


deleteSystemSettings

Description

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

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

Parameters

Name

Required

Type

Description

category Optional string

Category of settings

dimension Optional Object: dimension

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

keys Required String array

Keys to be deleted

app_id Optional string

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

Call Returns

Name

Required

Type

Description

method Required string

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

returnValue Required boolean

returnValue will always contain true.

Error References

Error Code

Error Text

Error Description

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

category Optional string

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

dimension Optional Object: dimension

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

keys Required array

Keys to be retrieved

subscribe Optional boolean

Indicates whether to subscribe for related events.

  • true: Subscribe
  • false: Do not subscribe
  • default value: false

Call Returns

Name

Required

Type

Description

settings Required Object: settings

Objects that holds setting values.

category Required string

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

dimension Required Object: dimension

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

method Required string

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

app_id Required string

Current foreground app ID

subscribed Optional boolean

Indicates the current subscription status.

  • true: Subscription is ON
  • false: Subscription is OFF
returnValue Required boolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorText Optional string

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

Subscription Returns

Name

Required

Type

Description

settings Required Object

Objects that holds setting values.

category Required String

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

dimension Optional Object: dimension

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

method Required String

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

app_id Required String

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

returnValue Required Boolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorText Optional String

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

Error References

Error Code

Error Text

Error Description

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

category Optional string

Category of settings

keys Optional array

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

key Optional string

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

app_id Optional String

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

current_app Optional Boolean

If app ID isn't specified, use current foreground app ID. If app ID is explicitly given, this parameter is ignored.

  • true: Use current foreground app ID
  • false: Don't use app ID
  • default value: false
subscribe Optional boolean

Indicates whether to subscribe for related events.

  • true: Subscribe
  • false: Do not subscribe
  • default value: false

Call Returns

Name

Required

Type

Description

category Required String

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

dbtype Required String

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

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

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

key Required String

Requested key

valueCheck Required boolean

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

  • true: The validation check is performed
  • false: The validation check is not performed
volatile Required boolean

Indicates whether to initialize with the factory default value when resetting the system.

  • true: Initialized with the factory default value
  • false: Not initialized with the factory default value
ui Required Object: ui

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

vtype Required String

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

values Required Object: values

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

app_id Optional String

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

returnValue Required Boolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorText Optional String

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

subscribed Optional Boolean

Indicates the current subscription status.

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

Subscription Returns

Name

Required

Type

Description

category Required String

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

dbtype Required String

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

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

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

key Required String

Requested key

valueCheck Required Boolean

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

  • true: The validation check is performed
  • false: The validation check is not performed.
volatile Required Boolean

Indicates whether to initialize with the factory default value when resetting the system.

  • true: Initialized with the factory default value
  • false: Not initialized with the factory default value
ui Required Object: ui

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

vtype Required String

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

values Required Object: values

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

errorText Optional String

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

returnValue Required Boolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure

Error References

Error Code

Error Text

Error Description

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

category Optional String

Category of settings

dimension Optional Object: dimension

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

keys Optional String array

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

key Optional String

A key to be retrieved. In case there is one key to be retrieved, directly input the strings. One of keys and key should be specified.

app_id Optional String

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

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorText Optional String

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

method Required String

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

dimension Required Object: dimension

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

category Required String

Settings category name

settings Required Object: settings

Object that holds setting values.

Error References

Error Code

Error Text

Error Description

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

Category Key Remarks
N/A localeInfo

Locale info such as Menu, Audio

N/A eulaStatus

End-User License Agreement 정보

caption captionEnable

Caption settings

option country

Country settings (ISO 3166-1 alpha-3)

option smartServiceCountryCode2

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

option smartServiceCountryCode3

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

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

Parameters

Name

Required

Type

Description

category Optional string

Category of settings

  • If the specified keys (key) has a category, you must specify this property.
  • If you only use this property without keys or key, this method will return all values which are in the specified category.
dimension Optional Object: dimension

Specify dimension information for special key (e.g. brightness has 3 dimensions, input, _3dMode, pictureMode). Current dimensions is applied if dimension is not specified.

keys Optional array

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

key Optional string

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

app_id Optional string

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

current_app Optional boolean

Indicates whether to use current foreground app ID instead of specific app ID.

  • true: Use current foreground app ID
  • false: Use specific app ID 
  • default value: false
subscribe Optional boolean

Indicates whether to subscribe for related events.

  • true: Subscribe
  • false: Do not subscribe

Call Returns

Name

Required

Type

Description

settings Required Object: settings

Objects that holds result setting values.

category Required string

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

dimension Required Object: dimension

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

method Required string

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

app_id Optional string

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

subscribed Optional boolean

Indicates the current subscription status.

  • true: Subscription is ON
  • false: Subscription is OFF
returnValue Required boolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorText Optional string

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

Subscription Returns

Name

Required

Type

Description

settings Required Object: settings

Objects that holds result setting values.

category Required String

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

dimension Required Object: dimension

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

method Required String

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

app_id Optional String

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

returnValue Optional String

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorText Optional String

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

Error References

Error Code

Error Text

Error Description

N/A There is no matched result from DB

Requested keys are undefined.

Example

Example response for a successful call:

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

{

"category": "option",

"method": "getSystemSettings",

"settings": {

"smartServiceCountryCode2": "GB",

"country": "FRA"

},

"returnValue": true

}

 

Example response for a successful call:

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

{

"method": "getSystemSettings",

"settings": {

"localeInfo": {

"locales": {

"UI": "en-GB",

"FMT": "en-GB",

"NLP": "en-GB",

"STT": "fr-FR",

"AUD": "fr-FR",

"AUD2": "en-GB"

},

"clock": "locale",

"keyboards": [

"en"

],

"timezone": ""

}

},

"returnValue": true

}

 

Example response for a failed call:

{

"method": "getSystemSettings",

"returnValue": false,

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

}


getSystemSettingValues

Description

Retrives possible items to be set

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

Parameters

Name

Required

Type

Description

category Optional String

Category of settings

key Required String

A key to be retrieved

app_id Optional String

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

subscribe Optional boolean

Indicates whether to subscribe for related events.

  • true: Subscribe
  • false: Do not subscribe
  • default value: false

Call Returns

Name

Required

Type

Description

method Required String

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

vtype Required String

Type of values object.

values Required Object: values

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

returnValue Required boolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorText Optional string

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

subscribed Required Boolean

Indicates the current subscription status.

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

Subscription Returns

Name

Required

Type

Description

method Required String

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

vtype Required String

Type of values object.

values Required Object: values

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

returnValue Required Boolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure

Error References

Error Code

Error Text

Error Description

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

returnValue Required Boolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
subscriptions Required Object array: subscription

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

errorText Optional String

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

Error References

Error Code

Error Text

Error Description

None cannot run command or ls-monitor is running

ls-monitor has been already running or cannot run command

None cannot parse result or ls-monitor is running

Cannot parse the ls-monitor results

None memory allocation error

Memory related errors

Example

Run luna-send command: (Create log)

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

 

Example response for a successful call:

{

"returnValue": true,

"subscriptions": [

{

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

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

"method": "getSystemSettings"

}

]

}


internal/instrument

Description

Generates log for debug and changes current app.

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

Parameters

Name

Required

Type

Description

control Required String

Information on internal method settings

params Optional Object

The current app ID to be changed

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
instrumentStatus Optional String

Instrument setting status

errorText Optional String

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

Error References

Error Code

Error Text

Error Description

N/A Error!! 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

category Optional string

Category of settings

keys Required array

Keys to be reset to the factory default value

app_id Optional String

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

Call Returns

Name

Required

Type

Description

method Required string

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

returnValue Required boolean

returnValue will always contain true.

Error References

Error Code

Error Text

Error Description

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

category Optional string

Category of settings

dimension Optional Object: dimension

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

keys Required array

Keys to be reset to the factory default value

app_id Optional string

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

resetAll Optional boolean

Indicates whether to reset the settings for all dimensions.

  • true: Reset
  • false: Do not reset
  • default value: false

Call Returns

Name

Required

Type

Description

method Required string

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

returnValue Required boolean

returnValue will always contain true.

Error References

Error Code

Error Text

Error Description

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

category Optional string

Category of settings

key Required string

A key to be set

app_id Optional String

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

ui Optional Object: ui

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

vtype Optional string

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

values Optional Object: values

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

    }

volatile Optional boolean

Indicates whether to initialize the setting when resetting the system.

  • true: Initialized 
  • false: Not initialized
valueCheck Optional boolean

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

  • true: Do not perform
  • false: Perform
notifySelf Optional boolean

Indicates whether to receive the subscription message.

  • true: The subscribe message will be sent to self
  • false: The subscribe message will not be sent to self
ext Optional Object: ext

reserved property

Call Returns

Name

Required

Type

Description

method Required string

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

returnValue Required boolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorText Optional string

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

Error References

Error Code

Error Text

Error Description

None The format of value is wrong

vtype and the combination of values do not match. (e.g. In case vtype is arrayExt, there must exist arrayExt in values object.)

Example

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

category Optional string

Category of settings

key Required string

Setting key

app_id Optional String

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

ui Optional Object array: ui

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

vtype Optional string

Type of values object. 

values Optional Object: values

Specify the properties of the values object according to vtype.

volatile Optional boolean

Indicates whether to initialize the setting when resetting the system.

  • true: Initialized 
  • false: Not initialized
valueCheck Optional boolean

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

  • true: Do not perform
  • false: Perform
notifySelf Optional boolean

Indicates whether to receive the subscription message.

  • true: The subscribe message will be sent to self
  • false: The subscribe message will not be sent to self
ext Optional Object: ext

reserved property

Call Returns

Name

Required

Type

Description

method Required string

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

returnValue Required boolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorText Optional string

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

Error References

Error Code

Error Text

Error Description

None The format of value is wrong

vtype and the combination of values do not match. (e.g. In case vtype is arrayExt, there must exist arrayExt in values object.)

Example

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

category Optional string

Category of settings

app_id Optional String

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

dimension Optional Object: dimension

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

settings Required Object: settings

Settings to be saved

setAll Optional boolean

Indicates whether to set the settings for all dimensions. Either dimension or setAll can be specified.

  • true: Set the settings for all dimensions
  • false: Set the settings for the given dimension only
  • default value: false
country Optional string

Set to change settings of a specific country only

Call Returns

Name

Required

Type

Description

method Required string

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

returnValue Required boolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure

Error References

Error Code

Error Text

Error Description

N/A Parsing Fail!

The payload isn't a correct JSON.

N/A Used both setAll and dimension

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

N/A no settings specified

Parameter validation failure: settings should be specified.

N/A 'settings' should be set json_object type

Parameter validation: settings isn't a JSON object

N/A 'Key' shouldn't be NULL

Parameter validation: settings shouldn't be empty.

N/A ERROR!! send a request to DB

Failed to send a request to the DB.

Example

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.

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

Parameters

Name

Required

Type

Description

category Optional string

Category of settings

dimension Optional Object: dimension

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

settings Required Object: settings

Settings to be saved

app_id Optional string

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

notifySelf Optional boolean

Indicates whether to receive the subscription message.

  • true: The subscribe message will be sent to self
  • false: The subscribe message will not be sent to self
current_app Optional boolean

Indicates whether to return the settings of the current foreground app

  • true: the settings of the current foreground app gets returned
  • false: use app ID specified in the perameter app_id
  • default value: false
setAll Optional boolean

Indicates whether to set the settings of all dimensions.

  • true: Set the settings for all dimensions
  • false: Set the settings for the dimension specified in the parameter dimension
  • default value: false
notify Optional boolean

Indicates whether to receive the subscription message.

  • true: The subscribe message will be sent
  • false: The subscribe message will not be sent
store Optional boolean

Indicates whether to store the subscription message in DB

  • true: Store in DB
  • false: Do not tore in DB. Only subscription message will be sent.
  • default value: true

Call Returns

Name

Required

Type

Description

method Required string

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

returnValue Required boolean

returnValue will always contain true.

Error References

Error Code

Error Text

Error Description

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

category Optional string

Category of settings

key Required string

Setting key

values Required Object: values

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

      }

    }

vtype Required string

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

op Required string

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

Call Returns

Name

Required

Type

Description

method Required string

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

returnValue Required boolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorText Optional string

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

Error References

Error Code

Error Text

Error Description

None The format of value is wrong

vtype and the combination of values do not match. (e.g. In case vtype is arrayExt, there must exist arrayExt in values object.)

None no result in DB

An undefined key is requested.

Example

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

input Optional String

You can use the following values:

dtv, atv, av1, av2, pictest, comp1, comp2, comp3,  rgb, hdmi1, hdmi2, hdmi3, hdmi4,  hdmi1_pc, hdmi2_pc, hdmi3_pc, hdmi4_pc, movie, photo, default, scart

_3dPattern Optional String

You can use the following values:

2dto3d, 3d

_3dStatus Optional String

You can use the following values:

2d, 3d

pictureMode Optional String

You can use the following values:

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

_3dMode Optional String

You can use the following values:

standard, sports, cinema, extreme, manual, auto

settings

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

ui

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

Name

Required

Type

Description

active Required Boolean

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

visible Required Boolean

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

displayNmae Required String

The name of Settings menu that is displayed to users.

widget Required String

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

values

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

Name

Required

Type

Description

array Optional String array

Array of configurable strings

arrayExt Optional Object array: arrayExt

Array of extended information of the configurable strings

range Optional Object: range

Valid range in integer

callback Optional Object: callback

Validation check for external callback

date Optional Object: date

Format of date and time

file Optional String

Describes valid data on the external file

ext

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

arrayExt

This object describes the strings among the selectable value type.

Name

Required

Type

Description

active Required Boolean

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

visible Required Boolean

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

value Required String

Defines the value that is stored when the user makes a selection.

range

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

Name

Required

Type

Description

interval Required Number (int32_t)

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

min Required Number (int32_t)

Minimum value among the integer values that the user can select

max Required Number (int32_t)

Maximum value among the integer values that the user can select

date

Reserved. Not implemented.

callback

Reserved. Not implemented.

batchOperation

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

Name

Required

Type

Description

method Required String

Method name

params Required Object: params

The object that includes the parameters defined by method.

params

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

subscription

This object describes an active subscription to the settings service.

Name

Required

Type

Description

message Required Object

The original payload of the subscription request.

sender Required String

Service name of the subscriber

method Required String

Method name that subscriber called to create the subscription.


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