Settings Service

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

Provides a method for retrieving system setting value.

Methods

MethodDescriptionSupported in Emulator
getSystemSettingsRetrieves 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:

CategoryKey NameDescriptionType
-localeInfoLocale settings for language, keyboard, time zone, and clock.Object
optioncountryCountry code (ISO 3166-1 alpha-3).String
smartServiceCountryCode2Service country code (ISO 3166 alpha-2). This code is related to the LG Content Store service.String
audioGuidanceAudio guidance setting of the accessibility menu. This key is available on webOS TV 3.0 or higher.String
captioncaptionEnableClosed caption setting of the accessibility menu.String

Parameters

NameRequiredTypeDescription
categoryOptionalStringCategory of settings.
  • If the specified keys (key) has a category, you must specify this property.
keysOptionalString arrayKeys for retrieving setting values. One of the keys and key property should be specified.
keyOptionalStringA key for retrieving the setting value. One of the keys and key property should be specified.
subscribeOptionalBooleanThe 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.
  • true: Subscribe.
  • false: Do not subscribe. Call the method only once. (Default)

Remarks

The following table shows the use cases of getSystemSettings.

CasecategorykeyskeyDescription
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

NameRequiredTypeDescription
returnValueRequiredBooleanThe flag that indicates success/failure of the request.
  • true: Success
  • false: Failure
errorCodeOptionalStringerrorCode 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.
errorTextOptionalStringerrorText 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.
categoryOptionalStringCategory string of the result setting values. It is the same as the category parameter in the method call.
methodRequiredStringMethod name that clarifies which method is called in subscription messages.
settingsRequiredObjectObjects that hold result setting values.
subscribedOptionalBooleanThe flag that decides whether to subscribe or not.
  • true: Subscribe
  • false: Do not subscribe. Call the method only once. (Default)

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 TextError Description
There is no matched result from DB.If the requested key is undefined, API returns an error.

Subscription Returns

NameRequiredTypeDescription
returnValueRequiredBooleanThe flag that indicates success/failure of the request.
  • true: Success
  • false: Failure
categoryOptionalStringCategory string of the result setting values. It is the same as the category parameter in the method call.
methodRequiredStringMethod name that is used for clarifying which method is called in subscription messages.
settingsRequiredObjectObjects 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
    } 
NameRequiredTypeDescription
localeInfoOptionalObjectObject that holds locale setting values.
smartServicecountryCode2OptionalStringService country code (ISO 3166-1 alpha-2).
countryOptionalStringCountry code (ISO 3166-1 alpha-3).
audioGuidanceOptionalStringAudio guidance setting value.
  • "on": The audio guidance is enabled.
  • "off": The audio guidance is disabled.
captionEnableOptionalStringClosed 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
    } 
NameRequiredTypeDescription
localesRequiredObjectObject that holds locale settings. Each property use language tag such as "en_US".
locales.UIRequiredStringThe general language that the UI uses in most parts of the system.
locales.TVRequiredStringLanguage for TV such as OSD (On Screen Display).
locales.FMTRequiredStringLocale for data formats such as date format and time format.
locales.NLPRequiredStringThe Natural Language Processing language.
locales.STTRequiredStringThe speech-to-text language.
locales.AUDRequiredStringLanguage for audio language.
locales.AUD2RequiredStringLanguage for secondary audio language.
clockRequiredStringClock setting shall have three possible values:
  • "12"
  • "24"
  • "locale"
keyboardsRequiredString arrayAdded languages for the virtual keyboard (language tag)
  • Example: ["en", "ko"]
timezoneRequiredStringTime zone setting value.
No Headings