top

TVChannel API

The TV Channel API provides the control of channel change and a way to get information about the television program for supporting an Electronic Program Guide(EPG) or Interactive Program Guide(IPG). Using this API, TV watchers can get continuously updated EPG information about the current and upcoming TV programs on all available channels.

Regarding tuning operation, there are some common behaviors.

  • errorCallback will be invoked if there is no channel corresponding to the request

Since: 2.3

Table of Contents

  1. 1. Type Definitions
    1. 1.1. TuneMode
    2. 1.2. SignalState
    3. 1.3. BroadcastStandard
  2. 2. Interfaces
    1. 2.1. TVChannelManager
    2. 2.2. ChannelManager
    3. 2.3. ProgramListSuccessCallback
    4. 2.4. FindChannelSuccessCallback
    5. 2.5. ChannelChangeCallback
    6. 2.6. SignalStateChangeCallback
    7. 2.7. TuneCallback
    8. 2.8. TuneOption
    9. 2.9. ChannelInfo
    10. 2.10. ProgramInfo
    11. 2.11. FavoriteList
  3. 3. Related Feature
  4. 4. Full WebIDL

Summary of Interfaces and Methods

Interface Method
TVChannelManager
ChannelManager
void tune (TuneOption tuneOption, TuneCallback successCallback, optional ErrorCallback? errorCallback, optional WindowType? type)
void tuneUp (TuneCallback successCallback, optional ErrorCallback? errorCallback, optional TuneMode? tuneMode, optional WindowType? type)
void tuneDown (TuneCallback successCallback, optional ErrorCallback? errorCallback, optional TuneMode? tuneMode, optional WindowType? type)
void findChannel (long major, long minor, FindChannelSuccessCallback successCallback, optional ErrorCallback? errorCallback)
void getChannelList (FindChannelSuccessCallback successCallback, optional ErrorCallback? errorCallback, optional TuneMode? mode, optional long? nStart, optional long? number)
void getProgramList (ChannelInfo channelInfo, TZDate startTime, ProgramListSuccessCallback successCallback, optional ErrorCallback? errorCallback, optional unsigned long? duration)
void removeChannelChangeListener (long channelListenerId)
void removeSignalStateChangeListener (long signalListenerId)
ProgramListSuccessCallback
void onsuccess (ProgramInfo[] programInfos)
FindChannelSuccessCallback
void onsuccess (ChannelInfo[] channelInfos)
ChannelChangeCallback
void onchanged (ChannelInfo channelInfo, WindowType type)
SignalStateChangeCallback
void onchanged (SignalState state)
TuneCallback
void onsuccess (ChannelInfo channel, WindowType type)
void onnosignal ()
TuneOption
ChannelInfo
ProgramInfo
FavoriteList
void addChannel (ChannelInfo channel, SuccessCallback successCallback, optional ErrorCallback? errorCallback)
void removeChannel (ChannelInfo channel, SuccessCallback successCallback, optional ErrorCallback? errorCallback)
void getChannels (FindChannelSuccessCallback successCallback, optional ErrorCallback? errorCallback, optional long? nStart, optional long? number)

1. Type Definitions

1.1. TuneMode

An enumerator to indicate the tune mode.
    enum TuneMode {
        "ALL",
        "DIGITAL",
        "ANALOG",
        "FAVORITE"
    };

Since: 2.3

It determines the scope of channel navigation.

  • ALL - The whole channels
  • DIGITAL - Only digital channels
  • ANALOG - Only analog channels
  • FAVORITE - Channels set as preferred by TV watchers

1.2. SignalState

An enumerator to indicate the signal state.
    enum SignalState {
        "SIGNAL_STATE_OK",
        "SIGNAL_STATE_NO_SIGNAL"
    };

Since: 2.4

  • SIGNAL_STATE_OK - Signal is OK
  • SIGNAL_STATE_NO_SIGNAL - No signal

1.3. BroadcastStandard

An enumerator to indicate the broadcast standard.
    enum BroadcastStandard {
        "ATSC",
        "DVB",
        "ISDB",
        "SATELLITE"
    };

Since: 2.4

  • ATSC - ATSC standards
  • DVB - DVB standards
  • ISDB - ISDB standards
  • SATELLITE - satellite standards

2. Interfaces

2.1. TVChannelManager

This interface defines what is instantiated by the tizen object.
    [NoInterfaceObject] interface TVChannelManager {
        readonly attribute ChannelManager tvchannel;
    };
    Tizen implements TVChannelManager;

Since: 2.3

There will be a tizen.tvchannel object that allows access to the functionality of the channel module.

2.2. ChannelManager

This interface provides access to the API functionalities through the tizen.tvchannel interface.
    [NoInterfaceObject] interface ChannelManager {

        void tune(TuneOption tuneOption,
                  TuneCallback successCallback,
                  optional ErrorCallback? errorCallback,
                  optional WindowType? type) raises(WebAPIException);

        void tuneUp(TuneCallback successCallback,
                    optional ErrorCallback? errorCallback,
                    optional TuneMode? tuneMode,
                    optional WindowType? type) raises(WebAPIException);

        void tuneDown(TuneCallback successCallback,
                      optional ErrorCallback? errorCallback,
                      optional TuneMode? tuneMode,
                      optional WindowType? type) raises(WebAPIException);

        void findChannel(long major,
                         long minor,
                         FindChannelSuccessCallback successCallback,
                         optional ErrorCallback? errorCallback) raises(WebAPIException);

        void getChannelList(FindChannelSuccessCallback successCallback,
                            optional ErrorCallback? errorCallback,
                            optional TuneMode? mode,
                            optional long? nStart,
                            optional long? number) raises(WebAPIException);

        ChannelInfo getCurrentChannel(optional WindowType? type) raises(WebAPIException);

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

        ProgramInfo? getCurrentProgram(optional WindowType? type) raises(WebAPIException);

        long addChannelChangeListener(ChannelChangeCallback callback,
                                       optional WindowType? type) raises(WebAPIException);

        void removeChannelChangeListener(long channelListenerId) raises(WebAPIException);

        long addSignalStateChangeListener(SignalStateChangeCallback callback
                                       ) raises(WebAPIException);

        void removeSignalStateChangeListener(long signalListenerId) raises(WebAPIException);

        FavoriteList[] getFavorites() raises(WebAPIException);

        BroadcastStandard getBroadcastStandard(optional WindowType? type) raises(WebAPIException);
    };

Since: 2.3

Methods

tune
Tunes the specified channel.
void tune(TuneOption tuneOption, TuneCallback successCallback, optional ErrorCallback? errorCallback, optional WindowType? type);
             

Since: 2.3

If there are more than one channel with the major and minor, the lowest channel in all possible channels will be switched to.

The ErrorCallback will be launched in the following situations:

  • NotFoundError - Failed to find a requested channel
  • UnknownError - Failed to set the selected channel or onprograminforeceived for another tune was invoked

Privilege level: public

Privilege: http://tizen.org/privilege/tv.channel

Parameters:

  • tuneOption: The tuning option. By default, this attribute is set to null.
  • successCallback: The method to invoke when the tunning operation is completed successfully.
  • errorCallback [optional] [nullable]: The method to invoke when an error occurs.
  • type [optional] [nullable]: The window type. By default, this attribute is set to MAIN.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input attribute is not compatible with the expected type for this attribute.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if this feature is not supported.

Code example:

 var tuneCB = {
    onsuccess: function() {
        console.log("Tune() is successfully done. And there is a signal.");
    }
    onnosignal: function() {
        console.log("Tune() is successfully done. But there is no signal.");
    }
 };

 function channelCB(channels) {
     console.log("getting channels is successful. " + channels.length + " channels are retreived.");
     if (channels.length === 0 ) {
         console.log("There is no found channel.");
         return;
     }
     try {
         tizen.tvchannel.tune({major: channels[0].major}, tuneCB);
     } catch(error) {
         console.log("Error name = "+ error.name + ", Error message = " + error.message);
     }
 }

 function errorCB(error) {
     console.log("Error name = "+ error.name + ", Error message = " + error.message);
 }

 try {
     // requests to get information about 10 channels.
     tizen.tvchannel.getChannelList(channelCB, errorCB, "ALL", 0, 10);
 } catch (error) {
     console.log("Error name = "+ error.name + ", Error message = " + error.message);
 }
 
tuneUp
Changes channel up.
void tuneUp(TuneCallback successCallback, optional ErrorCallback? errorCallback, optional TuneMode? tuneMode, optional WindowType? type);
             

Since: 2.3

When you call this api on the highest channel, the lowest channel would be tuned.

The ErrorCallback will be launched in the following situations:

  • NotFoundError - Failed to find the next higher channel (e.g. When there is no channels in favorites list, you call tuneUp() with 'FAVORITE' tune mode.)
  • UnknownError - Failed to change to the next higher channel or onprograminforeceived for another tune was invoked

Privilege level: public

Privilege: http://tizen.org/privilege/tv.channel

Parameters:

  • successCallback: The method to invoke when the tunning operation is completed successfully.
  • errorCallback [optional] [nullable]: The method to invoke when an error occurs.
  • tuneMode [optional] [nullable]: The tuning navigation mode. By default, this attribute is set to ALL.
  • type [optional] [nullable]: The window type. By default, this attribute is set to MAIN.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input attribute is not compatible with the expected type for this attribute.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if this feature is not supported.

Code example:

 var tuneCB = {
    onsuccess: function() {
        console.log("tuneUp() is successfully done. And there is a signal.");
    }
    onnosignal: function() {
        console.log("tuneUp() is successfully done. But there is no signal.");
    }
 };

 try {
     tizen.tvchannel.tuneUp(tuneCB, null, "ALL");
 } catch (error) {
     console.log("Error name = "+ error.name + ", Error message = " + error.message);
 }
 
tuneDown
Changes channel down.
void tuneDown(TuneCallback successCallback, optional ErrorCallback? errorCallback, optional TuneMode? tuneMode, optional WindowType? type);
             

Since: 2.3

When you call this api on the lowest channel, the highest channel would be tuned.

The ErrorCallback will be launched in the following situations:

  • NotFoundError - Failed to find the next lower channel (e.g. When there is no channels in favorites list, you call tuneDown() with 'FAVORITE' tune mode.)
  • UnknownError - Failed to change to the next lower channel or onprograminforeceived for another tune was invoked

Privilege level: public

Privilege: http://tizen.org/privilege/tv.channel

Parameters:

  • successCallback: The method to invoke when the tunning operation is completed successfully.
  • errorCallback [optional] [nullable]: The method to invoke when an error occurs.
  • tuneMode [optional] [nullable]: The tuning navigation mode. By default, this attribute is set to ALL.
  • type [optional] [nullable]: The window type. By default, this attribute is set to MAIN.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input attribute is not compatible with the expected type for this attribute.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if this feature is not supported.

Code example:

 var tuneCB = {
    onsuccess: function() {
        console.log("tuneDown() is successfully done. And there is a signal.");
    }
    onnosignal: function() {
        console.log("tuneDown() is successfully done. But there is no signal.");
    }
 };

 try {
     // change the channel down according to 'ALL' navigation mode.
     tizen.tvchannel.tuneDown(tuneCB);
 } catch (error) {
     console.log("Error name = "+ error.name + ", Error message = " + error.message);
 }
 
findChannel
Retrieves information about all available channels.
void findChannel(long major, long minor, FindChannelSuccessCallback successCallback, optional ErrorCallback? errorCallback);
             

Since: 2.3

The ErrorCallback will be launched in the following situations:

  • NotFoundError - Failed to find the channel (e.g. call findChannel() with invalid major and minor values(e.g. non-existing channel information))

Privilege level: public

Privilege: http://tizen.org/privilege/tv.channel

Parameters:

  • major: The major channel number
  • minor: The minor channel number
  • successCallback: The method to invoke when the channel searching is done successfully.
  • errorCallback [optional] [nullable]: The method to invoke when an error occurs.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input attribute is not compatible with the expected type for this attribute.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if this feature is not supported.

Code example:

 function successCB(channels) {
     console.log("findChannel() is successfully done. Totally " + channels.length + " channels are found.");
     for (var i = 0; i < channels.length; i++) {
         console.log("----- Channel [" + i + "] -----");
         console.log("Major channel = " + channels[i].major);
         console.log("Minor channel = " + channels[i].minor);
         console.log("Channel Name = " + channels[i].channelName);
         console.log("Program Number = " + channels[i].programNumber);
         // you can get other attributes provided in ChannelInfo
     }
 }

 try {
     tizen.tvchannel.findChannel(9, 0, successCB);
 } catch (error) {
     console.log("Error name = "+ error.name + ", Error message = " + error.message);
 }
 
getChannelList
Gets the TV channel list.
void getChannelList(FindChannelSuccessCallback successCallback, optional ErrorCallback? errorCallback, optional TuneMode? mode, optional long? nStart, optional long? number);
             

Since: 2.3

If this method is invoked without number parameter, all available channel informations will be retrieved.

If you call getChannelList() with 'FAVORITE' tune navigation mode,

  • All favorites channels will be retreived only if you have added favorites using your remote control.
  • Empty array will be returned if there is no favorites channel on a Tizen device.

The ErrorCallback will be launched in the following situations:

  • NotFoundError - Failed to find the channels

Privilege level: public

Privilege: http://tizen.org/privilege/tv.channel

Parameters:

  • successCallback: The method to invoke when a list of tv channels is retrieved successfully.
  • errorCallback [optional] [nullable]: The method to invoke when an error occurs.
  • mode [optional] [nullable]: The channel navigation mode. By default, this attribute is set to ALL.
  • nStart [optional] [nullable]: The starting index. By default, this attribute is set to 0.
    If nStart is a negative number, InvalidValuesError will occur.
  • number [optional] [nullable]: The number of the channel informations to retrieve. Without number, all vailable channel informations will be retrieved.
    If number is a negative number, InvalidValuesError will occur.

Exceptions:

  • WebAPIException
    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type TypeMismatchError, if any input attribute is not compatible with the expected type for this attribute.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if this feature is not supported.

Code example:

 function successCB(channels) {
     console.log("getChannelList() is successfully done. Totally " + channels.length + " channels are retrieved.");
     for (var i = 0; i < channels.length; i++) {
         console.log("----- Channel [" + i + "] -----");
         console.log("Major channel = " + channels[i].major);
         console.log("Minor channel = " + channels[i].minor);
         console.log("Channel Name = " + channels[i].channelName);
         console.log("Program Number = " + channels[i].programNumber);
         // you can get other attributes provided in ChannelInfo
     }
 }

 try {
     // gets 10 channel information among all channels
     tizen.tvchannel.getChannelList(successCB, null, "ALL", 0, 10);
 } catch (error) {
     console.log("Error name = "+ error.name + ", Error message = " + error.message);
 }
 

Code example:

 function successCB(channels) {
     console.log("getChannelList() is successfully done. Totally " + channels.length + " channels are retrieved.");
     for (var i = 0; i < channels.length; i++) {
         console.log("----- Channel [" + i + "] -----");
         console.log("Major channel = " + channels[i].major);
         console.log("Minor channel = " + channels[i].minor);
         console.log("Channel Name = " + channels[i].channelName);
         console.log("Program Number = " + channels[i].programNumber);
         // you can get other attributes provided in ChannelInfo
     }
 }

 try {
     // gets one digital channel.
     tizen.tvchannel.getChannelList(successCB, null, "DIGITAL", 0, 1);
 } catch (error) {
     console.log("Error name = "+ error.name + ", Error message = " + error.message);
 }
 
getCurrentChannel
Gets information about the current channel.
ChannelInfo getCurrentChannel(optional WindowType? type);
             

Since: 2.3

Privilege level: public

Privilege: http://tizen.org/privilege/tv.channel

Parameters:

  • type [optional] [nullable]: The window type. By default, this attribute is set to MAIN.

Return value:

ChannelInfo the current channel information

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input attribute is not compatible with the expected type for this attribute.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if this feature is not supported.

Code example:

 try {
     var channel = tizen.tvchannel.getCurrentChannel();
     console.log("The current channel name is "  + channel.channelName);
     console.log("The current channel's major number is "  + channel.major);
 } catch (error) {
     console.log("Error name = "+ error.name + ", Error message = " + error.message);
 }
 
getProgramList
Gets a list of programs for a specific channel within a specified time duration. If this method is invoked without the duration parameter, all available program informations are retrieved.
void getProgramList(ChannelInfo channelInfo, TZDate startTime, ProgramListSuccessCallback successCallback, optional ErrorCallback? errorCallback, optional unsigned long? duration);
             

Since: 2.3

The ErrorCallback will be launched in the following situations:

  • NotFoundError - Failed to retrieve any information about the TV program

Privilege level: public

Privilege: http://tizen.org/privilege/tv.channel

Remark : If a specified channel has never been tuned before, you cannot get a information about the programs. It will retrieve be empty array through ProgramListSuccessCallback.

Parameters:

  • channelInfo: The channel
  • startTime: The starting time to search programs.
  • successCallback: The method to invoke when a list of programs is retrieved successfully.
  • errorCallback [optional] [nullable]: The method to invoke when an error occurs.
  • duration [optional] [nullable]: The duration to search programs.(unit: hour) Without duration value, all available program informations are retrieved.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input attribute is not compatible with the expected type for this attribute.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if this feature is not supported.

Code example:

 function programListCB(programInfos) {
     console.log("getting all available programs is successfully retrieved.");
     for (var i = 0; i < programInfos.length; i++) {
         console.log("--------------- Program " + i + " ---------------");
         console.log("title = " + programInfos[i].title);
         console.log("duration = " + programInfos[i].duration);
         // you can get other attributes in the retrieved ProgramInfo objects.
     }
 }

 try {
     var channel = tizen.tvchannel.getCurrentChannel();
     // Get all available program information
     tizen.tvchannel.getProgramList(channel, tizen.time.getCurrentDateTime(), programListCB);
 } catch (error) {
     console.log(error.name);
 }
 
getCurrentProgram
Gets information about the current television program.
ProgramInfo? getCurrentProgram(optional WindowType? type);
             

Since: 2.3

If there is no TV program data grabbed from broadcaster, it will return null.

Privilege level: public

Privilege: http://tizen.org/privilege/tv.channel

Parameters:

  • type [optional] [nullable]: The window type. By default, this attribute is set to MAIN.

Return value:

ProgramInfo the information of television program

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input attribute is not compatible with the expected type for this attribute.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if this feature is not supported.

Code example:

 try {
     var program = tizen.tvchannel.getCurrentProgram();
     console.log("The current program is titled "  + program.title);
 } catch (error) {
     console.log("Error name = "+ error.name + ", Error message = " + error.message);
 }
 
addChannelChangeListener
Adds a channel change listener for getting notified about the channel changes.
long addChannelChangeListener(ChannelChangeCallback callback, optional WindowType? type);
             

Since: 2.3

Privilege level: public

Privilege: http://tizen.org/privilege/tv.channel

Parameters:

  • callback: The method to invoke when the channel has been changed
  • type [optional] [nullable]: The window type. By default, this attribute is set to MAIN.

Return value:

long The identifier to clear the watch subscription for channel changes.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input attribute is not compatible with the expected type for this attribute.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError, if it fails to create a listener or subscribe to a signal when channel changes.

Code example:

 function channelChangeCB(channelInfo, type) {
     console.log("Switched to the new channel (major = " + channelInfo.major + ", minor = " + channelInfo.minor + ", channel name = " + channelInfo.channelName);
 }

 try {
     var channelListenerID = tizen.tvchannel.addChannelChangeListener(channelChangeCB);
 } catch (error) {
     console.log("Error name = "+ error.name + ", Error message = " + error.message);
 }
 
removeChannelChangeListener
Removes the listener to stop receiving notifications for the channel changes.
void removeChannelChangeListener(long channelListenerId);
             

Since: 2.3

Privilege level: public

Privilege: http://tizen.org/privilege/tv.channel

Parameters:

  • channelListenerId: The identifier of the listener for channel changes

Exceptions:

  • WebAPIException
    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError in any other error case.

addSignalStateChangeListener
Adds a signal state change listener for getting notified about signal state changes.
long addSignalStateChangeListener(SignalStateChangeCallback callback);
             

Since: 2.4

Privilege level: public

Privilege: http://tizen.org/privilege/tv.channel

Parameters:

  • callback: The method to invoke when the signal state has been changed

Return value:

long The identifier to clear the watch subscription for signal state changes.

Exceptions:

  • WebAPIException
    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type TypeMismatchError, if any input attribute is not compatible with the expected type for this attribute.

    • with error type UnknownError, if it fails to create a listener or subscribe to a signal when channel changes.

Code example:

 function signalStateChangeCB(state) {
     console.log("Signal state changed to: " + state);
 }

 try {
     var signalStateChangeListenerID = tizen.tvchannel.addSignalStateChangeListener(signalStateChangeCB);
 } catch (error) {
     console.log("Error name = "+ error.name + ", Error message = " + error.message);
 }
 
removeSignalStateChangeListener
Removes the listener to stop receiving notifications about signal state changes.
void removeSignalStateChangeListener(long signalListenerId);
             

Since: 2.4

Privilege level: public

Privilege: http://tizen.org/privilege/tv.channel

Parameters:

  • signalListenerId: The identifier of the listener for signal state changes

Exceptions:

  • WebAPIException
    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError in any other error case.

getFavorites
Gets a list of available favorite lists.
FavoriteList[] getFavorites();
             

Since: 2.4

The returned array will contain at least one FavoriteList. It will also contain any empty favorite lists.

Privilege level: public

Privilege: http://tizen.org/privilege/tv.channel

Return value:

FavoriteList[] The array of favorite lists.

Exceptions:

  • WebAPIException
    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError in any other error case.

Code example:

 try {
     var favorites = tizen.tvchannel.getFavorites();
     for (var i = 0; i < favorites.length; ++i) {
         console.log("Favorite id: " + favorites[i].id);
     }
 } catch (error) {
     console.log("Error name = "+ error.name + ", Error message = " + error.message);
 }
 
getBroadcastStandard
Gets the video broadcast standard.
BroadcastStandard getBroadcastStandard(optional WindowType? type);
             

Since: 2.4

Privilege level: public

Privilege: http://tizen.org/privilege/tv.channel

Parameters:

  • type [optional] [nullable]: The window type. By default, this attribute is set to MAIN.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input attribute is not compatible with the expected type for this attribute.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError if any other error occurs.

Code example:

 var res = tizen.tvchannel.getBroadcastStandard();
 console.log("Video standard: " + res);
 

2.3. ProgramListSuccessCallback

This interface invokes the success callback that is invoked when the list of TV program informations is successfully retrieved.
    [Callback = FunctionOnly, NoInterfaceObject] interface ProgramListSuccessCallback {
        void onsuccess(ProgramInfo[] programInfos);
    };

Since: 2.3

Methods

onsuccess
The method invoked when the list of TV program informations is retrieved.
void onsuccess(ProgramInfo[] programInfos);
             

Since: 2.3

Parameters:

  • programInfos: A list of TV program informations of a channel

2.4. FindChannelSuccessCallback

The interface invokes the success callback that is invoked when all available channels are searched.
    [Callback = FunctionOnly, NoInterfaceObject] interface FindChannelSuccessCallback {
        void onsuccess(ChannelInfo[] channelInfos);
    };

Since: 2.3

Methods

onsuccess
Method invoked when all channels are found.
void onsuccess(ChannelInfo[] channelInfos);
             

Since: 2.3

Parameters:

  • channelInfos: A list of channel Informations

2.5. ChannelChangeCallback

The interface defines a channel change callback for getting notified information about the channel changes.
    [Callback = FunctionOnly, NoInterfaceObject] interface ChannelChangeCallback {
        void onchanged(ChannelInfo channelInfo, WindowType type);
    };

Since: 2.3

Methods

onchanged
Method invoked when the channel has been changed.
void onchanged(ChannelInfo channelInfo, WindowType type);
             

Since: 2.3

Parameters:

  • channelInfo: The switched channel information
  • type: The window type

2.6. SignalStateChangeCallback

The interface defines a signal state change callback for getting notified information about signal state changes.
    [Callback = FunctionOnly, NoInterfaceObject] interface SignalStateChangeCallback {
        void onchanged(SignalState state);
    };

Since: 2.4

Methods

onchanged
Method invoked when the signal state has been changed.
void onchanged(SignalState state);
             

Since: 2.4

Parameters:

  • state: The changed signal state.

2.7. TuneCallback

This interface invokes the callback that is invoked when the tuning has been completed.
    [Callback, NoInterfaceObject] interface TuneCallback {
        void onsuccess(ChannelInfo channel, WindowType type);

        void onnosignal();

        void onprograminforeceived(ProgramInfo program, WindowType type);
    };

Since: 2.3

This callback interface specifies two methods:

  • onsuccess() - Invoked when the tuning operation has been successfully done and there is a TV signal.
  • onnosignal() - Invoked when the tuning operation has been successfully done but there is no signal on the switched channel.
  • onprograminforeceived() - Invoked when information about the current program is available after the tune operation.

All these callback methods can be invoked by tizen.tvchannel.tune(), tuneUp() or tuneDown().

If there is a TV signal, onsuccess() will be invoked first, and then onprograminforeceived() will be invoked if information about TV program exists. But on the other hand, if there is no TV signal, onnosignal() will be invoked.

Methods

onsuccess
Method invoked when the tuning is successfully done.
void onsuccess(ChannelInfo channel, WindowType type);
             

Since: 2.3

Parameters:

  • channel: The tuned channel information
  • type: The window type
onnosignal
Method invoked when the tuning is successfully done but there is no signal on the switched channel.
void onnosignal();
             

Since: 2.3

onprograminforeceived
Method invoked when information about the current program is available after the tune operation
void onprograminforeceived(ProgramInfo program, WindowType type);
             

Since: 2.3

If there is no TV program data grabbed from broadcaster, onprograminreceived won't be invoked.

Parameters:

  • program: the information about program on offer from The tuned channel
  • type: The window type

2.8. TuneOption

This dictionary specifies the tunning option.
    dictionary TuneOption {
        long? major;

        long? minor;

        long? sourceID;

        long? programNumber;

        long? transportStreamID;

        long? ptc;

        long? originalNetworkID;

        DOMString? providerMBR;
    };

Since: 2.3

Dictionary members

long? major
The major channel number
The first number in a two-part number used to identify a virtual channel. Each virtual channel carries one service, such as a television program.

Since: 2.3

long? minor
The minor channel number
The second number in a two-part number used to identify a virtual channel. The minor number changes for each different service that is or will be present in a DTV transport stream.

Since: 2.3

long? sourceID
Source ID

It is a number that uniquely identifies a source of scheduled programming.

Since: 2.3

long? programNumber
Program number

Since: 2.3

long? transportStreamID
TSID (Transport Stream ID or transmission signal ID)

Since: 2.3

long? ptc
PTC(Physical Transmission Channel) number

Since: 2.3

long? originalNetworkID
Original network ID

Since: 2.3

DOMString? providerMBR
The set-top box provider name for a multi-brand remote control

Since: 3.0

Remark : providerMBR is only supported by the tune() method.

2.9. ChannelInfo

This interface represents the object for identifying a TV channel.
    [NoInterfaceObject] interface ChannelInfo {
        readonly attribute long major;

        readonly attribute long minor;

        readonly attribute DOMString channelName;

        readonly attribute long programNumber;

        readonly attribute long ptc;

        readonly attribute long lcn;

        readonly attribute long sourceID;

        readonly attribute long transportStreamID;

        readonly attribute long originalNetworkID;

        readonly attribute DOMString serviceName;
    };

Since: 2.3

Attributes

  • readonly long major
    The major channel number
    The first number in a two-part number used to identify a virtual channel. Each virtual channel carries one service, such as a television program.

    Since: 2.3

  • readonly long minor
    The minor channel number
    The second number in a two-part number used to identify a virtual channel. The minor number changes for each different service that is or will be present in a DTV transport stream.

    Since: 2.3

  • readonly DOMString channelName
    Channel Name to represent the station's indentity

    Since: 2.3

  • readonly long programNumber
    Program number

    Since: 2.3

  • readonly long ptc
    PTC(Physical Transmission Channel) number

    Since: 2.3

  • readonly long lcn
    The logical channel number
    It is used in DVB(Digital Video Broadcasting) standards for digital television.

    Since: 2.3

  • readonly long sourceID
    source ID

    It is a number that uniquely identifies a source of scheduled programming.

    Since: 2.3

  • readonly long transportStreamID
    TSID (Transport Stream ID or transmission signal ID)

    Since: 2.3

  • readonly long originalNetworkID
    Original Network ID

    Since: 2.3

  • readonly DOMString serviceName
    Service Name

    Since: 2.3

2.10. ProgramInfo

This interface represents information about the television program.
    [NoInterfaceObject] interface ProgramInfo {
        readonly attribute DOMString title;

        readonly attribute TZDate startTime;

        readonly attribute long duration;

        readonly attribute DOMString? detailedDescription;

        readonly attribute DOMString? language;

        readonly attribute DOMString? rating;
    };

Since: 2.3

Attributes

  • readonly DOMString title
    The program title

    Since: 2.3

  • readonly TZDate startTime
    The program start time

    Since: 2.3

  • readonly long duration
    The duration of the program

    Since: 2.3

  • readonly DOMString detailedDescription [nullable]
    A detailed description of the program's content.

    Since: 2.3

  • readonly DOMString language [nullable]
    Language information

    Since: 2.3

  • readonly DOMString rating [nullable]
    Rating information

    Since: 2.3

2.11. FavoriteList

This interface represents a favorite list.
    [NoInterfaceObject] interface FavoriteList {
        readonly attribute long id;

        void addChannel(ChannelInfo channel, SuccessCallback successCallback,
                  optional ErrorCallback? errorCallback) raises(WebAPIException);


        void removeChannel(ChannelInfo channel, SuccessCallback successCallback,
                  optional ErrorCallback? errorCallback) raises(WebAPIException);

        void getChannels(FindChannelSuccessCallback successCallback,
                            optional ErrorCallback? errorCallback,
                            optional long? nStart,
                            optional long? number) raises(WebAPIException);
    };

Since: 2.4

Attributes

  • readonly long id
    The ID of favorite list.

    Since: 2.4

Methods

addChannel
Adds a channel to a specific favorite list.
void addChannel(ChannelInfo channel, SuccessCallback successCallback, optional ErrorCallback? errorCallback);
             

Since: 2.4

If the channel already exists in a list, this operation has no effect. A channel can be added to multiple favorite lists.

The ErrorCallback will be launched in the following situations:

  • UnknownError - In case of unknown error

Privilege level: public

Privilege: http://tizen.org/privilege/tv.channel

Parameters:

  • channel: The channel to add.
  • successCallback: The method to invoke when the channel is added successfully.
  • errorCallback [optional] [nullable]: The method to invoke when an error occurs.

Exceptions:

  • WebAPIException
    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type TypeMismatchError, if any input attribute is not compatible with the expected type for this attribute.

    • with error type UnknownError in case of unknown error

Code example:

 try {
     var favorites = tizen.tvchannel.getFavorites();
     var channel = tizen.tvchannel.getCurrentChannel();
     favorites[0].addChannel(channel, function() {
         console.log("Channel added");
     }, function(error) {
         console.log("Error callback: name = "+ error.name + ", Error message = " + error.message);
     });
 } catch (error) {
     console.log("Error name = "+ error.name + ", Error message = " + error.message);
 }
 
removeChannel
Removes a channel from a specific favorite list.
void removeChannel(ChannelInfo channel, SuccessCallback successCallback, optional ErrorCallback? errorCallback);
             

Since: 2.4

If the channel is not in a favorite list, the operation completes without any error.

The ErrorCallback will be launched in the following situations:

  • UnknownError - In case of unknown error

Privilege level: public

Privilege: http://tizen.org/privilege/tv.channel

Parameters:

  • channel: The channel to remove.
  • successCallback: The method to invoke when the channel is removed successfully.
  • errorCallback [optional] [nullable]: The method to invoke when an error occurs.

Exceptions:

  • WebAPIException
    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type TypeMismatchError, if any input attribute is not compatible with the expected type for this attribute.

    • with error type UnknownError in case of unknown error

Code example:

 try {
     var favorites = tizen.tvchannel.getFavorites();
     var channel = tizen.tvchannel.getCurrentChannel();
     favorites[0].removeChannel(channel, function() {
         console.log("Channel removed");
     }, function(error) {
         console.log("Error callback: name = "+ error.name + ", Error message = " + error.message);
     });
 } catch (error) {
     console.log("Error name = "+ error.name + ", Error message = " + error.message);
 }
 
getChannels
Gets the list of TV channels in a specific favorite list.
void getChannels(FindChannelSuccessCallback successCallback, optional ErrorCallback? errorCallback, optional long? nStart, optional long? number);
             

Since: 2.4

If this method is called without specifying the number parameter, all channels from the given favorite list will be retrieved.

The ErrorCallback will be launched in the following situations:

  • UnknownError - In case of unknown error

Privilege level: public

Privilege: http://tizen.org/privilege/tv.channel

Parameters:

  • successCallback: The method to invoke when a list of TV channels is retrieved successfully.
  • errorCallback [optional] [nullable]: The method to invoke when an error occurs.
  • nStart [optional] [nullable]: The starting index. By default, this attribute is set to 0.
    If nStart is a negative number, the InvalidValuesError exception will occur
  • number [optional] [nullable]: The number of channels to retrieve. Without number, all channels in the favorite list will be retrieved..
    A negative nStart will cause InvalidValuesError.

Exceptions:

  • WebAPIException
    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type TypeMismatchError, if any input attribute is not compatible with the expected type for this attribute.

Code example:

 function successCB(channels) {
     console.log("Totally " + channels.length + " channels are retrieved.");
     for (var i = 0; i < channels.length; i++) {
         console.log("----- Channel [" + i + "] -----");
         console.log("Major channel = " + channels[i].major);
         console.log("Minor channel = " + channels[i].minor);
         console.log("Channel Name = " + channels[i].channelName);
         console.log("Program Number = " + channels[i].programNumber);
         // you can get other attributes provided in ChannelInfo
     }
 }

 try {
     var favorites = tizen.tvchannel.getFavorites();
     // gets channel information for 10 channels
     favorites[0].getChannels(successCB, null, 0, 10);
 } catch (error) {
     console.log("Error name = "+ error.name + ", Error message = " + error.message);
 }
 

3. Related Feature

You can check if this API is supported with tizen.systeminfo.getCapability() and decide enable/disable codes that need this API.

To guarantee the running of this application on a device with a tuner, define the following requirements in the config file:

  • http://tizen.org/feature/tv.tuner
  • For more information, see Application Filtering.

    4. Full WebIDL

    module TVChannel {
    
        enum TuneMode {
            "ALL",
            "DIGITAL",
            "ANALOG",
            "FAVORITE"
        };
    
        enum SignalState {
            "SIGNAL_STATE_OK",
            "SIGNAL_STATE_NO_SIGNAL"
        };
    
        enum BroadcastStandard {
            "ATSC",
            "DVB",
            "ISDB",
            "SATELLITE"
        };
    
        [NoInterfaceObject] interface TVChannelManager {
            readonly attribute ChannelManager tvchannel;
        };
        Tizen implements TVChannelManager;
    
        [NoInterfaceObject] interface ChannelManager {
    
            void tune(TuneOption tuneOption,
                      TuneCallback successCallback,
                      optional ErrorCallback? errorCallback,
                      optional WindowType? type) raises(WebAPIException);
    
            void tuneUp(TuneCallback successCallback,
                        optional ErrorCallback? errorCallback,
                        optional TuneMode? tuneMode,
                        optional WindowType? type) raises(WebAPIException);
    
            void tuneDown(TuneCallback successCallback,
                          optional ErrorCallback? errorCallback,
                          optional TuneMode? tuneMode,
                          optional WindowType? type) raises(WebAPIException);
    
            void findChannel(long major,
                             long minor,
                             FindChannelSuccessCallback successCallback,
                             optional ErrorCallback? errorCallback) raises(WebAPIException);
    
            void getChannelList(FindChannelSuccessCallback successCallback,
                                optional ErrorCallback? errorCallback,
                                optional TuneMode? mode,
                                optional long? nStart,
                                optional long? number) raises(WebAPIException);
    
            ChannelInfo getCurrentChannel(optional WindowType? type) raises(WebAPIException);
    
            void getProgramList(ChannelInfo channelInfo,
                                TZDate startTime,
                                ProgramListSuccessCallback successCallback,
                                optional ErrorCallback? errorCallback,
                                optional unsigned long? duration) raises(WebAPIException);
    
            ProgramInfo? getCurrentProgram(optional WindowType? type) raises(WebAPIException);
    
            long addChannelChangeListener(ChannelChangeCallback callback,
                                           optional WindowType? type) raises(WebAPIException);
    
            void removeChannelChangeListener(long channelListenerId) raises(WebAPIException);
    
            long addSignalStateChangeListener(SignalStateChangeCallback callback
                                           ) raises(WebAPIException);
    
            void removeSignalStateChangeListener(long signalListenerId) raises(WebAPIException);
    
            FavoriteList[] getFavorites() raises(WebAPIException);
    
            BroadcastStandard getBroadcastStandard(optional WindowType? type) raises(WebAPIException);
        };
    
        [Callback = FunctionOnly, NoInterfaceObject] interface ProgramListSuccessCallback {
            void onsuccess(ProgramInfo[] programInfos);
        };
    
        [Callback = FunctionOnly, NoInterfaceObject] interface FindChannelSuccessCallback {
            void onsuccess(ChannelInfo[] channelInfos);
        };
    
        [Callback = FunctionOnly, NoInterfaceObject] interface ChannelChangeCallback {
            void onchanged(ChannelInfo channelInfo, WindowType type);
        };
    
        [Callback = FunctionOnly, NoInterfaceObject] interface SignalStateChangeCallback {
            void onchanged(SignalState state);
        };
    
        [Callback, NoInterfaceObject] interface TuneCallback {
            void onsuccess(ChannelInfo channel, WindowType type);
    
            void onnosignal();
    
            void onprograminforeceived(ProgramInfo program, WindowType type);
        };
    
        dictionary TuneOption {
            long? major;
    
            long? minor;
    
            long? sourceID;
    
            long? programNumber;
    
            long? transportStreamID;
    
            long? ptc;
    
            long? originalNetworkID;
    
            DOMString? providerMBR;
        };
    
        [NoInterfaceObject] interface ChannelInfo {
            readonly attribute long major;
    
            readonly attribute long minor;
    
            readonly attribute DOMString channelName;
    
            readonly attribute long programNumber;
    
            readonly attribute long ptc;
    
            readonly attribute long lcn;
    
            readonly attribute long sourceID;
    
            readonly attribute long transportStreamID;
    
            readonly attribute long originalNetworkID;
    
            readonly attribute DOMString serviceName;
        };
    
        [NoInterfaceObject] interface ProgramInfo {
            readonly attribute DOMString title;
    
            readonly attribute TZDate startTime;
    
            readonly attribute long duration;
    
            readonly attribute DOMString? detailedDescription;
    
            readonly attribute DOMString? language;
    
            readonly attribute DOMString? rating;
        };
    
        [NoInterfaceObject] interface FavoriteList {
            readonly attribute long id;
    
            void addChannel(ChannelInfo channel, SuccessCallback successCallback,
                      optional ErrorCallback? errorCallback) raises(WebAPIException);
    
    
            void removeChannel(ChannelInfo channel, SuccessCallback successCallback,
                      optional ErrorCallback? errorCallback) raises(WebAPIException);
    
            void getChannels(FindChannelSuccessCallback successCallback,
                                optional ErrorCallback? errorCallback,
                                optional long? nStart,
                                optional long? number) raises(WebAPIException);
        };
    };