com.webos.service.configurator
API Summary
Creates the database schema, filecache configuration, and activities for webOS applications.
Overview of the API
Any webOS application typically needs standard resources, like:
- Register in DB8 database (maindb/tempdb/mediadb) kind, give permissions.
- Register/modify Activity Manager Activities.
- Provide the directories which should be cached by file cache.
Typically applications have two different approaches for achieving the above:
- The application can check by itself, that all required things are registered by itself by directly calling each required service
- Alternatively the application can provide config file for configurator for automatic resources registration/update
First approach offers more control to the application and allows the application to execute more complex logic to initialize/update resources. However such behavior is more complex.
The second approach has benefits as all logic for kind register and kind update, activities, filecache is executed by the configurator service. The application need only provide only text files with required information for configurator, and configurator will do all logic by itself.
The configurator logic works as follows:
On startup or when scan/rescan API is called, configurator reads each file from the configurator directory and:
- If the resource file is kind, then it makes a direct call to DB8 and executes the putKind API call
- If the resource file is kind permission, then it makes a direct call to DB8 and executes the putPermission API call
- If the resource file is activity, then it makes a direct call to Activity Manager and registers the activities
- If the resource file is File Cache conf, then it makes a direct call to the File Cache and register the directories
After processing a resource file, configurator will remember, that the resource file has been processed and will not process that file on the next configurator directory scan.
Configurator Directory:
In the webOS platform there exists two different type of applications: webOS services and third party applications. Configurator use two locations for resource file processing: system and runtime.
System Configurator Directory:
This directory is used for searching for resource files when the configurator service starts. By default this directory is: /etc/palm/db
Runtime Configurator Directory:
After configurator has started, it provides a luna API for dynamic processing of resource files. For those API calls, configurator uses the Runtime Configurator Directory
The application type and hint location gives configurator the information where it should search for resource files. configurator determines the configurator directory using the logic below.
configurator directory = (location) + offset + (type) + (app_id) + (postfixdir)
The default values for the above parameters are listed in the table below.
| Parameter | Value |
|---|---|
| Location | For system apps this is set to "/" For third party apps this is set to "/media/cryptfs/apps/" |
| Offset | "usr/palm" |
| Type | For apps this is set to "applications" For services this is set to "services" |
| app_id | application_id |
| postfixdir | /configuration |
Error handling:
If configurator cannot process API calls (internal error, bad params, no resources, etc) it always returns error in the following format:
- returnValue - if an error occurs, it will contain false
- errorCode - code that indicates the cause of the error
- errorText - text representation of the error code
Error codes and description are provided for each API call. For example, if the client calls the scan API with bad parameter:
luna-send -f -n 1 luna://com.webos.service.configurator/scan '[{
"id":"com.lge.app.phone",
"type":"app","location" :"system"
}]'
Response:
{
"errorCode": -1000,
"returnValue": false,
"errorText": "Application or service doesn't exist"
}
The above response indicates, that:
- returnValue: false - API call failed
- errorCode: -1000 - See API call scan for more details on error code -1000
- errorText: Application or service doesn't exist - A quick textual explanation of the error
Methods
scan
Description
Within the API call, application can notify Configurator about new resource files and ask Configurator to process those resource files.
Example of use case: application installed and runs at first. Application at first startup can ask configurator to register kind for itself.
For Path of resource files, see Runtime Configurator Directory in Overview section of this doc
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| id | Required | string | Application Id |
| type | Required | string | Either 'app' or 'service' |
| location | Required | string | Indicates if it is a system app or a third party app. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | boolean | Indicates the status of operation. Possible values are:
|
| configured | Required | Number | The number of resources which were successfully processed |
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -1000 | Application or service doesn't exist | This error code indicates that configurator did not find any resource file for the specified application id in the configurator directory |
Example
# luna-send -f -n 1 luna://com.webos.service.configurator/scan '[{"id":"com.webos.service.app.settings","type":"app","location" :"system"}]'
Response:
{
"configured": 0,
"returnValue": true
}
rescan
Description
Force rescan of resource file for application. Useful when application's resource file has been modified and it wants to update the resources.
For example, updated Kind or Kind permissions
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| id | Required | string | Application Id |
| type | Required | string | Either 'app' or 'service' |
| location | Required | string | Indicates if it is a system app or a third party app. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | boolean | Indicates the status of operation. Possible values are:
|
| configured | Required | Number | The number of resources which were successfully processed |
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -1000 | Application or service doesn't exist | This error code indicates that configurator did not find any resource file for the specified application id in the configurator directory |
Example
# luna-send -f -n 1 luna://com.webos.service.configurator/rescan '[{"id":"com.webos.service.app.settings","type":"app","location" :"system"}]'
Response:
{
"configured": 0,
"returnValue": true
}
unconfigure
Description
Rollback all actions that were made by the scan/rescan API calls. In other words, release used resources.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| id | Required | string | Application or Service Id |
| type | Required | string | Either 'app' or 'service' |
| location | Required | string | Indicates if it is a system or a third party app. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | boolean | Indicates the status of operation. Possible values are:
|
| configured | Required | Number | The number of resources which were successfully processed |
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -1000 | Application or service doesn't exist | This error code indicates that configurator did not find any resource file for the specified application id in the configurator directory |
Example
Example of successful call:
# luna-send -f -n 1 luna://com.webos.service.configurator/unconfigure '[{"id":"com.webos.service.app.settings","type":"app","location" :"system"}]'
{
"configured": 0,
"returnValue": true
}
Example of failed call:
# luna-send -f -n 1 luna://com.webos.service.configurator/unconfigure '[{"id":"com.lge.app.phone","type":"app","location" :"system"}]'
{
"errorCode": -1000,
"returnValue": false,
"errorText": "Application or service doesn't exist"
}
run
Description
This method will scan all folders and process all configuration files.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| types | Required | array | List of different configuration types. Types are dbkinds, filecache, activities. Note: For Auto, "activities" type parameter should be used only inside session or with sessionId. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | boolean | Indicates the status of operation. Possible values are:
|
| configured | Required | Number | The number of resources which were successfully processed |
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -1000 | Partial configuration - 4 ok, 7 failed | Error partial configuration can be generated when one or more services return failure while registering a resource. |
Example
# luna-send -n 1 luna://com.webos.service.configurator/run '{"types":["activities"]}'
Response:
{
"configured": 6,
"returnValue": true
}
# luna-send -n 1 luna://com.webos.service.configurator/run '{"types":["dbkinds"]}'
Response:
{
"configured": 4,
"returnValue": true
}
# luna-send -n 1 luna://com.webos.service.configurator/run '{"types":["filecache"]}'
Response:
{
"configured": 0,
"returnValue": true
}
# luna-send -n 1 luna://com.webos.service.configurator/run '{"types":["dbkinds", "filecache", "activities"]}'
Response:
{
"configured": 10,
"returnValue": true
}