Note
This API has been available since API level 11.
This API has been available since API level 11.
com.webos.service.config
API Summary
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
Between webOS 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 types of structures are supported for webOS
| Just define key:value pair | Define under "configs" category as array |
|---|---|
com.webos.surfacemanager.json | { |
[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"
]
}
}
}
Methods
getConfigs
ACG: activity.query,-
- Added: API level 11
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:
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates whether the execution succeeded.
|
| configs | Optional | 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 | Optional | 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.
|
| configs | Optional | Object | See 'RETURN' value section |
| missingConfigs | Optional | String array | See 'RETURN' value section |
Example
Example code
# luna-send -f -i luna://com.webos.service.config/getConfigs '{"configNames ":["com.webos.surfacemanager.compositorGeometry"]}'
Response:
{
"subscribed": false,
"configs": {
"com.webos.surfacemanager.compositorGeometry": "1920x1080+0+0r0"
},
"returnValue": true
}
# luna-send -f -i luna://com.webos.service.config/getConfigs '{
"configNames":["com.webos.test.missingConfigs", "com.webos.surfacemanager.missingForegroundApp"]}'
Response:
{
"missingConfigs": [
"com.webos.test.missingConfigs",
"com.webos.surfacemanager.missingForegroundApp"
],
"subscribed": false,
"returnValue": true
}
reconfigure
ACG: systemconfig.management
- Added: API level 11
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.
|
| 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
Example code
# luna-send -n 1 luna://com.webos.service.config/reconfigure '{}'
setConfigs
ACG: activity.operation,-
- Added: API level 11
Description
Overrides current settings of the configs.
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 configurations at once.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| configs | Required | Object: configs | JSON value with configd key full name and value pair. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates whether the execution 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. See the "API Error Codes Reference" section for details. |
Example
Example code
// Single config
# luna-send -n 1 -f luna://com.webos.service.config/setConfigs '{ "configs": {"com.webos.surfacemanager.testSetConfigs": true}}'
Response:
{
"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"]}}'
Response:
{
"returnValue": true
}
Objects
configs
It contains full name of config and value pair.
For example,
"configs": {
"com.webos.service.applicationmanager.testKey": "added"
}
API Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -5 | "Response error" | Make-up response payload error |
| -4 | "Json parsing error" | Json parsing error |
| -3 | "Invalid main database error" | Main Database is invalid |
| -2 | "Invalid parameter error" | Invalid Parameter Error |
| -1 | "Unknown error" | Unknown Error |