Samsung Electronics logo

Samsung Web API: Channel

© 2013 Samsung Electronics Co., Ltd. All rights reserved.

Introduction

This API provides the control of channel management and electronic program guide (EPG).

Using this EPG, television users can be provided with continuously updated menus displaying broadcast programming or scheduling information for current and upcoming programming.

A webapis.tv.channel object provides access to the functionality of the channel API.

For more information on the Channel features, see Channel Guide.

Table of Contents

Summary of Interfaces and Methods

Interface Method
TVChannelManager
TuneCallback void onsuccess()
void onnosignal()
ProgramListSuccessCallback void onsuccess(ProgramInfoArray programList)
FindChannelSuccessCallback void onsuccess(ChannelInfoArray channelInfoArray)
TuneOption
ChannelInfo
ProgramInfo
ChannelManager void tune(TuneOption tuneOption, SuccessCallback successCallback, ErrorCallback? errorCallback, unsigned short windowID)
void tuneUp(SuccessCallback successCallback, ErrorCallback? errorCallback, unsigned short tuneMode, unsigned short windowID)
void tuneDown(SuccessCallback successCallback, ErrorCallback? errorCallback, unsigned short tuneMode, unsigned short windowID)
void getChannelList(FindChannelSuccessCallback successCallback, ErrorCallback? errorCallback, unsigned short mode, unsigned long nStart, unsigned long number)
ChannelInfo getCurrentChannel(unsigned short windowID)
void findChannel(short major, short minor, FindChannelSuccessCallback successCallback, ErrorCallback? errorCallback)
ProgramInfo getCurrentProgram(unsigned short windowID)
void getProgramList(ChannelInfo channelInfo, unsigned long startTime, ProgramListSuccessCallback successCallback, ErrorCallback? errorCallback, unsigned long duration)
unsigned long getNumOfAvailableTuner()

1. Type Definitions

1.1. ChannelInfoArray

Array of channel information 

    typedef sequence<ChannelInfo> ChannelInfoArray;

1.2. ProgramInfoArray

Array of program information 

    typedef sequence<ProgramInfo> ProgramInfoArray;

2. Interfaces

2.1. TVChannelManager

Defines what is instantiated in the tv object. 

    [NoInterfaceObject] interface TVChannelManager {
        readonly attribute ChannelManager channel;
    };
    TV implements TVChannelManager;

A webapis.tv.channel object provides access to the functionality of the channel module.

2.2. TuneCallback

Specifies the options for TV channel tune callback subscriptions. 

    [Callback, NoInterfaceObject] interface TuneCallback
    {
       void onsuccess();

        void onnosignal();
    };

METHODS

onsuccess

Method invoked when the channel is tuned successfully.

Signature
void onsuccess();

onnosignal

Method invoked when the channel has no signal.

Signature
void onnosignal();

2.3. ProgramListSuccessCallback

Specifies the options for gathering the available program list. 

    [Callback=FunctionOnly, NoInterfaceObject] interface ProgramListSuccessCallback 
    {
        void onsuccess(ProgramInfoArray programList);
    };

METHODS

onsuccess

Method invoked when the program list is gathered.

Signature
void onsuccess(ProgramInfoArray programList);
Parameters
  • programList
    • Optional: No.
    • Nullable: No.
    • Type: ProgramInfoArray.
    • Description: Array of programs for a channel

2.4. FindChannelSuccessCallback

Specifies the options for finding channel 

    [Callback=FunctionOnly, NoInterfaceObject] interface FindChannelSuccessCallback 
    {
        void onsuccess(ChannelInfoArray channelInfoArray);
    };

METHODS

onsuccess

Method invoked when the given channel is found.

Signature
void onsuccess(ChannelInfoArray channelInfoArray);
Parameters
  • channelInfoArray
    • Optional: No.
    • Nullable: No.
    • Type: ChannelInfoArray.
    • Description: Array of Channel Information

2.5. TuneOption

Specifies the options for Tuning 

    dictionary TuneOption {
        long? ptc;

        long? major;

        long? minor;

        long? sourceID;

        long? programNumber;

        long? transportStreamID;

        long? originalNetworkID;

        TuneCallback tunecallback;
    };

Dictionary members

long? ptc

PTC(Physical Transmission Channel) number

long? major

Major channel number

long? minor

Minor channel number

long? sourceID

Source ID

long? programNumber

Program number

long? transportStreamID

Transport stream ID

long? originalNetworkID

Original network ID

TuneCallback tunecallback

callback which will be invoked on tuning

2.6. ChannelInfo

TV channel information 

    [NoInterfaceObject] interface ChannelInfo {

        attribute long ptc;

        attribute long major;

        attribute long minor;

        readonly attribute long lcn;

        readonly  attribute long sourceID;

        readonly  attribute long programNumber;

        readonly attribute long transportStreamID;

        readonly  attribute long originalNetworkID;

        readonly attribute DOMString servicelName;

        readonly attribute DOMString channelName;
    };

ATTRIBUTES

long ptc

PTC number

long major

major channel number

long minor

minor channel number

readonly long lcn

logical channel number

This attribute is read-only.

readonly long sourceID

source ID

This attribute is read-only.

readonly long programNumber

Program number

This attribute is read-only.

readonly long transportStreamID

Transport Stream ID

This attribute is read-only.

readonly long originalNetworkID

Original Network ID

This attribute is read-only.

readonly DOMString servicelName

Service Name

This attribute is read-only.

readonly DOMString channelName

Channel Name

This attribute is read-only.

2.7. ProgramInfo

EPG (Electric Program Guide) information 

    [NoInterfaceObject] interface ProgramInfo {
        readonly attribute DOMString title;

        readonly attribute long startTime;

        readonly attribute long duration;

        readonly attribute DOMString? detailedDescription;

        readonly attribute DOMString? language;

        readonly attribute DOMString? rating;
    };

ATTRIBUTES

readonly DOMString title

Program title

This attribute is read-only.

readonly long startTime

Start time by epoch time

This attribute is read-only.

readonly long duration

Duration

This attribute is read-only.

readonly DOMString? detailedDescription

Detailed information

This attribute is read-only.

readonly DOMString? language

Language information

This attribute is read-only.

readonly DOMString? rating

Rating information

This attribute is read-only.

2.8. ChannelManager

Defines what is instantiated in the TV object. 

    [NoInterfaceObject] interface ChannelManager {    
    
        const unsigned short NAVIGATOR_MODE_ALL = 0;

        const unsigned short NAVIGATOR_MODE_DIGITAL = 1;

        const unsigned short NAVIGATOR_MODE_ANALOG = 2;

        const unsigned short NAVIGATOR_MODE_FAVORITE = 3;

        void tune(TuneOption tuneOption,
                    SuccessCallback successCallback, 
                    ErrorCallback? errorCallback, 
                    optional unsigned short windowID)
                   ;
                              
        void tuneUp(SuccessCallback successCallback, 
                        ErrorCallback? errorCallback,
                        optional unsigned short tuneMode,
                        optional unsigned short windowID)
                       ;

        void tuneDown(SuccessCallback successCallback, 
                           ErrorCallback? errorCallback, 
                           optional unsigned short tuneMode, 
                           optional unsigned short windowID)
                          ;

        void getChannelList(FindChannelSuccessCallback successCallback,
                                                 ErrorCallback? errorCallback,  
                                                 optional unsigned short mode, 
                                                 optional unsigned long nStart, 
                                                 optional unsigned long number)
                                                ;

        ChannelInfo getCurrentChannel(optional unsigned short windowID);

        void findChannel(short major,
                             short minor, 
                             FindChannelSuccessCallback successCallback, 
                             ErrorCallback? errorCallback)
                            ;

        ProgramInfo getCurrentProgram(optional unsigned short windowID);    
        
        void getProgramList(ChannelInfo channelInfo, 
                                 unsigned long startTime, 
                                 ProgramListSuccessCallback successCallback, 
                                 ErrorCallback? errorCallback, 
                                 optional unsigned long duration);

        unsigned long getNumOfAvailableTuner();
    };

A webapis.tv.channel object provides access to the functionality of the channel module.

CONSTANTS

unsigned short NAVIGATOR_MODE_ALL

Navigation all channels

unsigned short NAVIGATOR_MODE_DIGITAL

Navigation by digital channels

unsigned short NAVIGATOR_MODE_ANALOG

Navigation by analog channels

unsigned short NAVIGATOR_MODE_FAVORITE

Navigation by favorite channels

METHODS

tune

Tunes the specified channel

Signature
void tune(TuneOption tuneOption, SuccessCallback successCallback, ErrorCallback? errorCallback, optional unsigned short windowID);

The ErrorCallback is launched with these error types:

  • InvalidValuesError: If the input attributes do not contain valid values.
  • UnknownError: In the case of any other error.

If the errorCallback does not contain a valid function (e.g. it contains null) or in the case of any other error that should be returned in the errorCallback (see above), the implementation MUST silently fail and no further action is required (i.e. the developer is not notified of the error).

Parameters
  • tuneOption
    • Optional: No.
    • Nullable: No.
    • Type: TuneOption.
    • Description: option for turning information
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: SuccessCallback.
    • Description: To be invoked if the operation is completed successfully.
  • errorCallback
    • Optional: No.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: To be invoked when an error occurs.
  • windowID
    • Optional: Yes.
    • Nullable: No.
    • Type: unsigned short.
    • Description: window identifier
Exceptions
  • WebAPIException:

    with error type NotSupportedError if this feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 function successCB() {
     console.log("tuning is successful");
 }

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

tuneUp

Goes to the next channel.

Signature
void tuneUp(SuccessCallback successCallback, ErrorCallback? errorCallback, optional unsigned short tuneMode, optional unsigned short windowID);

It will change the current channel to the next channel in the available channel list. The ErrorCallback is launched with these error types:

  • InvalidValuesError: If the input attributes do not contain valid values.
  • UnknownError: In the case of any other error.

If the errorCallback does not contain a valid function (e.g. it contains null) or in the case of any other error that should be returned in the errorCallback (see above), the implementation MUST silently fail and no further action is required (i.e. the developer is not notified of the error).

Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: SuccessCallback.
    • Description: To be invoked if the operation is completed successfully.
  • errorCallback
    • Optional: No.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: To be invoked when an error occurs.
  • tuneMode
    • Optional: Yes.
    • Nullable: No.
    • Type: unsigned short.
    • Description: tuning navigation mode
  • windowID
    • Optional: Yes.
    • Nullable: No.
    • Type: unsigned short.
    • Description: window identifier
Exceptions
  • WebAPIException:

    with error type NotSupportedError if this feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 function successCB() {
     console.log("tuning is successful");
 }

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

tuneDown

Goes to the previous channel.

Signature
void tuneDown(SuccessCallback successCallback, ErrorCallback? errorCallback, optional unsigned short tuneMode, optional unsigned short windowID);

It will change the current channel to the previous channel in the available channel list. The ErrorCallback is launched with these error types:

  • InvalidValuesError: If the input attributes do not contain valid values.
  • UnknownError: In the case of any other error.

If the errorCallback does not contain a valid function (e.g. it contains null) or in the case of any other error that should be returned in the errorCallback (see above), the implementation MUST silently fail and no further action is required (i.e. the developer is not notified of the error).

Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: SuccessCallback.
    • Description: To be invoked if the operation is completed successfully.
  • errorCallback
    • Optional: No.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: To be invoked when an error occurs.
  • tuneMode
    • Optional: Yes.
    • Nullable: No.
    • Type: unsigned short.
    • Description: a tuning navigation mode
  • windowID
    • Optional: Yes.
    • Nullable: No.
    • Type: unsigned short.
    • Description: a window identifier
Exceptions
  • WebAPIException:

    with error type NotSupportedError if this feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 function successCB() {
     console.log("tuning is successful");
 }

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

getChannelList

Gets the TV channel list.

Signature
void getChannelList(FindChannelSuccessCallback successCallback, ErrorCallback? errorCallback, optional unsigned short mode, optional unsigned long nStart, optional unsigned long number);

The ErrorCallback is launched with these error types:

  • InvalidValuesError: If the input attributes do not contain valid values.
  • UnknownError: In the case of any other error.

If the errorCallback does not contain a valid function (e.g. it contains null) or in the case of any other error that should be returned in the errorCallback (see above), the implementation MUST silently fail and no further action is required (i.e. the developer is not notified of the error).

Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: FindChannelSuccessCallback.
    • Description: To be invoked if the operation is completed successfully.
  • errorCallback
    • Optional: No.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: To be invoked when an error occurs.
  • mode
    • Optional: Yes.
    • Nullable: No.
    • Type: unsigned short.
    • Description: channel navigation mode
  • nStart
    • Optional: Yes.
    • Nullable: No.
    • Type: unsigned long.
    • Description: start index
  • number
    • Optional: Yes.
    • Nullable: No.
    • Type: unsigned long.
    • Description: number of the channel informations.
Exceptions
  • WebAPIException:

    with error type NotSupportedError if this feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 function successCB(channels) {
     console.log("getting channels is successful");
 }

 function errorCB(error) {
     console.log(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) {
     console.log(error.name);
 }

getCurrentChannel

Gets the current channel information

Signature
ChannelInfo getCurrentChannel(optional unsigned short windowID);
Parameters
  • windowID
    • Optional: Yes.
    • Nullable: No.
    • Type: unsigned short.
    • Description: window identifier
Return value
ChannelInfo the current tuned channel information
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type InvalidValuesError if the input attributes do not contain a valid value

    with error type TypeMismatchError if any of the input attributes are of the wrong type

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

findChannel

Gets the specified channel information

Signature
void findChannel(short major, short minor, FindChannelSuccessCallback successCallback, ErrorCallback? errorCallback);

The ErrorCallback is launched with these error types:

  • InvalidValuesError: If the input attributes do not contain valid values.
  • UnknownError: In the case of any other error.

If the errorCallback does not contain a valid function (e.g. it contains null) or in the case of any other error that should be returned in the errorCallback (see above), the implementation MUST silently fail and no further action is required (i.e. the developer is not notified of the error).

Parameters
  • major
    • Optional: No.
    • Nullable: No.
    • Type: short.
    • Description: major channel number
  • minor
    • Optional: No.
    • Nullable: No.
    • Type: short.
    • Description: minor channel number
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: FindChannelSuccessCallback.
    • Description: To be invoked if the operation is completed successfully.
  • errorCallback
    • Optional: No.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: To be invoked when an error occurs.
Exceptions
  • WebAPIException:

    with error type NotSupportedError if this feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 function successCB(channels) {
     console.log("getting channels is successful");
 }

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

getCurrentProgram

Gets the current program of tuned channel.

Signature
ProgramInfo getCurrentProgram(optional unsigned short windowID);
Parameters
  • windowID
    • Optional: Yes.
    • Nullable: No.
    • Type: unsigned short.
    • Description: window identifier
Return value
ProgramInfo the current EPG program information
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if this feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type InvalidValuesError if the input attributes do not contain a valid value

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 try {
     var program = webapis.tv.channel.getCurrentProgram();
     console.log("current channel shows "  + program.title);
 } catch (error) {
     console.log(error.name);
 }

getProgramList

Gets program list for a specific channel within a time duration

Signature
void getProgramList(ChannelInfo channelInfo, unsigned long startTime, ProgramListSuccessCallback successCallback, ErrorCallback? errorCallback, optional unsigned long duration);

The ErrorCallback is launched with these error types:

  • InvalidValuesError: If the input attributes do not contain valid values.
  • UnknownError: In the case of any other error.

If the errorCallback does not contain a valid function (e.g. it contains null) or in the case of any other error that should be returned in the errorCallback (see above), the implementation MUST silently fail and no further action is required (i.e. the developer is not notified of the error).

Parameters
  • channelInfo
    • Optional: No.
    • Nullable: No.
    • Type: ChannelInfo.
    • Description: Channel Info
  • startTime
    • Optional: No.
    • Nullable: No.
    • Type: unsigned long.
    • Description: start time to search programs.
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: ProgramListSuccessCallback.
    • Description: To be invoked if the operation is completed successfully.
  • errorCallback
    • Optional: No.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: To be invoked when an error occurs.
  • duration
    • Optional: Yes.
    • Nullable: No.
    • Type: unsigned long.
    • Description: time duration in which period programs will be searched.
Exceptions
  • WebAPIException:

    with error type NotSupportedError if this feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 function successCB(programs) {
     console.log("getting programs is successful");
 }

 function errorCB(error) {
     console.log(error.name);
 }

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

getNumOfAvailableTuner

Gets the number of available tuners.

Signature
unsigned long getNumOfAvailableTuner();
Return value
unsigned long the number of available tuner
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

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

3. Full WebIDL 

module Channel {

    typedef sequence<ChannelInfo> ChannelInfoArray;

    typedef sequence<ProgramInfo> ProgramInfoArray;
    
    [NoInterfaceObject] interface TVChannelManager {
        readonly attribute ChannelManager channel;
    };
    TV implements TVChannelManager;

    [Callback, NoInterfaceObject] interface TuneCallback
    {
       void onsuccess();

        void onnosignal();
    };
    
    [Callback=FunctionOnly, NoInterfaceObject] interface ProgramListSuccessCallback 
    {
        void onsuccess(ProgramInfoArray programList);
    };  
    
    [Callback=FunctionOnly, NoInterfaceObject] interface FindChannelSuccessCallback 
    {
        void onsuccess(ChannelInfoArray channelInfoArray);
    }; 

    dictionary TuneOption {
        long? ptc;

        long? major;

        long? minor;

        long? sourceID;

        long? programNumber;

        long? transportStreamID;

        long? originalNetworkID;

        TuneCallback tunecallback;
    };
    
    [NoInterfaceObject] interface ChannelInfo {

        attribute long ptc;

        attribute long major;

        attribute long minor;

        readonly attribute long lcn;

        readonly  attribute long sourceID;

        readonly  attribute long programNumber;

        readonly attribute long transportStreamID;

        readonly  attribute long originalNetworkID;

        readonly attribute DOMString servicelName;

        readonly attribute DOMString channelName;
    };
  
    [NoInterfaceObject] interface ProgramInfo {
        readonly attribute DOMString title;

        readonly attribute long startTime;

        readonly attribute long duration;

        readonly attribute DOMString? detailedDescription;

        readonly attribute DOMString? language;

        readonly attribute DOMString? rating;
    };
    
    [NoInterfaceObject] interface ChannelManager {    
    
        const unsigned short NAVIGATOR_MODE_ALL = 0;

        const unsigned short NAVIGATOR_MODE_DIGITAL = 1;

        const unsigned short NAVIGATOR_MODE_ANALOG = 2;

        const unsigned short NAVIGATOR_MODE_FAVORITE = 3;

        void tune(TuneOption tuneOption,
                    SuccessCallback successCallback, 
                    ErrorCallback? errorCallback, 
                    optional unsigned short windowID)
                   ;
                              
        void tuneUp(SuccessCallback successCallback, 
                        ErrorCallback? errorCallback,
                        optional unsigned short tuneMode,
                        optional unsigned short windowID)
                       ;

        void tuneDown(SuccessCallback successCallback, 
                           ErrorCallback? errorCallback, 
                           optional unsigned short tuneMode, 
                           optional unsigned short windowID)
                          ;

        void getChannelList(FindChannelSuccessCallback successCallback,
                                                 ErrorCallback? errorCallback,  
                                                 optional unsigned short mode, 
                                                 optional unsigned long nStart, 
                                                 optional unsigned long number)
                                                ;

        ChannelInfo getCurrentChannel(optional unsigned short windowID);

        void findChannel(short major,
                             short minor, 
                             FindChannelSuccessCallback successCallback, 
                             ErrorCallback? errorCallback)
                            ;

        ProgramInfo getCurrentProgram(optional unsigned short windowID);    
        
        void getProgramList(ChannelInfo channelInfo, 
                                 unsigned long startTime, 
                                 ProgramListSuccessCallback successCallback, 
                                 ErrorCallback? errorCallback, 
                                 optional unsigned long duration);

        unsigned long getNumOfAvailableTuner();
    };
   
};