Samsung Electronics logo

Managing Channels

Table of Contents


If your application must show channels on TV, you can use the TV Channel API. The TV Channel API allows you to control channel management and the electronic program guide. It also gives you the ability to tune channels and get channel information, program information, and so on.

Prerequisites

The TV Channel API allows you to access the functionality of the channel module.

When the application is launched, a channel object is instantiated automatically in the webapis object. The webapis.tv.channel object is an instance of the TVChannelManager interface, which gives your application the power to control channels, programs, and their information.

Adding the webapis JavaScript file in your application is required to invoke this API properly. Please refer to the script code below to add the webapis file:

 
<html><head>
    <!-- including the JavaScript file which supports Samsung Web API -->
    <script type="text/javascript" language="javascript" src="$MANAGER_WIDGET/Common/webapi/1.0/webapis.js"></script> 
</head></html>

Tune a Specific Channel

If an application must tune a specific channel on a TV, it can use the tune() method to tune the channel.

The TVChannelManager interface provides the tune() that takes the TuneOption, successCallback, errorCallback, and an optional windowID as parameters. On successful tuning of the channel specified by TuneOption, the tune() method calls the successCallback, with the program list of that channel as parameter. The errorCallback is called if an error occurs or input attributes do not contain valid values.

 
function successCB() {
     alert("tuning is successful");
 }

 function errorCB(error) {
     alert(error.name);
 }
 
 webapis.tv.channel.tune({
     ptc: 9,
     major: 9,
     minor: 0,
     sourceID : 9,
     programNumber: 9
     transportStreamID : 90,
     tunecallback: {
         onsucess: function(programList) { alert("getting program list is successful."); }, 
         onnosignal: function(channelList) { alert("getting channel list is successful.");  }
         }
     }, successCB, errorCB, 0);

The TuneCallback interface specifies the options for TV channel tune callback subscriptions. It has two methods: onsuccess and onnosignal. The onsuccess method is invoked when the channel is tuned successfully. The onnosignal method is invoked when the channel has no signal.

Tune the Previous or Next Channel

If an application must tune the previous or next channel, the TVChannelManager interface provides the tuneUp() and tuneDown() methods.
Your app can use the tuneUp() or tuneDown() method to tune the previous or next channel, respectively.

Tuning previous channel

If an application must tune the previous channel, it can use the tuneDown() method.

 The tuneDown() method provided by TVChannelManager takes successCallback, errorCallback, optional tuneMode, and optional windowID as parameters. On successful tuning of the previous channel, the tuneDown() method calls the successCallback. The errorCallback is called with an error object passed as an argument representing the error if an error occurs or input attributes do not contain valid values.

function successCB() {
     alert("tuning is successful");
 }

 function errorCB(error) {
     alert(error.name);
 }
 
 webapis.tv.channel.tuneDown(successCB, errorCB, webapis.tv.channel.NAVIGATOR_MODE_ALL, 0);

The tuneMode parameter can have one of the following values:

  • webapis.tv.channel.NAVIGATOR_MODE_ALL
  • webapis.tv.channel.NAVIGATOR_MODE_DIGITAL
  • webapis.tv.channel.NAVIGATOR_MODE_ANALOG
  • webapis.tv.channel.NAVIGATOR_MODE_FAVORITE

Tuning the next channel

If an application must tune the next channel, it can use the tuneUp() method.

The tuneUp) method provided by TVChannelManager takes successCallback, errorCallback, optional tuneMode, and optional windowID as parameters. On successful tuning of the next channel, the tuneUp() method calls the successCallback. The errorCallback is called with an error object passed as an argument representing the error if an error occurs or input attributes do not contain valid values.

function successCB() {
     alert("tuning is successful");
 }

 function errorCB(error) {
     alert(error.name);
 }
 
 webapis.tv.channel.tuneUp(successCB, errorCB, webapis.tv.channel.NAVIGATOR_MODE_ALL, 0);

Get Channel Information and Find Specific Channels

If an application must get information about the current channel or a list of channels, the TVChannelManager interface provides the getChannelList() and getCurrentChannel(). Similarly, the findChannel() method is provided to find specific channels.

Getting the list of TV channels

If an application must get a list of TV channels, it can use the getChannelList() method.

The getChannelList() method provided by TVChannelManager takes successCallback, errorCallback, optional mode, optional nStart, and an optional number as parameters. On successful retrieval of the TV channel list, the getChannelList() method calls the successCallback, with passing channels list as argument. The errorCallback is called with an error object passed as an argument representing the error if an error occurs or input attributes do not contain valid values.

function successCB(channels) {
     alert("getting channels is successful");
 }

 function errorCB(error) {
     alert(error.name);
 }
 
 try { 
     // gets 10 channel list of all channels
     webapis.tv.channel.getChannelList(successCB, errorCB, webapis.tv.channel.NAVIGATOR_MODE_ALL, 0, 10);
     
 } catch (error) {
     alert(error.name);
 }

The mode parameter can have one of the following values:

  • webapis.tv.channel.NAVIGATOR_MODE_ALL
  • webapis.tv.channel.NAVIGATOR_MODE_DIGITAL
  • webapis.tv.channel.NAVIGATOR_MODE_ANALOG
  • webapis.tv.channel.NAVIGATOR_MODE_FAVORITE

Getting information for the current channel

If an application must get information for the currently tuned channel, it can use the getCurrentChannel() method. The getCurrentChannel() method provided by TVChannelManager takes an optional windowID as parameter. The getCurrentChannel() method returns the current channel information according to the ChannelInfo interface. If an error occurs, the getCurrentChannel() method throws exception accordingly.

try {
     var channel = webapis.tv.channel.getCurrentChannel();
     alert("current channel is "  + channel.channelName);
     
 } catch (error) {
     alert(error.name);
 }

Getting the information for a specific channel

If an application must get information for a specific channel, it can use the findChannel() method.

The findChannel() method provided by TVChannelManager takes major, minor, successCallback, and errorCallback as parameters. On successful retrieval of specific channel information, the findChannel() method calls successCallback, with passing specific channels list as argument. The errorCallback is called with an error object passed as an argument representing the error if an error occurs or input attributes do not contain valid values.

function successCB(channels) {
     alert("getting channels is successful");
 }

 function errorCB(error) {
     alert(error.name);
 }
 
 try {
 
     webapis.tv.channel.findChannel(9, 0, successCB, errorCB);
 } catch (error) {
     alert(error.name);
 }

Get Program Information

If an application must get information about the current program or a list of programs, the TVChannelManager interface provides getCurrentProgram() and getProgramList().
Your app can use getCurrentProgram() and getProgramList() to get the information of the current program or a list of programs, respectively.

Getting information for the current program

If an application must get information about the current program on a tuned channel, it can use the getCurrentProgram() method.

The getCurrentProgram() method provided by TVChannelManager takes optional windowID parameters.  The getCurrentProgram() method returns the current program information of the tuned channel according to the ProgramInfo interface. If an error occurs, the getCurrentProgram() method throws exception accordingly.

try {

     var program = webapis.tv.channel.getCurrentProgram();
     alert("current channel shows "  + program.title);
     
 } catch (error) {
     alert(error.name);
 }

Getting program lists

If an application must get a list of programs for a tuned channel, it can use the getProgramList() method.

The getProgramList() method provided by TVChannelManager takes channelInfo, startTime, successCallback, errorCallback, and optional duration as parameters. On successful retrieval of a program list, the getProgramList() method calls the successCallback with passing programs list as an argument. The errorCallback is called with an error object passed as an argument representing the error if an error occurs or input attributes do not contain valid values.

function successCB(programs) {
     alert("getting programs is successful");
 }

 function errorCB(error) {
     alert(error.name);
 }

 try {
  
     var channel = webapis.tv.channel.getCurrentChannel();
     webapis.tv.channel.getProgramList(channel, webapis.tv.info.getEpochTime(), successCB, errorCB, 3600);
 } catch (error) {
     alert(error.name);
 }

Get the Number of Available Tuners

If an application must get the number of available tuners for a TV, the TVChannelManager interface provides the getNumOfAvailableTuner() method.

The getProgramList() method provided by TVChannelManager does not take any parameters. However, the getCurrentProgram() method returns the number of available tuners as an unsigned long integer. If an error occurs, the getCurrentProgram() method throws exception accordingly.

try {				
     var tuners = webapis.tv.channel.getNumOfAvailableTuner();
     alert("TV has " + tuners + " tuners");
 } catch (error) {
     alert(error.name);
 }