com.webos.service.bus

Note
This API has been available since API level 26.

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 the status of operation. Possible values are:

true: Indicates that the operation was successful.
false: Indicates that the operation failed.

errorText

Optional

String

Indicates the reason for the failure in operation.

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 the status of operation. Possible values are:

true: Indicates that the operation was successful.
false: Indicates that the operation failed.

errorText

Optional

String

Indicates the reason for the failure in operation

Example

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
}

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

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	True in case of success, false if input list contains invalid names.
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.

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 the status of operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed.
allowed	Optional	Boolean	True if call is allowed, otherwise false. Will not be returned if returnValue is false.
errorCode	Optional	Number (int32_t)	Error code is returned if returnValue is false else no error code is returned if returnValue is true.
errorText	Optional	String	Indicates the reason for the failure in operation.

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

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 the status of operation. Possible values are:

true: Indicates that the operation was successful.
false: Indicates that the operation failed.

errorText

Optional

String

Indicates the reason for the failure in operation

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 the status of operation. Possible values are:

true: Indicates that the operation was successful.
false: Indicates that the operation failed.

errorText

Optional

String

Indicates the reason for the failure in operation

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: None

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: /com/palm/bluetooth/gap/radioon /com/palm/bluetooth/gap/radiooff /com/palm/bluetooth/gap/visibleon /com/palm/bluetooth/gap/visibleoff /com/palm/bluetooth/gap/searchon /com/palm/bluetooth/gap/searchoff 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.

Name

Required

Type

Description

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	If the signal/addmatch method succeeds then the returnValue will contain true. If the signal/addmatch method fails then the returnValue will contain false. The signal/addmatch method may fail because of missing category parameter.

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. If service is unregistered, connected contains false.

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: None

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: /recognition/finger 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.

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

Call Returns

Name	Required	Type	Description
category name	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.