com.webos.service.configurator

API Summary

Creates the database schema, filecache configuration, 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, which dirs should be cached by File Cache

Typically applications have two different aproaches 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 sbove reponse 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

idRequiredstring

Application Id

typeRequiredstring

Either 'app' or 'service'

locationRequiredstring

Indicates if it is a system app or a third party app.

Call Returns

Name

Required

Type

Description

returnValueRequiredboolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
configuredRequiredNumber

The number of resources which were successfully processed

errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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

-1000Application 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"}]'
{
"configured": 0,
"returnValue": true
}

-- example of failed call:
root@w2:/# luna-send -f -n 1 luna://com.webos.service.configurator/scan '[{"id":"com.lge.app.phone","type":"app","location" :"system"}]'
{
"errorCode": -1000,
"returnValue": false,
"errorText": "Application or service doesn't exist"
}

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

idRequiredstring

Application Id

typeRequiredstring

Either 'app' or 'service'

locationRequiredstring

Indicates if it is a system app or a third party app.

Call Returns

Name

Required

Type

Description

returnValueRequiredboolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
configuredRequiredNumber

The number of resources which were successfully processed

errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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

-1000Application 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"}]'
{
"configured": 0,
"returnValue": true
}

-- example of failed call:
root@w2:/# luna-send -f -n 1 luna://com.webos.service.configurator/rescan '[{"id":"com.lge.app.phone","type":"app","location" :"system"}]'
{
"errorCode": -1000,
"returnValue": false,
"errorText": "Application or service doesn't exist"
}

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

idRequiredstring

Application or Service Id

typeRequiredstring

Either 'app' or 'service'

locationRequiredstring

Indicates if it is a system or a third party app.

Call Returns

Name

Required

Type

Description

returnValueRequiredboolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
configuredRequiredNumber

The number of resources which were successfully processed

errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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

-1000Application 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/unconfigure '[{"id":"com.webos.service.app.settings","type":"app","location" :"system"}]'
{
"configured": 0,
"returnValue": true
}
-- example of failed call:
root@w2:/# 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

typesRequiredarray

List of different configuration types. Types are dbkinds, filecache, activities.

Call Returns

Name

Required

Type

Description

returnValueRequiredboolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
configuredRequiredNumber

The number of resources which were successfully processed

errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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

-1000Partial configuration - 4 ok, 7 failed

Error partial configuration can be generated when one or more services return failure while registering a resource.
For example, If activity manager could not register a activity, configurator will return a warning that one activity could not be registered.

Example

/usr/bin/luna-send -n 1 luna://com.webos.service.configurator/run '{"types":["activities"]}'
{
"configured": 0,
"returnValue": true
}

---
Example of failed call:
root@w2:/# luna-send -f -n 1 luna://com.webos.service.configurator/run '{"types":["activities"]}'
{
"errorCode": -1000,
"returnValue": false,
"errorText": "Partial configuration - 4 ok, 7 failed"
}

Contents