Download API Documentation

Abstract

This specification defines an API that provides information and a series of operations about the download tasks of the hosting device.

1. Introduction

This section is non-normative.

The Download API specification defines a means for web developers or android app developers to operate the download tasks of the hosting device, including creating new downloads, controlling ongoing downloads, retrieving downloads and getting a list of download tasks. Without those operations we have designed for the download tasks, an application developer must design the web application with operations connected to the OS of the hosting device. That means the developers must have great knowledge of norms for development concerning a specific OS, such as Android or iOS. This requirement will obstruct the developers who must spend a lot of time designing an APP. Using the download API we will design below, developers are able to operate the download tasks more efficiently.

2. Conformance

As well as sections marked as non-normative , all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

he key words must , must not , required , should , should not , recommended , may , and optional in this specification are to be interpreted as described in RFC2119.

This specification defines conformance criteria that apply to a single product: the user agent that calls the services that it contains.

3. Terminology

The following concepts, terms and interfaces are defined in HTML5:

• EventHandler
• event handler and event types

Promise objects are defined in ECMASCRIPT.

4. The DownloadItem interface

This interface defines a single download task with necessary attributes and operations.

WebIDL:

enum DownloadState {"running","paused","canceled","failed","successful"};
enum DownloadError {"unknownError","fileAlreadyExistError","deviceNotFoundError",
                    "httpDataError","insufficientSpaceError","unhandledHttpError",
                    "cannotResumError","invalidValuesError","typeMismatchError",
                    "notFoundError"};
                    
[NoInterfaceObject] interface DownloadItem{
	readonly attribute unsigned long id;
	readonly attribute DOMString sourceUrl;
	readonly attribute DOMString targetFile;
	readonly attribute Date startTime;
	readonly attribute DownloadState state;
	readonly attribute DownloadError error;
	readonly attribute long totalBytes;
	readonly attribute DOMString MIMEType;
	         attribute EventHandler onPause;
	         attribute EventHandler onResume;
	         attribute EventHandler onCancel;
	         attribute EventHandler onProgress;

	Promise start();
        Promise pause();
	Promise resume();
	Promise cancel();
};

The user agent have no permission to create a new DownloadItem object. A new DownloadItem object can be only created by a method of the DownloadManager object named createDownload.

Enumeration type:

• enum DownloadState: defines all the states which will occur in the process of download
• enum DownloadError: defines all the errors which will occur in the process of download. The meaning of every error will be described in the following.

Attributes:

• readonly int id : the download item identifier.
• readonly DOMString sourceUrl : the URL of the download source
• readonly DOMString targetFile : the target file or the absolute path for putting the downloaded data
• readonly Date startTime : the time when the download task starts.
• readonly DownloadState state : the current state of the download task.
• readonly DownlaodError error : the current error of the download task.
• readonly long totalBytes : the total bytes of the download file.
• readonly DOMString MIMEType : the mime type of the download file

Event Handlers:

The following are the event handlers (and their corresponding event handler event types) that must be supported as attributes by the DownloadItem object:

Event Handlers	event handler event types
onPause	pause
onResume	resume
onCancel	cancel
onProgress	progress

Methods：

###1. start:

starts the download task for the first time, or restarts a download task that failed or has been canceled.

Privilege level: public

Parameters: none

Exceptions:

• Exception with error type FileAlreadyExistError, if the requested destination file already exists.
• Exception with error type DeviceNotFoundError, if no external storage was found
• Exception with error type HttpDataError, if an error receiving data occurred at the HTTP level.
• Exception with error type InsufficientSpaceError, if there was insufficient storage space
• Exception with error type UnhandledHttpError, if a HTTP code was received that download manager can’t handle
• Exception with error type UnknownError, if the method cannot be completed because of an unknown error.

###2. pause:

pauses the download when the download task is running.

Privilege level: public

Parameters: none

Exceptions:

• Exception with error type HttpDataError, if an error receiving data occurred at the HTTP level.
• Exception with error type UnhandledHttpError, if a HTTP code was received that download manager can’t handle
• Exception with error type UnknownError, if the method cannot be completed because of an unknown error.

###3. resume:

resumes the download task when it has been paused.

Privilege level: public

Parameters: none

Exceptions:

• Exception with error type HttpDataError, if an error receiving data occurred at the HTTP level.
• Exception with error type UnhandledHttpError, if a HTTP code was received that download manager can’t handle
• Exception with error type UnknownError, if the method cannot be completed because of an unknown error.
• Exception with error type CanNotResumeError, if some possibly transient error occurred but we can’t resume the download.

###4. cancel:

cancels the download task

Privilege level: public

Parameters: none

Exceptions:

• Exception with error type HttpDataError, if an error receiving data occurred at the HTTP level.
• Exception with error type UnhandledHttpError, if a HTTP code was received that download manager can’t handle
• Exception with error type UnknownError, if the method cannot be completed because of an unknown error.

5. The DownloadManager interface

This interface provides a single entry point to manage the download tasks, including starting new downloads, controlling ongoing downloads, removing downloads and getting a list of download tasks.

[NoInterfaceObject] interface DownloadManager{
	
	Promise<DownloadItem> createDownload( sourcrUrl, targetFile);
	
	Promise<Array<DownloadItem>> getAll();
	
	Promise<DownloadItem> getDownloadItemById(id);
	
	Promise<Array<DownloadItem>> getDownloadItemsByState( state );

	Promise removeDownloadItems( idArray );
	
	Promise removeAll();
};

Since this interface have no attribute, when the user agent is to create a new DownloadManager object, it can instantiate a new DownloadManager object without set any attribute’s value.

Methods:

###1. createDownload：

creates a new DownloadItem object.

Privilege level: public

Parameters:

• sourceUrl [required]: URL of the download source. It must be DOMString.
• targetFile [optional]: the target file or the absolute path for putting the downloaded data. It must be DOMString.

Exceptions:

• Exception with error type InvalidValuesError, if any input parameter does not contain a valid value.
• Exception with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
• Exception with error type UnknownError, if the method cannot be completed because of an unknown error.

###2. getAll:

gets an array of DownloadItem objects that are currently in the system.

Privilege level: public

Parameters: none

Return value: DownloadItem[] : all DownloadItem objects.

Exceptions:

• Exception with error type HttpDataError, if an error receiving or processing data occurred at the HTTP level
• Exception with error type UnknownError, if the method cannot be completed because of an unknown error.

###3. getDownloadItemById: gets a DownloadItem object of the same id as the parameter

Privilege level: public

Parameters:

• id: The ID of the download item to retrieve. It must be unsigned long.

Return value:
DownloadItem: a DownloadItem object with the specified ID.

Exceptions:

• Exception with error type NotFoundError, if this download task identifier cannot be found in the system of the hosting device.
• Exception with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
• Exception with error type InvalidValuesError, if any input parameter does not contain a valid value.
• Exception with error type UnknownError, if the method cannot be completed because of an unknown error.

###4. getDownloadItemsByState: gets an array of DownloadItem objects of the same state as the parameter.

Privilege level: public

Parameters:

• state: The state of the download items to retrieve. It must be one of values within the enum type DownloadState .

Every value as follows:

“running” , “paused” , “canceled” , “failed”, “successful”.

Return value:
DownloadItem[]: all DownloadItem objects with the specified state.

Exceptions:

• Exception with error type NotFoundError, if this download task identifier cannot be found in the system of the hosting device.
• Exception with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
• Exception with error type InvalidValuesError, if any input parameter does not contain a valid value.
• Exception with error type UnknownError, if the method cannot be completed because of an unknown error.

###5. removeDownloads: removes some DownloadItem objects whose identifier is within the parameter.

Privilege level: public

Parameters:

• idArray: a list of IDs of the download items to remove. It must be an Array of unsigned long type.

Exceptions:

• Exception with error type NotFoundError, if any download task identifier cannot be found in the system of the hosting device
• Exception with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
• Exception with error type InvalidValuesError, if any input parameter does not contain a valid value.
• Exception with error type UnknownError, if the method cannot be completed because of an unknown error.

###6. removeAll: removes all DownloadItem objects which are currently in the system.

Privilege level: public

Parameters: none

Exceptions:

• Exception with error type UnknownError, if the method cannot be completed because of an unknown error.

6. Example

This section is non-normative.

A simple download example:

var url = "http://www.download.com/example.html";
var targetFile = "download/file/example.html";

var downloadItem;

DownloadManager.createDownload(url, tagetFile). then( function (item) {
          // create the download successfully
          downloadItem = item;
          //start the download task
          downloadItem.start().then(function(){
          	    //start the download successfully
          	    //console output the log
          	    console.log(downlaodItem.startTime);
          	    console.log(downlaodItem.MIMEType);

          	    //add event listener to pause
          	    downloadItem.addEventListener('pause', function() {
          	    	console.log(this.state);
          	    });

          	    //if the download task has been paused successfully then resume it.
          	    if(downloadItem.state == "paused"){
          	    	downloadItem.onResume = function(){
                         console.log(this.state);
                    }
          	    }
          	    // cancel the download task
          	    downloadItem.cancel();

          },function(error){
          	    //fail to start the download task
          	    console.log(downlaodItem.error);
          	    console.log(downlaodItem.state);
          });
}, function (error){ 
         //fail to create the download 
});