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 the subscribe property is set to true, the method remains 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 resubscribes 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 is called when a request has been successful. This function receives 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 is called when a request has failed. This function receives 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 is 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

The JSON object containing the service's response data. It has 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 returns 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

webOSTV.js is a portable library specialized for webOS TV. Any application can include webOSTV.js, and you can make webOS service calls using the webOS.service.request API.

From webOS TV 4.0, we provide webOSTV.js library instead of the webOS.js library.  Bootplate-web templates contain the webOSTV.js library in its webOSTVjs-1.1.1 directory. You can add this library to your app as below:

<script type="text/javascript" src="webOSTVjs-1.1.1/webOSTV.js"></script>

For more details about webOSTV.js, see the webOSTV.js guide. 

Example of how a webOS service can be called using webOSTV.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 a variable to call or subscribe Luna APIs as the above code example.

Calling webOS Services Using Enyo

Enyo framework is not supported by webOS TV that is released in 2019 (version number is 4.5). However, if Enyo libraries and resources are packaged along with the app, it is compatible for execution.

For more information about supporting Enyo and Enact, see Enyo/Enact Guides.

To call webOS services using the Enyo framework, see the following documents.

Version

URL

2.6.3-rc.8

http://enyojs.com/enyo-2.6.3-rc.8/docs/developer-guide/deploying-apps/using-webos-features.html

2.5.5-pre.8

http://enyojs.com/enyo-2.5.5-pre.8/docs/developer-guide/building-apps/using-webos-features.html

Calling webOS Services Using Enact

To call webOS services using the Enact framework, see the following documents.

Doc

URL

webOS Support Module

http://enactjs.com/docs/developer-guide/webos/

webOS Library

http://enactjs.com/docs/modules/webos/LS2Request/

Navigation