The Configuration class

Support in HbbTV

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

Support for read-only access to the following properties is mandatory:

– preferredAudioLanguage

– preferredSubtitleLanguage

– preferredUILanguage

– countryId

The extensions to the Configuration class defined in clause A.2.20 shall be supported.

All other properties and methods are not included.

Comment

This class shall be extended with the following additional property.

readonly Boolean subtitlesEnabled
Shall be set to false if subtitles are disabled by the terminal. When set to false, subtitle components that are selected using a video/broadcast object, A/V control object or HTML5 media element will not be presented. See also clause 10.2.7.

The following property is added to the Configuration class.

readonly Boolean timeShiftSynchronized
Returns a boolean indicating if the terminal is capable of maintaining synchronization between applications and A/V components during time-shift. A definition of synchronization between applications and A/V components can be found in clause 6.2.2.4.

This class shall be extended with the following additional property.

readonly Boolean audioDescriptionEnabled
Shall be set to false if audio description is disabled by the terminal, otherwise shall be set to true. If set to false, applications should not enable audio description using the component selection API of the supported media objects i.e. A/V Control object, video/broadcast object and HTML5 media elements.

This class shall be extended with the following additional property:

readonly Number dtt_network_ids[]
Returns the ordered list of DVB network_ids from the DTT channels, if any, that are included in the terminal’s channel list.

If the terminal does not have a DTT receiver or no DTT channels are present in the channel list then the property shall be undefined.

The following property is added to the Configuration class.

readonly String deviceId
NOTE 1:   This property is named deviceId for historical reasons but it does not return a permanent identifier for the device.

Returns either a string representing a distinctive identifier that is unique for the combination of the terminal and the HTML document origin or a status code. The distinctive identifier shall use a character set that is restricted to alphanumeric characters and the hyphen. The status code shall be a number preceded by the ‘#’ character.

Valid status codes are:

Status code Description
#1 The terminal is configured to request explicit user approval for this application. The application may call requestAccessToDistinctiveIdentifier to obtain such approval even if this method has previously been called and the user did not grant access.
#2 Access to the distinctive identifier is denied explicitly by the user following a previous call by the application to requestAccessToDistinctiveIdentifier. Further calls to requestAccessToDistinctiveIdentifier do not result in the user being asked again for approval. This is for use by terminals that restrict the number of times that an application may call this method.
#3 Access to the distinctive identifier is denied in accordance with the user option setting – see clause 12.1.5).
#4 Access to the distinctive identifier is denied by the terminal manufacturer, e.g. because the application provider and the terminal manufacturer have not entered into a suitable agreement covering such access.
#5 Access to the distinctive identifier is denied as the application has not yet been activated.

NOTE 2:   Other status codes may be defined in future versions of the present document.

The value of this property may change after a call to requestAccessToDistinctiveIdentifier, a change to the user option, a request by the user to generate a new distinctive identifier or some other event.

The following method is added to the Configuration class.

requestAccessToDistinctiveIdentifier(function callback)
Description Calls the callback with true as the first argument if the deviceId property contains a distinctive identifier, otherwise calls the callback with false as the first argument. This callback takes place either immediately or after a user interaction according to the following rules.

Calls to this method while a callback is outstanding shall be ignored.

If this method is supported, the terminal shall provide some native UI that requests the user to grant access to the distinctive identifier for the calling application. The terminal may persistently store the user response between invocations of the application.

If the deviceId property contains the value “#1”, the terminal shall display this native UI when this method is called. The callback shall be called only after the UI is removed and the argument shall reflect the updated state of the deviceId property following the interaction with the user. This method call shall not block while the UI is displayed.

If the deviceId property contains a different status code, the terminal shall not display the native UI and shall immediately call the callback with false as the first argument.

If the deviceId property already contains a distinctive identifier, the terminal shall not display the native UI and shall immediately call the callback with true as the first argument.

The Configuration object allows configuration items within the system to be read and modified. This includes settings such as audio and subtitle languages, display aspect ratios and other similar settings. Unlike the LocalSystem object, this is concerned with software- and application-related settings rather than hardware configuration and control.

Properties

String preferredAudioLanguage

A comma-separated set of languages to be used for audio playback, in order of preference.

Each language SHALL be indicated by its ISO 639-2 language code as defined in [ISO 639-2].

String preferredSubtitleLanguage

A comma-separated set of languages to be used for subtitle playback, in order of preference. The subtitle component (see section 7.16.5.5) that matches the highest ordered language SHALL be activated (equivelant to the selectComponent method) and all other subtitle components SHALL be deactivated (equivelant to the unselectComponent method).

Each language SHALL be indicated by its ISO 639-2 language code as defined in [ISO 639-2] or as a wildcard specifier “***”.

If the wildcard is included it SHALL be the last item in the set. If no subtitle component in the content matches a language in this property and the wildcard is included then the first (lowest) subtitle component SHALL be selected.

String preferredUILanguage

A comma-separated set of languages to be used for the user interface of a service, in order of preference.

Each language SHALL be indicated by its ISO 639-2 language code as defined in [ISO 639-2].

If present, the HTTP Accept-language header shall contain the same languages as the preferredUILanguage property with the same order of preference. NOTE: The order of preference in the Accept-language header is indicated using the quality factor.

String countryId

An ISO-3166 three character country code identifying the country in which the receiver is deployed.

Integer regionId

An integer indicating the time zone within a country in which the receiver is deployed. A value of 0 SHALL represent the eastern-most time zone in the country, a value of 1 SHALL represent the next time zone to the west, and so on.

Valid values are in the range 0 – 60.

Integer pvrPolicy

The policy dictates what mechanism the system should use when storage space is exceeded.

Valid values are shown in the table below.

Value

Description

0

Indicates a recording management policy where no recordings are to be deleted.

1

Indicates a recording management policy where only watched recordings MAY be deleted.

2

Indicates a recording management policy where only recordings older than the specified threshold (given by the pvrSaveDays and pvrSaveEpisodes properties) MAY be deleted.

Integer pvrSaveEpisodes

When the pvrPolicy property is set to the value 2, this property indicates the minimum number of episodes that SHALL be saved for series-link recordings.

Integer pvrSaveDays

When the pvrPolicy property is set to the value 2, this property indicates the minimum save time (in days) for individual recordings. Only recordings older than the save time MAY be deleted.

Integer pvrStartPadding

The default padding (measured in seconds) to be added at the start of a recording.

Integer pvrEndPadding

The default padding (measured in seconds) to be added at the end of a recording.

Integer preferredTimeShiftMode

The time shift mode indicates the preferred mode of operation for support of timeshift playback in the video/broadcast object. Valid values are defined in the timeShiftMode property in section 7.13.2.2. The default value is 0, timeshift is turned off.

Methods

String getText( String key )

Description

Get the system text string that has been set for the specified key.

Arguments

key

A key identifying the system text string to be retrieved.

void setText( String key, String value )

Description

Set the system text string that has been set for the specified key. System text strings are used for automatically-generated messages in certain cases, e.g. parental control messages.

Arguments

key

The key for the text string to be set. Valid keys are:

Key

Description

no_title

Text string used as the title for programmes and channels where no guide information is available.

Defaults to “No information”

no_synopsis

Text string used as the synopsis for programmes where no guide information is available.

Defaults to “No further information available”

manual_recording

Text string used to identify a manual recording.

Defaults to “Manual Recording”

value

The new value for the system text string.