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 |
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 |
Parameters
Name | Required | Type | Description |
---|---|---|---|
category | Optional | String | Category of settings.
|
keys | Optional | String array | Keys for retrieving setting values. One of the keys and key property should be specified. |
key | Optional | String | A key for retrieving the setting value. One of the keys and key property should be specified. |
subscribe | Optional | Boolean | The flag that decides whether to subscribe or not. If you enable the subscription, you get an event when the value of the specified settings is changed.
|
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 | The flag that indicates success/failure of the request.
|
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 the same as the category parameter in the method call. |
method | Required | String | Method name that clarifies which method is called in subscription messages. |
settings | Required | Object | Objects that hold result setting values. |
subscribed | Optional | Boolean | The flag that decides whether to subscribe or not.
|
Remarks
If you subscribe to 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 the 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 | The flag that indicates success/failure of the request.
|
category | Optional | String | Category string of the result setting values. It is the same as the category parameter in the method call. |
method | Required | String | Method name that is used for clarifying which method 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.
|
captionEnable | Optional | String | Closed caption setting value.
|
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:
|
keyboards | Required | String array | Added languages for the virtual keyboard (language tag)
|
timezone | Required | String | Time zone setting value. |