miscservices_request/README_zh.md

miscservices_download

介绍

Request组件向三方应用提供系统下载/上传服务能力，以支撑应用开发者方便、高效的使用以及管理下载/上传业务的功能，包含新建、移除、暂停、恢复以及查询下载/上传任务。

图 1 下载子系统架构图

仓路径

/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":{}

3. 在foundation/distributedschedule/samgr/interfaces/innerkits/samgr_proxy/include 的system_ability_definition.h中添加自己服务的id:3706。 
信息：DOWNLOAD_SERVICE_ID = 3706,

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 完成即可