# downloader

Downloader模块管理网络文件下载任务，用于从服务器下载各种文件，并支持跨域访问操作。通过plus.downloader获取下载管理对象。Downloader下载使用HTTP的GET/POST方式请求下载文件，符合标准HTTP/HTTPS传输协议。

## 方法：

- createDownload: 新建下载任务
- enumerate: 枚举下载任务
- clear: 清除下载任务
- startAll: 开始所有下载任务

## 对象：

- Download: Download对象管理一个下载任务
- DownloadEvent: 下载任务事件类型
- DownloadState: 下载任务状态
- DownloadOptions: 下载任务参数

## 回调方法：

- DownloadCompletedCallback: 下载任务完成时的回调
- DownloadStateChangedCallback: 下载任务状态变化回调
- DownloadEnumerateCallback: 枚举下载任务回调

## 权限：

5+功能模块（permissions）

    {
    // ...
    "permissions":{
    	// ...
    	"Downloader": {
    		"description": "文件下载，管理文件下载任务"
    	}
    }
    }

# Download

Download对象管理一个下载任务

    interface plus.downloader.Download {
    	readonly attribute String id;
    	readonly attribute String url;
    	readonly attribute Number state;
    	readonly attribute DownloadOptions options;
    	readonly attribute String filename;
    	readonly attribute Number downloadedSize;
    	readonly attribute Number totalSize;
    	function void abort();
    	function void addEventListener(String event, function Callback listener, Boolean capture);
    	function String getAllResponseHeaders();
    	function String getResponseHeader(String headerName);
    	function void pause();
    	function void resume();
    	function void setRequestHeader(String headerName, String headerValue);
    	function void start();
    }

## 属性：

- id: 下载任务的标识
- url: 下载文件的地址
- state: 任务的状态
- options: 下载任务的参数
- filename: 下载的文件名称
- downloadedSize: 已完成下载文件的大小
- totalSize: 下载任务文件的总大小

## 方法：

- abort: 取消下载任务
- addEventListener: 添加下载任务事件监听器
- getAllResponseHeaders: 获取下载请求HTTP响应头部信息
- getResponseHeader: 获取下载请求指定的HTTP响应头部的值
- pause: 暂停下载任务
- resume: 恢复暂停的下载任务
- setRequestHeader: 设置下载请求的HTTP头数据
- start: 开始下载任务

# DownloadEvent

下载任务事件类型

## 常量：

- "statechanged": (String 类型 )下载任务状态变化事件

  当下载任务状态发生变化时触发此事件，事件原型参考DownloadStateChangedCallback。

# DownloadState

下载任务状态

## 常量：

- undefined: (undefined 类型 )下载任务未开始

  通过plus.downloader.createDownload()方法创建下载任务后的初始状态，此时可调用其start()方法开始下载。

- 0: (Number 类型 )下载任务开始调度

  调用下载任务的start()方法之后处于此状态，此时下载任务处于可调度下载状态。

- 1: (Number 类型 )下载任务开始请求

  下载任务建立网络连接，发送请求到服务器并等待服务器的响应。

- 2: (Number 类型 )下载任务请求已经接收

  下载任务网络连接已建立，服务器返回响应，准备传输数据内容。

- 3: (Number 类型 )下载任务接收数据

  下载任务接收数据，监听statechanged事件时可多次触发此状态。

- 4: (Number 类型 )下载任务已完成

  下载任务完成数据传输并断开连接，下载成功或失败都会设置为此状态。

- 5: (Number 类型 )下载任务已暂停

  调用下载任务的pause()方法将任务暂停，此时可调用其resume()方法重新开始下载。

- -1: (Number 类型 )枚举任务状态

  非下载任务状态，泛指所有下载任务的状态，用于enumerate()和clear()操作时指定作用于所有下载任务。

# DownloadOptions

下载任务参数

    interface plus.downloader.DownloadOptions {
    	readonly attribute String method;
    	readonly attribute String data;
    	readonly attribute String filename;
    	readonly attribute Number priority;
    	readonly attribute Number timeout;
    	readonly attribute Number retry;
    	readonly attribute Number retryInterval;
    }

## 说明：

在创建下载任务时设置的参数，如设置下载任务使用的HTTP协议类型、优先级等。

## 属性：

- method: (String 类型 )网络请求类型

  支持http协议的“GET”、“POST”，默认为“GET”请求。

- data: (String 类型 )POST请求时提交的数据

  仅在网络请求类型method设置为"POST"时有效，"GET"请求时忽略此数据。

- filename: (String 类型 )下载文件保存的路径

  保存文件路径仅支持以"_downloads/"、"_doc/"、"_documents/"开头的字符串。 文件路径以文件后缀名结尾（如"_doc/download/a.doc"）表明指定保存文件目录及名称，以“/”结尾则认为指定保存文件的目录（此时程序自动生成文件名）。 如果指定的文件已经存在，则自动在文件名后面加"(i)"，其中i为数字，如果文件名称后面已经是此格式，则数字i递增，如"download(1).doc"。 默认保存目录为（"_downloads"），并自动生成文件名称。

- priority: (Number 类型 )下载任务的优先级

  数值类型，数值越大优先级越高，默认优先级值为0。

- timeout: (Number 类型 )下载任务超时时间

  数值类型，单位为s(秒)，默认值为120s。 超时时间为服务器响应请求的时间（不是下载任务完成的总时间），如果设置为0则表示永远不超时。

- retry: (Number 类型 )下载任务重试次数

  数值类型，默认为重试3次。

- retryInterval: (Number 类型 )下载任务重试间隔时间

  数值类型，单位为s(秒)，默认值为30s。

# DownloadCompletedCallback

下载任务完成时的回调

    vaoid onCompleted(Download download, Number status) {
    	// Download file complete code
    }

## 说明：

下载任务完成时的回调函数，在下载任务完成时调用。 下载任务失败也将触发此回调。

## 参数：

- download : ( Download ) 必选 下载任务对象
- status: ( Number ) 必选 下载结果状态码
  HTTP传输协议状态码，如果未获取传输状态则其值则为0，如下载成功其值通常为200。

## 返回值：

void : 无

# DownloadStateChangedCallback

下载任务状态变化回调

    void onStateChanged( Download download, status ) {
    	// Download state changed code.
    }

## 参数：

- download : ( Download ) 必选 下载任务对象
- status: ( Number ) 必选 下载结果状态码
  HTTP传输协议状态码，如果未获取传输状态则其值则为0，如下载成功其值通常为200。

## 返回值：

void : 无

# DownloadEnumerateCallback

枚举下载任务回调

    void onEnumerated( Download[] downloads ) {
    	// Enumerate success code
    }

## 参数：

- downloads: ( Array[ Download ] ) 必选 枚举到的下载任务对象数组

## 返回值：

void : 无