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
| 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:
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. |