The application/oipfApplicationManager embedded object

Support in HbbTV

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

The getOwnerApplication() method, onLowMemory and onApplicationLoadError properties (and corresponding DOM 2 events) shall be supported. All other properties, methods and DOM 2 events are not included.

An OITF SHALL support a non-visual embedded object of type “application/oipfApplicationManager”, with the following JavaScript API, to enable applications to access the privileged functionality related to application lifecycle and management that is provided by the application model defined in this section.

If one of the methods on the application/oipfApplicationManager is called by a webpage that is not a privileged DAE application, the OITF SHALL throw an error as defined in section 10.1.1.

Constants

Name

Value

Use

WIDGET_INSTALLATION_STARTED

0

The Widget installation has started. This state SHALL be used to indicate that the download of the Widget package is completed (possibly because the Widget was already stored locally) and the OITF is ready to start the Widget installation process. This state SHALL NOT be signalled if the package download fails.

WIDGET_INSTALLATION_COMPLETED

1

The Widget installation has completed successfully

WIDGET_INSTALLATION_FAILED

2

The Widget installation has failed either because the Widget package download failed or because, after the download, the Widget installation process failed.

WIDGET_UNINSTALLATION_STARTED

3

The Widget uninstallation has started

WIDGET_UNINSTALLATION_COMPLETED

4

The Widget uninstallation has completed successfully

WIDGET_UNINSTALLATION_FAILED

5

The Widget uninstallation has failed

WIDGET_ERROR_STORAGE_AREA_FULL

10

The local storage device is full

WIDGET_ERROR_DOWNLOAD

11

The Widget cannot be downloaded

WIDGET_ERROR_INVALID_ZIP_ARCHIVE

12

The Widget package is corrupted or is an Invalid Zip Archive (as defined in [Widgets-Packaging] )

WIDGET_ERROR_INVALID_SIGNATURE

13

Widget’s Signature Validation failed

WIDGET_ERROR_GENERIC

14

Other reason

WIDGET_ERROR_SIZE_EXCEEDED

15

The Widget exceeded the maximum size for a single widget allowed by the platform, as defined in section 9.1.

WIDGET_ERROR_PERMISSION_DENIED

16

The user and/or the OITF denied the installation or update of a Widget

Properties

function onLowMemory()

The function that is called when the OITF is running low on available memory for running DAE applications. The exact criteria determining when to generate such an event is implementation specific.

function onApplicationLoaded( Application appl )

The function that is called immediately prior to a load event being generated in the affected application. The specified function is called with one argument appl, which provides a reference to the affected application.

function onApplicationUnloaded( Application appl )

The function that is called immediately prior to an unload event being generated in the affected application. The specified function is called with one argument appl, which provides a reference to the affected application.

function onApplicationLoadError( Application appl )

The function that is called when the OITF fails to load either the file containing the initial HTML document of an application or an XML AIT file (e.g. due to an HTTP 404 error, an HTTP timeout, being unable to load the file from a DSM-CC object carousel or due to the file not being either an HTML file or a XML AIT file as appropriate), All properties of the Application object referred to by appl SHALL have the value undefined and calling any methods on that object SHALL fail.

function onWidgetInstallation( WidgetDescriptor wd, Integer state,
Integer reason )

The callback function that is called during the installation process of a Widget. The function is called with three arguments:

  • WidgetDescriptor wd – the WidgetDescriptor for the installed Widget. Some attributes of this argument may not have been initialised and may be null when the function is called until the Widget is successfully installed.
  • Integer state – the state of the installation; valid values are:
    • WIDGET_INSTALLATION_STARTED
    • WIDGET_INSTALLATION_COMPLETED
    • WIDGET_INSTALLATION_FAILED

as defined in section 7.2.1.1.

  • Integer reason: indicates the reason for installation failure. This is only valid if the value of the state argument is WIDGET_INSTALLATION_FAILED otherwise this argument SHALL be null. Valid values for this field are:
    • WIDGET_ERROR_STORAGE_AREA_FULL
    • WIDGET_ERROR_DOWNLOAD
    • WIDGET_ERROR_INVALID_ZIP_ARCHIVE
    • WIDGET_ERROR_INVALID_SIGNATURE
    • WIDGET_ERROR_GENERIC
    • WIDGET_ERROR_SIZE_EXCEEDED
    • WIDGET_ERROR_PERMISSION_DENIED

as defined in section 7.2.1.1.

function onWidgetUninstallation( WidgetDescriptor wd, Integer state )

The function that is called during the uninstallation process of a Widget. The function is called with two arguments, defined below:

  • WidgetDescriptor wd – the WidgetDescriptor of the Widget to be uninstalled.
  • Integer state – the state of the installation; valid values are:
    • WIDGET_UNINSTALLATION_STARTED,
    • WIDGET_UNINSTALLATION_COMPLETED
    • WIDGET_UNINSTALLATION_FAILED

as defined in section 7.2.1.1.

readonly WidgetDescriptorCollection widgets

A collection of WidgetDescriptor objects for the Widgets currently installed on the OITF.

Methods

Integer getApplicationVisualizationMode()

Description

Returns the current mode used by the OITF to visualize applications, whereby a return value:

1

corresponds to the application visualization mode as defined by bullet 1) of section 4.4.6, i.e. multiple applications visible simultaneously with DAE applications managing their own visibility

2

corresponds to the application visualization mode as defined by bullet 2) of section 4.4.6, i.e. multiple applications visible simultaneously with OITF managing the size, position, visibility of applications

3

corresponds to the application visualization mode as defined by bullet 3) of section 4.4.6, i.e. only a single application visible at any time.

Application getOwnerApplication( Document document )

Description

Get the application that the specified document is part of. If the document is not part of an application, or the calling application does not have permission to access that application, this method will return null.

Arguments

document

The document for which the Application object should be obtained.

ApplicationCollection getChildApplications( Application application )

Description

Get the applications that are children of the specified application.

Arguments

application

The application whose children should be returned.

void gc()

Description

Provide a hint to the execution environment that a garbage collection cycle should be initiated. The OITF is not required to act upon this hint.

void installWidget( String uri )

Description

Attempts to install on the OITF a Widget located at the URI passed. If the Widget is stored on a remote server it SHALL first be downloaded. This specification does not specify where the OITF stores the Widget package, nor does it define what happens to the original package after the installation process has finished (regardless of whether it succeeded or failed).

When trying to install a Widget with an “id” that collides with the id of an already installed Widget (where the “id” is defined in section 7.6.1 of [Widgets-Packaging] along with the extension defined in section 11.1 of this specification), the OITF SHOULD ask the user for confirmation before installing the Widget. The OITF SHOULD provide information about the conflict (e.g. the version numbers, if available) to allow the user to decide whether to proceed with the installation or to cancel it.

If the user confirms the installation, then the new Widget SHALL replace the one already installed; any storage area associated with the replaced Widget SHALL be retained. Note that the user can also choose to downgrade a Widget, i.e. install an old version of the Widget to replace the installed, more recent, one.

Arguments

uri

The resource locator in form of a URI, which points to a Widget package to be installed.

void uninstallWidget( WidgetDescriptor wd )

Description

Uninstalls a Widget. If this Widget is running it will be stopped. Any storage areas associated with the uninstalled Widget SHALL be deleted.

Arguments

wd

A WidgetDescriptor object for a Widget installed on the OITF.

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

onLowMemory

LowMemory

Bubbles: No

Cancellable: No

Context Info: None

onApplicationLoaded

ApplicationLoaded

Bubbles: No

Cancellable: No

Context Info: appl

onApplicationUnloaded

ApplicationUnloaded

Bubbles: No

Cancellable: No

Context Info: appl

onApplicationLoadError

ApplicationLoadError

Bubbles: No

Cancellable: No

Context Info: appl

onWidgetInstallation

WidgetInstallation

Bubbles: No

Cancellable: No

Context: wd, state, reason

onWidgetUninstallation

WidgetUninstallation

Bubbles: No

Cancellable: No

Context: wd, state

NOTE: the above DOM events are directly dispatched to the event target, and will not bubble nor capture. Applications SHOULD NOT rely on receiving the events listed above during the bubbling or the capturing phase. Applications that use DOM event handlers SHALL call the addEventListener() method on the application/oipfApplicationManager object. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.