Note
This API has been available since API level 26.
This API has been available since API level 26.
com.webos.service.bus
API Summary
The service provides:
- an interface for clients to register to signals from other clients
- methods for receiving from com.webos.service.bus data about registered clients.
- methods for configuring com.webos.service.bus internal security data
Overview of the API
About the com.webos.service.bus API
The luna-service2 uses signals as part of interprocess communication (IPC) between webOS IPC participants. The com.webos.service.bus API provides an interface to enable the clients to receive the signals. The webOS IPC participants post various signals to the system bus which are sent to the clients interested in those signals. To avoid clients from receiving unwanted signals, they must register for a particular signal or a category of signals. This will enable the bus to perform a match and forward only the relevant signals to the respective clients.
com.webos.service.bus API methods allow to receive additional data about webOS IPC participants.
Using the com.webos.service.bus
The signals mentioned in this API cannot be called directly. The clients should send specific messages to invoke these methods as mentioned in the Internal Notes section.
Additional Remarks
- Currently signals can be generated only by the internal services such as com.palm, com.webos, com.lge.
- During registration, if the signal name is not specified then that client will be registered to receive all signals from the category.
Methods
addManifestsDir
ACG: servicebus.configuration
- Added:
API level 26
Description
Adds a directory containing manifests (security configuration files).
Note: Only services present in the "hub.configuration" security group are allowed to call this method.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| prefix | Optional | String | Prefix that adjust relative paths for manifests directory path and paths in manifests to absolute |
| dirpath | Required | String | Directory path (treated as relative if prefix is specified or absolute if not) |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates status of method execution. Possible values are:
|
Example
Example : Successful request to add manifest file to hub security configuration
# luna-send -n 1 -f -m "com.webos.some.trusted.service" luna://com.webos.service.bus/addManifestsDir '{"prefix": "/prefix", "dirpath": "path/to/manifests"}'
Response:
{
"returnValue": true
}
Example : Unsuccessful request to add manifest file to hub security configuration
# luna-send -n 1 -f -m "com.webos.some.not_trusted.service" luna://com.webos.service.bus/addManifestsDir '{"prefix": "/prefix", "dirpath": "path/to/manifests"}'
Response:
{
"returnValue": false,
"errorText": "com.webos.some.not_trusted.service does not allowed to call addManifestsDir"
}
addOneManifest
ACG: servicebus.configuration
- Added:
API level 26
Description
Adds manifest file data to hub security configuration.
Only services present in the "hub.configuration" security group are allowed to call this method.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| path | Required | String | Path to the manifest file. |
| prefix | Required | String | Prefix that will be applied to all entries in the manifest file and their internal data. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates status of method execution. Possible values are:
|
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -1 | "Schema error. 19: Missing required key" | Required Parameter is missing |
| -1 | "Schema error. 13: Not string" | If parameter is not string type |
| -1 | "Manifest " " parse error: "Invalid parameters error. Can't open file: "" | When invalid prefix or file path is given this error appears . *Note - the file path will vary in the error text depending upon the file name. |
Example
Example : Error response when services that are not present in the hub.configuration security group call this method
# luna-send -n 1 -f -m "com.webos.some.not_trusted.service" luna://com.webos.service.bus/addOneManifest '{"prefix": "/prefix", "path": "path/to/manifest.json"}'
Response:
{
"returnValue": false,
"errorText": "com.webos.some.not_trusted.service does not allowed to call addOneManifest"
}
Example : Add manifest file data to hub security configuration
# luna-send -n 1 -f luna://com.webos.service.bus/addOneManifest '{"prefix": "/prefix", "path": "path/to/manifest.json"}'
Response:
{
"returnValue": true
}
getServiceAPIVersions
ACG: servicebus.communication
- Added:
API level 26
Description
Gets service API version from the ls-hub. API version will be returned as a value of "versions" object. Value may have any type. It depends from the JSON object, which is set as a version for a particular service name in a role file. If service doesn't have service info, "returnValue" will be set to false and "unknown" list will contain the name.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| services | Required | String array | A list of service names, which versions we are requesting for. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates status of method execution. Possible values are:
|
| versions | Required | Object | An object with keys as service names, and values as corresponding versions. |
| unknown | Optional | String array | A list of unknown/invalid service names. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -1 | "Schema error. 3: Not array" | When type is not array . |
| -1 | Schema error. 19: Missing required key" | When required parameter is missing. |
Example
Example : When unknown service is provided in input
# luna-send -n 1 -f luna://com.webos.service.bus/getServiceAPIVersions '{"services": ["com.palm.systemservice", "com.webos.unknown_service"]}'
Response:
{
"returnValue": false,
"versions": { "com.palm.systemservice": "1.0" },
"unknown": [ "com.webos.unknown_service" ]
}
Example : When only known services are provided
# luna-send -n 1 -f 'luna://com.webos.service.bus/getServiceAPIVersions '{"services": ["com.palm.systemservice"]}'
Response:
{
"returnValue": true,
"versions": { "com.palm.systemservice": "1.0" }
}
isCallAllowed
ACG: servicebus.communication
- Added:
API level 26
Description
Checks that call is allowed from specified requester to specified URI.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| uri | Required | String | Uri that will be called by specified requester |
| requester | Required | String | Requester that will call specified uri. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates status of method execution. Possible values are:
|
| allowed | Required | Boolean | Indicates if call is allowed. Possible values are:
|
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -22 | Not a valid %part in% uri | Uri is invalid or has invalid part: service name, path or method name |
Example
Example scenario
# luna-send -n 1 -f luna://com.webos.service.bus/isCallAllowed '{"requester": "com.webos.customer", "uri": "luna://com.webos.product/method"}'
Response:
{
"returnValue": true,
"allowed": true
}
queryServicePermissions
ACG: servicebus.communication
- Added:
API level 26
Description
Queries a service to:
- Obtain the set of rules that are relevant to the service.
- List the API that are required (client permissions)
- List the API that are provided (API permissions).
The API permissions are compiled from the .api.json files and the client permissions are compiled from the .perm.json files and from service registration in run time.
Note: This method must be used for debugging a service. Do not use it in your runtime application.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| service | Required | String | Name of the service to be queried. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates status of method execution. Possible values are:
|
| client | Required | String array | Description of client permissions: list of groups to which the requested service has access. |
| api | Required | Object: ApiPermissionsObject | Description of API permissions as a JSON object. Note: Check example below. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -1 | Invalid payload format | Invalid payload format, error message describes the details |
| -1 | "Schema error. 19: Missing required key" | When required parameter is missing |
| -1 | Schema error. 13: Not string" | When parameter is not string type |
Example
Example scenario
Sample to query the "com.webos.booster" service:
# luna-send -n 1 -f luna://com.webos.service.bus/queryServicePermissions '{"service": "com.webos.booster"}'
Response:
{
"client": [
"private",
"signals.all",
"luna.internal.public",
"signals.all.subscribe"
],
"returnValue": true,
"api": {
"/launch": [
"private",
"applications.internal"
],
"/close": [
"private",
"applications.internal"
],
"/com/palm/luna/private/ping": [
"public",
"luna.internal.public"
],
"/com/palm/luna/private/*": [
"private",
"luna.internal"
],
"/*": [
"all"
],
"/com/palm/luna/private/cancel": [
"public",
"luna.internal.public"
],
"/running": [
"private",
"applications.internal"
]
}
}
removeManifestsDir
ACG: servicebus.configuration
- Added:
API level 26
Description
Removes manifests directory which were added by the addManifestsDir method.
Note: Only services present in the "hub.configuration" security group are allowed to call this method.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| prefix | Optional | String | Prefix that adjust relative paths for manifests directory path and paths in manifests to absolute |
| dirpath | Required | String | Directory path (treated as relative if prefix is specified or absolute if not) |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates status of method execution. Possible values are:
|
Example
Example : Successful request to remove manifest file to hub security configuration
# luna-send -n 1 -f luna://com.webos.service.bus/removeManifestsDir '{"prefix": "/prefix", "dirpath": "path/to/manifests"}'
Response:
{
"returnValue": true
}
Example : Unsuccessful request to remove manifest file to hub security configuration
# luna-send -n 1 -f -m "com.webos.some.not_trusted.service" luna://com.webos.service.bus/addManifestsDir '{"prefix": "/prefix", "dirpath": "path/to/manifests"}'
Response:
{
"returnValue": false,
"errorText": "com.webos.some.not_trusted.service does not allowed to call removeManifestsDir"
}
removeOneManifest
ACG: servicebus.configuration
- Added:
API level 26
Description
Removes manifest file data from hub security configuration.
Only services present in the "hub.configuration" security group are allowed to call this method.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| path | Required | String | Path to the manifest file. |
| prefix | Required | String | Prefix that will be applied for all files in the manifest file. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates status of method execution. Possible values are:
|
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -1 | "Schema error. 13: Not string" | When parameter is not string type. |
| -1 | "Schema error. 19: Missing required key" | When required parameter is missing. |
Example
Example : Remove manifest file data from hub security configuration
# luna-send -n 1 -f luna://com.webos.service.bus/removeOneManifest '{"prefix": "/prefix", "path": "path/to/manifest.json"}'
Response:
{
"returnValue": true
}
Example : Error response when services not present in the hub configuration security group call this method
# luna-send -n 1 -f -m "com.webos.some.not_trusted.service" luna://com.webos.service.bus/removeOneManifest '{"prefix": "/prefix", "path": "path/to/manifest.json"}'
Response:
{
"returnValue": false,
"errorText": "com.webos.some.not_trusted.service does not allowed to call removeOneManifest"
}
signal/addmatch
ACG: servicebus.communication
- Added:
API level 26
Description
Registers a client to receive signals from webOS services matching the category and method specified in the parameters.
If method parameter is not specified then the client will be registered to receive all signals matching the category.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| category | Required | String | Specifies a category name. A category represents a set of signals. |
| method | Optional | String | Specifies a signal name from the category. Examples of signals in the category /com/palm/bluetooth/gap: If the signal name specified in the method parameter is /com/palm/bluetooth/gap/visibleon then the client will be registered to receive this signal. If the signal name is not specified in the method parameter then the client will be registered to receive all the signals under /com/palm/bluetooth/gap category. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates status of method execution. Possible values are:
|
Example
Example scenario
# luna-send -i luna://com.webos.service.bus/signal/addmatch '{"category": "/com/palm/power"}'
Response:
{
"returnValue":true
}
signal/registerServerStatus
ACG: servicebus.communication
- Added:
API level 26
Description
Registers a client to receive the signal sent by the bus, when a service is registered/unregistered on the bus.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| serviceName | Required | String | Name of a service that the client wants to be notified, when it is registered/unregistered on the bus. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| serviceName | Required | String | Name of the service. |
| connected | Required | Boolean | If service is registered, connected contains true. |
Example
Example scenario
# luna-send -i luna://com.webos.service.bus/signal/registerServerStatus '{"serviceName": "com.webos.service.sleep"}'
Response:
{
"serviceName":"com.webos.service.sleep",
"connected":true
}
In another session restart sleepd daemon.
Response:
{
"serviceName":"com.webos.service.sleep",
"connected":true
}
{
"serviceName":"com.webos.service.sleep",
"connected":false
}
{
"serviceName":"com.webos.service.sleep",
"connected":true
}
signal/registerServiceCategory
ACG: servicebus.communication
- Added:
API level 26
Description
Registers a client to the signal sent by the bus, when a service adds the specified category. This method does not register the specified category but registers a client interested to receive the signal when the category is added to the service.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| serviceName | Required | String | Name of the service that a client wants to be notified, when the specified category is added to that service. Example : com.webos.service.systemservice |
| category | Optional | String | Category name. Example:
Example: If the values in the above example parameters are used then the client will receive the signal if com.webos.service.systemservice registers the /recognition/finger category. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| categoryname | Optional | String array | List of registered methods in the category. |
Example
Example scenario
# luna-send -i luna://com.webos.service.bus/signal/registerServiceCategory '{"serviceName": "com.palm.sleep"}'
Response:
{
"/com/palm/power":[
"TESTSuspend",
"clientCancelByName",
"identify",
"forceSuspend",
"prepareSuspendAck",
"suspendRequestAck",
"prepareSuspendRegister",
"suspendRequestRegister",
"activityEnd",
"activityStart",
"TESTSuspend",
"clientCancelByName",
"identify",
"forceSuspend",
"prepareSuspendAck",
"suspendRequestAck",
"prepareSuspendRegister",
"suspendRequestRegister",
"TESTSuspend",
"clientCancelByName",
"identify",
"forceSuspend",
"prepareSuspendAck",
"suspendRequestAck",
"prepareSuspendRegister",
"suspendRequestRegister",
"activityEnd",
"activityStart",
"TESTSuspend",
"clientCancelByName",
"identify",
"forceSuspend",
"prepareSuspendAck",
"suspendRequestAck",
"prepareSuspendRegister",
"suspendRequestRegister",
"activityEnd",
"activityStart",
"TESTSuspend",
"clientCancelByName",
"identify",
"forceSuspend",
"prepareSuspendAck",
"suspendRequestAck",
"prepareSuspendRegister",
"suspendRequestRegister",
"TESTSuspend",
"clientCancelByName",
"identify",
"forceSuspend",
"prepareSuspendAck",
"suspendRequestAck",
"prepareSuspendRegister",
"suspendRequestRegister",
"activityEnd",
"activityStart"
],
"/timeout":[
"clear",
"set",
"clear",
"set"
],
"/time":[
"internalAlarmFired",
"alarmRemove",
"alarmQuery",
"alarmAdd",
"alarmAddCalendar"
],
"/shutdown":[
"machineReboot",
"machineOff",
"TESTresetShutdownState",
"shutdownServicesAck",
"shutdownServicesRegister",
"shutdownApplicationsAck",
"shutdownApplicationsRegister",
"initiate"
]
}
Objects
ApiPermissionsObject
Describe the group to which methods of the service belong. The properties of this object serve as patterns for methods (including their categories) and the values for these properties are set of groups for the methods matching the patterns.
Name | Required | Type | Description |
|---|---|---|---|
| <method pattern> | Required | String array | List of groups that the methods matching the pattern in the property name belong to. |