webos-service Library API Reference

About webos-service

The webos-service module for Node.js provides an interface to the system bus, wrapped in familiar Node.js idioms.

webos-service Example

This example registers a service (luna://com.example.helloworld/hello) on the system bus, which responds to a request with a “Hello, World!” message.

//helloworld.js
//simple service, based on webos-service Library API
var Service = require('webos-service');

var service = new Service("com.example.helloworld");
service.register("hello", function(message) {
    message.respond({
        greeting: "Hello, World!"
    });
});

Loading webos-service library

This loads the webos-service module. The only thing exported from the webos-service module is the Service constructor.

var Service = require("webos-service");

webos-service Library API Reference

Service Object

Property/Method	Description
Service (busID)	Creates a Service object, which handles registering methods on the system bus. busId: A string containing the bus address of the service, e.g. "com.example.helloworld" For example, var service = new Service(busID)
service.activityManager	The ActivityManager proxy object for this service. See the ActivityManager object for details.
service.busId	The busId used when creating the Service.
service.call(uri, arguments, function callback(message){...})	This sends a one-shot request to another service. `uri`: The bus address of the service to send to, for example: luna://com.webos.service.wifi/getstatus `arguments`: A JSON-compatible object which is encoded by the library and sent as part of the request `callback`: Called with a single parameter, which is a Message. See the Message object for details.
service.register(methodName, [function request(message){...}], [function cancel(message){...}])	Registers a method for the service. When a request is made for that method, the callback function will be called. The callback gets one argument, which is a Message object. `methodName` is the name of the method to register. You can group methods in categories by putting a category at the front of the methodName, separated by "/" characters, for example, service.register("/config/setup", function callback(message)\{...}); This function returns a Method object, which emits the `request` and `cancel` events. If the request and cancel arguments are provided, they're bound to the `request` and `cancel` events, respectively.
service.subscribe(uri, arguments)	This sends a subscription request to another service, for services that support it. The `uri` and `arguments` are the same as those of `call` method above. This function returns a Subscription object, which emits events as responses come back from the other service.
service.subscriptions	All of the {{Message}}s currently subscribed to this service, indexed by their System Bus unique token.

Message Object

Message objects are used to represent messages coming in from other services or apps.

Property/Method	Description
message.cancel()	This sends a "cancel" message to the sender, which indicates no more responses will be coming. This is normally only used for subscribed calls. Single-shot calls do not require a "cancel" response.
message.category	The category of the method that was called.
message.isSubscription	This is set to `true` if "subscribe": `true` is included in the payload, which indicates the sender wants to subscribe.
message.method	The name of the method that was called. This is the part of the service URI that's before the method name.
message.respond(payload)	This sends a response to the requester. payload: The payload object will be JSON-encoded before being sent. Every response should include a `returnValue` property, which is set to `true` for success replies, and `false` for errors.
message.sender	The appID or busID of the message sender, depending on whether it was sent from an app or another service.
message.uniqueToken	A string which uniquely identifies this request. It is guaranteed to be unique within any one run of the service. If you need to track service requests, this is probably the token you want to use.
message.payload	A parameter passed when the method is called.

Method Object

Property/Method	Description
service.register(methodName[, requestCallback][, cancelCallback])	Creates a Method object, which is an EventEmitter that emits the request and cancel methods. For example, var method = service.register(methodName[, requestCallback][, cancelCallback])
event "request"	This event is emitted when a message is sent to the registered method. The event handler receives the Message object corresponding to the request.
event "cancel"	This event is emitted when a sender of a message indicates that it is no longer interested in receiving replies. This event is only emitted for subscribed messages.

service.register(methodName[,

requestCallback][,

cancelCallback])

Creates a Method object, which is an EventEmitter that emits the request and cancel methods.

For example,

var method = service.register(methodName[, requestCallback][, cancelCallback])

event "request"

This event is emitted when a message is sent to the registered method. The event handler receives the Message object corresponding to the request.

event "cancel"

This event is emitted when a sender of a message indicates that it is no longer interested in receiving replies. This event is only emitted for subscribed messages.

Subscription Object

Property/Method	Description
service.subscribe(uri, payload)	This creates a Subscription object, representing a request to uri. `uri`: The complete URI for the service method, e.g. luna://com.webos.service.wifi/getstatus `payload`: An object, which is JSON-encoded before sending
subscription.on("response", function callback(message){...})	A `response` event is sent every time the other service sends a response. The callback receives a single Message parameter.
subscription.on("cancel", function callback(message){...})	The `cancel` response indicates that the other service has canceled that subscription. It is a good idea to remove any references to the subscription at that time so that the message can be garbage-collected.
subscription.cancel()	Sends a cancel message to the other service, indicating that you no longer wish to receive responses.

ActivityManager Object

Property/Method Description

Property/Method	Description
service.activityManager	This object represents a proxy to the ActivityManager System Bus service (com.webos.service.activitymanager) and also provides a timer that's used to control a service's lifetime. Example var activityManager = service.activityManager;
activityManager.create ("name", callback)	Creates an activity with a reasonable set of default properties, for immediate execution by the service. The service will not exist due to timeout while an activity is active. Note that the `webos-service` library creates a new activity for each request that comes in, so you don't need to create your own for simple cases. Your callback will be called with the new activity as an argument.
activityManager.create (activitySpecification, callback)	Creates an activity with the given activity specification. This is useful when you want to create an activity with a callback, to cause your service to be executed at a later time. Your callback will be called with the new activity as an argument. You might call complete explicitly if you wanted to specify options for the complete operation, for example, to restart the activity, or change the triggers or schedule associated with the activity.
activityManager.complete (activitySpecification, options, callback)	The activity associated with a command will automatically be completed when you send a response. You might call complete explicitly if you wanted to specify options for the complete operation, for example, to restart the activity, or change the triggers or schedule associated with the activity.

service.activityManager

This object represents a proxy to the ActivityManager System Bus service (com.webos.service.activitymanager) and also provides a timer that's used to control a service's lifetime.

Example

var activityManager = service.activityManager;

activityManager.create

("name", callback)

Creates an activity with a reasonable set of default properties, for immediate execution by the service. The service will not exist due to timeout while an activity is active.

Note that the webos-service library creates a new activity for each request that comes in, so you don't need to create your own for simple cases. Your callback will be called with the new activity as an argument.

activityManager.create

(activitySpecification,

callback)

Creates an activity with the given activity specification. This is useful when you want to create an activity with a callback, to cause your service to be executed at a later time. Your callback will be called with the new activity as an argument.

You might call complete explicitly if you wanted to specify options for the complete operation, for example, to restart the activity, or change the triggers or schedule associated with the activity.

activityManager.complete

(activitySpecification,

options, callback)

The activity associated with a command will automatically be completed when you send a response. You might call complete explicitly if you wanted to specify options for the complete operation, for example, to restart the activity, or change the triggers or schedule associated with the activity.