Settings Service
Service URI - luna://com.webos.settingsservice
Provides a method for retrieving system setting value.
Methods
Method |
Description |
Supported in Emulator |
---|---|---|
Retrieves values from system settings with keys. |
Yes |
-
Open All
-
- getSystemSettings
-
Description
Retrieves values from system settings with keys that are specified in an array as a parameter. The following keys are available:
Category
Key Name
Description
Type
-
localeInfo
Locale settings for language, keyboard, time zone, and clock.
Object
option
country
Country code (ISO 3166-1 alpha-3).
String
smartServiceCountryCode2
Service country code (ISO 3166 alpha-2). This code is related to the LG Content Store service.
String
audioGuidance
Audio guidance setting of the accessibility menu. This key is available on webOS TV 3.0 or higher.
String
caption
captionEnable
Closed caption setting of the accessibility menu.
String
Syntax
getSystemSettings([String category][, String[] keys|String key], [Boolean subscribe])Parameters
Name
Required
Type
Description
category
Optional
String
Category of settings.
-
If the specified keys (key) has a category, you must specify this property.
keys
Optional
String array
Keys for retrieving setting values. One of keys and key property should be specified.
key
Optional
String
A key for retrieving the setting value. One of keys and key property should be specified.
subscribe
Optional
Boolean
Flag that decides whether to subscribe or not. If you enabled the subscription, you will get an event when settings value, you specified, is changed.
-
true: Subscribe.
-
false: Do not subscribe. Call the method only once. (Default)
Remarks
The following table shows the use cases of getSystemSettings.
Case
category
keys
key
Description
Specify non-categorized key
-
-
"localeInfo"
Returns the corresponding locale setting values.
Specify a category without key.
"option"
-
-
Returns an error.
Specify key with category name
"option"
-
"country"
Returns the country setting value.
Specify key with wrong category
"option"
-
"localeInfo"
Returns an error.
Specify keys with category name
"option"
["country", "smartServiceCountryCode2"]
-
Returns the specified setting. (country and samrtServiceCountryCode2)
Specify keys included in different categories
"option"
["localeInfo", "country"]
-
Returns an error.
Specify nothing.
-
-
-
Returns an error.
Call Returns
Name
Required
Type
Description
returnValue
Required
Boolean
Flag that indicates success/failure of the request.
-
true: Success
-
false: Failure
errorCode
Optional
String
errorCode contains the error code if the method fails. The method will return errorCode only if it fails.
See the Error Codes Reference of this method for more details.errorText
Optional
String
errorText contains the error text if the method fails. The method will return errorText only if it fails.
See the Error Codes Reference of this method for more details.category
Optional
String
Category string of the result setting values. It is same as the category parameter in API call.
method
Required
String
API name that clarifies which API is called in subscription messages.
Required
Object
Objects that holds result setting values.
subscribed
Optional
Boolean
Flag that decides whether to subscribe or not.
-
true: Subscribe
-
false: Do not subscribe. Call the method only once. (Default)
Remarks
If you subscribe more than one key, you will receive the result data for whole keys at the first return. After the first return, you will receive the result data for each key when corresponding system information is changed.
Error Reference
Error Text
Error Description
There is no matched result from DB.
If the requested key is undefined, API returns an error.
Subscription Returns
Name
Required
Type
Description
returnValue
Required
Boolean
Flag that indicates success/failure of the request.
-
true: Success
-
false: Failure
category
Optional
String
Category string of the result setting values. It is same as the category parameter in API call
method
Required
String
API name that is used for clarifying which API is called in subscription messages.
Required
Object
Objects that hold the result setting values.
Example
// Get country information var request = webOS.service.request("luna://com.webos.settingsservice", { method: "getSystemSettings", parameters: { "category": "option", "keys": ["country", "smartServiceCountryCode2"] }, onSuccess: function (inResponse) { console.log("Result: " + JSON.stringify(inResponse)); // To-Do something }, onFailure: function (inError) { console.log("Failed to get settings' value"); console.log("[" + inError.errorCode + "]: " + inError.errorText); // To-Do something return; } }); // Get locale information with subscription var subscriptionHandle; subscriptionHandle = webOS.service.request("luna://com.webos.settingsservice", { method: "getSystemSettings", parameters: { "keys": ["localeInfo"], "subscribe": true }, onSuccess: function (inResponse) { if (typeof(inResponse.subscribed) != 'undefined') { if (!inResponse.subscribed) { console.log("Failed to subscribe settings' value"); return; } } console.log("Result: " + JSON.stringify(inResponse)); // To-Do something }, onFailure: function (inError) { console.log("Failed to get settings' value"); console.log("[" + inError.errorCode + "]: " + inError.errorText); // To-Do something return; } }); ... // Get audio guidance information var audioGuidanceRequest = webOS.service.request("luna://com.webos.settingsservice", { method: "getSystemSettings", parameters: { "category": "option", "keys": ["audioGuidance"] }, onSuccess: function (inResponse) { console.log("Result: " + JSON.stringify(inResponse)); // To-Do something }, onFailure: function (inError) { console.log("Failed to get settings' value"); console.log("[" + inError.errorCode + "]: " + inError.errorText); // To-Do something return; } }); // Get caption information var captionRequest = webOS.service.request("luna://com.webos.settingsservice", { method: "getSystemSettings", parameters: { "category": "caption", "keys": ["captionEnable"] }, onSuccess: function (inResponse) { console.log("Result: " + JSON.stringify(inResponse)); // To-Do something }, onFailure: function (inError) { console.log("Failed to get settings' value"); console.log("[" + inError.errorCode + "]: " + inError.errorText); // To-Do something return; } }); // If you need to unsubscribe the data, use cancel() method as below subscriptionHandle.cancel();
Return Example
// Success return - country information { "category": "option", "method": "getSystemSettings", "settings": { "smartServiceCountryCode2": "GB", "country": "FRA" }, "returnValue": true } // Success return - locale information { "method": "getSystemSettings", "settings": { "localeInfo": { "locales": { "UI": "en-GB", "TV": "en-GB", "FMT": "en-GB", "NLP": "en-GB", "STT": "fr-FR", "AUD": "fr-FR", "AUD2": "en-GB" }, "clock": "locale", "keyboards": [ "en" ], "timezone": "" } }, "returnValue": true } // Success return - audio guidance information { "subscribed": false, "category": "option", "method": "getSystemSettings", "settings": { "audioGuidance": "off" }, "returnValue": true } // Success return - caption information { "subscribed": false, "category": "caption", "method": "getSystemSettings", "settings": { "captionEnable": "off" }, "returnValue": true } // Failure return { "method": "getSystemSettings", "returnValue": false, "errorText": "There is no matched result from DB" }
See Also
None
-
- Object
-
settings Object
The object that holds the setting values from setting service. Locale and country settings can be contained.
{ "localeInfo": object, "smartServiceCountryCode2": String, "country": String, "audioGuidance": String, "captionEnable": String }
Name
Required
Type
Description
localeInfo
Optional
Object
Object that holds locale setting values.
smartServicecountryCode2
Optional
String
Service country code (ISO 3166-1 alpha-2).
country
Optional
String
Country code (ISO 3166-1 alpha-3).
audioGuidance Optional String Audio guidance setting value.
-
"on": The audio guidance is enabled.
-
"off": The audio guidance is disabled.
captionEnable Optional String Closed caption setting value.
-
"on": The closed caption is enabled.
-
"off": The closed caption is disabled.
localeInfo Object
Object that holds the language, keyboard, and time settings.
{ "locales": { "UI": String, "TV": String, "FMT": String, "NLP": String, "STT": String, "AUD": String, "AUD2": String }, "clock": String, "keyboards": String array, "timezone": String }
Name
Required
Type
Description
locales
Required
Object
Object that holds locale settings. Each property use language tag such as "en_US".
locales.UI
Required
String
The general language that the UI uses in most parts of the system.
locales.TV
Required
String
Language for TV such as OSD (On Screen Display).
locales.FMT
Required
String
Locale for data formats such as date format and time format.
locales.NLP
Required
String
The Natural Language Processing language.
locales.STT
Required
String
The speech-to-text language.
locales.AUD
Required
String
Language for audio language.
locales.AUD2
Required
String
Language for secondary audio language.
clock
Required
String
Clock setting shall have three possible values:
-
"12"
-
"24"
-
"locale"
keyboards
Required
String array
Added languages for the virtual keyboard (language tag)
-
Example: ["en", "ko"]
timezone
Required
String
Time zone setting value.
-