The Channel class

Support in HbbTV

Available since: HbbTV 1.0 (ETSI TS 102 796 V1.1.1, OIPF DAE V1.1)

The following properties shall be supported:

– channelType

– ccid

– dsd

– idType- nid

– onid

– tsid

– sid

– name

– majorChannel

– terminalChannel

All other properties and methods are not included.

See clause 8.2.5 for more details regarding the properties majorChannel and terminalChannel.

Application developers need to be aware of clause A.2.29.1 concerning security.

Comment

Broadcast-related

The following additional property on the Channel class (as defined in OIPF DAE specification [1]) shall be supported.

readonly Number terminalChannel
DescriptionAn integer property which shall be set to the value of the terminal’s Logical Channel Number as used by the terminal’s native UI. This allows for terminals to have different channel values (for example by way of user sorting) from the LCN values provided in SI by the broadcast network.

The property majorChannel (as defined in OIPF DAE specification [1]) from the Channel class shall be supported with the following definition.

readonly Number majorChannel
DescriptionAn integer property that shall be set to the value of the Logical Channel Number as defined by the logical channel information provided by the SI from the broadcast network.

 

The values shall be equal to the final LCN assignments after any sorting performed by the terminal as part of the channel scan only, taking into account other SI descriptors relating to network sorting (such as logical_channel_descriptor, HD_Simulcast_Logical_Channel_descriptor, target_region_descriptor, etc., as defined by the country profile).

 

It shall also be unaffected by any re-assignment of the LCN due to the terminal retaining and re-numbering duplicate services.

Application developers should be aware that some APIs return data that may not be authenticated. In some circumstances an attacker may be able to modify the broadcast signalling from which this data is derived. This particularly applies to the properties and methods of the Channel and Programme classes:

  • Applications should be written to be tolerant of values which are outside the expected range without hanging up, locking up or crashing.
  • Applications should treat the values returned by name, Programme.name, Programme.description and Programme.longDescription with caution as an attacker may modify the broadcast signalling to include HTML or JavaScript as well as values that are outside the expected set. Applications shall not use the data returned by these properties in a way that would result in them being executed by the browser.
  • Applications should treat data returned by the getSIDescriptors method with caution. Applications shall not use this data in a way that would result in that such data being executed by the browser. Applications should be written to be tolerant of values which are outside the expected range without hanging up, locking up or crashing.

The Channel object represents a broadcast stream or service.

Channel objects typically represent channels stored in the channel list (see section 7.13.10). Channel objects may also represent locally defined channels created by an application using the createChannelObject() methods on the video/broadcast embedded object or the ChannelConfig class or the createChannelList() method on the ChannelConfig class. Accessing the channel property of a ScheduledRecording object or Recording object which is scheduled on a locally defined channel SHALL return a Channel object representing that locally defined channel.

Except for the hidden property, writing to the writable properties on a Channel object SHALL have no effect for Channel objects representing channels stored in the channel list. Applications SHOULD only change these writable properties of a locally defined channel before the Channel object is referenced by another object or passed to an API call as an input parameter. The effects of writing to these properties at any other time is implementation dependent.

The Channel class is defined as follows:

Constants

NameValueUse
TYPE_TV0Used in the channelType property to indicate a TV channel.
TYPE_RADIO1Used in the channelType property to indicate a radio channel.
TYPE_OTHER2Used in the channelType property to indicate that the type of the channel is unknown, or known but not of type TV or radio.
TYPE_ALL128Used during channel scanning to indicate that all TV, radio and other channel types should scanned.
TYPE_HBBTV_DATA256Reserved for data services defined by [TS 102 796].
ID_ANALOG0Used in the idType property to indicate an analogue channel identified by the property ‘freq’ and optionally ‘cni’ or ‘name’.
ID_DVB_C10Used in the idType property to indicate a DVB-C channel identified by the three properties: ‘onid’, ‘tsid’, ‘sid’.
ID_DVB_S11Used in the idType property to indicate a DVB-S channel identified by the three properties: ‘onid’, ‘tsid’, ‘sid’.
ID_DVB_T12Used in the idType property to indicate a DVB-T channel identified by the three properties: ‘onid’, ‘tsid’, ‘sid’.
ID_DVB_SI_DIRECT13Used in the idType property to indicate a channel that is identified through its delivery system descriptor as defined by DVB-SI [EN 300 468] section 6.2.13.
ID_DVB_C214Used in the idType property to indicate a DVB-C or DVB-C2 channel identified by the three properties: ‘onid’, ‘tsid’, ‘sid’.
ID_DVB_S215Used in the idType property to indicate a DVB-S or DVB-S2 channel identified by the three properties: ‘onid’, ‘tsid’, ‘sid’.
ID_DVB_T216Used in the idType property to indicate a DVB-T or DVB-T2 channel identified by the three properties: ‘onid’, ‘tsid’, ‘sid’.
ID_ISDB_C20Used in the idType property to indicate an ISDB-C channel identified by the three properties: ‘onid’, ‘tsid’, ‘sid’.
ID_ISDB_S21Used in the idType property to indicate an ISDB-S channel identified by the three properties: ‘onid’, ‘tsid’, ‘sid’.
ID_ISDB_T22Used in the idType property to indicate an ISDB-T channel identified by the three properties: ‘onid’, ‘tsid’, ‘sid’.
ID_ATSC_T30Used in the idType property to indicate a terrestrial ATSC channel identified by the property ‘sourceID’.
ID_IPTV_SDS40Used in the idType property to indicate an IP broadcast channel identified through SD&S by a DVB textual service identifier specified in the format “ServiceName.DomainName” as value for property ‘ipBroadcastID’, with ServiceName and DomainName as defined in [DVB-IPTV]. This idType SHALL be used to indicate Scheduled content service defined by [OIPF_PROT2].
ID_IPTV_URI41Used in the idType property to indicate an IP broadcast channel identified by a DVB MCAST URI (i.e. dvb-mcast://) or by a URI referencing a HAS or MPEG DASH MPD (i.e. http:// or https://), as value for property ipBroadcastID.

Properties

This section defines the properties of the Channel object.

Properties that do not apply in a specific circumstance (e.g. onid does not apply unless the channel is of type ID_DVB_* or ID_ISDB_*) SHALL be undefined. The mapping to these properties is defined in section 8.4.3.

readonly Integer channelType
The type of channel. The value MAY be indicated by one of the TYPE_* constants defined above. If the type of the channel is unknown then the value SHALL be “undefined”. NOTE: Values of this type between 256 and 511 are reserved for use by related specifications on request by liaison.
readonly Integer idType
The type of identification for the channel, as indicated by one of the ID_* constants defined above
readonly String ccid
Unique identifier of a channel within the scope of the OITF. The ccid is defined by the OITF and SHALL have prefix ‘ccid’: e.g. ‘ccid:{tunerID.}majorChannel{.minorChannel}’. Note: the format of this string is platform-dependent.
readonly String tunerID
Optional unique identifier of the tuner within the scope of the OITF that is able to receive the given channel.
readonly Integer onid
DVB or ISDB original network ID.
readonly Integer nid
The DVB or ISDB network ID.
readonly Integer tsid
DVB or ISDB transport stream ID.
readonly Integer sid
DVB or ISDB service ID.
readonly Integer sourceID
ATSC source_ID value.
readonly Integer freq
For analogue channels, the frequency of the video carrier in kHz.
readonly Integer cni
For analogue channels, the VPS/PDC confirmed network identifier.
String name
The name of the channel. Can be used for linking analog channels without CNI. Typically, it will contain the call sign of the station (e.g. ‘HBO’).
readonly Integer majorChannel
The major channel number, if assigned. Value undefined otherwise. Typically used for channels of type ID_ATSC_* or for channels of type ID_DVB_* or ID_IPTV_SDS in markets where logical channel numbers are used.
readonly Integer minorChannel
The minor channel number, if assigned. Value undefined otherwise. Typically used for channels of type ID_ATSC_*.
readonly String dsd
For channels of type ID_DVB_SI_DIRECT created through createChannelObject(), this property defines the delivery system descriptor (tuning parameters) as defined by DVB-SI [EN 300 468] section 6.2.13. The dsd property provides a string whose characters shall be restricted to the ISO Latin-1 character set. Each character in the dsd represents a byte of a delivery system descriptor as defined by DVB-SI [EN 300 468] section 6.2.13, such that a byte at position “i” in the delivery system descriptor is equal the Latin-1 character code of the character at position “i” in the dsd. Described in the syntax of JavaScript: let sdd[] be the byte array of a system delivery descriptor, in which sdd[0] is the descriptor_tag, then, dsd is its equivalent string, if : dsd.length==sdd.length and for each integer i : 0<=i<dsd.length holds: sdd[i] == dsd.charCodeAt(i).
readonly Boolean favourite
Flag indicating whether the channel is marked as a favourite channel or not in one of the favourite lists as defined by the property favIDs.
readonly StringCollection favIDs
The names of the favourite lists to which this channel belongs (see the favouriteLists property on the ChannelConfig class).
readonly Boolean locked
Flag indicating whether the current state of the parental control system prevents the channel from being viewed (e.g. a correct parental control pin has not been entered). Note that this property supports the option of client-based management of parental control without excluding server-side implementation of parental control.
readonly Boolean manualBlock
Flag indicating whether the user has manually blocked viewing of this channel. Manual blocking of a channel will treat the channel as if its parental rating value always exceeded the system threshold. Note that this property supports the option of client-based management of manual blocking without excluding server-side management of blocked channels.
readonly String ipBroadcastID
If the channel has an idType of ID_IPTV_SDS, this property denotes the DVB textual service identifier of the IP broadcast service, specified in the format “ServiceName.DomainName” with the ServiceName and DomainName as defined in [DVB-IPTV]. If the Channel has an idType of ID_IPTV_URI, this element denotes a URI of the IP broadcast service.
readonly Integer channelMaxBitRate
If the channel has an idType of ID_IPTV_SDS, this property denotes the maximum bitrate associated to the channel.
readonly Integer channelTTR
If the channel has idType ID_IPTV_SDS, this property denotes the TimeToRenegotiate associated to the channel.
readonly Boolean recordable
Flag indicating whether the channel is available to the recording functionality of the OITF. If the value of the pvrSupport property on the application/oipfConfiguration object as defined in section 7.3.3.2 is 0, this property SHALL be false for all Channel objects.

Metadata extensions to Channel

This subsections SHALL apply for OITFs that have indicated <clientMetadata> with value “true” and a type attribute with values “bcg”, “sd-s”, “eit-pf” or “dvb-si” as defined in section 9.3.7 in their capability profile.

The OITF SHALL extend the Channel class with the properties and methods described below.

The values of many of these properties may be derived from elements in the BCG metadata. For optional elements that are not present in the metadata, the default value of any property that derives its value from one of those elements SHALL be undefined.

Properties
String longName
The long name of the channel. If both short and long names are being transmitted, this property SHALL contain the long name of the station (e.g. ‘Home Box Office’). If the long name is not available, this property SHALL be undefined. The value of this property may be derived from the Name element that is a child of the BCG ServiceInformation element describing the channel, where the length attribute of the Name element has the value ‘long’.
String description
The description of the channel. If no description is available, this property SHALL be undefined. The value of this field may be taken from the ServiceDescription element that is a child of the BCG ServiceInformation element describing this channel.
readonly Boolean authorised
Flag indicating whether the receiver is currently authorised to view the channel. This describes the conditional access restrictions that may be imposed on the channel, rather than parental control restrictions.
StringCollection genre
A collection of genres that describe the channel. The value of this field may be taken from the ServiceGenre elements that are children of the BCG ServiceInformation element describing the channel.
Boolean hidden
Flag indicating whether the channel SHALL be included in the default channel list.
readonly Boolean is3D
Flag indicating whether the channel is a 3D channel.
readonly Boolean isHD
Flag indicating whether the channel is an HD channel.
string logoURL
The URL for the default logo image for this channel. The value of this field may be derived from the value of the first Logo element that is a child of the BCG ServiceInformation element describing the channel. If this element specifies anything other than the URL of an image, the value of this filed SHALL be undefined.
Methods

String getField( String fieldId )

Description

Get the value of the field referred to by fieldId that is contained in the BCG metadata for this channel. If the field does not exist, this method SHALL return undefined.

Arguments

fieldId

The name of the field whose value SHALL be retrieved.

String getLogo( Integer width, Integer height )

Description

Get the URI for the logo image for this channel. The width and height parameters specify the desired width and height of the image; if an image of that size is not available, the URI of the logo with the closest available size not exceeding the specified dimensions SHALL be returned. If no image matches these criteria, this method SHALL return null.

The URI returned SHALL be suitable for use as the SRC attribute in an HTML IMG element or as a background image.

The URIs returned by this method will be derived from the values of the Logo elements that are children of the BCG ServiceInformation element describing the channel.

Arguments

width

The desired width of the image

height

The desired height of the image