Using webOS API Services

Essentials of an API Service Call

Service URI

The Service URI is the URI to the service, in the form:

luna://service name

e.g.

luna://com.webos.mediadb

Parameters

Parameters are service request options and are passed as a JSON object. These consist of properties required for the service request as well as a few reserved properties that are common to all service requests.

Method Name

The API service method that is called. The method name can be passed as part of the URI or could be passed separately as a property of the parameters object.

Subscribe Property

The 'subscribe' property is a reserved property of the parameter object and can be sent to services that allow subscriptions. If subscribe is set to true, the method will remain in memory and return responses either at periodic intervals or when its data is updated.

Resubscribe Property

The 'resubscribe' property is a reserved property of the parameter object and Is used along with the 'subscribe' property. If resubscribe is set to true, it will resubscribe to a method after a failure has occurred.

Success Callback

The 'onSuccess' property is a reserved property of the parameter object and is used to set a callback function that will be called when a request has been successful. This function will receive a JSON object containing the service's response data.

Failure Callback

The 'onFailure' property is a reserved property of the parameter object and is used to set a function that will be called when a request has failed. This function will receive a JSON object containing the service's error details.

Complete Callback

The 'onComplete' property is a reserved property of the parameter object and is used to set a function that will be called when a request is complete (regardless of its success or failure)

Request Object

The object returned by a service request call. It can be used to cancel the service request and any associated subscription.

Response Object

JSON object containing the service's response data. It will have a reserved property 'returnValue' to indicate the success or failure of a call.

If returnValue is set to false, it means the call failed and the response object may contain further properties such as the errorCode and errorText that give more information about the error.

If 'returnValue' is true, the call is a success and the response object may have additional properties depending on the API call being made. If the subscribe property in the parameters was set to true, the response object will return a property subscribed to indicate the success of the subscription. A value of true in subscribed indicates that the subscription was a success.

 

Calling webOS Services from Any Web App

Any application can include webOS.js and make webOS service calls using the webOS.service.request API.

 

In webOS TV SDK v2.0.0, bootplate-web template contains the webOS library in its webOSjs-0.1.0 directory. You can add this library in your app as below:

<script type="text/javascript" src="webOSjs-0.1.0/webOS.js"></script>


If you use webOS TV SDK v1.2.0 or import already existing web app, follow next steps: 

  1. Download the compressed library file from here. Then, unzip webOS.zip.
     
  2. In your app project, create a sub-folder named webOSjs-0.1.0 and copy the downloaded webOS.js file into this folder. The webOS library file can be placed in any folder within your app project. You should set the proper directory when including the library in source code. 
     
  3. Include webOS library in your app as above.

 

Example of how a webOS service can be called using webOS.js

var request = webOS.service.request("luna://com.mycom.helloworld.service", {
	method:"hello",
	parameters: {"input": inputMessage},

	onSuccess: function (args) {
		//TO-DO
	},

	onFailure: function(inError) {
		//TO-DO
	},

	onComplete: function(inResponse) {
		//....
	},

	subscribe: subscribeStatus ,
	resubscribe: resubscribeStatus 
});
Implicit objects, used for Luna API call, might be removed by garbage collection (GC) before you get the return data. Therefore, we recommend using variable to call or subscribe Luna APIs as above code example.

Calling webOS Services Using Enyo

Enyo applications can use enyo.ServiceRequest and enyo.LunaService kinds to make webOS service calls. Enyo applications should include the "enyo-webos" library to make webOS service calls in Enyo applications. The "enyo-webos" library is included by default in the "bootplate-moonstone" templates.

 

  1. Create an instance of enyo.ServiceRequest with the information of the service that you want to use.
  2. After creating the instance, register a response method using the response property of the instance you just created. By registering the method, you can handle the result returned by the service call as you wish.
  3. Call the registered method by using the go method.
var request = new enyo.ServiceRequest({
	service: "luna://com.mycom.helloworld.service",
	method: "Hello"
});
 
request.response(this, function(inSender, inResponse) {
	// TODO
});
 
request.go();

 

Navigation