The application/oipfDownloadManager embedded object

Support in HbbTV

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

The discInfo property and the updateRegisteredDownload, pause, resume and getDownloads method are not included.

A download using FDP which has completed with errors shall be reported as successfully completed, in case discard_file_on_error_flag = 0 for this download (see clause H.4.2).

The behaviour of the reserve() method is clarified by clause A.2.18 below.

Note that the oipfDownloadManager object,  download via broadcast using FDP and download via broadband using HTTP are likely to be removed in the next revision of the present document.

Comment

Security: Trusted

The following rules and clarifications shall apply to the reserve() method of the application/oipfDownloadManager embedded object.

In all cases, if a call to the reserve() method does not succeed (i.e. if the return status is other than RESERVE_OK), this call shall have no effect. Any prior reservation is kept unchanged.

NOTE: The oipfDownloadManager object is likely to be removed in the next revision of the present document.

In a managed deployment, privileged applications may need access to the download management functionality in a CoD system. This access may be required to implement a UI to the download manager, to queue a download or to display the progress of a specific download. OITFs SHOULD support an “application/oipfDownloadManager” object with the following interface.

Clients supporting the download management APIs as specified in this section SHALL indicate this by adding the attribute “manageDownloads” to the <download> element with a value unequal to “none” in the client capability description as defined in section 9.3.4.

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

State diagram for the application/oipfDownloadManager object

The following state machine provides an overview of the state changes that are possible in the download manager. The states reflect the changes signalled to applications via the onDownloadStateChange event handler.

Figure 12: State diagram for embedded application/oipfDownloadManager objects (normative)

Note that newly-registered downloads may pre-empt downloads which are currently in progress, if they have a higher priority than in-progress downloads.  This may cause downloads to be paused or resumed without application intervention.

Properties

function onDownloadStateChange( Download item, Integer state, Integer reason )

The function that is called when the status of a download has changed. The specified function is called with three arguments item, state and reason, which are defined as follows:

· Download item – the Download object whose state has changed.

· Integer state – the new state of the download. Valid values include:

Status

Semantics

1

The download has completed successfully.

2

The download is in progress.

4

The download has been paused (either by an application or automatically by the OITF).

8

The download has failed.

16

The download has been queued but has not yet started.

32

The download has stalled due to a transient failure and the Download Manager is attempting to recuperate and re-establish the download.

· Integer reason. Extended reason code. This is only valid if the value of the state argument is 8.

Reason

Semantics

0

The local storage device is full.

1

The item cannot be downloaded (e.g. because it has not been purchased).

2

The item is no longer available for download.

3

The item is invalid due to bad checksum or length.

4

Other reason.

If no error has occurred, this argument SHALL take the value undefined.

readonly DiscInfo discInfo

Get information about the status of the local storage device. The DiscInfo class is defined in section 7.16.4.

readonly Integer hasReserved

Returns the size (in megabytes) of any current reservation for the applications from the same organisation as the calling application otherwise -1.

readonly Integer allocated

Returns the size (in megabytes) of any current reservation for the applications from the same organisation as the calling application otherwise -1.

Methods

Boolean pause( Download download )

Description

Pause an in-progress, queued or stalled download and return true. For in-progress downloads, more data SHALL NOT be downloaded until the download is resumed. The HTTP request and TCP socket are interrupted and closed.

For completed or failed downloads, this operation SHALL return false.

Arguments

download

The download to be paused.

Boolean resume( Download download )

Description

Resume a paused download. If the download is not paused, this operation SHALL return false.

Arguments

download

The download to be resumed.

Boolean remove( Download download )

Description

Remove the download and any data and media content associated with it and return true. Return false if the download attribute does not refer to a valid download.

As a side effect of this method, all properties on download SHALL be set to undefined. Any method calls subsequently performed by an application which pass download as an argument SHALL return false.

If an A/V Control object is referring to the indicated download for playback then the state of the A/V Control object SHALL be automatically changed to state 6 (the error state).

Arguments

download

The download to be deleted.

DownloadCollection getDownloads( String id )

Description

Returns a collection of downloads, for which the value of the Download.id property corresponds to the given id parameter. The downloads returned in the collection SHALL be filtered according to the value of the manageDownloads attribute of the <download> element in the OITF’s capability description (i.e. from the same application, same domain or from all applications).

For downloads initiated from registerDownloadURL() with a contentType value “application/vnd.oipf.ContentAccessDownload+xml” SHALL return null until the Content Access Download Descriptor has been retrieved and parsed.

If the value of id is null, it returns all downloads for the scope indicated by the manageDownloads attribute.

Arguments

id

Optional argument identifying the downloads to be retrieved. If present and not null, this is an identifier corresponding to the “id” attribute of zero or more Download objects. If the value of id is null, or the argument is not included, all downloads for the scope indicated by the manageDownloads attribute in the capability description are returned.

DownloadCollection createFilteredList( Boolean currentDomain, Integer states )

Description

Create a filtered list of downloads. Returns a subset of downloads that are managed by the receiver.

The currentDomain flag indicates whether downloads from FQDNs other than the current page are included in the returned collection. This flag MAY be set to one of three values:

Value

Meaning

true

The download is added if and only if it was initiated from the FQDN of the calling document.

If the application has the permission permission_downloadmanager (see section 10.1.4), only downloads initiated by the calling application shall be added.

false

The download is added if and only if it was not initiated from the FQDN of the calling document.

If the application does not have the permission permission_downloadmanager_all (see section 10.1.4), the OITF SHALL return an empty collection.

undefined

The download is added regardless of the domain that the download was initiated from.

If the application has the permission permission_downloadmanager (see section 10.1.4), only downloads initiated by the calling application shall be added.

If the application has the permission permission_downloadmanager_samedomain (see section 10.1.4), only downloads initiated by applications from the same FQDN shall be added.

The states flag indicates which state(s) of downloads that should be included in the list. The value of this flag is the arithmetic sum of one or more possible values of the state property of the Download object; only downloads whose state matches one of the values included in this sum are included in the returned collection.

Arguments

currentDomain

Flag indicating whether downloads from other domains SHALL be added to the list.

states

Indicates that states of downloads that should be included in the returned list.

Boolean updateRegisteredDownload( Download download, string newURL )

Description

The method updateRegisteredDownload() provides a way to update the URL to be used for a download. The OITF SHALL use the new URL for any future retrieval.

If the download is already in progress or paused (indicated by a state property value of 4), it SHALL be stopped. The download SHALL continue from the last byte received during the previous download.

If the state property of the download argument has the value 8 (download failed) or 32 (download stalled) then the OITF SHALL resume the download from the last byte received during the previous download but using the new URL.

If the state property of the download argument has the value 16 (download not started) no further action is taken until the download is started or resumed.

If the state property of the download argument has the value 1 (download completed) then this method SHALL return false. Otherwise it SHALL return true.

Arguments

download

The download object to be updated.

newURL

The new URL from which the content can be retrieved.

Integer reserve( Integer bytes )

Description

Requests the reservation of space for downloads to be made by applications from the same organization as the calling application. Reservation is OPTIONAL for applications to use and applications may use the Download API without reserving space in advance

If there is already a reservation for the calling application’s organization, this requests adjusting the reservation to the new value. If a call to reserve shrinks an already existing reservation then the application SHOULD ensure that the new size is sufficient for all the completed, in progress and requested downloads by applications from the calling application’s organization. The OITF SHALL refuse to shrink the reservation if this has not been done.

This specification intentionally does not define the criteria that are used in deciding whether or not to make or adjust a reservation

Either the OITF or the end-user MAY cancel a reservation completely, shrink one to recover some or all of the free space in the reservation or expand it. This specification intentionally does not define circumstances when this may happen. If a request to reserve space is granted to an organisation then applications from that organisation SHALL have the reserved space available to them for downloads. Attempts to use more than the reserved space SHALL fail.

A reservation is cancelled by calling this method with size zero.

Returns one of the RESERVE_ constants defined in section 7.4.3.5 below.

Arguments

bytes

The number of bytes to reserve.

Events

For the intrinsic event “onDownloadStateChange”, a corresponding DOM event SHALL be generated, in the following manner:

Intrinsic event

Corresponding DOM event

DOM Event properties

onDownloadStateChange

DownloadStateChange

Bubbles: No

Cancellable: No

Context Info: item, state , reason

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

Constants

Name

Use

RESERVE_OK

Reservation succeeded

RESERVE_NEVER

Reservations by the calling application will never succeed.

RESERVE_USER_INTERVENTION_REQD

Reservation failed and user intervention is required. This result SHALL only be returned by OITFs that include a platform provided UI enabling end-users to manage storage. RESERVE_TOO_LARGE SHALL be returned in preference to this if both apply

RESERVE_USER_DECLINED

Reservation failed as the user was asked to approve this request and declined.

RESERVE_TOO_LARGE

Reservation failed as the size requested was larger than what is permitted by the OITF.

RESERVE_SMALLER_THAN_USED

Request to shrink an already existing reservation failed as the requested size is smaller than the space currently used from the reservation.

RESERVE_UNKNOWN

Reservation failed for another reason.