The application/oipfDownloadTrigger embedded object

Support in HbbTV

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

The definition of the registerDownloadURL method shall be modified as defined in clause A.2.19 of the present document.

For the registerDownload and registerDownloadURL methods, the downloadStart parameter shall be ignored by terminals.

Comment

Security: Trusted

In clause 7.4.1.1 of the OIPF DAE specification [1], the definition of the registerDownloadURL() method shall be superseded by the following definition.

String registerDownloadURL(String URL, String contentType,Date downloadStart,

Integer priority )
Description This method triggers the terminal to initiate a download of the content pointed to by the URL and the given content type.

The contentType argument SHALL reflect the expected type of content returned by the content server when connecting to the URL. The contentType can be used to evaluate if the content type is part of the list of accepted content types of the terminal. For example, if the terminal does not support content type “video/MP2T”, then the registerDownloadURL() method could return undefined to indicate this to the application in advance of the download.

 

If contentType has value “application/vnd.oipf.ContentAccessDownload+xml”, the method SHALL return a download identifier, after which the terminal SHALL immediately fetch the Content Access Download Descriptor. In cases where the Content Access Download Descriptor is not accepted by the terminal, the state property of the download shall be immediately changed to the value 8 (‘Failed’) and the reason property shall be set to 4 (‘Other reason’). Otherwise, the same SHALL happen as if registerDownload() as defined in clause 4.6.3.1 with the given Content Access Download Descriptor as argument was called. The downloadStart argument only applies to the individual Download objects described by the Content Access Download Descriptor and SHALL NOT apply to the retrieval of the Content Access Download Descriptor itself.

 

Note that if the Content Access Download Descriptor contains multiple content items to be downloaded, the associated Download objects for each of these content items SHALL have the same value for the id property. The associated Download objects can be retrieved through the createFilteredList() method as defined in clause 7.4.3.3.

Returns a String value representing a unique identifier to identify the download, if the given arguments are acceptable by the terminal to trigger a download. If the terminal supports the application/oipfDownloadManager as specified in clause 7.4.3, this SHALL be the value of the id attribute of the associated Download object(s).

 

The terminal SHALL guarantee that download identifiers are unique in relation to recording identifiers and CODAsset identifiers.

 

The method returns undefined if the given arguments are not acceptable by the terminal to trigger a download.
Arguments URL The URL from which the content can be fetched.
contentType The type of content referred to by the URL attribute. The contentType can be used to evaluate if the content type is part of the list of supported content types of the terminal.
downloadStart Optional argument indicating the time at which the download should be started. If the argument is not included, or takes a value of null then the download should start as soon as possible.
priority Optional argument indicating the relative priority of the download with respect to other downloads registered by the same organization as the calling application. Higher values indicate a higher priority. If the argument is not included then a priority of 0 shall be assigned.

An OITF SHALL support a non-visual embedded object of type application/oipfDownloadTrigger, with the following JavaScript API to enable passing a content-access descriptor to an underlying download manager using JavaScript.

The functionality as described in this section is subject to the security model of section 10.

Methods

String registerDownload( String contentAccessDownloadDescriptor,
Date downloadStart, Integer priority )

Description

Send contentAccessDownloadDescriptor to the underlying download manager as a String formatted according to the Content Access Download Descriptor XML Schema as specified in Annex E.

Returns a String value representing a unique identifier to identify the download, if the contentAccessDownloadDescriptor is valid and is accepted for triggering a download. If the OITF supports the application/oipfDownloadManager as specified in section 7.4.3, this SHALL be the value of the “id” attribute of the associated Download object. Note that if the Content Access Download Descriptor contains multiple content items to be downloaded, the associated Download objects for each of these content items SHALL have the same value for the “id” value. The associated Download objects can be retrieved through the method getDownloads() as defined in section 7.4.3.3.

The OITF SHALL guarantee that download identifiers are unique in relation to recording identifiers and CODAsset identifiers.

The method returns undefined if the contentAccessDownloadDescriptor is not accepted for triggering a download.

Arguments

contentAccessDownloadDescriptor

String formatted according to the Content Access Download Descriptor XML Schema as specified in Annex E.

downloadStart

Optional argument indicating the time at which the download should be started. If the argument is not included, or takes a value of null then the download should start as soon as possible.

priority

Optional argument indicating the relative priority of the download with respect to other downloads registered by the same organisation as the calling application. Higher values indicate a higher priority. If the argument is not included then a priority of 0 shall be assigned.

String registerDownloadURL( String URL, String contentType, Date downloadStart,
Integer priority )

Description

This method triggers the OITF to initiate a download of the content pointed to by the URL and the given content type.

The contentType attribute SHALL reflect the expected type of content returned by the content server when connecting to the URL. The contentType can be used to evaluate if the content type is part of the list of accepted content types of the OITF. For example, if the OITF does not support content type “video/MP2T”, then the registerDownloadURL method could return undefined to indicate this to the application in advance of the download.

If contentType has value “application/vnd.oipf.ContentAccessDownload+xml”, the method SHALL return a download identifier, after which the OITF SHALL immediately fetch the Content Access Download Descriptor, after which the same SHALL happen as if registerDownload() as defined in section 4.6.3.1 with the given Content Access Download Descriptor as argument was called. The downloadStart argument only applies to the individual Download objects described by the Content Access Download Descriptor and SHALL NOT apply to the retrieval of the Content Access Download Descriptor itself.

Note that if the Content Access Download Descriptor contains multiple content items to be downloaded, the associated Download objects for each of these content items SHALL have the same value for the “id” value. The associated Download objects can be retrieved through method getDownloads() as defined in section 7.4.3.3.

Returns a String value representing a unique identifier to identify the download, if the given arguments are acceptable by the OITF to trigger a download. If the OITF supports the application/oipfDownloadManager as specified in section 7.4.3, this SHALL be the value of the “id” attribute of the associated Download object(s).

The OITF SHALL guarantee that download identifiers are unique in relation to recording identifiers and CODAsset identifiers.

The method returns undefined if the given arguments are not acceptable by the OITF to trigger a download.

Arguments

URL

The URL from which the content can be fetched.

contentType

The type of content referred to by the URL attribute. The contentType can be used to evaluate if the content type is part of the list of supported content types of the OITF.

downloadStart

Optional argument indicating the time at which the download should be started. If the argument is not included, or takes a value of null then the download should start as soon as possible.

priority

Optional argument indicating the relative priority of the download with respect to other downloads registered by the same organisation as the calling application. Higher values indicate a higher priority. If the argument is not included then a priority of 0 shall be assigned.

Integer checkDownloadPossible( Integer sizeInBytes )

Description

Checks whether a download of a given sizeInBytes would be possible at this moment in time. The value is application specific. For an application whose organization has a reservation, only the free space in the reservation SHALL be considered when making the check.

Possible return values are:

Value

Semantics

0

Successful, i.e. the download could be successfully completed if it would be started at this moment in time.

1

Insufficient Storage, i.e. the download could be started, but is unlikely to complete successfully, since insufficient storage capacity is available to fully store the content to be downloaded.

2

Storage not available, i.e. the download would fail, since the storage is currently unavailable, e.g. in case of removable storage.

Arguments

sizeInBytes

Integer value with the given size of the download in bytes.