Settings Service

Service URI - luna://com.webos.settingsservice

Provides a method for retrieving system setting value.

Methods

Method	Description	Supported in Emulator
getSystemSettings	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.
settings	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.
settings	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.