webOS-Service API Reference

Service object

Service object

Syntax

Service(busID)

Description
Creates a Service object, which handles registering methods on the system bus.

Parameter

  • busID: A string containing the bus address of the service, e.g., "com.example.helloworld"

Example

var service = new Service(busID)

service.activityManager

Description
The ActivityManager proxy object for this service. See the ActivityManager object for details.

service.busId

Description
The busId used when creating a Service

service.call

Description
Sends a one-shot request to another service.

Syntax

service.call(uri, arguments, function callback(message) {
    ...
})

Parameters

  • uri: This parameter is the bus address of the service to send to, for example: luna://com.palm.wifi/status
  • arguments: This parameter is a JSON-compatible object which is encoded by the library and sent as part of the request.
  • callback: This callback function is called with a single parameter, which is a Message. See the Message object for details.

service.register

Description
Registers a method for the service. When a request is made for that method, the callback function is called. The callback gets one argument, which is a Message object.

Syntax

service.register(methodName, [function request(message) {
    ...
}], [function cancel(message) {
    ...
}])

Parameter

  • methodName: This parameter 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)\ {
      ...
    });
    

Returns
This method returns a Method object, which emits the request and the cancel events. If the request and cancel arguments are provided, they're bound to the request and cancel events, respectively.

service.subscribe

Description
Sends a subscription request to another service for services that support it.

Syntax

service.subscribe(uri, arguments) 

Parameter

  • The uri and arguments parameters are the same as the call method above.

Returns
This method returns a Subscription object, which emits events as responses come back from the other service.

service.subscriptions

Description
All of the Messages currently subscribed to this service, indexed by their System Bus uniqueToken.

Message object

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

message.cancel

Description
Sends a "cancel" message to the sender, which indicates no more responses will be coming.
This method is normally only used for subscribed calls. Single-shot calls do not require a "cancel" response.

Syntax

message.cancel()

message.category

Description
The category of the method that was called.

message.isSubscription

Description
This property is set to true if "subscribe": true is included in the payload, which indicates the sender wants to subscribe.

message.method

Description
The name of the method that was called. This property is the part of the service URI that's before the method name.

message.respond

Description
Sends a response to the requester.

Syntax

message.respond(payload)

Parameter

  • payload: This parameter is an object that is 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

Description
The applicationID or busID of the message sender, depending on whether it was sent from an app or another service

message.uniqueToken

Description
A string that 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.

Method object

service.register

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

Syntax

service.register(methodName[, requestCallback][, cancelCallback])

event "request"

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

Description
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

service.subscribe

Description
Creates a Subscription object, representing a request to uri.

Syntax

service.subscribe(uri, payload)

Parameters

  • uri: This parameter is the complete URI for the service method, e.g. luna://com.palm.wifi/status
  • payload: This parameter is an object, which is JSON-encoded before sending.

subscription.on with "response"

Description
A response event is sent every time the other service sends a response. The callback receives a single Message parameter.
Syntax

subscription.on("response", function callback(message) {
    ...
})

subscription.on with "cancel"

Description
The cancel 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.

Syntax

subscription.on("cancel", function callback(message) {
    ...
})

subscription.cancel

Description
Sends a cancel message to the other service, indicating that you no longer wish to receive responses.

Syntax

subscription.cancel()

ActivityManager object

service.activityManager

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

Example

var activityManager = service.activityManager;

activityManager.create with "name"

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

Syntax

activityManager.create("name", callback)

activityManager.create with given activity specification

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

Syntax

activityManager.create(activitySpecification, callback)

activityManager.complete

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

Syntax

activityManager.complete(activitySpecification, options, callback)
No Headings