<!DOCTYPE HTML>
|
<html>
|
<head>
|
<meta charset="utf-8">
|
<meta name="viewport" content="initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no">
|
<meta name="HandheldFriendly" content="true">
|
<meta name="MobileOptimized" content="320">
|
<title>Downloader Document</title>
|
<link rel="stylesheet" type="text/css" href="res/doc.css" charset="utf-8">
|
<link rel="stylesheet" type="text/css" href="res/prettify.sons.css" charset="utf-8">
|
<script type="text/javascript" src="res/doc.js" charset="utf-8"></script><script type="text/javascript" src="res/prettify.js" charset="utf-8"></script>
|
</head>
|
<body><div id="content" class="content">
|
<h1><a name="plus.downloader">downloader</a></h1>
|
<p>Downloader模块管理网络文件下载任务，用于从服务器下载各种文件，并支持跨域访问操作。通过plus.downloader获取下载管理对象。Downloader下载使用HTTP的GET/POST方式请求下载文件，符合标准HTTP/HTTPS传输协议。</p>
|
<h2>方法：</h2>
|
<ul>
|
<li>
|
<a href="#plus.downloader.createDownload">createDownload</a>: 新建下载任务</li>
|
<li>
|
<a href="#plus.downloader.enumerate">enumerate</a>: 枚举下载任务</li>
|
<li>
|
<a href="#plus.downloader.clear">clear</a>: 清除下载任务</li>
|
<li>
|
<a href="#plus.downloader.startAll">startAll</a>: 开始所有下载任务</li>
|
</ul>
|
<h2>对象：</h2>
|
<ul>
|
<li>
|
<a href="#plus.downloader.Download">Download</a>: Download对象管理一个下载任务</li>
|
<li>
|
<a href="#plus.downloader.DownloadEvent">DownloadEvent</a>: 下载任务事件类型</li>
|
<li>
|
<a href="#plus.downloader.DownloadState">DownloadState</a>: 下载任务状态</li>
|
<li>
|
<a href="#plus.downloader.DownloadOptions">DownloadOptions</a>: 下载任务参数</li>
|
</ul>
|
<h2>回调方法：</h2>
|
<ul>
|
<li>
|
<a href="#plus.downloader.DownloadCompletedCallback">DownloadCompletedCallback</a>: 下载任务完成时的回调</li>
|
<li>
|
<a href="#plus.downloader.DownloadStateChangedCallback">DownloadStateChangedCallback</a>: 下载任务状态变化回调</li>
|
<li>
|
<a href="#plus.downloader.DownloadEnumerateCallback">DownloadEnumerateCallback</a>: 枚举下载任务回调</li>
|
</ul>
|
<h2>权限：</h2>
|
<p>5+功能模块（permissions）</p>
|
<pre class="prettyprint linenums">
|
{
|
// ...
|
"permissions":{
|
// ...
|
"Downloader": {
|
"description": "文件下载，管理文件下载任务"
|
}
|
}
|
}
|
</pre>
|
<h1><a name="plus.downloader.Download">Download</a></h1>
|
<p>Download对象管理一个下载任务</p>
|
<pre class="prettyprint linenums">
|
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();
|
}
|
</pre>
|
<h2>属性：</h2>
|
<ul>
|
<li>
|
<a href="#plus.downloader.Download.id">id</a>: 下载任务的标识</li>
|
<li>
|
<a href="#plus.downloader.Download.url">url</a>: 下载文件的地址</li>
|
<li>
|
<a href="#plus.downloader.Download.state">state</a>: 任务的状态</li>
|
<li>
|
<a href="#plus.downloader.Download.options">options</a>: 下载任务的参数</li>
|
<li>
|
<a href="#plus.downloader.Download.filename">filename</a>: 下载的文件名称</li>
|
<li>
|
<a href="#plus.downloader.Download.downloadedSize">downloadedSize</a>: 已完成下载文件的大小</li>
|
<li>
|
<a href="#plus.downloader.Download.totalSize">totalSize</a>: 下载任务文件的总大小</li>
|
</ul>
|
<h2>方法：</h2>
|
<ul>
|
<li>
|
<a href="#plus.downloader.Download.abort">abort</a>: 取消下载任务</li>
|
<li>
|
<a href="#plus.downloader.Download.addEventListener">addEventListener</a>: 添加下载任务事件监听器</li>
|
<li>
|
<a href="#plus.downloader.Download.getAllResponseHeaders">getAllResponseHeaders</a>: 获取下载请求HTTP响应头部信息</li>
|
<li>
|
<a href="#plus.downloader.Download.getResponseHeader">getResponseHeader</a>: 获取下载请求指定的HTTP响应头部的值</li>
|
<li>
|
<a href="#plus.downloader.Download.pause">pause</a>: 暂停下载任务</li>
|
<li>
|
<a href="#plus.downloader.Download.resume">resume</a>: 恢复暂停的下载任务</li>
|
<li>
|
<a href="#plus.downloader.Download.setRequestHeader">setRequestHeader</a>: 设置下载请求的HTTP头数据</li>
|
<li>
|
<a href="#plus.downloader.Download.start">start</a>: 开始下载任务</li>
|
</ul>
|
<h1><a name="plus.downloader.DownloadEvent">DownloadEvent</a></h1>
|
<p>下载任务事件类型</p>
|
<h2>常量：</h2>
|
<ul><li>"statechanged": <em>(<font class="type">String</font>
|
类型
|
)</em>下载任务状态变化事件<br><p>
|
当下载任务状态发生变化时触发此事件，事件原型参考DownloadStateChangedCallback。
|
</p>
|
</li></ul>
|
<h1><a name="plus.downloader.DownloadState">DownloadState</a></h1>
|
<p>下载任务状态</p>
|
<h2>常量：</h2>
|
<ul>
|
<li>undefined: <em>(<font class="type">undefined</font>
|
类型
|
)</em>下载任务未开始<br><p>
|
通过plus.downloader.createDownload()方法创建下载任务后的初始状态，此时可调用其start()方法开始下载。
|
</p>
|
</li>
|
<li>0: <em>(<font class="type">Number</font>
|
类型
|
)</em>下载任务开始调度<br><p>
|
调用下载任务的start()方法之后处于此状态，此时下载任务处于可调度下载状态。
|
</p>
|
</li>
|
<li>1: <em>(<font class="type">Number</font>
|
类型
|
)</em>下载任务开始请求<br><p>
|
下载任务建立网络连接，发送请求到服务器并等待服务器的响应。
|
</p>
|
</li>
|
<li>2: <em>(<font class="type">Number</font>
|
类型
|
)</em>下载任务请求已经接收<br><p>
|
下载任务网络连接已建立，服务器返回响应，准备传输数据内容。
|
</p>
|
</li>
|
<li>3: <em>(<font class="type">Number</font>
|
类型
|
)</em>下载任务接收数据<br><p>
|
下载任务接收数据，监听statechanged事件时可多次触发此状态。
|
</p>
|
</li>
|
<li>4: <em>(<font class="type">Number</font>
|
类型
|
)</em>下载任务已完成<br><p>
|
下载任务完成数据传输并断开连接，下载成功或失败都会设置为此状态。
|
</p>
|
</li>
|
<li>5: <em>(<font class="type">Number</font>
|
类型
|
)</em>下载任务已暂停<br><p>
|
调用下载任务的pause()方法将任务暂停，此时可调用其resume()方法重新开始下载。
|
</p>
|
</li>
|
<li>-1: <em>(<font class="type">Number</font>
|
类型
|
)</em>枚举任务状态<br><p>
|
非下载任务状态，泛指所有下载任务的状态，用于enumerate()和clear()操作时指定作用于所有下载任务。
|
</p>
|
</li>
|
</ul>
|
<h1><a name="plus.downloader.DownloadOptions">DownloadOptions</a></h1>
|
<p>下载任务参数</p>
|
<pre class="prettyprint linenums">
|
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;
|
}
|
</pre>
|
<h2>说明：</h2>
|
<p class="des">
|
在创建下载任务时设置的参数，如设置下载任务使用的HTTP协议类型、优先级等。
|
</p>
|
<h2>属性：</h2>
|
<ul>
|
<li>method: <em>(<font class="type">String</font>
|
类型
|
)</em>网络请求类型<br><p>
|
支持http协议的“GET”、“POST”，默认为“GET”请求。
|
</p>
|
</li>
|
<li>data: <em>(<font class="type">String</font>
|
类型
|
)</em>POST请求时提交的数据<br><p>
|
仅在网络请求类型method设置为"POST"时有效，"GET"请求时忽略此数据。
|
</p>
|
</li>
|
<li>filename: <em>(<font class="type">String</font>
|
类型
|
)</em>下载文件保存的路径<br><p>
|
保存文件路径仅支持以"_downloads/"、"_doc/"、"_documents/"开头的字符串。
|
文件路径以文件后缀名结尾（如"_doc/download/a.doc"）表明指定保存文件目录及名称，以“/”结尾则认为指定保存文件的目录（此时程序自动生成文件名）。
|
如果指定的文件已经存在，则自动在文件名后面加"(i)"，其中i为数字，如果文件名称后面已经是此格式，则数字i递增，如"download(1).doc"。
|
默认保存目录为（"_downloads"），并自动生成文件名称。
|
</p>
|
</li>
|
<li>priority: <em>(<font class="type">Number</font>
|
类型
|
)</em>下载任务的优先级<br><p>
|
数值类型，数值越大优先级越高，默认优先级值为0。
|
</p>
|
</li>
|
<li>timeout: <em>(<font class="type">Number</font>
|
类型
|
)</em>下载任务超时时间<br><p>
|
数值类型，单位为s(秒)，默认值为120s。
|
超时时间为服务器响应请求的时间（不是下载任务完成的总时间），如果设置为0则表示永远不超时。
|
</p>
|
</li>
|
<li>retry: <em>(<font class="type">Number</font>
|
类型
|
)</em>下载任务重试次数<br><p>
|
数值类型，默认为重试3次。
|
</p>
|
</li>
|
<li>retryInterval: <em>(<font class="type">Number</font>
|
类型
|
)</em>下载任务重试间隔时间<br><p>
|
数值类型，单位为s(秒)，默认值为30s。
|
</p>
|
</li>
|
</ul>
|
<h1><a name="plus.downloader.DownloadCompletedCallback">DownloadCompletedCallback</a></h1>
|
<p>下载任务完成时的回调</p>
|
<pre class="prettyprint linenums">
|
vaoid onCompleted(Download download, Number status) {
|
// Download file complete code
|
}
|
</pre>
|
<h2>说明：</h2>
|
<p class="des">
|
下载任务完成时的回调函数，在下载任务完成时调用。
|
下载任务失败也将触发此回调。
|
</p>
|
<h2>参数：</h2>
|
<ul>
|
<li>download :
|
<em>(
|
<a href="#plus.downloader.Download">Download</a>
|
)
|
必选 </em>下载任务对象<br>
|
</li>
|
<li>status:
|
<em>(
|
<font class="type">Number</font>
|
)
|
必选 </em>下载结果状态码<br>
|
HTTP传输协议状态码，如果未获取传输状态则其值则为0，如下载成功其值通常为200。
|
</li>
|
</ul>
|
<h2>返回值：</h2>
|
<font class="type">void</font>
|
: 无<h1><a name="plus.downloader.DownloadStateChangedCallback">DownloadStateChangedCallback</a></h1>
|
<p>下载任务状态变化回调</p>
|
<pre class="prettyprint linenums">
|
void onStateChanged( Download download, status ) {
|
// Download state changed code.
|
}
|
</pre>
|
<h2>参数：</h2>
|
<ul>
|
<li>download :
|
<em>(
|
<a href="#plus.downloader.Download">Download</a>
|
)
|
必选 </em>下载任务对象<br>
|
</li>
|
<li>status:
|
<em>(
|
<font class="type">Number</font>
|
)
|
必选 </em>下载结果状态码<br>
|
HTTP传输协议状态码，如果未获取传输状态则其值则为0，如下载成功其值通常为200。
|
</li>
|
</ul>
|
<h2>返回值：</h2>
|
<font class="type">void</font>
|
: 无<h1><a name="plus.downloader.DownloadEnumerateCallback">DownloadEnumerateCallback</a></h1>
|
<p>枚举下载任务回调</p>
|
<pre class="prettyprint linenums">
|
void onEnumerated( Download[] downloads ) {
|
// Enumerate success code
|
}
|
</pre>
|
<h2>参数：</h2>
|
<ul><li>downloads:
|
<em>(
|
<font class="type">Array</font>[
|
<font class="type">Download</font>
|
]
|
|
)
|
必选 </em>枚举到的下载任务对象数组<br>
|
</li></ul>
|
<h2>返回值：</h2>
|
<font class="type">void</font>
|
: 无<br><br>
|
</div></body>
|
</html>
|
