com.webos.service.config

API Summary

The 'com.webos.service.config' is a static service in the system that provides product specific configurations to webOS components.

This service provides simple get/set interfaces to access the configurations.

[Terminology]

  • config : It consists of 'key' and 'value'. Following is an example of config.
    • { 'language' : 'KOR' } // configName is 'language'. configValue is 'KOR'
  • configs & configs.json : 'configs' is a set of configs. We called a file which describes the set as 'configs.json'. Normally, the file name is url name
    • com.webos.service.surfacemanager.json : configs.json file for lsm(luna surface manager)
    • layer & selector & selection : 'layer' is a set of 'configs.json' files. It means layer is same with directory. 
      • basedir in layer :It is a parent dir of others. Basically directories could be there.
      • selection in layer :It is leaf dir name. All 'configs.json' files should be in 'basedir' + 'selection'. If the layer type is "none" and there is no selection, configs.json files would be in basedir.
      • selector in layer : It is a method to get right selection. There are many types of selector in configd.
  • configuration & reconfiguration
    • configuration is a set of layer. Actually, higher layer can overwrite lower layer's configs.
    • reconfiguration is a process to make configuration again. If selector can be changed, reconfiguration process is needed. Please refer below sections for more information.

 

Overview of the API

(click to expand)

[Overview]

Between webOS Open Source Edition platform being built and its reaching the customer, it goes through various configs. For example, configs based on country, provider, language and etc. Making and maintaining separate builds for each of the variants is not practical.

At the moment, there are various non-uniform ways to customize the behavior of various components. Some depend on json config files stored on the root file system and some depend on the file system flags. Such disparity makes it impossible to provide the mechanism or tools to customize the product as a whole.

By specifying a common way to represent various flags and features, config service can provide a streamlined mechanism to our customers to customize the product.


[config & configs.json]

config name : Configd sets config name as CONFIGS_JSON_FILENAME.NAME.

  • If there is a key-value like "compositorGeometry": "1920x1080+0+0r0" in com.webos.surfacemanager.json
  • User can get configs as "com.webos.surfacemanager.compositorGeometry" or "com.webos.surfacemanager.*".
  • As config name contains file name, key should be added in related feature file, and it is recommended that users add feature file same as service name. 

configs.json file structure Both type of structures are supported for webOS OSE

Just define key:value pair  Define under "configs" category as array

com.webos.surfacemanager.json 
{
"compositorGeometry": "1920x1080+0+0r0"
}

{
    "configs" : [
        {
        "data": {
            "compositorGeometry" : "1920x1080+0+0r0"
        }
    }
    ]
}


[Restriction of getConfig values]

ACG is enabled on Configd and registered services can get configs via private or public bus. But for some cases, configs should be opened for only privileged services. To support this feature, configd allows to define permission by describing service name as array type at feature.json.

To define permission, config values should be described as new format of feature.json like explained above. Permission field would be fetched same way as configs are fetched, and it means that permission would be replaced while fetching upper layers' feature.json. 

Configd checks if requester is in the permitted service list, before returning getConfig and configd support servicename ended with asterisk.

Below example shows that only app3, app4 can get com.webos.component1.fileKey1, com.webos.component1.multiLayerKey. 

#cat com.webos.component1.json

{
    "configs": {
        "data": {
            "fileKey1": true,
            "multiLayerKey": true
        },
        "permissions": {
            "read": [
                "app3",
                "app4"
            ]
        }
    }
}

 


Open All


getConfigs

Description

It returns the requested configs which is the pairs of key-value as a JSON object and also supports a subscription.

configd provides asterisk but configNames should starts feature file name. For example, to get all configs for com.webos.surfacemanager, configNames should be "com.webos.surfacemanager.*". Note that "com.webos.*" or "com.webos.surfacemanager*" is not supported.  

If subscribe is true and multiple configs are requested, configd only returns changed config. ( from the second return)
(But missingConfigs would be returned everytime even missingConfigs is not changed)

If a config is limited for defined services, only permitted services can get Configs, if the requester doesn't  have rights, the configd would be in missingConfigs

Parameters

Name

Required

Type

Description

configNames Required String array

Passes the requested configNames by the client. Can be a single config or multiple names.

Syntax:

"configNames": ["com.webos.surfacemanager.*"]

Ex:

1.com.webos.surfacemanager.compositorGeometry (return the requested value)

2. "com.webos.surfacemanager.*".* (All the pairs of "key:value" in com.webos.surfacemanager component)

subscribe Optional Boolean

Subscribe for notifications . Possible values are:

  • true - Receives notifications when the database changes.
  • false - Notifications are not received.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
configs Required Object

Returns the pairs of current "key:value" for the requested component.

Ex:

1. input for configNames:["com.webos.surfacemanager.compositorGeometry"] - returns all the key:value pairs under "compositorGeometry" category

2. input for configNames:["com.webos.surfacemanager.*"] - returns the JSON object containing the pairs of "key:value" for the lsm component

missingConfigs Required String array

Returns a string array of configs which is not found in the database when returnValue is true.

If a permission is defined at feature.json and requester has no permission to read it, the config key would be shown at missingConfigs

subscribed Required Boolean

Indicates whether the subscription request succeeded

errorCode Optional Number (int32_t)

The error code for the failed operation.

errorText Optional String

Indicates the reason for the failure of the operation and errorCode is -1. See the " API Error Codes Reference"  for more details.

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
configs Required Object

See 'RETURN' value section

missingConfigs Required String array

See 'RETURN' value section

Example

// # luna-send -f -i palm://com.webos.service.config/getConfigs '{"configNames ":["com.webos.surfacemanager.compositorGeometry"]}'
{
    "subscribed": false,
    "configs": {
        "com.webos.surfacemanager.compositorGeometry": "1920x1080+0+0r0"
    },
    "returnValue": true
}               

// missingConfigs/ # luna-send -f -i palm://com.webos.service.config/getConfigs '{"configNames
":["com.webos.test.missingConfigs", "com.webos.surfacemanager.missingForegroundApp"]}'
{
    "missingConfigs": [
        "com.webos.test.missingConfigs",
        "com.webos.surfacemanager.missingForegroundApp"
    ],
    "subscribed": false,
    "returnValue": true
}


reconfigure

Description

Configd parses all configuration files again and regenerates the values of configs.

Parameters

None

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorCode Optional Number (int32_t)

The error code for the failed operation.

errorText Optional String

Indicates the reason for the failure of the operation. See the " API Error Codes Reference"  for more details.

Example

luna-send -n 1 palm://com.webos.service.config/reconfigure '{}'

{

"returnValue": true

}


setConfigs

Description

It overrides current settings of the configs with the passed value. The overridden values will be kept until rebooting or returning back in any future queries for the config. It is useful for changing configuration in factory test process.

User can set multiple Configs at once.

 

Parameters

Name

Required

Type

Description

configs Required Object: configs

JValue with configd key fullName and value pair. 

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates whether the execution succeeded.

  • true: Success
  • false: Failure
errorCode Optional Number (int32_t)

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

errorText Optional String

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

Example

//single config

# luna-send -n 1 -f luna://com.webos.service.config/setConfigs '{ "configs": {"com.webos.surfacemanager.testSetConfigs": true}}'

{

    "returnValue": true

}

 

//multiple configs

# luna-send -n 1 -f luna://com.webos.service.config/setConfigs '{ "configs": {"com.webos.surfacemanager.testSetConfigs": true,

"com.webos.surfacemanager.testSetConfigsArray": ["com.webos.app.test1", "com.webos.app.test2"]}}'

{

    "returnValue": true

}


Objects

configs

It contains full name of config and value pair.

For example,

"configs": {

    "com.webos.applicationManager.testKey": "added"

}


ERROR REFERENCES

Error Code

Error Text

Error Description

-1 "Unknown error"

Unknown Error

-2 "Invalid parameter error"

Invalid Parameter Error

-3 "Invalid main database error"

Main Database is invalid

-4 "Json parsing error"

Json parsing error

-5 "Response error"

Make-up response payload error


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