© 2013 Samsung Electronics Co., Ltd. All rightsreserved.
In Samsung Web API specifications, there is a set of APIs to control Smart TVs. These features work like the remote controller (a.k.a remocon), keyboard, and mouse. TVController represents a set of features that allow you to control your Samsung TV. It can be discovered using APIs provided by the DeviceFinder API. ViewController is provided for expanded control of the Digital Media Renderer (DMR) for images. A ViewController instance can be obtained by invoking getViewController() through an ImageViewer instance.
To control the Web browser on a Samsung Smart TV, you must find a TV controller device in the network by invoking getDeviceList('TVCONTROLLER') and establishing a socket connection using connect() in TVController as shown in the sample code below :
/**
* Get a TV controller instance.
*/
var tvController = null;
var sCB = function (serviceProvider) {
// Get DeviceFinder instance
var deviceFinder = serviceProvider.getDeviceFinder();
// Get TV Controller instance.
var tvControllers = deviceFinder.getDeviceList('TVCONTROLLER');
if (tvControllers.length != 0) {
tvController = tvControllers[0];
} else {
return;
}
// Define success callback for connecting to TV Controller.
function connSCB(controllerID) {
// TV Controller is connected successfully.
}
// Define error callback for connecting to TV Controller.
function connECB(error, controllerID) {
console.log(“error: “ + error + “, controller id: “ + controllerID);
}
tvController.connect(connSCB, connECB);
};
var eCB = function(e, state){
console.log("createServiceProvider error: " + e + ", state: "+ state);
};
webapis.allshare.serviceconnector.createServiceProvider(sCB, eCB);
All the TV remote control buttons are stored in RemoteKey enumeration. If it establishes a connection between the mobile device and TV, you can use several commands to control the TV. The remote controller commands can be called through the sendRemoteKey() function, as shown in the sample code below:
/**
* Control web browser.
*/
var tvController = null;
var sCB = function(serviceProvider) {
// Get DeviceFinder instance
var deviceFinder = serviceProvider.getDeviceFinder();
// Get TV Controller instance.
var tvControllers = deviceFinder.getDeviceList('TVCONTROLLER');
if (tvControllers.length != 0) {
tvController = tvControllers[0];
} else {
return;
}
// Define success callback for connecting to TV Controller.
function connSCB(controllerID) {
// TV Controller is connected successfully.
// Send remote key to Smart TV.
tvController. sendRemoteKey('KEY_CH_UP');
}
// Define error callback for connecting to TV Controller.
function connECB(error, controllerID) {
console.log(“error: “ + error + “, controller id: “ + controllerID);
}
tvController.connect(connSCB, connECB);
};
var eCB = function(e, state) {
console.log("createServiceProvider error: " + e + ", state: "+ state);
};
webapis.allshare.serviceconnector.createServiceProvider(sCB, eCB);
Also, you can send strings to the TV controller when the keyboard is on screen.
/**
* Control web browser.
*/
// It is assumed that you have obtained a TVController instance.
var tvController;
// Send the TV keyboard string input.
tvController.sendKeyboardString('TV TEST');
// Send the end of TV keyboard string input.
tvController.sendKeyboardEnd();
AllShare related APIs in Samsung Web APIs allow you to move the mouse pointer over the controlled TV. It can be invoked with a set of TVController methods:
// It is assumed that you have obtained a TVController instance.
var tvController;
// Define common success callback to notify the application an operation request is successful.
function commSCB(playerID){
console.log(“operation success!”);
}
// Define common error callback to notify the application an operation request failed.
function commECB(error, playerID) {
console.log(“operation failed!”);
}
/*
* To use below APIs, the TV Controller should be in POINT_BROWSING mode.
*/
// Define success callback for getBrowserMode.
function getBroModeSCB(mode, controllerID) {
if (mode == 'LINK_BROWSING'){
// Set browse mode to POINT_BROWSING
tvController.setBrowserMode('POINT_BROWSING', commSCB, commECB);
}
}
tvController.getBrowserMode(getBroModeSCB, commECB);
//Send the touch down of the TV mouse input.
tvControllers.sendTouchDown();
// Move the mouse pointer.
tvController.sendTouchMove(230,480);
//send the touch up of the TV mouse input.
tvController.sendTouchUp();
//Send the touch click of the TV mouse input which the cursor points.
tvControllers.sendTouchClick();
The TVController interface has some methods for Web browsing, which allow sharing a Web page between the mobile device and TV. You can send the web address from the mobile browser to the TV. Below sample code shows some functions that support Web browsing activities:
//It is assumed that you have obtained a TVController instance.
var tvController;
// Define common success callback to notify the application an operation request is successful.
function commSCB(playerID) {
console.log(“operation success!”);
}
// Define common error callback to notify the application an operation request failed.
function commECB(error, playerID){
console.log(“operation failed!”);
}
// Attach the event handlers when user select browser's button remotely
function onClickBrowserButtons(buttonType) {
switch (buttonType) {
case 'OPEN' :
// Open a web site
tvController.openWebPage(“http://www.google.com”, commSCB, commECB);
break;
case 'CLOSE' :
// Close the web page
tvController.closeWebPage(commSCB, commECB);
break;
case 'REFLESH' :
// Refresh the web page
tvController.refreshWebPage(commSCB, commECB);
break;
case 'STOP' :
// Stop the current web page on loading
tvController.stopWebPageLoading(commSCB, commECB);
break;
case 'HOME' :
// Go home page
tvController.goHomePage(commSCB, commECB);
break;
case 'NEXT' :
// Go next web page
tvController.goNextWebPage(commSCB, commECB);
break;
case 'PREVIOUS' :
// Go previous web page
tvController.goPreviousWebPage(commSCB, commECB);
break;
}
}
// Define success callback for getBrowserUrl.
function getBroUrlSCB(url, controllerID) {
console.log(“Current web site url: “ + url);
}
// Get current web page url.
tvController.getBrowserUrl(getBroUrlSCB, commECB);
// Attach event handlers when user scrolls or zooms the web page remotely.
function onControlPage(controlType) {
switch (controlType) {
case 'SCROLL_UP' :
// Scroll web page
tvController.scrollWebPage (“SCROLL_UP”, commSCB, commECB);
break;
case 'ZOOM_IN' :
//Zoom web page
tvController.zoomWebPage(“ZOOM_IN”, commSCB, commECB);
break;
}
}
Scroll direction in a browser is defined in the following table:
Scroll Direction Enumeration | Description |
---|---|
SCROLL_UP | Scroll up |
SCROLL_DOWN | Scroll down |
Zoom mode in a browser is defined in the following table:
Zoom Mode Enumeration | Description |
---|---|
ZOOM_IN | Set zoom in |
ZOOM_OUT | Set zoom out |
ZOOM_DEFAULT | Set the zoom ratio as default value, i.e 1.0x |
To receive notification from the TV Web browser, the application must register an event listener as follows:
// It is assumed that you have obtained a TVController instance.
var tvController;
var tvEventListener = {
onauthenticationfailed: function(controllerId) {
console.log(“Authentication failed!”);
},
onconnected: function(controllerId) {
console.log(“Connected!”);
},
ondisconnected: function(controllerId) {
console.log(“Disconnected!”);
},
onstringchanged: function(text, controllerId) {
console.log(“String changed!”);
}
};
var listenerID = tvController.addTVControllerEventListener(tvEventListener);
// Remote listener
tvControllers.removeTVControllerEventListener(listenerID);
To set the input mode of the web browser, you can use setBrowserMode(). setBrowserMode() requires TVControllerBrowserMode as input parameter. The sample code is as follows:
var controller; // it is assumed that a TV controller object is obtained.
function successCB(controllerId) {
console.log("TV browser mode is successfully set.");
}
function errorCB(error, controllerId) {
console.log(error.name);
}
try {
if (controller.isConnected) {
controller.setBrowserMode("LINK_BROWSING", successCB, errorCB);
}
} catch (e) {
console.log(e.name);
}
If you want to get the input mode of the Web browser, you can use getBrowserMode() of the TVController. TVControllBrowserMode can be retrieved in TVControllGetBrowserModeSuccessCallback. The sample code is as follows:
var controller; // it is assumed that a TV controller object is obtained.
function successCB(mode, controllerId) {
console.log("TV browser mode is " + mode);
}
function errorCB(error, controllerId) {
console.log(error.name);
}
try {
if (controller.isConnected) {
var mode = controller.getBrowserMode(successCB, errorCB);
}
} catch (e) {
console.log(e.name);
}
setBrowserMode() and getBrowserMode() are valid under the condition when a controlled TV launched a TV browser. Otherwise, it is ignored. Possible values of TVControllerBrowserMode are listed below:
Browse Mode Enumeration | Description |
---|---|
POINT_BROWSING | Input mode using the mouse cursor |
LINK_BROWSING | Input mode using the arrow keys |
UNKNOWN | The unknown mode |
To control the image player on Samsung Smart TVs, you must find a TV controller device in the network by invoking getDeviceList(“IMAGEVIEWER”) and establishing a persistent connection using connect() in ViewController. Below is a sample code showing the use of the connect() method:
var serviceProvider; // it is assumed that you obtained serviceProvider.
try {
var imageViewer = serviceProvider.getDeviceFinder().getDeviceList("IMAGEVIEWER");
var viewController = null;
if (imageViewer.length > 0) {
viewController = imageViewer[0].getViewController();
}
if (viewController != null) {
// Developer can control view controller
// Define a success callback.
function viewControllerSCB(controllerId) {
console.log("connection is made properly.");
}
// Define an error callback
function viewControllerECB(error, controllerId) {
console.log(error.message);
}
try {
viewController.connect(viewControllerSCB, viewControllerECB);
} catch (e) {
console.log(e.name);
}
}
} catch (e) {
console.log(e.name);
}
An application can receive ViewController event by registering the listener as follows:
var handle = null;
var eventListener = {
onauthenticationfailed: function(viewControllerId) {
console.log("failed to authentication.");
},
onconnected: function(viewControllerId) {
console.log("connected.");
},
ondisconnected(viewControllerId) {
console.log("disconnected.");
}
};
try {
if (viewController.isConnected) {
handle = viewController.addViewControllerEventListener(eventListener);
}
} catch (e) {
console.log(e.name);
}
// Remote listener
var eventListenerId; // it is assumed that an eventListenerId which is registered.
if (handle != null) {
if (viewController.isConnected) {
viewController.removeViewControllerEventListener(handle);
}
}
ViewController is used for controlling the view. You can use ViewController for moving, rotating, and zooming the photo view. To get the ViewController instance, call the getViewController() method in ImageViewer. ViewController requires continuous network communication. If the connection between a device and a TV is successful, you can use three methods to the control TV image viewer:
For move(), you must specify new horizontal and vertical coordinates for the view center. Invoke the move() method as follows:
var viewController; // it is assumed that a proper view controller object which has connected;
// Define a success callback.
function moveSCB(controller) {
console.log("moveSCB");
}
// Define an error callback
function moveECB(error, controller) {
console.log(“move failed: “+error.message);
}
try {
if (viewController.isConnected) {
viewController.move(18, 18, true, moveSCB, moveECB);
}
} catch (e) {
console.log(e.name);
}
Also, you can rotate the image using setViewAngle(). Below is sample code showing the use of the setViewAngle() method.
var viewController; // it is assumed that a proper view controller object has connected;
// Define a success callback.
function setViewAngleSCB(controller) {
console.log("setViewAngleSCB.");
}
// Define an error callback
function setViewAngleECB(error, controller) {
console.log(“setViewAngle failed: “+error.message);
}
try {
if (viewController.isConnected) {
viewController.setViewAngle("90", setViewAngleSCB, setViewAngleECB);
}
} catch (e) {
console.log(e.name);
}
For zoom(), you must specify the position of the zoom center, zoom scale in percentage units, view angle, and image resolution. Invoke the zoom() method as follows:
var viewController; // It is assumed that a proper view controller object has connected;
var zoomRatio = 100;
var originalWidth, originalHeight; // It is assumed that original size of an image stored.
try {
if (viewController.isConnected) {
viewController.zoom(8, 8, zoomRatio * 1, "180", orginalWidth, orginalHeight);
}
} catch (e) {
console.log(e.name);
}