From 3b389732bd9800187520536537041413cdc5c9b9 Mon Sep 17 00:00:00 2001 From: liulinna4 Date: Thu, 10 Mar 2022 19:54:49 +0800 Subject: [PATCH] =?UTF-8?q?IssueNo:#I45HTT:README=E4=BF=AE=E6=94=B9=20Desc?= =?UTF-8?q?ription:README=E4=BF=AE=E6=94=B9=20Sig:SIG=5FBscSoftSrv=20Featu?= =?UTF-8?q?re=20or=20Bugfix:Feature=20Binary=20Source:=20No?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: liulinna4 --- README.en.md | 36 --- README.md | 789 ++------------------------------------------------- README_zh.md | 777 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 801 insertions(+), 801 deletions(-) delete mode 100644 README.en.md create mode 100644 README_zh.md diff --git a/README.en.md b/README.en.md deleted file mode 100644 index 76e183d..0000000 --- a/README.en.md +++ /dev/null @@ -1,36 +0,0 @@ -# miscservices_download - -#### Description -{**When you're done, you can delete the content in this README and update the file with details for others getting started with your repository**} - -#### Software Architecture -Software architecture description - -#### Installation - -1. xxxx -2. xxxx -3. xxxx - -#### Instructions - -1. xxxx -2. xxxx -3. xxxx - -#### Contribution - -1. Fork the repository -2. Create Feat_xxx branch -3. Commit your code -4. Create Pull Request - - -#### Gitee Feature - -1. You can use Readme\_XXX.md to support different languages, such as Readme\_en.md, Readme\_zh.md -2. Gitee blog [blog.gitee.com](https://blog.gitee.com) -3. Explore open source project [https://gitee.com/explore](https://gitee.com/explore) -4. The most valuable open source project [GVP](https://gitee.com/gvp) -5. The manual of Gitee [https://gitee.com/help](https://gitee.com/help) -6. The most popular members [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/) diff --git a/README.md b/README.md index 4013346..76e183d 100644 --- a/README.md +++ b/README.md @@ -1,777 +1,36 @@ # miscservices_download -#### 介绍 +#### Description +{**When you're done, you can delete the content in this README and update the file with details for others getting started with your repository**} -Request组件向三方应用提供系统下载/上传服务能力，以支撑应用开发者方便、高效的使用以及管理下载/上传业务的功能，包含新建、移除、暂停、恢复以及查询下载/上传任务。 +#### Software Architecture +Software architecture description -**图 1** 下载子系统架构图 -![](figures/download_architecture.png "子系统架构图") +#### Installation -#### 仓路径 +1. xxxx +2. xxxx +3. xxxx -/base/miscservices/request +#### Instructions -#### 框架代码介绍 +1. xxxx +2. xxxx +3. xxxx -``` -/base/miscservices/request -├── figures # 构架图 -├── download/ability # 下载服务数据库管理模块 -├── download/etc # 下载服务包含的进程配置文件 -├── interfaces/kits/js/napi # 本组件对外提供的下载服务接口代码 -│ └── download_single # 下载服务的napi接口 -├── download/sa_profile # 下载服务包含的系统服务的配置文件 -├── download/services # 下载系统服务实现 -├── download/utils # 下载服务包含日志打印和公共事件定义的常量 -├── upload/frameworks # 上传服务功能实现 -├── upload/interfaces/kits # 本组件对外提供的上传服务接口代码 -│ ├── js # 本组件js接口定义 -│ └── napi # 上传服务的napi接口 -└── upload/unitest # 上传模块的单元测试 -``` +#### Contribution -#### js 接口及使用说明 +1. Fork the repository +2. Create Feat_xxx branch +3. Commit your code +4. Create Pull Request -1. js 接口 -**表 1** Request组件的主要功能 - - - - - - - - - - - - - - - - - - -

接口名

-

描述

-

download(config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void

-

异步接口，用于文件下载，使用callback形式回调返回DownloadTask实例，该实例代表一个下载任务，用户可以通过该实例操作该下载任务，比如添加progress、complete、fail监听，暂停、恢复、移除和查询下载任务。

-

download(config: DownloadConfig): Promise<DownloadTask>

-

异步接口，用于文件下载，使用promise形式回调返回DownloadTask实例，该实例代表一个下载任务，用户可以通过该实例操作该下载任务，比如添加progress、complete、fail监听，暂停、恢复、移除和查询下载任务。

-

upload(config: UploadConfig, callback: AsyncCallback<UploadTask>): void

-

异步接口，用于上传一组文件，使用callback形式回调返回UploadTask实例，该实例代表一个上传任务，用户可以通过该实例操作该上传任务，比如添加progress、headerReceive、fail监听，移除上传任务。

-

upload(config: UploadConfig): Promise<UploadTask>

-

异步接口，用于上传一组文件，使用promise形式回调返回UploadTask实例，该实例代表一个上传任务，用户可以通过该实例操作该上传任务，比如添加progress、headerReceive、fail监听，移除上传任务。

-
+#### Gitee Feature -**表 2** DownloadTask的主要功能 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

接口名

-

描述

-

on(type: 'progress', callback:(receivedSize: number, totalSize: number) => void): void

-

开启下载任务进度监听，使用callback形式返回下载进度结果。多次调用的场合最后一次调用时传入的callback有效。

-

on(type: 'complete' | 'pause' | 'remove', callback:() => void): void

-

开启下载任务状态：complete、pause、remove监听，使用callback形式返回。多次调用的场合最后一次调用时传入的callback有效。

-

on(type: 'fail', callback:(error: number) => void): void

-

开启下载任务fail监听，使用callback形式返回错误码。多次调用的场合最后一次调用时传入的callback有效。

-

off(type: 'progress', callback?:(receivedSize: number, totalSize: number) => void): void

-

关闭下载任务进度监听，使用callback形式返回结果。

-

off(type: 'complete' | 'pause' | 'remove', callback?:() => void): void

-

关闭下载任务状态：complete、pause、remove监听，使用callback形式返回结果。

-

off(type: 'fail', callback?:(error: number) => void): void

-

关闭下载任务fail监听，使用callback形式返回结果。

-

remove(): Promise<boolean>

-

移除下载任务，异步方法，使用promise形式返回结果。

-

remove(callback: AsyncCallback<boolean>): void

-

移除下载任务，异步方法，使用callback形式返回结果。

-

pause(): Promise<boolean>

-

暂停下载任务，异步方法，使用promise形式返回结果。

-

pause(callback: AsyncCallback<boolean>): void

-

暂停下载任务，异步方法，使用callback形式返回结果。

-

resume(): Promise<boolean>

-

恢复下载任务，异步方法，使用promise形式返回结果。

-

resume(callback: AsyncCallback<boolean>): void

-

恢复下载任务，异步方法，使用callback形式返回结果。

-

query(): Promise<DownloadInfo>

-

查询下载任务，异步方法，使用promise形式返回DownloadInfo。

-

query(callback: AsyncCallback<DownloadInfo>): void

-

查询下载任务，异步方法，使用callback形式返回DownloadInfo。

-

queryMimeType(): Promise<string>

-

查询下载任务的MIME type，异步方法，使用promise形式返回MIME type。

-

queryMimeType(callback: AsyncCallback<string>): void

-

查询下载任务的MIME type，异步方法，使用callback形式返回MIME type。

-
- -**表 3** 参数 DownloadConfig的描述 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

名称

-

类型

-

说明

-

url

-

string

-

目标URL。

-

header

-

Object

-

请求头。

-

enableMetered

-

boolean

-

计费网络时允许下载。

-

enableRoaming

-

boolean

-

网络漫游时允许下载。

-

description

-

string

-

下载任务描述。

-

networkType

-

number

-

指定网络允许下载。

-

filePath

-

string

-

文件保存路径。

-

title

-

string

-

下载任务标题。

-
- -**表 4** 参数 DownloadInfo的描述 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

名称

-

类型

-

说明

-

description

-

string

-

下载任务描述。

-

downloadedBytes

-

number

-

已下载字节数。

-

downloadId

-

number

-

下载任务ID。

-

failedReason

-

number

-

下载任务失败的理由。

-

fileName

-

string

-

保存文件名。

-

filePath

-

string

-

文件保存路径。

-

pausedReason

-

number

-

下载暂停的理由。

-

status

-

number

-

下载任务状态。

-

targetURI

-

string

-

下载任务URL。

-

downloadTitle

-

string

-

下载任务标题。

-

downloadTotalBytes

-

number

-

文件总字节数。

-
- -**表 5** UploadTask的主要功能 - - - - - - - - - - - - - - - - - - - - - - - -

接口名

-

描述

-

on(type: 'progress', callback:AsyncCallback <uploadedSize: number, totalSize: number> => void): void

-

开启上传任务监听，异步方法，使用callback形式返回上传进度结果。多次调用的场合最后一次调用时传入的callback有效。

-

on(type: 'headerReceive', callback: AsyncCallback<object> => void): void

-

开启上传任务监听，异步方法，使用callback形式返回HTTP header response结果。多次调用的场合最后一次调用时传入的callback有效。

-

off(type: 'progress', callback:AsyncCallback<uploadedSize: number, totalSize: number>=> void): void

-

关闭上传任务进度监听，异步方法，使用callback形式返回结果。

-

off(type: 'headerReceive', callback:AsyncCallback<object> => void): void

-

关闭上传任务HTTP Header response监听，异步方法，使用callback形式返回结果。

-

remove(): Promise<boolean>

-

移除上传的任务，异步方法，使用promise形式返回结果。

-

remove(callback: AsyncCallback<boolean>): void

-

移除上传的任务，异步方法，使用callback形式返回结果。

-
- -**表 6** 参数 UploadConfig的描述 - - - - - - - - - - - - - - - - - - - - - - - - - - -

名称

-

类型

-

说明

-

url

-

string

-

目标URL。 -

-

header

-

Object

-

请求头。

-

method

-

string

-

请求方式。

-

files

-

Array<File>

-

本地文件列表信息。

-

data

-

Array<RequestData>

-

上传请求表单列表信息。

-
- -**表 7** File 描述 - - - - - - - - - - - - - - - - - - - - - - -

名称

-

类型

-

说明

-

filename

-

string

-

提交多部分时，请求头中的文件名。

-

name

-

string

-

提交多部分时，表单项目的名称，缺省为file。

-

uri

-

string

-

文件的本地存储路径。 -支持“dataability”和“internal”两种协议类型，但“internal”仅支持临时目录，示例： -dataability:///com.domainname.dataability.persondata/person/10/file.txt -internal://cache/path/to/file.txt

-

type

-

string

-

文件的内容类型，默认根据文件名或路径的后缀获取。

-
- -**表 8** RequestData 描述 - - - - - - - - - - - - - - -

名称

-

类型

-

说明

-

name

-

string

-

表单元素的名称。

-

value

-

string

-

表单元素的值。

-
- -2. js 接口使用说明 - -``` -// 导入模块 -import request from '@ohos.requestability'; - -// 1、下载服务接口使用说明 -let downloadConfig = { - url: 'http://mirror.bjtu.edu.cn/kernel/linux/libs/libc5/libc5.cvs.tar.gz', - header: {}, - enableMetered: true, - enableRoaming: true, - description: 'download libc from mirror site', - networkType: 1, - filePath: '/data/libc5.cvs.tgz', - title: 'download libc', -} -let downloadTask; - -// 使用callback形式回调返回DownloadTask实例。 -request.download(downloadConfig, (err, data) => { - if (err) { - console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); - return; - } - console.info('Success to request the download.); - downloadTask = data; -}); - -// 使用promise形式回调返回DownloadTask实例。 -request.download(downloadConfig).then((data) => { - console.info('Success to request the download.); - downloadTask = data; -}).catch((err) => { - console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); -}) - -// 开启下载进度监听，使用callback形式返回下载进度结果。 -downloadTask.on('progress', (receivedSize, totalSize) => { - console.info("download receivedSize :" + receivedSize + " totalSize :" + totalSize); -}); - -// 开启下载任务complete监听，使用callback形式返回。 -downloadTask.on('complete', () => { - console.info("download task has been completed"); -}); - -// 开启下载任务pause监听，使用callback形式返回。 -downloadTask.on('pause', () => { - console.info("download task has been paused"); -}); - -// 开启下载任务remove监听，使用callback形式返回。 -downloadTask.on('remove', () => { - console.info("download task has been removed"); -}); - -// 开启下载任务fail监听，使用callback形式返回错误码。 -downloadTask.on('fail', (error) => { - console.info("download fail error:" + error); -}); - -// 关闭下载任务进度监听，使用callback形式返回下载进度结果。 -downloadTask.off('progress', (receivedSize, totalSize) => { - console.info("download receivedSize :" + receivedSize + " totalSize :" + totalSize); -}); - -// 关闭下载任务complete监听，使用callback形式返回。 -downloadTask.off('complete', () => { - console.info("delete complete notification"); -}); - -// 关闭下载任务pause监听，使用callback形式返回。 -downloadTask.off('pause', () => { - console.info("delete pause notification"); -}); - -// 关闭下载任务remove监听，使用callback形式返回。 -downloadTask.off('remove', () => { - console.info("delete remove notification"); -}); - -// 关闭下载任务fail监听，使用callback形式返回错误码。 -downloadTask.off('fail', (error) => { - console.info("remove fail notification error:" + error); -}); - -// 移除下载的任务，使用promise形式返回结果。 -downloadTask.remove().then((result) => { - if (result) { - console.info('Success to remove the download task.(promise) '); - } else { - console.error('Failed to remove the download task.(promise) '); - } -}).catch((err) => { - console.error('Failed to remove the download task.(promise) Cause: ' + JSON.stringify(err)); -}); - -// 移除下载的任务，使用callback形式返回结果。 -downloadTask.remove((err, result) => { - if (err) { - console.error('Failed to remove the download task.(callback) Cause: ' + JSON.stringify(err)); - return; - } - if (result) { - console.info('Success to remove the download task.(callback) '); - } else { - console.error('Failed to remove the download task.(callback) '); - } -}); - -// 暂停下载的任务，使用promise形式返回结果。 -downloadTask.pause().then(() => { - console.info('Success to pause the download task.(promise) '); -}).catch((err) => { - console.error('Failed to pause the download task.(promise) Cause: ' + JSON.stringify(err)); -}); - -// 暂停下载的任务，使用callback形式返回结果。 -downloadTask.pause((err) => { - if (err) { - console.error('Failed to pause the download task.(callback) Cause: ' + JSON.stringify(err)); - return; - } - console.info('Success to pause the download task.(callback) '); -}); - -// 恢复下载的任务，使用promise形式返回结果。 -downloadTask.resume().then(() => { - console.info('Success to resume the download task.(promise) '); -}).catch((err) => { - console.error('Failed to resume the download task.(promise) Cause: ' + JSON.stringify(err)); -}); - -// 恢复下载的任务，使用callback形式返回结果。 -downloadTask.resume((err) => { - if (err) { - console.error('Failed to resume the download task.(callback) Cause: ' + JSON.stringify(err)); - return; - } - console.info('Success to resume the download task.(callback) '); -}); - -// 查询下载的任务，使用promise形式返回结果。 -downloadTask.query().then((downloadInfo) => { - console.info('Success to query the download task.(promise) '); -}).catch((err) => { - console.error('Failed to query the download task.(promise) Cause: ' + JSON.stringify(err)); -}); - -// 查询下载的任务，使用callback形式返回结果。 -downloadTask.query((err, downloadInfo) => { - if (err) { - console.error('Failed to query the download task.(callback) Cause: ' + JSON.stringify(err)); - return; - } - console.info('Success to query the download task.(callback) '); -}); - -// 查询下载任务的mime type，使用promise形式返回结果。 -downloadTask.queryMimeType().then((mime) => { - console.info('Success to queryMimeType the download task.(promise) MimeType ' + JSON.stringify(mime)); -}).catch((err) => { - console.error('Failed to queryMimeType the download task.(promise) Cause: ' + JSON.stringify(err)); -}); - -// 查询下载任务的mime type，使用callback形式返回结果。 -downloadTask.queryMimeType((err, mime) => { - if (err) { - console.error('Failed to queryMimeType the download task.(callback) Cause: ' + JSON.stringify(err)); - return; - } - console.info('Success to queryMimeType the download task.(promise) MimeType ' + JSON.stringify(mime)); -}); - -// 2、上传服务接口使用说明 -// 上传一组文件，以及添加移除progress、headerReceive、fail监听，移除上传任务。 -let url = 'http://192.168.2.211/files/'; -let file1 = { filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }; -let file2 = { filename: "test", name: "test", uri: "internal://cache/test.zip", type: "zip" }; -let file3 = { filename: "test", name: "test", uri: "internal://cache/test.mp4", type: "mp4" }; -let file4 = { filename: "test", name: "test", uri: "internal://cache/test.exe", type: "exe" }; -let file5 = { filename: "test", name: "test", uri: "internal://cache/test.pdf", type: "pdf" }; -let file6 = { filename: "test", name: "test", uri: "internal://cache/test.txt", type: "txt" }; -let largeFile = { filename: "test", name: "test", uri: "internal://cache/testLarge.txt", type: "txt" }; -let dataabilityFile = { filename: "test", name: "test", - uri: "dataability://com.test.testApp/person/test.txt", type: "txt" }; -let files = [file1, file2, file3, file4, file5, file6, largeFile, dataabilityFile]; -let data = [{ name: "name123", value: "123" }]; -let uploadTask; - -// 使用callback形式回调返回UploadTask实例。 -request.upload({ url, header, "POST", files, data }, (err, data) => { - if (err) { - console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); - return; - } - console.info('Success to request the upload.); - uploadTask = data; -}); - -// 使用promise形式回调返回UploadTask实例。 -request.upload({ url, header, "POST", files, data }).then((data) => { - console.info('Success to request the upload.); - uploadTask = data; -}).catch((err) => { - console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); -}) - -// 开启上传任务监听，使用callback形式返回上传进度结果。 -uploadTask.on('progress', (uploadedSize, totalSize) => { - console.info("on progress upload uploadedSize :" + uploadedSize + " totalSize :" + totalSize); -}); - -// 开启上传任务监听，使用callback形式返回HTTP header response结果。 -uploadTask.on('headerReceive', (headers) => { - console.info("on headerReceive headers:" + JSON.stringify(headers)); -}); - -// 开启上传任务监听，使用callback形式返回错误码。 -uploadTask.on('fail', (error) => { - console.info("on fail error:" + error); -}); - -// 关闭上传任务监听，使用callback形式返回上传进度结果。 -uploadTask.off('progress', (uploadedSize, totalSize) => { - console.info("on progress upload uploadedSize :" + uploadedSize + " totalSize :" + totalSize); -}); - -// 关闭上传任务监听，使用callback形式返回HTTP header response结果。 -uploadTask.off('headerReceive', (headers) => { - console.info("on headerReceive headers:" + JSON.stringify(headers)); -}); - -// 关闭上传任务监听，使用callback形式返回错误码。 -uploadTask.off('fail', (error) => { - console.info("on fail error:" + error); -}); - -// 移除上传的任务，使用promise形式返回结果。 -uploadTask.remove().then((result) => { - if (result) { - console.info('Success to remove the upload task.(promise) '); - } else { - console.error('Failed to remove the upload task.(promise) '); - } -}).catch((err) => { - console.error('Failed to remove the upload task.(promise) Cause: ' + JSON.stringify(err)); -}); - -// 移除上传的任务，使用callback形式返回结果。 -uploadTask.remove((err, result) => { - if (err) { - console.error('Failed to remove the upload task.(callback) Cause: ' + JSON.stringify(err)); - return; - } - if (result) { - console.info('Success to remove the upload task.(callback) '); - } else { - console.error('Failed to remove the upload task.(callback) '); - } -}); -``` - -#### 本框架编译调试方法 (以rk3568平台为例) - -1. 配置编译参数 -``` -1. 仓库代码下载下来，修改工程名为request，放在源码base/miscservices 目录下 -``` -``` -2. OpenHarmony/productdefine/common/products/rk3568.json中在文件末尾添加 "miscservices:request":{} -``` - -![](figures/build_target.png "step 1") - -``` -3. 在foundation/distributedschedule/samgr/interfaces/innerkits/samgr_proxy/include 的system_ability_definition.h中添加自己服务的id:3706。 -信息：DOWNLOAD_SERVICE_ID = 3706, -``` - -![](figures/service_id.png "step 2") - -2. 编译命令 - -``` -./build.sh --product-name rk3568 --build-target request -``` - -3. 推送 so 文件 - -``` -将工程目录下out/rk3568/miscservices/request下的libdownload_server.z.so推送到system/lib; -将libdownloadsingle.z.so、librequestability.z.so和libupload_lib.z.so推送到system/lib/module下，并确保四个so至少为可读状态。 -``` - -4. 安装download dataability HAP包 - -``` -将工程目录下out/rk3568/obj/base/miscservices/request/download/ability/下的download_dataability.hap安装到rk3568开发板。 -``` - -5. 重启设备 - -#### 参与贡献 - -1. Fork 本仓库 -2. 提交代码 -3. 新建 Pull Request -4. commit 完成即可 \ No newline at end of file +1. You can use Readme\_XXX.md to support different languages, such as Readme\_en.md, Readme\_zh.md +2. Gitee blog [blog.gitee.com](https://blog.gitee.com) +3. Explore open source project [https://gitee.com/explore](https://gitee.com/explore) +4. The most valuable open source project [GVP](https://gitee.com/gvp) +5. The manual of Gitee [https://gitee.com/help](https://gitee.com/help) +6. The most popular members [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/) diff --git a/README_zh.md b/README_zh.md new file mode 100644 index 0000000..4013346 --- /dev/null +++ b/README_zh.md @@ -0,0 +1,777 @@ +# miscservices_download + +#### 介绍 + +Request组件向三方应用提供系统下载/上传服务能力，以支撑应用开发者方便、高效的使用以及管理下载/上传业务的功能，包含新建、移除、暂停、恢复以及查询下载/上传任务。 + +**图 1** 下载子系统架构图 +![](figures/download_architecture.png "子系统架构图") + +#### 仓路径 + +/base/miscservices/request + +#### 框架代码介绍 + +``` +/base/miscservices/request +├── figures # 构架图 +├── download/ability # 下载服务数据库管理模块 +├── download/etc # 下载服务包含的进程配置文件 +├── interfaces/kits/js/napi # 本组件对外提供的下载服务接口代码 +│ └── download_single # 下载服务的napi接口 +├── download/sa_profile # 下载服务包含的系统服务的配置文件 +├── download/services # 下载系统服务实现 +├── download/utils # 下载服务包含日志打印和公共事件定义的常量 +├── upload/frameworks # 上传服务功能实现 +├── upload/interfaces/kits # 本组件对外提供的上传服务接口代码 +│ ├── js # 本组件js接口定义 +│ └── napi # 上传服务的napi接口 +└── upload/unitest # 上传模块的单元测试 +``` + +#### js 接口及使用说明 + +1. js 接口 + +**表 1** Request组件的主要功能 + + + + + + + + + + + + + + + + + + +

接口名

+

描述

+

download(config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void

+

异步接口，用于文件下载，使用callback形式回调返回DownloadTask实例，该实例代表一个下载任务，用户可以通过该实例操作该下载任务，比如添加progress、complete、fail监听，暂停、恢复、移除和查询下载任务。

+

download(config: DownloadConfig): Promise<DownloadTask>

+

异步接口，用于文件下载，使用promise形式回调返回DownloadTask实例，该实例代表一个下载任务，用户可以通过该实例操作该下载任务，比如添加progress、complete、fail监听，暂停、恢复、移除和查询下载任务。

+

upload(config: UploadConfig, callback: AsyncCallback<UploadTask>): void

+

异步接口，用于上传一组文件，使用callback形式回调返回UploadTask实例，该实例代表一个上传任务，用户可以通过该实例操作该上传任务，比如添加progress、headerReceive、fail监听，移除上传任务。

+

upload(config: UploadConfig): Promise<UploadTask>

+

异步接口，用于上传一组文件，使用promise形式回调返回UploadTask实例，该实例代表一个上传任务，用户可以通过该实例操作该上传任务，比如添加progress、headerReceive、fail监听，移除上传任务。

+
+ +**表 2** DownloadTask的主要功能 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

接口名

+

描述

+

on(type: 'progress', callback:(receivedSize: number, totalSize: number) => void): void

+

开启下载任务进度监听，使用callback形式返回下载进度结果。多次调用的场合最后一次调用时传入的callback有效。

+

on(type: 'complete' | 'pause' | 'remove', callback:() => void): void

+

开启下载任务状态：complete、pause、remove监听，使用callback形式返回。多次调用的场合最后一次调用时传入的callback有效。

+

on(type: 'fail', callback:(error: number) => void): void

+

开启下载任务fail监听，使用callback形式返回错误码。多次调用的场合最后一次调用时传入的callback有效。

+

off(type: 'progress', callback?:(receivedSize: number, totalSize: number) => void): void

+

关闭下载任务进度监听，使用callback形式返回结果。

+

off(type: 'complete' | 'pause' | 'remove', callback?:() => void): void

+

关闭下载任务状态：complete、pause、remove监听，使用callback形式返回结果。

+

off(type: 'fail', callback?:(error: number) => void): void

+

关闭下载任务fail监听，使用callback形式返回结果。

+

remove(): Promise<boolean>

+

移除下载任务，异步方法，使用promise形式返回结果。

+

remove(callback: AsyncCallback<boolean>): void

+

移除下载任务，异步方法，使用callback形式返回结果。

+

pause(): Promise<boolean>

+

暂停下载任务，异步方法，使用promise形式返回结果。

+

pause(callback: AsyncCallback<boolean>): void

+

暂停下载任务，异步方法，使用callback形式返回结果。

+

resume(): Promise<boolean>

+

恢复下载任务，异步方法，使用promise形式返回结果。

+

resume(callback: AsyncCallback<boolean>): void

+

恢复下载任务，异步方法，使用callback形式返回结果。

+

query(): Promise<DownloadInfo>

+

查询下载任务，异步方法，使用promise形式返回DownloadInfo。

+

query(callback: AsyncCallback<DownloadInfo>): void

+

查询下载任务，异步方法，使用callback形式返回DownloadInfo。

+

queryMimeType(): Promise<string>

+

查询下载任务的MIME type，异步方法，使用promise形式返回MIME type。

+

queryMimeType(callback: AsyncCallback<string>): void

+

查询下载任务的MIME type，异步方法，使用callback形式返回MIME type。

+
+ +**表 3** 参数 DownloadConfig的描述 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

名称

+

类型

+

说明

+

url

+

string

+

目标URL。

+

header

+

Object

+

请求头。

+

enableMetered

+

boolean

+

计费网络时允许下载。

+

enableRoaming

+

boolean

+

网络漫游时允许下载。

+

description

+

string

+

下载任务描述。

+

networkType

+

number

+

指定网络允许下载。

+

filePath

+

string

+

文件保存路径。

+

title

+

string

+

下载任务标题。

+
+ +**表 4** 参数 DownloadInfo的描述 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

名称

+

类型

+

说明

+

description

+

string

+

下载任务描述。

+

downloadedBytes

+

number

+

已下载字节数。

+

downloadId

+

number

+

下载任务ID。

+

failedReason

+

number

+

下载任务失败的理由。

+

fileName

+

string

+

保存文件名。

+

filePath

+

string

+

文件保存路径。

+

pausedReason

+

number

+

下载暂停的理由。

+

status

+

number

+

下载任务状态。

+

targetURI

+

string

+

下载任务URL。

+

downloadTitle

+

string

+

下载任务标题。

+

downloadTotalBytes

+

number

+

文件总字节数。

+
+ +**表 5** UploadTask的主要功能 + + + + + + + + + + + + + + + + + + + + + + + +

接口名

+

描述

+

on(type: 'progress', callback:AsyncCallback <uploadedSize: number, totalSize: number> => void): void

+

开启上传任务监听，异步方法，使用callback形式返回上传进度结果。多次调用的场合最后一次调用时传入的callback有效。

+

on(type: 'headerReceive', callback: AsyncCallback<object> => void): void

+

开启上传任务监听，异步方法，使用callback形式返回HTTP header response结果。多次调用的场合最后一次调用时传入的callback有效。

+

off(type: 'progress', callback:AsyncCallback<uploadedSize: number, totalSize: number>=> void): void

+

关闭上传任务进度监听，异步方法，使用callback形式返回结果。

+

off(type: 'headerReceive', callback:AsyncCallback<object> => void): void

+

关闭上传任务HTTP Header response监听，异步方法，使用callback形式返回结果。

+

remove(): Promise<boolean>

+

移除上传的任务，异步方法，使用promise形式返回结果。

+

remove(callback: AsyncCallback<boolean>): void

+

移除上传的任务，异步方法，使用callback形式返回结果。

+
+ +**表 6** 参数 UploadConfig的描述 + + + + + + + + + + + + + + + + + + + + + + + + + + +

名称

+

类型

+

说明

+

url

+

string

+

目标URL。 +

+

header

+

Object

+

请求头。

+

method

+

string

+

请求方式。

+

files

+

Array<File>

+

本地文件列表信息。

+

data

+

Array<RequestData>

+

上传请求表单列表信息。

+
+ +**表 7** File 描述 + + + + + + + + + + + + + + + + + + + + + + +

名称

+

类型

+

说明

+

filename

+

string

+

提交多部分时，请求头中的文件名。

+

name

+

string

+

提交多部分时，表单项目的名称，缺省为file。

+

uri

+

string

+

文件的本地存储路径。 +支持“dataability”和“internal”两种协议类型，但“internal”仅支持临时目录，示例： +dataability:///com.domainname.dataability.persondata/person/10/file.txt +internal://cache/path/to/file.txt

+

type

+

string

+

文件的内容类型，默认根据文件名或路径的后缀获取。

+
+ +**表 8** RequestData 描述 + + + + + + + + + + + + + + +

名称

+

类型

+

说明

+

name

+

string

+

表单元素的名称。

+

value

+

string

+

表单元素的值。

+
+ +2. js 接口使用说明 + +``` +// 导入模块 +import request from '@ohos.requestability'; + +// 1、下载服务接口使用说明 +let downloadConfig = { + url: 'http://mirror.bjtu.edu.cn/kernel/linux/libs/libc5/libc5.cvs.tar.gz', + header: {}, + enableMetered: true, + enableRoaming: true, + description: 'download libc from mirror site', + networkType: 1, + filePath: '/data/libc5.cvs.tgz', + title: 'download libc', +} +let downloadTask; + +// 使用callback形式回调返回DownloadTask实例。 +request.download(downloadConfig, (err, data) => { + if (err) { + console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); + return; + } + console.info('Success to request the download.); + downloadTask = data; +}); + +// 使用promise形式回调返回DownloadTask实例。 +request.download(downloadConfig).then((data) => { + console.info('Success to request the download.); + downloadTask = data; +}).catch((err) => { + console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); +}) + +// 开启下载进度监听，使用callback形式返回下载进度结果。 +downloadTask.on('progress', (receivedSize, totalSize) => { + console.info("download receivedSize :" + receivedSize + " totalSize :" + totalSize); +}); + +// 开启下载任务complete监听，使用callback形式返回。 +downloadTask.on('complete', () => { + console.info("download task has been completed"); +}); + +// 开启下载任务pause监听，使用callback形式返回。 +downloadTask.on('pause', () => { + console.info("download task has been paused"); +}); + +// 开启下载任务remove监听，使用callback形式返回。 +downloadTask.on('remove', () => { + console.info("download task has been removed"); +}); + +// 开启下载任务fail监听，使用callback形式返回错误码。 +downloadTask.on('fail', (error) => { + console.info("download fail error:" + error); +}); + +// 关闭下载任务进度监听，使用callback形式返回下载进度结果。 +downloadTask.off('progress', (receivedSize, totalSize) => { + console.info("download receivedSize :" + receivedSize + " totalSize :" + totalSize); +}); + +// 关闭下载任务complete监听，使用callback形式返回。 +downloadTask.off('complete', () => { + console.info("delete complete notification"); +}); + +// 关闭下载任务pause监听，使用callback形式返回。 +downloadTask.off('pause', () => { + console.info("delete pause notification"); +}); + +// 关闭下载任务remove监听，使用callback形式返回。 +downloadTask.off('remove', () => { + console.info("delete remove notification"); +}); + +// 关闭下载任务fail监听，使用callback形式返回错误码。 +downloadTask.off('fail', (error) => { + console.info("remove fail notification error:" + error); +}); + +// 移除下载的任务，使用promise形式返回结果。 +downloadTask.remove().then((result) => { + if (result) { + console.info('Success to remove the download task.(promise) '); + } else { + console.error('Failed to remove the download task.(promise) '); + } +}).catch((err) => { + console.error('Failed to remove the download task.(promise) Cause: ' + JSON.stringify(err)); +}); + +// 移除下载的任务，使用callback形式返回结果。 +downloadTask.remove((err, result) => { + if (err) { + console.error('Failed to remove the download task.(callback) Cause: ' + JSON.stringify(err)); + return; + } + if (result) { + console.info('Success to remove the download task.(callback) '); + } else { + console.error('Failed to remove the download task.(callback) '); + } +}); + +// 暂停下载的任务，使用promise形式返回结果。 +downloadTask.pause().then(() => { + console.info('Success to pause the download task.(promise) '); +}).catch((err) => { + console.error('Failed to pause the download task.(promise) Cause: ' + JSON.stringify(err)); +}); + +// 暂停下载的任务，使用callback形式返回结果。 +downloadTask.pause((err) => { + if (err) { + console.error('Failed to pause the download task.(callback) Cause: ' + JSON.stringify(err)); + return; + } + console.info('Success to pause the download task.(callback) '); +}); + +// 恢复下载的任务，使用promise形式返回结果。 +downloadTask.resume().then(() => { + console.info('Success to resume the download task.(promise) '); +}).catch((err) => { + console.error('Failed to resume the download task.(promise) Cause: ' + JSON.stringify(err)); +}); + +// 恢复下载的任务，使用callback形式返回结果。 +downloadTask.resume((err) => { + if (err) { + console.error('Failed to resume the download task.(callback) Cause: ' + JSON.stringify(err)); + return; + } + console.info('Success to resume the download task.(callback) '); +}); + +// 查询下载的任务，使用promise形式返回结果。 +downloadTask.query().then((downloadInfo) => { + console.info('Success to query the download task.(promise) '); +}).catch((err) => { + console.error('Failed to query the download task.(promise) Cause: ' + JSON.stringify(err)); +}); + +// 查询下载的任务，使用callback形式返回结果。 +downloadTask.query((err, downloadInfo) => { + if (err) { + console.error('Failed to query the download task.(callback) Cause: ' + JSON.stringify(err)); + return; + } + console.info('Success to query the download task.(callback) '); +}); + +// 查询下载任务的mime type，使用promise形式返回结果。 +downloadTask.queryMimeType().then((mime) => { + console.info('Success to queryMimeType the download task.(promise) MimeType ' + JSON.stringify(mime)); +}).catch((err) => { + console.error('Failed to queryMimeType the download task.(promise) Cause: ' + JSON.stringify(err)); +}); + +// 查询下载任务的mime type，使用callback形式返回结果。 +downloadTask.queryMimeType((err, mime) => { + if (err) { + console.error('Failed to queryMimeType the download task.(callback) Cause: ' + JSON.stringify(err)); + return; + } + console.info('Success to queryMimeType the download task.(promise) MimeType ' + JSON.stringify(mime)); +}); + +// 2、上传服务接口使用说明 +// 上传一组文件，以及添加移除progress、headerReceive、fail监听，移除上传任务。 +let url = 'http://192.168.2.211/files/'; +let file1 = { filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }; +let file2 = { filename: "test", name: "test", uri: "internal://cache/test.zip", type: "zip" }; +let file3 = { filename: "test", name: "test", uri: "internal://cache/test.mp4", type: "mp4" }; +let file4 = { filename: "test", name: "test", uri: "internal://cache/test.exe", type: "exe" }; +let file5 = { filename: "test", name: "test", uri: "internal://cache/test.pdf", type: "pdf" }; +let file6 = { filename: "test", name: "test", uri: "internal://cache/test.txt", type: "txt" }; +let largeFile = { filename: "test", name: "test", uri: "internal://cache/testLarge.txt", type: "txt" }; +let dataabilityFile = { filename: "test", name: "test", + uri: "dataability://com.test.testApp/person/test.txt", type: "txt" }; +let files = [file1, file2, file3, file4, file5, file6, largeFile, dataabilityFile]; +let data = [{ name: "name123", value: "123" }]; +let uploadTask; + +// 使用callback形式回调返回UploadTask实例。 +request.upload({ url, header, "POST", files, data }, (err, data) => { + if (err) { + console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); + return; + } + console.info('Success to request the upload.); + uploadTask = data; +}); + +// 使用promise形式回调返回UploadTask实例。 +request.upload({ url, header, "POST", files, data }).then((data) => { + console.info('Success to request the upload.); + uploadTask = data; +}).catch((err) => { + console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); +}) + +// 开启上传任务监听，使用callback形式返回上传进度结果。 +uploadTask.on('progress', (uploadedSize, totalSize) => { + console.info("on progress upload uploadedSize :" + uploadedSize + " totalSize :" + totalSize); +}); + +// 开启上传任务监听，使用callback形式返回HTTP header response结果。 +uploadTask.on('headerReceive', (headers) => { + console.info("on headerReceive headers:" + JSON.stringify(headers)); +}); + +// 开启上传任务监听，使用callback形式返回错误码。 +uploadTask.on('fail', (error) => { + console.info("on fail error:" + error); +}); + +// 关闭上传任务监听，使用callback形式返回上传进度结果。 +uploadTask.off('progress', (uploadedSize, totalSize) => { + console.info("on progress upload uploadedSize :" + uploadedSize + " totalSize :" + totalSize); +}); + +// 关闭上传任务监听，使用callback形式返回HTTP header response结果。 +uploadTask.off('headerReceive', (headers) => { + console.info("on headerReceive headers:" + JSON.stringify(headers)); +}); + +// 关闭上传任务监听，使用callback形式返回错误码。 +uploadTask.off('fail', (error) => { + console.info("on fail error:" + error); +}); + +// 移除上传的任务，使用promise形式返回结果。 +uploadTask.remove().then((result) => { + if (result) { + console.info('Success to remove the upload task.(promise) '); + } else { + console.error('Failed to remove the upload task.(promise) '); + } +}).catch((err) => { + console.error('Failed to remove the upload task.(promise) Cause: ' + JSON.stringify(err)); +}); + +// 移除上传的任务，使用callback形式返回结果。 +uploadTask.remove((err, result) => { + if (err) { + console.error('Failed to remove the upload task.(callback) Cause: ' + JSON.stringify(err)); + return; + } + if (result) { + console.info('Success to remove the upload task.(callback) '); + } else { + console.error('Failed to remove the upload task.(callback) '); + } +}); +``` + +#### 本框架编译调试方法 (以rk3568平台为例) + +1. 配置编译参数 +``` +1. 仓库代码下载下来，修改工程名为request，放在源码base/miscservices 目录下 +``` +``` +2. OpenHarmony/productdefine/common/products/rk3568.json中在文件末尾添加 "miscservices:request":{} +``` + +![](figures/build_target.png "step 1") + +``` +3. 在foundation/distributedschedule/samgr/interfaces/innerkits/samgr_proxy/include 的system_ability_definition.h中添加自己服务的id:3706。 +信息：DOWNLOAD_SERVICE_ID = 3706, +``` + +![](figures/service_id.png "step 2") + +2. 编译命令 + +``` +./build.sh --product-name rk3568 --build-target request +``` + +3. 推送 so 文件 + +``` +将工程目录下out/rk3568/miscservices/request下的libdownload_server.z.so推送到system/lib; +将libdownloadsingle.z.so、librequestability.z.so和libupload_lib.z.so推送到system/lib/module下，并确保四个so至少为可读状态。 +``` + +4. 安装download dataability HAP包 + +``` +将工程目录下out/rk3568/obj/base/miscservices/request/download/ability/下的download_dataability.hap安装到rk3568开发板。 +``` + +5. 重启设备 + +#### 参与贡献 + +1. Fork 本仓库 +2. 提交代码 +3. 新建 Pull Request +4. commit 完成即可 \ No newline at end of file