The ChannelConfig class
Support in HbbTV
Available since: HbbTV 1.0 (ETSI TS 102 796 V1.1.1, OIPF DAE V1.1)
The channelList property shall be supported. Other properties, methods and events are not included.
Comment
Broadcast-related
The ChannelConfig class provides the entry point for applications to get information about the list of channels available. It can be obtained in two ways:
- By calling the method getChannelConfig() of the video/broadcast embedded object as defined in section 7.13.1.3.
- By calling the method createChannelConfig() of the object factory API as defined in section 1.1.
The availability of the properties and methods are dependent on the capabilities description as specified in section 9.3. The following table provides a list of the capabilities and the associated properties and methods. If the capability is false the properties and methods SHALL NOT be available to the application. Properties and methods not listed in the following table SHALL be available to all applications as long as the OITF has indicated support for tuner control (i.e. <video_broadcast>true</video_broadcast> as defined in section 9.3.1) in their capability.
| Capability | Properties | Methods |
| Element <extendedAVControl> is set to “true” as defined in section 9.3.6. | onChannelScan | startScan() stopScan() |
| Element <video_broadcast type=”ID_IPTV_SDS”> is set as defined in section 9.3.6. | createChannelList() |
The functionality as described in this section is subject to the security model of section 10.1.3.1.1 (for obtaining a ChannelConfig object) and section 10.1.3.8 (for properties and methods covered by the <extendedAVControl> capability as defined below).
Properties
| readonly ChannelList channelList |
| The list of channels. If an OITF includes a platform-specific application that enables the end-user to choose a channel to be presented from a list then all the channels in the list offered to the user by that application SHALL be included in this ChannelList. The list of channels will be a subset of all those available to the OITF. The precise algorithm by which this subset is selected will be market and/or implementation dependent. For example; · If an OITF with a DVB-T tuner receives multiple versions of the same channel, one would be included in the list and the duplicates discarded · An OITF with a DVB tuner will often filter services based on service type to discard those which are obviously inappropriate or impossible for that device to present to the end-user, e.g. firmware download services. The order of the channels in the list corresponds to the channel ordering as managed by the OITF. SHALL return the value null if the channel list is not (partially) managed by the OITF (i.e., if the channel list information is managed entirely in the network). The properties of channels making up the channel list SHALL be set by the OITF to the appropriate values as determined by the tables in section 8.4.3. The OITF SHALL store all these values as part of the channel list. Some values are set according to the data carried in the broadcast stream. In this case, the OITF MAY set these values to undefined until such time as the relevant data has been received by the OITF, for example after tuning to the channel. Once the data has been received, the OITF SHALL update the properties of the channel in the channel list according to the received data. Note: There is no requirement for the OITF to pro-actively tune to every channel to gather such data. |
| readonly FavouriteListCollection favouriteLists |
| A list of favourite lists. SHALL return the value null if the favourite lists are not (partially) managed by the OITF (i.e., if the favourite lists information is managed entirely in the network). |
| readonly FavouriteList currentFavouriteList |
| Currently active Favourite channel list object. If currentFavouriteList is undefined, no favourite filter list is currently applied. The OITF SHALL return the value null if the favourite lists are not (partially) managed by the OITF (i.e. if the favourite lists information is managed entirely in the network). |
| function onChannelListUpdate() |
| This function is the DOM 0 event handler for events relating to channel list updates. Upon receiving a ChannelListUpdate event, if an application has references to any Channel objects then it SHOULD dispose of them and rebuild its references. Where possible Channel objects are updated rather than removed, but their order in the ChannelConfig.all collection MAY have changed. Any lists created with ChannelConfig.createFilteredList() SHOULD be recreated in case channels have been removed. |
| readonly Channel currentChannel |
| The current channel of the OITF if the user has given permission to share this information, possibly through a mechanism outside the scope of this specification. If no channel is being presented, or if this information is not visible to the caller, the value of this property SHALL be null. In an OITF where exactly one video/broadcast object is in any state other than Unrealized and the channel being presented by that video/broadcast object is the only broadcast channel being presented by the OITF then changes to the channel presented by that video/broadcast object SHALL result in changes to the current channel of the OITF. In an OITF which is presenting more than one broadcast channel at the same time, the current channel of the OITF is the channel whose audio is being presented (as defined in the bindToCurrentChannel() method). If that current channel is under the control of a DAE application via a video/broadcast object then changes to the channel presented by that video/broadcast object SHALL result in changes to the current channel of the OITF. |
Methods
| ChannelList createFilteredList( Boolean blocked, Boolean favourite, | ||||||||||
Description | Create a filtered list of channels. Returns a subset of ChannelConfig.channelList. The blocked, favourite and hidden flags indicate whether a channel is included in the returned list. These flags correspond to the properties on Channel with the same names. Each flag MAY be set to one of three values:
A channel will only be added to the list if the values of all three flags allow it to be added. The favouriteListID attribute is used to select a particular favouriteList that the createFilteredList method uses as a basis of the filtering process. If favouriteListID is the empty string (i.e. “”), then the filtering is performed on all available channels as defined by ChannelConfig.channelList. | |||||||||
Arguments | blocked | Flag indicating whether manually blocked channels SHALL be added to the list. | ||||||||
favourite | Flag indicating whether favourite channels SHALL be added to the list. | |||||||||
hidden | Flag indicating whether hidden channels SHALL be added to the list. | |||||||||
favouriteListID | If the value of the favourite flag is true, indicates which favourites list SHALL be filtered upon. | |||||||||
| void startScan( ChannelScanOptions options, ChannelScanParameters scanParameters ) | ||
Description | Start a scan for new channels on all available sources. When each source finishes scanning, an UpdateEvent SHALL be raised with the type CHANNELS_INVALIDATED and any channel lists for that source SHALL have been updated. On IP-only receivers, this method SHALL have no effect. | |
Arguments | options | The options to the channel scan operation. |
scanParameters | The tuning parameters to be scanned. The value of this argument SHALL be one of the classes that implement the ChannelScanParameters interface and SHALL NOT be an instance of the ChannelScanParameters class. | |
| void stopScan() | |
Description | Stop a channel scan, if one is in progress. Any sources that have not finished scanning SHALL have their scans aborted and channel line-ups for SHALL NOT be changed. On IP-only receivers, this method SHALL have no effect. |
| ChannelList createChannelList( String bdr ) | ||
Description | Creates a ChannelList object from the specified SD&S Broadcast Discovery Record. Channels in the returned channel list will not be included in the channel list that can be retrieved via calls to getChannelConfig(). | |
Arguments | bdr | An XML-encoded string containing an SD&S Broadcast Discovery Record as specified in [OIPF_META2]. If the string is not a valid Broadcast Discovery Record, this method SHALL return null. |
| Channel createChannelObject( Integer idType, Integer onid, Integer tsid, | ||
Description | Creates a Channel object of the specified idType. The Channel object can subsequently be used by the setChannel method to switch a tuner to a channel that is not part of the channel list which was conveyed by the OITF to the server. The scope of the resulting Channel object is limited to the JavaScript environment (incl. video/broadcast object) to which the Channel object is returned, i.e. it does not get added to the channellist available through method getChannelConfig. If the channel of the given idType cannot be created or the given (combination of) arguments are not considered valid or complete, the method SHALL return null. If the channel of the given type can be created and arguments are considered valid and complete, the method SHALL return a Channel object whereby at a minimum the properties with the same names are given the same value as the given arguments of the createChannelObject method. The values specified for the remaining properties of the Channel object are set to undefined. | |
Arguments | idType | The type of channel, as indicated by one of the ID_* constants defined in section 7.13.11.1. |
onid | The original network ID. Optional argument that SHALL be specified when the idType specifies a channel of type ID_DVB_* or ID_ISDB_*. | |
tsid | The transport stream ID. Optional argument that MAY be specified when the idType specifies a channel of type ID_DVB_* or ID_ISDB_*. | |
sid | The service ID. Optional argument that SHALL be specified when the idType specifies a channel of type ID_DVB_* or ID_ISDB_*. | |
sourceID | The source_ID. Optional argument that SHALL be specified when the idType specifies a channel of type ID_ATSC_T. | |
ipBroadcastID | The DVB textual service identifier of the IP broadcast service, specified in the format “ServiceName.DomainName”, or the URI of the IP broadcast service. Optional argument that SHALL be specified when the idType specifies a channel of type ID_IPTV_SDS or ID_IPTV_URI. | |
| ChannelScanParameters createChannelScanParametersObject( Integer idType ) | ||
Description | Create an instance of one of the subclasses of the ChannelScanParameters class (or one of its subclasses). The exact subclass that will be returned SHALL be determined by the value of the idType parameter. Initial values of all properties on the returned object SHALL be undefined. | |
Arguments | idType | The type of object to be created. Valid values are given by the following constants on the Channel class (see section 7.13.11.1): · ID_DVB_T or ID_DVB_T2 – returns an instance of the DVBTChannelScanParameters class. · ID_DVB_C or ID_DVB_C2 – returns an instance of the DVBCChannelScanParameters class. · ID_DVB_S or ID_DVB_S2 – returns an instance of the DVBSChannelScanParameters class. · ID_ATSC_T – returns an instance of the ATSCTChannelScanParameters class. All other values, or channel types which are not supported by the OITF, SHALL cause this method to return null. |
| ChannelScanOptions createChannelScanOptionsObject() | |
Description | Create an instance of the ChannelScanOptions class. Initial values of all properties on the returned object SHALL be undefined. |
Events
For the intrinsic events listed in the table below, a corresponding DOM event SHALL be generated, in the following manner:
| Intrinsic event | Corresponding DOM event | DOM Event properties |
| onChannelScan | ChannelScan | Bubbles: No Cancellable: No Context Info: scanEvent, progress, frequency, signalStrength, channelNumber, channelType, channelCount, transponderCount, newChannel |
| onChannelListUpdate | ChannelListUpdate | Bubbles: No Cancellable: No Context Info: None |
Note: the above DOM event is directly dispatched to the event target, and will not bubble nor capture. Applications SHOULD NOT rely on receiving these events during the bubbling or the capturing phase. Applications that use DOM event handlers SHALL call the addEventListener() method on the ChannelConfig object itself. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.