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.

CapabilityPropertiesMethods
Element <extendedAVControl> is set to “true” as defined in section 9.3.6.onChannelScanstartScan() 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 onChannelScan( Integer scanEvent, Integer progress, Integer frequency,
Integer signalStrength, Integer channelNumber, Integer channelType,
Integer channelCount, Integer transponderCount, Channel newChannel)

This function is the DOM 0 event handler for events relating to channel scanning. On IP-only receivers, setting this property SHALL have no effect.

The specified function is called with the following arguments:

· Integer scanEvent – The type of event. Valid values are:

Value

Description

0

A channel scan has started.

1

Indicates the current progress of the scan.

2

A new channel has been found.

3

A new transponder has been found.

4

A channel scan has completed.

5

A channel scan has been aborted.

· Integer progress – the progress of the scan. Valid values are in the range 0 – 100, or -1 if the progress is unknown.

· Integer frequency – The frequency of the transponder in kHz (for scans on RF sources only).

· Integer signalStrength – The signal strength for the current channel. Valid values are in the range 0 – 100, or -1 if the signal strength is unknown.

· Integer channelNumber – The logical channel number of the channel that has been found.

· Integer channelType – The type of channel that has been found. Valid values are the same as for Channel.channelType.

· Integer channelCount – The total number of channels found so far during the scan.

· Integer transponderCount – The total number of transponders found so far during the scan (RF sources only).

· Channel newChannel – When scanEvent equals 2, this argument provides a reference to the Channel object that represents the newly identified channel. For other scanEvent values this argument SHALL be NULL

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,
Boolean hidden, String favouriteListID )

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:

Value

Meaning

true

The channel is added if and only if the corresponding property has the value true.

false

The channel is added if and only if the corresponding property has the value false.

undefined

The channel is added regardless of the state of the corresponding property.

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,
Integer sid, Integer sourceID, String ipBroadcastID )

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 eventCorresponding DOM eventDOM Event properties
onChannelScanChannelScanBubbles: No Cancellable: No Context Info: scanEvent, progress, frequency, signalStrength, channelNumber, channelType, channelCount, transponderCount, newChannel
onChannelListUpdateChannelListUpdateBubbles: 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.