void addStreamEventListener(String targetURL, String eventName, EventListener listener)

Description

Add a listener for the specified DSM-CC stream event.

When a broadcaster transmits an identical instance of the MPEG private data section carrying a stream event descriptor (including the version number), only one StreamEvent event shall be dispatched.

When a broadcaster transmits different events using the same event name id (i.e. with different version numbers), one StreamEvent event shall be dispatched for each different stream event descriptor received.

An event shall also be dispatched in case of error.

Listeners can only be added while the video/broadcast object is in the Presenting or Stopped states. Calls to this function when the video/broadcast object is in other states shall have no effect.

The terminal shall automatically unregister all listeners on the video/broadcast object in the following cases:

· A transition to the Unrealized state (e.g. when becoming broadcast-independent).

· A transition to the Connecting state that is due to a channel change.

Listeners are not unregistered when transitioning to the Connecting state due to a transient error that does not result in a change of channel.

Arguments

targetURL

The URL of the DSM-CC StreamEvent object or an HTTP or HTTPS URL referring to an XML event description file (as defined in clause 8.2 of ETSI TS 102 809 [3] and profiled in clause 7.2.4) describing the event.

eventName

The name of the event (of the DSM-CC StreamEvent object) that shall be subscribed to.

listener

The listener for the event.

void removeStreamEventListener(String targetURL, String eventName, EventListener listener)

Description

Remove a stream event listener for the specified stream event name.

Arguments

targetURL

The URL of the DSM-CC StreamEvent object or an HTTP or HTTPS URL referring to an event description file describing the event.

eventName

The name of the event (of the DSM-CC StreamEvent object) whose subscription shall be removed.

listener

The listener for the event.

interface StreamEvent : Event{

readonly attribute String name;

readonly attribute String data;

readonly attribute String text;

readonly attribute DOMString status;

}

Properties

name

The name of the DSM-CC StreamEvent’s event.

data

Data of the DSM-CC StreamEvent’s event encoded in hexadecimal.

EXAMPLE: “0A10B81033” (for a payload 5 bytes long).

text

Text data of the DSM-CC StreamEvent’s event as a string assuming UTF-8 as the encoding for the DSM-CC StreamEvent’s event. Characters that cannot be transcoded are skipped.

Application developers should be aware that in some circumstances an attacker may be able to modify the broadcast signalling from which this data is derived. Applications shall not use this data in a way that would result in it being executed by the browser. Applications should be written to be tolerant of incorrectly formatted data or values for this data which are outside the expected range without hanging up or crashing.

status

Equal to “trigger” when the event is dispatched in response to a trigger in the stream or “error” when an error occurred (e.g. attempting to add a listener for an event that does not exist, or when a StreamEvent object with registered listeners is removed from the carousel).

Circumstances under which an event shall be dispatched with an error status include:

· the StreamEvent object pointed to by targetURL is not found in the carousel or via broadband;

· the StreamEvent object pointed to by targetURL does not contain the event specified by the eventName parameter;

· the carousel cannot be mounted;

· the elementary stream which contains the StreamEvent event descriptor is no longer being monitored (e.g. due to another monitoring request or because it disappears from the PMT).

Once an error is dispatched, the listener is automatically unregistered by the terminal.