com.webos.service.configurator

API Summary

Creates the database schema, filecache configuration, activities for webOS Applications.

Overview of the API

(click to expand)

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.mycom.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

Open All


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

True if API call success, False if some of parameter wrong

configured Required Number

The number of resources which were successfully processed

Error References

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

-- example of failed call:
root@w2:/# luna-send -f -n 1 luna://com.webos.service.configurator/scan '[{"id":"com.mycom.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

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

True if the API call succeeded, False if one or more parameter is wrong

configured Required Number

The number of resources which were successfully processed

Error References

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

-- example of failed call:
root@w2:/# luna-send -f -n 1 luna://com.webos.service.configurator/rescan '[{"id":"com.mycom.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

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

True if the API call succeeded, False if one or more parameters are wrong

configured Required Number

The number of resources which were successfully processed

Error References

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/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.mycom.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.

Call Returns

Name

Required

Type

Description

returnValue Required boolean

True if the API call succeeded, False if one or more parameters are wrong

configured Required Number

The number of resources which were successfully processed

Error References

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.
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"
}


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