# miscservices_request **Repository Path**: geekgaoxiang/miscservices_request ## Basic Information - **Project Name**: miscservices_request - **Description**: Request Sysystem Ability | 上传下载请求服务 - **Primary Language**: C++ - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 198 - **Created**: 2022-05-10 - **Last Updated**: 2022-05-10 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 杂散子系统/Request服务 ## 简介 ### 内容介绍 Request服务向三方应用提供系统下载/上传服务能力，以支撑应用开发者方便、高效地使用以及管理下载/上传业务的功能，包含新建、移除、暂停、恢复以及查询下载/上传任务。 ### 架构图介绍 **图 1** 下载子系统架构图 ![](figures/download_architecture.png "子系统架构图") 系统应用：依赖的系统应用如浏览器等。 三方应用：依赖的第三方应用如淘宝等。 Download API：提供下载功能的接口。 IDL：提供NAPI之间的相互通信。 下载服务：负责下载的具体过程，客户端发起一个下载请求，下载内部创建下载任务，处理下载请求并完成下载任务。 DataAbility能力：用来保存每一次下载的记录。 **图 2** 上传子系统架构图 ![](figures/subsystem_architecture_zh.png "子系统架构图") 扩展/三方 应用：上传功能的客户端，是上传的发起方。 JS接口：对外提供上传功能JS接口。 本地接口：对外提供上传功能本地接口。 上传任务：客户端每发起一个上传请求，上传内部都会创建一个上传任务，用于处理上传请求，转发服务器的上传应答。 Curl适配：对三方库libcurl的一个封装。 获取文件：根据客户端发起上传请求时传入的文件路径获取要上传的文件。 libcurl: 三方库。 DataAbility能力：DataAbility的使用方，用户获取DataAbility文件协议路径下的文件。 ## 目录 ``` /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 # 上传模块的单元测试 ``` ## 说明 ### 接口说明 **表 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

表单元素的值。
### 使用说明 ```js // 导入模块 import request from '@ohos.request'; ``` ```js // 下载服务接口使用说明 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; ``` 1.获取DownloadTask实例 ```js // 使用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)); }) ``` 2.创建监听下载进度 ```js // 开启下载进度监听，使用callback形式返回下载进度结果。 downloadTask.on('progress', (receivedSize, totalSize) => { console.info("download receivedSize :" + receivedSize + " totalSize :" + totalSize); }); ``` 3.创建监听complete事件 ``` // 开启下载任务complete监听，使用callback形式返回。 downloadTask.on('complete', () => { console.info("download task has been completed"); }); ``` 4.创建监听pause事件 ```js // 开启下载任务pause监听，使用callback形式返回。 downloadTask.on('pause', () => { console.info("download task has been paused"); }); ``` 5.创建监听remove事件 ```js // 开启下载任务remove监听，使用callback形式返回。 downloadTask.on('remove', () => { console.info("download task has been removed"); }); ``` 6.创建监听fail事件 ```js // 开启下载任务fail监听，使用callback形式返回错误码。 downloadTask.on('fail', (error) => { console.info("download fail error:" + error); }); ``` 7.关闭监听下载进度 ```js // 关闭下载任务进度监听，使用callback形式返回下载进度结果。 downloadTask.off('progress', (receivedSize, totalSize) => { console.info("download receivedSize :" + receivedSize + " totalSize :" + totalSize); }); ``` 8.关闭监听complete事件 ```js // 关闭下载任务complete监听，使用callback形式返回。 downloadTask.off('complete', () => { console.info("delete complete notification"); }); ``` 9.关闭监听pause事件 ```js // 关闭下载任务pause监听，使用callback形式返回。 downloadTask.off('pause', () => { console.info("delete pause notification"); }); ``` 10.关闭监听pause事件 ```js // 关闭下载任务remove监听，使用callback形式返回。 downloadTask.off('remove', () => { console.info("delete remove notification"); }); ``` 11.关闭监听fail事件 ```js // 关闭下载任务fail监听，使用callback形式返回错误码。 downloadTask.off('fail', (error) => { console.info("remove fail notification error:" + error); }); ``` 12.删除下载任务 ```js // 移除下载的任务，使用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) '); } }); ``` 13.暂停下载 ```js // 暂停下载的任务，使用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) '); }); ``` 14.恢复下载 ```js // 恢复下载的任务，使用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) '); }); ``` 15.查询下载 ```js // 查询下载的任务，使用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) '); }); ``` 16.查询下载的mime type ```js // 查询下载任务的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)); }); ``` ```js // 上传服务接口使用说明 ``` 1.上传文件创建 ```js // 上传一组文件，以及添加移除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; ``` 2.获取上传的UploadTask实例 ```js // 使用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)); }) ``` 3.创建上传任务进度的监听 ```js // 开启上传任务监听，使用callback形式返回上传进度结果。 uploadTask.on('progress', (uploadedSize, totalSize) => { console.info("on progress upload uploadedSize :" + uploadedSize + " totalSize :" + totalSize); }); ``` 4.创建上传的HTTP header response监听事件 ```js // 开启上传任务监听，使用callback形式返回HTTP header response结果。 uploadTask.on('headerReceive', (headers) => { console.info("on headerReceive headers:" + JSON.stringify(headers)); }); ``` 5.创建上传的错误码监听事件 ```js // 开启上传任务监听，使用callback形式返回错误码。 uploadTask.on('fail', (error) => { console.info("on fail error:" + error); }); ``` 6.关闭上传任务进度任务监听 ```js // 关闭上传任务监听，使用callback形式返回上传进度结果。 uploadTask.off('progress', (uploadedSize, totalSize) => { console.info("on progress upload uploadedSize :" + uploadedSize + " totalSize :" + totalSize); }); ``` 7.关闭上传的HTTP header response监听事件 ```js // 关闭上传任务监听，使用callback形式返回HTTP header response结果。 uploadTask.off('headerReceive', (headers) => { console.info("on headerReceive headers:" + JSON.stringify(headers)); }); ``` 8.关闭上传的错误码监听事件 ```js // 关闭上传任务监听，使用callback形式返回错误码。 uploadTask.off('fail', (error) => { console.info("on fail error:" + error); }); ``` 9.删除上传的任务 ```js // 移除上传的任务，使用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) '); } }); ``` ## 相关仓 [miscservices_request](https://gitee.com/openharmony/miscservices_request/tree/master/)