request模块给应用提供上传下载文件、后台代理传输的基础功能。

* request暂不支持在Extension中调用。

说明

本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

## 导入模块

PhonePC/2in1TabletTVWearable



```
1. import { request } from '@kit.BasicServicesKit';
```

## 常量

PhonePC/2in1TabletTVWearable

**系统能力**：SystemCapability.MiscServices.Download

说明

**网络类型**：下载支持自定义网络类型，可以在[DownloadConfig](/consumer/cn/doc/harmonyos-references/js-apis-request#downloadconfig)中通过networkType配置成以下网络类型。

**下载任务错误码**：下载[on('fail')](/consumer/cn/doc/harmonyos-references/js-apis-request#onfail7)事件callback的错误参数、[getTaskInfo](/consumer/cn/doc/harmonyos-references/js-apis-request#gettaskinfo9)返回值的failedReason字段取值。

**下载任务暂停原因**：下载相关[getTaskInfo](/consumer/cn/doc/harmonyos-references/js-apis-request#gettaskinfo9)返回值的pausedReason字段取值。

**下载任务状态码**：下载相关[getTaskInfo](/consumer/cn/doc/harmonyos-references/js-apis-request#gettaskinfo9)返回值的status字段取值。

展开

| 名称 | 类型 | 值 | 说明 |
| --- | --- | --- | --- |
| EXCEPTION\_PERMISSION9+ | number | 201 | 通用错误码：权限校验失败。 |
| EXCEPTION\_PARAMCHECK9+ | number | 401 | 通用错误码：参数检查失败。 |
| EXCEPTION\_UNSUPPORTED9+ | number | 801 | 通用错误码：该设备不支持此API。 |
| EXCEPTION\_FILEIO9+ | number | 13400001 | 特有错误码：文件操作异常。 |
| EXCEPTION\_FILEPATH9+ | number | 13400002 | 特有错误码：文件路径异常。 |
| EXCEPTION\_SERVICE9+ | number | 13400003 | 特有错误码：服务异常。 |
| EXCEPTION\_OTHERS9+ | number | 13499999 | 特有错误码：其他错误。 |
| NETWORK\_MOBILE | number | 0x00000001 | 网络类型：使用蜂窝网络时允许下载的位标志。 |
| NETWORK\_WIFI | number | 0x00010000 | 网络类型：使用WLAN时允许下载的位标志。 |
| ERROR\_CANNOT\_RESUME7+ | number | 0 | 下载任务错误码：网络原因导致恢复下载失败。 |
| ERROR\_DEVICE\_NOT\_FOUND7+ | number | 1 | 下载任务错误码：找不到SD卡等存储设备。 |
| ERROR\_FILE\_ALREADY\_EXISTS7+ | number | 2 | 下载任务错误码：要下载的文件已存在，下载会话无法覆盖现有文件。 |
| ERROR\_FILE\_ERROR7+ | number | 3 | 下载任务错误码：文件操作失败。 |
| ERROR\_HTTP\_DATA\_ERROR7+ | number | 4 | 下载任务错误码：HTTP传输失败。 |
| ERROR\_INSUFFICIENT\_SPACE7+ | number | 5 | 下载任务错误码：存储空间不足。 |
| ERROR\_TOO\_MANY\_REDIRECTS7+ | number | 6 | 下载任务错误码：网络重定向过多导致的错误。 |
| ERROR\_UNHANDLED\_HTTP\_CODE7+ | number | 7 | 下载任务错误码：无法识别的HTTP代码。 |
| ERROR\_UNKNOWN7+ | number | 8 | 下载任务错误码：未知错误。  例如：API version 12及以下版本，系统仅支持串行地尝试连接域名相关IP，不支持单个IP的连接时间控制。若DNS返回的首个IP被阻塞，可能会由于握手超时导致ERROR\_UNKNOWN错误。 |
| ERROR\_OFFLINE9+ | number | 9 | 下载任务错误码：网络未连接。 |
| ERROR\_UNSUPPORTED\_NETWORK\_TYPE9+ | number | 10 | 下载任务错误码：网络类型不匹配。 |
| PAUSED\_QUEUED\_FOR\_WIFI7+ | number | 0 | 下载任务暂停原因：文件大小超过了使用蜂窝网络会话允许的最大值，下载被暂停并等待WLAN连接。 |
| PAUSED\_WAITING\_FOR\_NETWORK7+ | number | 1 | 下载任务暂停原因：网络问题导致下载暂停。  例如：网络断开。 |
| PAUSED\_WAITING\_TO\_RETRY7+ | number | 2 | 下载任务暂停原因：网络错误导致下载会话将被重试。 |
| PAUSED\_BY\_USER9+ | number | 3 | 下载任务暂停原因：用户暂停会话。 |
| PAUSED\_UNKNOWN7+ | number | 4 | 下载任务暂停原因：未知原因导致暂停下载。 |
| SESSION\_SUCCESSFUL7+ | number | 0 | 下载任务状态码：下载会话已完成。 |
| SESSION\_RUNNING7+ | number | 1 | 下载任务状态码：下载会话正在进行中。 |
| SESSION\_PENDING7+ | number | 2 | 下载任务状态码：下载会话正在被调度中。 |
| SESSION\_PAUSED7+ | number | 3 | 下载任务状态码：下载会话已暂停。 |
| SESSION\_FAILED7+ | number | 4 | 下载任务状态码：下载会话已失败，将不会重试。 |

## request.uploadFile9+

PhonePC/2in1TabletTVWearable

uploadFile(context: BaseContext, config: UploadConfig): Promise<UploadTask>

创建并启动一个上传任务，使用Promise异步回调，支持HTTP协议。通过[on('complete'|'fail')](/consumer/cn/doc/harmonyos-references/js-apis-request#oncomplete--fail9)可获取任务上传时的成功信息或错误信息。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Upload

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| context | [BaseContext](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-inner-application-basecontext) | 是 | 基于应用程序的上下文。 |
| config | [UploadConfig](/consumer/cn/doc/harmonyos-references/js-apis-request#uploadconfig) | 是 | 上传的配置信息。 |

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<[UploadTask](/consumer/cn/doc/harmonyos-references/js-apis-request#uploadtask)> | 使用Promise方式，异步返回上传任务UploadTask的Promise对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |
| 401 | The parameters check fails. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |
| 13400002 | File path not supported or invalid. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let uploadTask: request.UploadTask;
7. let uploadConfig: request.UploadConfig = {
8. url: 'http://www.example.com', // 需要手动将url替换为真实服务器的HTTP协议地址
9. header: { 'Accept': '*/*' },
10. method: "POST",
11. files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "image/jpeg" }], // 建议type填写HTTP协议规范的MIME类型
12. data: [{ name: "name123", value: "123" }],
13. };
14. try {
15. request.uploadFile(context, uploadConfig).then((data: request.UploadTask) => {
16. uploadTask = data;
17. }).catch((err: BusinessError) => {
18. console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`);
19. });
20. } catch (err) {
21. console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`);
22. }
```

## request.uploadFile9+

PhonePC/2in1TabletTVWearable

uploadFile(context: BaseContext, config: UploadConfig, callback: AsyncCallback<UploadTask>): void

创建并启动一个上传任务，使用callback异步回调，支持HTTP协议。通过[on('complete'|'fail')](/consumer/cn/doc/harmonyos-references/js-apis-request#oncomplete--fail9)可获取任务上传时的成功信息或错误信息。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Upload

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| context | [BaseContext](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-inner-application-basecontext) | 是 | 基于应用程序的上下文。 |
| config | [UploadConfig](/consumer/cn/doc/harmonyos-references/js-apis-request#uploadconfig) | 是 | 上传的配置信息。 |
| callback | AsyncCallback<[UploadTask](/consumer/cn/doc/harmonyos-references/js-apis-request#uploadtask)> | 是 | 回调函数，异步返回UploadTask对象。当上传成功，err为undefined，data为获取到的UploadTask对象；否则为错误对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |
| 401 | The parameters check fails. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |
| 13400002 | File path not supported or invalid. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let uploadTask: request.UploadTask;
7. let uploadConfig: request.UploadConfig = {
8. url: 'http://www.example.com', // 需要手动将url替换为真实服务器的HTTP协议地址
9. header: { 'Accept': '*/*' },
10. method: "POST",
11. files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "image/jpeg" }], // 建议type填写HTTP协议规范的MIME类型
12. data: [{ name: "name123", value: "123" }],
13. };
14. try {
15. request.uploadFile(context, uploadConfig, (err: BusinessError, data: request.UploadTask) => {
16. if (err) {
17. console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`);
18. return;
19. }
20. uploadTask = data;
21. });
22. } catch (err) {
23. console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`);
24. }
```

## request.upload(deprecated)

PhonePC/2in1TabletTVWearable

upload(config: UploadConfig): Promise<UploadTask>

创建并启动一个上传任务，使用Promise异步回调。

**模型约束**：此接口仅可在FA模型下使用。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Upload

说明

从API version 6 开始支持，从API version 9 开始废弃，建议使用[request.uploadFile](/consumer/cn/doc/harmonyos-references/js-apis-request#requestuploadfile9)替代。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| config | [UploadConfig](/consumer/cn/doc/harmonyos-references/js-apis-request#uploadconfig) | 是 | 上传的配置信息。 |

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<[UploadTask](/consumer/cn/doc/harmonyos-references/js-apis-request#uploadtask)> | 使用Promise方式，异步返回上传任务UploadTask的Promise对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. let uploadTask: request.UploadTask;
2. let uploadConfig: request.UploadConfig = {
3. url: 'http://www.example.com', // 需要手动将url替换为真实服务器的HTTP协议地址
4. header: { 'Accept': '*/*' },
5. method: "POST",
6. files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "image/jpeg" }], // 建议type填写HTTP协议规范的MIME类型
7. data: [{ name: "name123", value: "123" }],
8. };
9. request.upload(uploadConfig).then((data: request.UploadTask) => {
10. uploadTask = data;
11. }).catch((err: BusinessError) => {
12. console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`);
13. })
```

## request.upload(deprecated)

PhonePC/2in1TabletTVWearable

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

创建并启动一个上传任务，使用callback异步回调。

**模型约束**：此接口仅可在FA模型下使用。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Upload

说明

从API version 6 开始支持，从API version 9 开始废弃，建议使用[request.uploadFile](/consumer/cn/doc/harmonyos-references/js-apis-request#requestuploadfile9)替代。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| config | [UploadConfig](/consumer/cn/doc/harmonyos-references/js-apis-request#uploadconfig) | 是 | 上传的配置信息。 |
| callback | AsyncCallback<[UploadTask](/consumer/cn/doc/harmonyos-references/js-apis-request#uploadtask)> | 是 | 回调函数，异步返回UploadTask对象。当上传成功，err为undefined，data为获取到的UploadTask对象；否则为错误对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. let uploadTask: request.UploadTask;
2. let uploadConfig: request.UploadConfig = {
3. url: 'http://www.example.com', // 需要手动将url替换为真实服务器的HTTP协议地址
4. header: { 'Accept': '*/*' },
5. method: "POST",
6. files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "image/jpeg" }], // 建议type填写HTTP协议规范的MIME类型
7. data: [{ name: "name123", value: "123" }],
8. };
9. request.upload(uploadConfig, (err: BusinessError, data: request.UploadTask) => {
10. if (err) {
11. console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`);
12. return;
13. }
14. uploadTask = data;
15. });
```

## UploadTask

PhonePC/2in1TabletTVWearable

上传任务，使用下列方法前，需要先获取UploadTask对象，promise形式通过[request.uploadFile](/consumer/cn/doc/harmonyos-references/js-apis-request#requestuploadfile9)获取，callback形式通过[request.uploadFile](/consumer/cn/doc/harmonyos-references/js-apis-request#requestuploadfile9-1)获取。

### on('progress')

PhonePC/2in1TabletTVWearable

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

订阅上传任务进度事件，使用callback异步回调。

**系统能力**：SystemCapability.MiscServices.Upload

说明

应用处于后台时，为满足功耗性能要求，不支持调用此接口进行回调。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 订阅的事件类型。取值为'progress'，表示上传的进度信息，任务进度有进展时触发该事件。 |
| callback | function | 是 | 上传任务进度的回调函数，返回已上传文件大小和上传文件总大小。 |

回调函数的参数：

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| uploadedSize | number | 是 | 当前已上传文件大小，单位为字节（B）。 |
| totalSize | number | 是 | 上传文件的总大小，单位为字节（B）。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | The parameters check fails. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. let upProgressCallback = (uploadedSize: number, totalSize: number) => {
2. console.info("upload totalSize:" + totalSize + "  uploadedSize:" + uploadedSize);
3. };
4. uploadTask.on('progress', upProgressCallback);
```

### on('headerReceive')7+

PhonePC/2in1TabletTVWearable

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

订阅上传任务HTTP响应事件，使用callback异步回调。

**系统能力**：SystemCapability.MiscServices.Upload

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 订阅的事件类型。  - 取值为'headerReceive'，HTTP请求接收到响应时触发该事件。 |
| callback | function | 是 | HTTP Response事件的回调函数，返回响应请求内容。 |

回调函数的参数：

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| header | object | 是 | HTTP响应。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | The parameters check fails. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. let headerCallback = (headers: object) => {
2. console.info("upOnHeader headers:" + JSON.stringify(headers));
3. };
4. uploadTask.on('headerReceive', headerCallback);
```

### on('complete' | 'fail')9+

PhonePC/2in1TabletTVWearable

on(type: 'complete' | 'fail', callback: Callback<Array<TaskState>>): void

订阅上传任务完成或失败事件，使用callback异步回调。

**系统能力**：SystemCapability.MiscServices.Upload

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 订阅的事件类型，支持的事件包括：'complete'|'fail'。  - 'complete'：表示上传任务完成，任务完成时触发该事件。  - 'fail'：表示上传任务失败，任务失败时触发该事件。 |
| callback | Callback<Array<[TaskState](/consumer/cn/doc/harmonyos-references/js-apis-request#taskstate9)>> | 是 | 上传任务完成或失败的回调函数。返回上传任务的任务状态信息。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | The parameters check fails. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. let upCompleteCallback = (taskStates: Array<request.TaskState>) => {
2. for (let i = 0; i < taskStates.length; i++) {
3. console.info("upOnComplete taskState:" + JSON.stringify(taskStates[i]));
4. }
5. };
6. uploadTask.on('complete', upCompleteCallback);

8. let upFailCallback = (taskStates: Array<request.TaskState>) => {
9. for (let i = 0; i < taskStates.length; i++) {
10. console.info("upOnFail taskState:" + JSON.stringify(taskStates[i]));
11. }
12. };
13. uploadTask.on('fail', upFailCallback);
```

### off('progress')

PhonePC/2in1TabletTVWearable

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

取消订阅上传任务进度事件。

**系统能力**：SystemCapability.MiscServices.Upload

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 取消订阅的事件类型。  - 取值为'progress'，表示上传的进度信息。 |
| callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 |

回调函数的参数

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| uploadedSize | number | 是 | 当前已上传文件大小，单位为字节（B）。 |
| totalSize | number | 是 | 上传文件的总大小，单位为字节（B）。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | The parameters check fails. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. let upProgressCallback1 = (uploadedSize: number, totalSize: number) => {
2. console.info('Upload delete progress notification.' + 'totalSize:' + totalSize + 'uploadedSize:' + uploadedSize);
3. };
4. let upProgressCallback2 = (uploadedSize: number, totalSize: number) => {
5. console.info('Upload delete progress notification.' + 'totalSize:' + totalSize + 'uploadedSize:' + uploadedSize);
6. };
7. uploadTask.on('progress', upProgressCallback1);
8. uploadTask.on('progress', upProgressCallback2);
9. // 表示取消upProgressCallback1的订阅
10. uploadTask.off('progress', upProgressCallback1);
11. // 表示取消订阅上传任务进度事件的所有回调
12. uploadTask.off('progress');
```

### off('headerReceive')7+

PhonePC/2in1TabletTVWearable

off(type: 'headerReceive', callback?: (header: object) => void): void

取消订阅上传任务HTTP响应事件。

**系统能力**：SystemCapability.MiscServices.Upload

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 取消订阅的事件类型。  - 取值为'headerReceive'，表示HTTP请求接收到响应。 |
| callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 |

回调函数的参数：

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| header | object | 是 | HTTP响应。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | The parameters check fails. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. let headerCallback1 = (header: object) => {
2. console.info(`Upload delete headerReceive notification. header: ${JSON.stringify(header)}`);
3. };
4. let headerCallback2 = (header: object) => {
5. console.info(`Upload delete headerReceive notification. header: ${JSON.stringify(header)}`);
6. };
7. uploadTask.on('headerReceive', headerCallback1);
8. uploadTask.on('headerReceive', headerCallback2);
9. // 表示取消headerCallback1的订阅
10. uploadTask.off('headerReceive', headerCallback1);
11. // 表示取消订阅上传任务HTTP标头事件的所有回调
12. uploadTask.off('headerReceive');
```

### off('complete' | 'fail')9+

PhonePC/2in1TabletTVWearable

off(type: 'complete' | 'fail', callback?: Callback<Array<TaskState>>): void

取消订阅上传任务的完成或失败事件。

**系统能力**：SystemCapability.MiscServices.Upload

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 取消订阅的事件类型。  - 取值为'complete'，表示上传任务完成。  - 取值为'fail'，表示上传任务失败。 |
| callback | Callback<Array<[TaskState](/consumer/cn/doc/harmonyos-references/js-apis-request#taskstate9)>> | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | the parameters check fails. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. let upCompleteCallback1 = (taskStates: Array<request.TaskState>) => {
2. console.info('Upload delete complete notification.');
3. for (let i = 0; i < taskStates.length; i++) {
4. console.info('taskState:' + JSON.stringify(taskStates[i]));
5. }
6. };
7. let upCompleteCallback2 = (taskStates: Array<request.TaskState>) => {
8. console.info('Upload delete complete notification.');
9. for (let i = 0; i < taskStates.length; i++) {
10. console.info('taskState:' + JSON.stringify(taskStates[i]));
11. }
12. };
13. uploadTask.on('complete', upCompleteCallback1);
14. uploadTask.on('complete', upCompleteCallback2);
15. // 表示取消headerCallback1的订阅
16. uploadTask.off('complete', upCompleteCallback1);
17. // 表示取消订阅上传任务完成的所有回调
18. uploadTask.off('complete');

20. let upFailCallback1 = (taskStates: Array<request.TaskState>) => {
21. console.info('Upload delete fail notification.');
22. for (let i = 0; i < taskStates.length; i++) {
23. console.info('taskState:' + JSON.stringify(taskStates[i]));
24. }
25. };
26. let upFailCallback2 = (taskStates: Array<request.TaskState>) => {
27. console.info('Upload delete fail notification.');
28. for (let i = 0; i < taskStates.length; i++) {
29. console.info('taskState:' + JSON.stringify(taskStates[i]));
30. }
31. };
32. uploadTask.on('fail', upFailCallback1);
33. uploadTask.on('fail', upFailCallback2);
34. // 表示取消headerCallback1的订阅
35. uploadTask.off('fail', upFailCallback1);
36. // 表示取消订阅上传任务失败的所有回调
37. uploadTask.off('fail');
```

### delete9+

PhonePC/2in1TabletTVWearable

delete(): Promise<boolean>

移除上传的任务，使用Promise异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Upload

说明

由于不存在401报错场景，在api12中 401 the parameters check fails 这个错误码被移除。

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<boolean> | Promise对象。返回true表示移除上传任务成功；返回false表示移除上传任务失败。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. uploadTask.delete().then((result: boolean) => {
2. console.info('Succeeded in deleting the upload task.');
3. }).catch((err: BusinessError) => {
4. console.error(`Failed to delete the upload task. Code: ${err.code}, message: ${err.message}`);
5. });
```

### delete9+

PhonePC/2in1TabletTVWearable

delete(callback: AsyncCallback<boolean>): void

移除上传的任务，使用callback异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Upload

说明

由于不存在401报错场景，在api12中 401 the parameters check fails 这个错误码被移除。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示移除上传任务成功；返回false表示移除上传任务失败。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. uploadTask.delete((err: BusinessError, result: boolean) => {
2. if (err) {
3. console.error(`Failed to delete the upload task. Code: ${err.code}, message: ${err.message}`);
4. return;
5. }
6. console.info('Succeeded in deleting the upload task.');
7. });
```

### remove(deprecated)

PhonePC/2in1TabletTVWearable

remove(): Promise<boolean>

移除上传的任务，使用Promise异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Upload

说明

从API version 6开始支持，从API version 9开始废弃，建议使用[delete](/consumer/cn/doc/harmonyos-references/js-apis-request#delete9)替代。

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<boolean> | 使用Promise方式异步回调，返回true表示移除上传任务成功；返回false表示移除上传任务失败。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. uploadTask.remove().then((result: boolean) => {
2. console.info('Succeeded in removing the upload task.');
3. }).catch((err: BusinessError) => {
4. console.error(`Failed to remove the upload task. Code: ${err.code}, message: ${err.message}`);
5. });
```

### remove(deprecated)

PhonePC/2in1TabletTVWearable

remove(callback: AsyncCallback<boolean>): void

移除上传的任务，使用callback异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Upload

说明

从API version 6开始支持，从API version 9开始废弃，建议使用[delete](/consumer/cn/doc/harmonyos-references/js-apis-request#delete9-1)替代。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示移除上传任务成功；返回false表示移除上传任务失败。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. uploadTask.remove((err: BusinessError, result: boolean) => {
2. if (err) {
3. console.error(`Failed to remove the upload task. Code: ${err.code}, message: ${err.message}`);
4. return;
5. }
6. if (result) {
7. console.info('Succeeded in removing the upload task.');
8. }
9. });
```

## UploadConfig

PhonePC/2in1TabletTVWearable

上传任务的配置信息。

**系统能力**：SystemCapability.MiscServices.Upload

展开

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| url | string | 否 | 否 | 资源地址。从API 6到API 14，最大长度为2048个字符；从API 15开始，最大长度为8192个字符。支持[HTTP拦截](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-file-upload-download#http拦截)功能。 |
| header | Object | 否 | 否 | 添加要包含在上传请求中的HTTP或HTTPS标志头。 |
| method | string | 否 | 否 | HTTP请求方法：POST、PUT，缺省为POST。使用POST新增资源，使用PUT修改资源。 |
| index11+ | number | 否 | 是 | 任务的路径索引，默认值为0。 |
| begins11+ | number | 否 | 是 | 上传任务开始时读取的文件起点，单位为字节（B）。默认值为0，取值范围为闭区间，表示从头开始传输。 |
| ends11+ | number | 否 | 是 | 上传任务结束时读取的文件终点，单位为字节（B）。默认值为-1，取值范围为闭区间，表示传输到整个文件末尾结束。 |
| files | Array<[File](/consumer/cn/doc/harmonyos-references/js-apis-request#file)> | 否 | 否 | 要上传的文件列表。文件以HTTP的multipart/form-data格式提交。 |
| data | Array<[RequestData](/consumer/cn/doc/harmonyos-references/js-apis-request#requestdata)> | 否 | 否 | 请求的表单数据。 |

## TaskState9+

PhonePC/2in1TabletTVWearable

上传任务的任务信息，是[on('complete' | 'fail')](/consumer/cn/doc/harmonyos-references/js-apis-request#oncomplete--fail9)和[off('complete' | 'fail')](/consumer/cn/doc/harmonyos-references/js-apis-request#offcomplete--fail9)接口的回调参数。

**系统能力**：SystemCapability.MiscServices.Upload

展开

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| path | string | 否 | 否 | 文件路径。 |
| responseCode | number | 否 | 否 | 上传任务返回码。返回0表示上传任务成功，返回其它值表示上传任务失败，具体请参见message参数中的上传任务结果描述信息。  此处推荐使用[request.agent.create](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentcreate10-1)创建上传任务，并获取标准错误码处理异常分支。 |
| message | string | 否 | 否 | 上传任务结果描述信息。 |

其中，responseCode包含的返回码值如下。

展开

| 返回码 | 具体信息 |
| --- | --- |
| 0 | 上传成功。 |
| 5 | 任务被主动暂停或被动停止。 |
| 6 | 任务所属应用被切换到后台或终止，导致前台任务被停止，请检查应用状态。 |
| 7 | 无网络，请检查设备是否处于联网状态。 |
| 8 | 网络类型不匹配，请检查当前网络类型和任务所需网络类型是否匹配。 |
| 10 | 创建HTTP请求失败，请检查参数是否正确或重试任务。 |
| 12 | 超时，请检查参数是否正确、检查网络状况是否允许，或重试任务。 |
| 13 | 连接失败，请检查参数是否正确、检查网络状况是否允许，或重试任务。 |
| 14 | 请求失败，请检查参数是否正确、检查网络状况是否允许，或重试任务。 |
| 15 | 上传失败，请检查参数是否正确、检查网络状况是否允许，或重试任务。 |
| 16 | 重定向失败，请检查参数是否正确、检查网络状况是否允许，或重试任务。 |
| 17 | 协议错误，服务器返回 4XX 或 5XX 状态码，请检查参数是否正确。 |
| 20 | 其他错误，请检查参数是否正确、检查网络状况是否允许，或重试任务。 |

## File

PhonePC/2in1TabletTVWearable

[UploadConfig](/consumer/cn/doc/harmonyos-references/js-apis-request#uploadconfig)中的文件列表。

**系统能力**：SystemCapability.MiscServices.Download

展开

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| filename | string | 否 | 否 | multipart提交时，请求头中的文件名。 |
| name | string | 否 | 否 | multipart提交时，表单项目的名称，缺省为file。 |
| uri | string | 否 | 否 | 文件的本地存储路径。  仅支持"internal://cache/"，即调用方（传入的context）对应的缓存路径context.cacheDir。  示例：internal://cache/path/to/file.txt |
| type | string | 否 | 否 | 文件的内容类型，默认根据文件名或路径的后缀获取。 |

## RequestData

PhonePC/2in1TabletTVWearable

[UploadConfig](/consumer/cn/doc/harmonyos-references/js-apis-request#uploadconfig)中的表单数据。

**系统能力**：SystemCapability.MiscServices.Download

展开

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| name | string | 否 | 否 | 表示表单元素的名称。 |
| value | string | 否 | 否 | 表示表单元素的值。 |

## request.downloadFile9+

PhonePC/2in1TabletTVWearable

downloadFile(context: BaseContext, config: DownloadConfig): Promise<DownloadTask>

创建并启动一个下载任务，使用Promise异步回调，支持HTTP协议。通过[on('complete'|'pause'|'remove')](/consumer/cn/doc/harmonyos-references/js-apis-request#oncompletepauseremove7)可以获取任务下载时的状态信息，包括任务完成、暂停或移除。通过[on('fail')](/consumer/cn/doc/harmonyos-references/js-apis-request#onfail7)可以获取任务下载时的错误信息。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| context | [BaseContext](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-inner-application-basecontext) | 是 | 基于应用程序的上下文。 |
| config | [DownloadConfig](/consumer/cn/doc/harmonyos-references/js-apis-request#downloadconfig) | 是 | 下载的配置信息。 |

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<[DownloadTask](/consumer/cn/doc/harmonyos-references/js-apis-request#downloadtask)> | 使用Promise方式，异步返回下载任务DownloadTask的Promise对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |
| 401 | The parameters check fails. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |
| 13400001 | Invalid file or file system error. |
| 13400002 | File path not supported or invalid. |
| 13400003 | Task service ability error. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. try {
7. // 需要手动将url替换为真实服务器的HTTP协议地址
8. request.downloadFile(context, { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
9. let downloadTask: request.DownloadTask = data;
10. }).catch((err: BusinessError) => {
11. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
12. })
13. } catch (err) {
14. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
15. }
```

## request.downloadFile9+

PhonePC/2in1TabletTVWearable

downloadFile(context: BaseContext, config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void

创建并启动一个下载任务，使用callback异步回调，支持HTTP协议。通过[on('complete'|'pause'|'remove')](/consumer/cn/doc/harmonyos-references/js-apis-request#oncompletepauseremove7)可获取任务下载时的状态信息，包括任务完成、暂停或移除。通过[on('fail')](/consumer/cn/doc/harmonyos-references/js-apis-request#onfail7)可获取任务下载时的错误信息。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| context | [BaseContext](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-inner-application-basecontext) | 是 | 基于应用程序的上下文。 |
| config | [DownloadConfig](/consumer/cn/doc/harmonyos-references/js-apis-request#downloadconfig) | 是 | 下载的配置信息。 |
| callback | AsyncCallback<[DownloadTask](/consumer/cn/doc/harmonyos-references/js-apis-request#downloadtask)> | 是 | 回调函数。当下载任务成功，err为undefined，data为获取到的DownloadTask对象；否则为错误对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |
| 401 | The parameters check fails. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |
| 13400001 | Invalid file or file system error. |
| 13400002 | File path not supported or invalid. |
| 13400003 | Task service ability error. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. try {
7. // 需要手动将url替换为真实服务器的HTTP协议地址
8. request.downloadFile(context, {
9. url: 'https://xxxx/xxxxx.hap',
10. filePath: 'xxx/xxxxx.hap'
11. }, (err: BusinessError, data: request.DownloadTask) => {
12. if (err) {
13. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
14. return;
15. }
16. });
17. } catch (err) {
18. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
19. }
```

## request.download(deprecated)

PhonePC/2in1TabletTVWearable

download(config: DownloadConfig): Promise<DownloadTask>

创建并启动一个下载任务，使用Promise异步回调。

**模型约束**：此接口仅可在FA模型下使用。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

从API version 6 开始支持，从API version 9 开始废弃，建议使用[request.downloadFile](/consumer/cn/doc/harmonyos-references/js-apis-request#requestdownloadfile9)替代。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| config | [DownloadConfig](/consumer/cn/doc/harmonyos-references/js-apis-request#downloadconfig) | 是 | 下载的配置信息。 |

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<[DownloadTask](/consumer/cn/doc/harmonyos-references/js-apis-request#downloadtask)> | 使用Promise方式，异步返回下载任务DownloadTask的Promise对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. let downloadTask: request.DownloadTask;
2. // 需要手动将url替换为真实服务器的HTTP协议地址
3. request.download({ url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
4. downloadTask = data;
5. }).catch((err: BusinessError) => {
6. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
7. })
```

## request.download(deprecated)

PhonePC/2in1TabletTVWearable

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

创建并启动一个下载任务，使用callback异步回调。

**模型约束**：此接口仅可在FA模型下使用。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

从API version 6 开始支持，从API version 9 开始废弃，建议使用[request.downloadFile](/consumer/cn/doc/harmonyos-references/js-apis-request#requestdownloadfile9-1)替代。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| config | [DownloadConfig](/consumer/cn/doc/harmonyos-references/js-apis-request#downloadconfig) | 是 | 下载的配置信息。 |
| callback | AsyncCallback<[DownloadTask](/consumer/cn/doc/harmonyos-references/js-apis-request#downloadtask)> | 是 | 回调函数。当下载任务成功，err为undefined，data为获取到的DownloadTask对象；否则为错误对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. let downloadTask: request.DownloadTask;
2. // 需要手动将url替换为真实服务器的HTTP协议地址
3. request.download({ url: 'https://xxxx/xxxxx.hap',
4. filePath: 'xxx/xxxxx.hap'}, (err: BusinessError, data: request.DownloadTask) => {
5. if (err) {
6. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
7. return;
8. }
9. downloadTask = data;
10. });
```

## DownloadTask

PhonePC/2in1TabletTVWearable

下载任务，使用下列方法前，需要先获取DownloadTask对象，promise形式通过[request.downloadFile](/consumer/cn/doc/harmonyos-references/js-apis-request#requestdownloadfile9)获取，callback形式通过[request.downloadFile](/consumer/cn/doc/harmonyos-references/js-apis-request#requestdownloadfile9-1)获取。

### on('progress')

PhonePC/2in1TabletTVWearable

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

订阅下载任务进度事件，使用callback异步回调。

**系统能力**：SystemCapability.MiscServices.Download

说明

应用处于后台时，为满足功耗性能要求，不支持调用此接口进行回调。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 订阅的事件类型。  - 取值为'progress'，表示下载的进度信息，当任务进度有进展时触发该事件。 |
| callback | function | 是 | 下载任务进度的回调函数，返回已上传文件大小和上传文件大小总和。 |

回调函数的参数：

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| receivedSize | number | 是 | 当前下载的进度，单位为字节（B）。 |
| totalSize | number | 是 | 下载文件的总大小，单位为字节（B）。在下载过程中，若服务器使用chunk方式传输导致无法从请求头中获取文件总大小时，totalSize为 -1。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | The parameters check fails. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. try {
7. // 需要手动将url替换为真实服务器的HTTP协议地址
8. request.downloadFile(context, { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
9. let downloadTask: request.DownloadTask = data;
10. let progressCallback = (receivedSize: number, totalSize: number) => {
11. console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize);
12. };
13. downloadTask.on('progress', progressCallback);
14. }).catch((err: BusinessError) => {
15. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
16. })
17. } catch (err) {
18. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
19. }
```

### off('progress')

PhonePC/2in1TabletTVWearable

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

取消订阅下载任务进度事件。

**系统能力**：SystemCapability.MiscServices.Download

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 取消订阅的事件类型。  - 取值为'progress'，表示下载的进度信息。 |
| callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 |

回调函数的参数：

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| receivedSize | number | 是 | 当前下载的进度，单位为字节（B）。 |
| totalSize | number | 是 | 下载文件的总大小，单位为字节（B）。在下载过程中，若服务器使用chunk方式传输导致无法从请求头中获取文件总大小时，totalSize为 -1。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | The parameters check fails. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. try {
7. // 需要手动将url替换为真实服务器的HTTP协议地址
8. request.downloadFile(context, { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
9. let downloadTask: request.DownloadTask = data;
10. let progressCallback1 = (receivedSize: number, totalSize: number) => {
11. console.info('Download delete progress notification.' + 'receivedSize:' + receivedSize + 'totalSize:' + totalSize);
12. };
13. let progressCallback2 = (receivedSize: number, totalSize: number) => {
14. console.info('Download delete progress notification.' + 'receivedSize:' + receivedSize + 'totalSize:' + totalSize);
15. };
16. downloadTask.on('progress', progressCallback1);
17. downloadTask.on('progress', progressCallback2);
18. // 表示取消progressCallback1的订阅
19. downloadTask.off('progress', progressCallback1);
20. // 表示取消订阅下载任务进度事件的所有回调
21. downloadTask.off('progress');
22. }).catch((err: BusinessError) => {
23. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
24. })
25. } catch (err) {
26. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
27. }
```

### on('complete'|'pause'|'remove')7+

PhonePC/2in1TabletTVWearable

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

订阅下载任务相关的事件，使用callback异步回调。

**系统能力**：SystemCapability.MiscServices.Download

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 订阅的事件类型。  - 取值为'complete'，表示下载任务完成，任务完成时触发该事件。  - 取值为'pause'，表示下载任务暂停，任务暂停时触发该事件。  - 取值为'remove'，表示下载任务移除，任务移除时触发该事件。 |
| callback | function | 是 | 下载任务相关的回调函数。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | The parameters check fails. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. try {
7. // 需要手动将url替换为真实服务器的HTTP协议地址
8. request.downloadFile(context, { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
9. let downloadTask: request.DownloadTask = data;
10. let completeCallback = () => {
11. console.info('Download task completed.');
12. };
13. downloadTask.on('complete', completeCallback);

15. let pauseCallback = () => {
16. console.info('Download task pause.');
17. };
18. downloadTask.on('pause', pauseCallback);

20. let removeCallback = () => {
21. console.info('Download task remove.');
22. };
23. downloadTask.on('remove', removeCallback);
24. }).catch((err: BusinessError) => {
25. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
26. })
27. } catch (err) {
28. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
29. }
```

### off('complete'|'pause'|'remove')7+

PhonePC/2in1TabletTVWearable

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

取消订阅下载任务相关的事件。

**系统能力**：SystemCapability.MiscServices.Download

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 取消订阅的事件类型。  - 取值为'complete'，表示下载任务完成。  - 取值为'pause'，表示下载任务暂停。  - 取值为'remove'，表示下载任务移除。 |
| callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | The parameters check fails. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. try {
7. // 需要手动将url替换为真实服务器的HTTP协议地址
8. request.downloadFile(context, { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
9. let downloadTask: request.DownloadTask = data;
10. let completeCallback1 = () => {
11. console.info('Download delete complete notification.');
12. };
13. let completeCallback2 = () => {
14. console.info('Download delete complete notification.');
15. };
16. downloadTask.on('complete', completeCallback1);
17. downloadTask.on('complete', completeCallback2);
18. // 表示取消completeCallback1的订阅
19. downloadTask.off('complete', completeCallback1);
20. // 表示取消订阅下载任务完成的所有回调
21. downloadTask.off('complete');

23. let pauseCallback1 = () => {
24. console.info('Download delete pause notification.');
25. };
26. let pauseCallback2 = () => {
27. console.info('Download delete pause notification.');
28. };
29. downloadTask.on('pause', pauseCallback1);
30. downloadTask.on('pause', pauseCallback2);
31. // 表示取消pauseCallback1的订阅
32. downloadTask.off('pause', pauseCallback1);
33. // 表示取消订阅下载任务暂停的所有回调
34. downloadTask.off('pause');

36. let removeCallback1 = () => {
37. console.info('Download delete remove notification.');
38. };
39. let removeCallback2 = () => {
40. console.info('Download delete remove notification.');
41. };
42. downloadTask.on('remove', removeCallback1);
43. downloadTask.on('remove', removeCallback2);
44. // 表示取消removeCallback1的订阅
45. downloadTask.off('remove', removeCallback1);
46. // 表示取消订阅下载任务移除的所有回调
47. downloadTask.off('remove');
48. }).catch((err: BusinessError) => {
49. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
50. })
51. } catch (err) {
52. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
53. }
```

### on('fail')7+

PhonePC/2in1TabletTVWearable

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

订阅下载任务失败事件，使用callback异步回调。

**系统能力**：SystemCapability.MiscServices.Download

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 订阅的事件类型。  - 取值为'fail'，表示下载失败，任务失败时触发该事件。 |
| callback | function | 是 | 下载失败的回调函数。 |

回调函数的参数：

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| err | number | 是 | 下载失败的错误码，错误原因见[下载任务的错误码](/consumer/cn/doc/harmonyos-references/js-apis-request#常量)。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | The parameters check fails. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. try {
7. // 需要手动将url替换为真实服务器的HTTP协议地址
8. request.downloadFile(context, { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
9. let downloadTask: request.DownloadTask = data;
10. let failCallback = (err: number) => {
11. console.error(`Failed to download the task. Code: ${err}`);
12. };
13. downloadTask.on('fail', failCallback);
14. }).catch((err: BusinessError) => {
15. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
16. })
17. } catch (err) {
18. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
19. }
```

### off('fail')7+

PhonePC/2in1TabletTVWearable

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

取消订阅下载任务失败事件。

**系统能力**：SystemCapability.MiscServices.Download

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 取消订阅的事件类型。  - 取值为'fail'，表示下载失败。 |
| callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 |

回调函数的参数：

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| err | number | 是 | 下载失败的错误码，错误原因见[下载任务的错误码](/consumer/cn/doc/harmonyos-references/js-apis-request#常量)。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | The parameters check fails. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. try {
7. // 需要手动将url替换为真实服务器的HTTP协议地址
8. request.downloadFile(context, { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
9. let downloadTask: request.DownloadTask = data;
10. let failCallback1 = (err: number) => {
11. console.error(`Failed to download the task. Code: ${err}`);
12. };
13. let failCallback2 = (err: number) => {
14. console.error(`Failed to download the task. Code: ${err}`);
15. };
16. downloadTask.on('fail', failCallback1);
17. downloadTask.on('fail', failCallback2);
18. // 表示取消failCallback1的订阅
19. downloadTask.off('fail', failCallback1);
20. // 表示取消订阅下载任务失败的所有回调
21. downloadTask.off('fail');
22. }).catch((err: BusinessError) => {
23. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
24. })
25. } catch (err) {
26. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
27. }
```

### delete9+

PhonePC/2in1TabletTVWearable

delete(): Promise<boolean>

移除下载的任务，使用Promise异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

由于不存在401报错场景，在api12中 401 the parameters check fails 这个错误码被移除。

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<boolean> | Promise对象。返回true表示移除下载任务成功；返回false表示移除下载任务失败。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. try {
7. // 需要手动将url替换为真实服务器的HTTP协议地址
8. request.downloadFile(context, { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
9. data.delete().then((result: boolean) => {
10. console.info('Succeeded in removing the download task.');
11. }).catch((err: BusinessError) => {
12. console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`);
13. });
14. }).catch((err: BusinessError) => {
15. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
16. })
17. } catch (err) {
18. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
19. }
```

### delete9+

PhonePC/2in1TabletTVWearable

delete(callback: AsyncCallback<boolean>): void

移除下载的任务，使用callback异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

由于不存在401报错场景，在api12中 401 the parameters check fails 这个错误码被移除。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示移除下载任务成功；返回false表示移除下载任务失败。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. try {
7. // 需要手动将url替换为真实服务器的HTTP协议地址
8. request.downloadFile(context, { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
9. let downloadTask: request.DownloadTask = data;
10. downloadTask.delete((err: BusinessError, result: boolean) => {
11. if (err) {
12. console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`);
13. return;
14. }
15. console.info('Succeeded in removing the download task.');
16. });
17. }).catch((err: BusinessError) => {
18. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
19. })
20. } catch (err) {
21. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
22. }
```

### getTaskInfo9+

PhonePC/2in1TabletTVWearable

getTaskInfo(): Promise<DownloadInfo>

查询下载任务的信息，使用Promise异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

由于不存在401报错场景，在api12中 401 the parameters check fails 这个错误码被移除。

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<[DownloadInfo](/consumer/cn/doc/harmonyos-references/js-apis-request#downloadinfo7)> | Promise对象，返回DownloadInfo对象。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. try {
7. // 需要手动将url替换为真实服务器的HTTP协议地址
8. request.downloadFile(context, { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
9. let downloadTask: request.DownloadTask = data;
10. downloadTask.getTaskInfo().then((downloadInfo: request.DownloadInfo) => {
11. console.info('Succeeded in querying the download task')
12. }).catch((err: BusinessError) => {
13. console.error(`Failed to query the download task. Code: ${err.code}, message: ${err.message}`)
14. });
15. }).catch((err: BusinessError) => {
16. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
17. })
18. } catch (err) {
19. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
20. }
```

### getTaskInfo9+

PhonePC/2in1TabletTVWearable

getTaskInfo(callback: AsyncCallback<DownloadInfo>): void

查询下载的任务，使用callback异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

由于不存在401报错场景，在api12中 401 the parameters check fails 这个错误码被移除。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| callback | AsyncCallback<[DownloadInfo](/consumer/cn/doc/harmonyos-references/js-apis-request#downloadinfo7)> | 是 | 回调函数。当查询下载任务操作成功，err为undefined，data为获取到的DownloadInfo对象；否则为错误对象。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. try {
7. // 需要手动将url替换为真实服务器的HTTP协议地址
8. request.downloadFile(context, { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
9. let downloadTask: request.DownloadTask = data;
10. downloadTask.getTaskInfo((err: BusinessError, downloadInfo: request.DownloadInfo) => {
11. if (err) {
12. console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`);
13. } else {
14. console.info('Succeeded in querying the download mimeType');
15. }
16. });
17. }).catch((err: BusinessError) => {
18. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
19. })
20. } catch (err) {
21. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
22. }
```

### getTaskMimeType9+

PhonePC/2in1TabletTVWearable

getTaskMimeType(): Promise<string>

查询下载的任务的MimeType(HTTP中表示资源的媒体类型)，使用Promise异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

由于不存在401报错场景，在api12中 401 the parameters check fails 这个错误码被移除。

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<string> | Promise对象。返回下载任务的MimeType。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. try {
7. // 需要手动将url替换为真实服务器的HTTP协议地址
8. request.downloadFile(context, { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
9. let downloadTask: request.DownloadTask = data;
10. downloadTask.getTaskMimeType().then((data: string) => {
11. console.info('Succeeded in querying the download MimeType');
12. }).catch((err: BusinessError) => {
13. console.error(`Failed to query the download MimeType. Code: ${err.code}, message: ${err.message}`)
14. });
15. }).catch((err: BusinessError) => {
16. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
17. })
18. } catch (err) {
19. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
20. }
```

### getTaskMimeType9+

PhonePC/2in1TabletTVWearable

getTaskMimeType(callback: AsyncCallback<string>): void

查询下载任务的 MimeType（HTTP中表示资源的媒体类型），使用callback异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

由于不存在401报错场景，在api12中 401 the parameters check fails 这个错误码被移除。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| callback | AsyncCallback<string> | 是 | 回调函数。当查询下载任务MimeType成功，err为undefined，data为获取到的下载任务的MimeType的对象；否则为错误对象。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. try {
7. // 需要手动将url替换为真实服务器的HTTP协议地址
8. request.downloadFile(context, { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
9. let downloadTask: request.DownloadTask = data;
10. downloadTask.getTaskMimeType((err: BusinessError, data: string) => {
11. if (err) {
12. console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`);
13. } else {
14. console.info('Succeeded in querying the download mimeType');
15. }
16. });
17. }).catch((err: BusinessError) => {
18. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
19. })
20. } catch (err) {
21. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
22. }
```

### suspend9+

PhonePC/2in1TabletTVWearable

suspend(): Promise<boolean>

暂停下载正在运行中的任务，已暂停的任务可被[restore](/consumer/cn/doc/harmonyos-references/js-apis-request#restore9)恢复，使用Promise异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

由于不存在401报错场景，在api12中 401 the parameters check fails 这个错误码被移除。

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<boolean> | Promise对象。返回true表示暂停下载正在运行中的任务成功；返回false表示暂停下载正在运行中的任务失败。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. try {
7. // 需要手动将url替换为真实服务器的HTTP协议地址
8. request.downloadFile(context, { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
9. let downloadTask: request.DownloadTask = data;
10. downloadTask.suspend().then((result: boolean) => {
11. console.info('Succeeded in pausing the download task.');
12. }).catch((err: BusinessError) => {
13. console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`);
14. });
15. }).catch((err: BusinessError) => {
16. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
17. })
18. } catch (err) {
19. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
20. }
```

### suspend9+

PhonePC/2in1TabletTVWearable

suspend(callback: AsyncCallback<boolean>): void

暂停下载正在运行中的任务，已暂停的任务可被[restore](/consumer/cn/doc/harmonyos-references/js-apis-request#restore9)恢复，使用callback异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

由于不存在401报错场景，在api12中 401 the parameters check fails 这个错误码被移除。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示暂停下载任务成功；返回false表示暂停下载任务失败。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. try {
7. // 需要手动将url替换为真实服务器的HTTP协议地址
8. request.downloadFile(context, { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
9. let downloadTask: request.DownloadTask = data;
10. downloadTask.suspend((err: BusinessError, result: boolean) => {
11. if (err) {
12. console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`);
13. return;
14. }
15. console.info('Succeeded in pausing the download task.');
16. });
17. }).catch((err: BusinessError) => {
18. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
19. })
20. } catch (err) {
21. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
22. }
```

### restore9+

PhonePC/2in1TabletTVWearable

restore(): Promise<boolean>

重新启动被暂停的下载任务，使用Promise异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

由于不存在401报错场景，在api12中 401 the parameters check fails 这个错误码被移除。

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<boolean> | Promise对象。返回true表示重新启动被暂停的下载任务成功；返回false表示重新启动被暂停的下载任务失败。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. try {
7. // 需要手动将url替换为真实服务器的HTTP协议地址
8. request.downloadFile(context, { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
9. let downloadTask: request.DownloadTask = data;
10. downloadTask.restore().then((result: boolean) => {
11. console.info('Succeeded in resuming the download task.')
12. }).catch((err: BusinessError) => {
13. console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`);
14. });
15. }).catch((err: BusinessError) => {
16. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
17. })
18. } catch (err) {
19. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
20. }
```

### restore9+

PhonePC/2in1TabletTVWearable

restore(callback: AsyncCallback<boolean>): void

重新启动被暂停的下载任务，使用callback异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

由于不存在401报错场景，在api12中 401 the parameters check fails 这个错误码被移除。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示重新启动已暂停的下载任务成功；返回false表示重新启动下载任务失败。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. try {
7. // 需要手动将url替换为真实服务器的HTTP协议地址
8. request.downloadFile(context, { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
9. let downloadTask: request.DownloadTask = data;
10. downloadTask.restore((err: BusinessError, result: boolean) => {
11. if (err) {
12. console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`);
13. return;
14. }
15. console.info('Succeeded in resuming the download task.');
16. });
17. }).catch((err: BusinessError) => {
18. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
19. })
20. } catch (err) {
21. console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
22. }
```

### remove(deprecated)

PhonePC/2in1TabletTVWearable

remove(): Promise<boolean>

移除下载的任务，使用Promise异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

从API version 6开始支持，从API version 9开始废弃，建议使用[delete](/consumer/cn/doc/harmonyos-references/js-apis-request#delete9-2)替代。

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<boolean> | Promise对象。返回true表示移除下载任务成功；返回false表示移除下载任务失败。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. downloadTask.remove().then((result) => {
2. console.info('Succeeded in removing the download task.');
3. }).catch ((err: BusinessError) => {
4. console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`);
5. });
```

### remove(deprecated)

PhonePC/2in1TabletTVWearable

remove(callback: AsyncCallback<boolean>): void

移除下载的任务，使用callback异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

从API version 6开始支持，从API version 9开始废弃，建议使用[delete](/consumer/cn/doc/harmonyos-references/js-apis-request#delete9-3)替代。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示移除下载任务成功；返回false表示移除下载任务失败。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. downloadTask.remove((err, result)=>{
2. if(err) {
3. console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`);
4. return;
5. }
6. console.info('Succeeded in removing the download task.');
7. });
```

### query(deprecated)

PhonePC/2in1TabletTVWearable

query(): Promise<DownloadInfo>

查询下载任务，返回下载任务的信息，使用Promise异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

从API version 7开始支持，从API version 9开始废弃,建议使用[getTaskInfo](/consumer/cn/doc/harmonyos-references/js-apis-request#gettaskinfo9)替代。

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<[DownloadInfo](/consumer/cn/doc/harmonyos-references/js-apis-request#downloadinfo7)> | Promise对象。返回DownloadInfo。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. downloadTask.query().then((downloadInfo) => {
2. console.info('Succeeded in querying the download task.')
3. }).catch((err: BusinessError) => {
4. console.error(`Failed to query the download task. Code: ${err.code}, message: ${err.message}`)
5. });
```

### query(deprecated)

PhonePC/2in1TabletTVWearable

query(callback: AsyncCallback<DownloadInfo>): void

查询下载任务，返回下载任务的信息，使用callback异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

从API version 7开始支持，从API version 9开始废弃，建议使用[getTaskInfo](/consumer/cn/doc/harmonyos-references/js-apis-request#gettaskinfo9-1)替代。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| callback | AsyncCallback<[DownloadInfo](/consumer/cn/doc/harmonyos-references/js-apis-request#downloadinfo7)> | 是 | 回调函数。当查询下载任务成功，err为undefined，data为获取到的DownloadInfo对象；否则为错误对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. downloadTask.query((err: BusinessError, downloadInfo: request.DownloadInfo)=>{
2. if(err) {
3. console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`);
4. } else {
5. console.info('Succeeded in querying the download task.');
6. }
7. });
```

### queryMimeType(deprecated)

PhonePC/2in1TabletTVWearable

queryMimeType(): Promise<string>

查询下载任务的MimeType，使用Promise异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

从API version 7开始支持，从API version 9开始废弃，建议使用[getTaskMimeType](/consumer/cn/doc/harmonyos-references/js-apis-request#gettaskmimetype9)替代。

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<string> | Promise对象。返回下载任务的MimeType。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. downloadTask.queryMimeType().then((data: string) => {
2. console.info('Succeeded in querying the download MimeType.');
3. }).catch((err: BusinessError) => {
4. console.error(`Failed to query the download MimeType. Code: ${err.code}, message: ${err.message}`)
5. });
```

### queryMimeType(deprecated)

PhonePC/2in1TabletTVWearable

queryMimeType(callback: AsyncCallback<string>): void

查询下载的任务的MimeType，使用callback异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

从API version 7开始支持，从API version 9开始废弃，建议使用[getTaskMimeType](/consumer/cn/doc/harmonyos-references/js-apis-request#gettaskmimetype9-1)替代。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| callback | AsyncCallback<string> | 是 | 回调函数。当查询下载任务的MimeType成功，err为undefined，data为获取到的任务的MimeType对象；否则为错误对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. downloadTask.queryMimeType((err: BusinessError, data: string)=>{
2. if(err) {
3. console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`);
4. } else {
5. console.info('Succeeded in querying the download mimeType.');
6. }
7. });
```

### pause(deprecated)

PhonePC/2in1TabletTVWearable

pause(): Promise<void>

暂停下载正在运行中的任务，使用Promise异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

从API version 7开始支持，从API version 9开始废弃，建议使用[suspend](/consumer/cn/doc/harmonyos-references/js-apis-request#suspend9)替代。

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. downloadTask.pause().then(() => {
2. console.info('Succeeded in pausing the download task.');
3. }).catch((err: BusinessError) => {
4. console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`);
5. });
```

### pause(deprecated)

PhonePC/2in1TabletTVWearable

pause(callback: AsyncCallback<void>): void

暂停下载正在运行中的任务，使用callback异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

从API version 7开始支持，从API version 9开始废弃，建议使用[suspend](/consumer/cn/doc/harmonyos-references/js-apis-request#suspend9-1)替代。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| callback | AsyncCallback<void> | 是 | 回调函数。当暂停下载任务成功，err为undefined，否则为错误对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. downloadTask.pause((err: BusinessError) => {
2. if(err) {
3. console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`);
4. return;
5. }
6. console.info('Succeeded in pausing the download task.');
7. });
```

### resume(deprecated)

PhonePC/2in1TabletTVWearable

resume(): Promise<void>

重新启动被暂停的下载任务，使用Promise异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

从API version 7开始支持，从API version 9开始废弃，建议使用[restore](/consumer/cn/doc/harmonyos-references/js-apis-request#restore9)替代。

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. downloadTask.resume().then(() => {
2. console.info('Succeeded in resuming the download task.')
3. }).catch((err: BusinessError) => {
4. console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`);
5. });
```

### resume(deprecated)

PhonePC/2in1TabletTVWearable

resume(callback: AsyncCallback<void>): void

重新启动被暂停的下载任务，使用callback异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.MiscServices.Download

说明

从API version 7开始支持，从API version 9开始废弃，建议使用[restore](/consumer/cn/doc/harmonyos-references/js-apis-request#restore9-1)替代。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| callback | AsyncCallback<void> | 是 | 回调函数。当重新启动已暂停的下载任务成功，err为undefined，否则为错误对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | The permissions check fails. |

**示例：**



```
1. downloadTask.resume((err: BusinessError) => {
2. if (err) {
3. console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`);
4. return;
5. }
6. console.info('Succeeded in resuming the download task.');
7. });
```

## DownloadConfig

PhonePC/2in1TabletTVWearable

下载任务的配置信息。

**系统能力**：SystemCapability.MiscServices.Download

展开

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| url | string | 否 | 否 | 资源地址。从API 6到API 14，最大长度为2048个字符；从API 15开始，最大长度为8192个字符。支持[HTTP拦截](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-file-upload-download#http拦截)功能。 |
| header | Object | 否 | 是 | 添加要包含在下载请求中的HTTPS标志头。默认值为空。 |
| enableMetered | boolean | 否 | 是 | 表示设置是否允许在按流量计费的连接下下载任务的配置信息。true表示允许，false表示不允许。默认值为false。  **说明：**  Wi-Fi为非计费网络，数据流量为计费网络。 |
| enableRoaming | boolean | 否 | 是 | 表示设置是否允许在漫游网络中下载任务的配置信息。true表示允许，false表示不允许。默认值为false。 |
| description | string | 否 | 是 | 设置下载会话的描述。默认值为空字符串。 |
| filePath7+ | string | 否 | 是 | 设置下载路径。默认为调用方（即传入的context）对应的缓存路径。默认文件名从url的最后一个"/"后截取。  - FA模型下使用[Context.getCacheDir](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-inner-app-context#contextgetcachedir)方法获取应用存储路径。  - Stage模型下使用[Context (Stage模型的上下文基类)](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-inner-application-context)中AbilityContext的类获取文件路径。 |
| networkType | number | 否 | 是 | 设置允许下载的网络类型，通过[网络类型常量](/consumer/cn/doc/harmonyos-references/js-apis-request#常量)的位运算方式决定允许的网络类型，支持如下几种设置方式:  - 仅支持蜂窝网络下载，参数为NETWORK\_MOBILE或0x00000001  - 仅支持WLAN网络下载，参数为NETWORK\_WIFI或0x00010000  - 参数默认值，支持蜂窝/WLAN网络下载，参数为NETWORK\_MOBILE | NETWORK\_WIFI或0x00010001。  当参数为NETWORK\_MOBILE | NETWORK\_WIFI时，enableMetered和enableRoaming参数不生效。 |
| title | string | 否 | 是 | 设置下载任务名称。默认值为download。 |
| background9+ | boolean | 否 | 是 | 后台任务通知开关，启用后可在通知中显示下载状态。true表示启用，false表示禁用。默认值为false。 |

## DownloadInfo7+

PhonePC/2in1TabletTVWearable

下载任务信息，[getTaskInfo](/consumer/cn/doc/harmonyos-references/js-apis-request#gettaskinfo9)接口的回调参数。

**系统能力**：SystemCapability.MiscServices.Download

展开

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| downloadId | number | 否 | 否 | 下载任务id。 |
| failedReason | number | 否 | 否 | 下载失败原因，可以是任何[下载任务的错误码](/consumer/cn/doc/harmonyos-references/js-apis-request#常量)常量。 |
| fileName | string | 否 | 否 | 下载的文件名。 |
| filePath | string | 否 | 否 | 存储文件的URI。 |
| pausedReason | number | 否 | 否 | 会话暂停的原因，可以是任何[下载任务暂停原因](/consumer/cn/doc/harmonyos-references/js-apis-request#常量)常量。 |
| status | number | 否 | 否 | 下载状态码，可以是任何[下载任务状态码](/consumer/cn/doc/harmonyos-references/js-apis-request#常量)常量。 |
| targetURI | string | 否 | 否 | 下载文件的URI。 |
| downloadTitle | string | 否 | 否 | 下载任务名称。 |
| downloadTotalBytes | number | 否 | 否 | 下载的文件的总大小，单位为字节（B）。 |
| description | string | 否 | 否 | 待下载任务的描述信息。 |
| downloadedBytes | number | 否 | 否 | 实时下载大小，单位为字节（B）。 |

## request.agent10+

PhonePC/2in1TabletTVWearable

### 常量

PhonePC/2in1TabletTVWearable

**系统能力**：SystemCapability.Request.FileTransferAgent

展开

| 名称 | 类型 | 值 | 说明 |
| --- | --- | --- | --- |
| VISIBILITY\_COMPLETION21+ | number | 1 | [通知栏](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentnotification15)展示类型：显示完成通知 |
| VISIBILITY\_PROGRESS21+ | number | 2 | [通知栏](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentnotification15)展示类型：显示进度通知 |

## request.agent.Action10+

PhonePC/2in1TabletTVWearable

定义操作选项。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

展开

| 名称 | 值 | 说明 |
| --- | --- | --- |
| DOWNLOAD | 0 | 表示下载任务。 |
| UPLOAD | 1 | 表示上传任务。 |

## request.agent.Mode10+

PhonePC/2in1TabletTVWearable

定义模式选项。

当应用的前台任务切换到后台一段时间后会显示运行失败或暂停，而后台任务不受此操作影响。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

展开

| 名称 | 值 | 说明 |
| --- | --- | --- |
| BACKGROUND | 0 | 表示后台任务。 |
| FOREGROUND | 1 | 表示前台任务。 |

## request.agent.Network10+

PhonePC/2in1TabletTVWearable

定义网络选项。

网络不满足设置条件时，未执行的任务会等待执行，执行中的任务将失败或暂停。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

展开

| 名称 | 值 | 说明 |
| --- | --- | --- |
| ANY | 0 | 表示不限网络类型。 |
| WIFI | 1 | 表示无线网络。 |
| CELLULAR | 2 | 表示蜂窝数据网络。 |

## request.agent.BroadcastEvent11+

PhonePC/2in1TabletTVWearable

定义自定义系统事件。用户可以使用公共事件接口获取该事件。

上传下载SA具有'ohos.permission.SEND\_TASK\_COMPLETE\_EVENT'权限，用户可以配置事件的metadata指向的二级配置文件来拦截其他事件发送者。

调用CommonEventData类型传输公共事件相关数据，成员的内容填写和 [CommonEventData](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-inner-commonevent-commoneventdata) 介绍的有所区别，其中CommonEventData.code表示任务的状态，目前为0x40 COMPLETE或0x41 FAILED；CommonEventData.data表示任务的taskId。

**系统能力**：SystemCapability.Request.FileTransferAgent

展开

| 名称 | 值 | 说明 |
| --- | --- | --- |
| COMPLETE | ohos.request.event.COMPLETE | 表示自定义系统事件完成。在任务结束后会触发该事件，根据任务的成功或失败，事件的code返回0x40或者0x41。 |

## request.agent.FileSpec10+

PhonePC/2in1TabletTVWearable

表单项的文件信息。

**系统能力**：SystemCapability.Request.FileTransferAgent

展开

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| path | string | 否 | 否 | 文件路径。  - 相对路径，位于调用方的缓存路径下。  例如："./xxx/yyy/zzz.html"、"xxx/yyy/zzz.html"。  - internal协议路径，支持"internal://"及其子路径。internal为调用方（即传入的context）对应路径，"internal://cache"对应context.cacheDir。  例如："internal://cache/path/to/file.txt"。  - 应用沙箱目录，只支持到base及其子目录下。  例如："/data/storage/el1/base/path/to/file.txt"。  - file协议路径，必须匹配应用包名，只支持到base及其子目录下。  例如："file://com.example.test/data/storage/el2/base/file.txt"。  - 用户公共文件，仅支持上传任务。  例如："file://media/Photo/path/to/file.img"。仅支持前台任务。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| mimeType(deprecated) | string | 否 | 是 | 文件的mimeType，通过文件名获取，默认值为文件名后缀。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。  从 API version 18 开始废弃，建议使用contentType替代。 |
| contentType18+ | string | 否 | 是 | 文件内容类型，默认值为文件名后缀。该选项会被填写到HTTP表单指定的Content-Type字段中。 |
| filename | string | 否 | 是 | 文件名，默认值通过路径获取。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| extras | object | 否 | 是 | 文件信息的附加内容，该参数不会体现在HTTP请求中。默认值为空。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |

## request.agent.FormItem10+

PhonePC/2in1TabletTVWearable

任务的表单项信息。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

展开

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| name | string | 否 | 否 | 表单参数名。 |
| value | string | [FileSpec](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentfilespec10) | Array<[FileSpec](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentfilespec10)> | 否 | 否 | 表单参数值。 |

## request.agent.Config10+

PhonePC/2in1TabletTVWearable

上传/下载任务的配置信息。

**系统能力**：SystemCapability.Request.FileTransferAgent

展开

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| action | [Action](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentaction10) | 否 | 否 | 任务操作选项。  - UPLOAD表示上传任务。  - DOWNLOAD表示下载任务。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| url | string | 否 | 否 | 资源地址。从API 6到API 14，最大长度为2048个字符；从API 15开始，最大长度为8192个字符。支持[HTTP拦截](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-file-upload-download#http拦截)功能。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| title | string | 否 | 是 | 任务标题，其最大长度为256个字符，默认值为小写的 upload 或 download，与上面的 action 保持一致。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| description | string | 否 | 是 | 任务的详细信息，其最大长度为1024个字符，默认值为空字符串。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| mode | [Mode](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentmode10) | 否 | 是 | 任务模式，默认为后台任务。从API version 20开始，下载到用户文件场景必须为request.agent.Mode.FOREGROUND。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| overwrite | boolean | 否 | 是 | 下载过程中路径已存在时的解决方案选择，默认为false。  - true，覆盖已存在的文件。  - false，下载失败。  从API version 20开始，下载到用户文件场景必须为true。  设置为 true 时，不建议创建多个任务同时往同一个文件下载内容，会导致文件内容混乱。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| method | string | 否 | 是 | 上传或下载HTTP的标准方法，包括GET、POST和PUT，不区分大小写。  - 上传时，使用PUT或POST，默认值为PUT。  - 下载时，使用GET或POST，默认值为GET。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| headers | object | 否 | 是 | 添加要包含在任务中的HTTP协议标志头。  - 上传请求，默认的Content-Type为"multipart/form-data"。  - 下载请求，默认的Content-Type为"application/json"。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| data | string | Array<[FormItem](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentformitem10)> | 否 | 是 | - 下载时，data为字符串类型，通常情况下使用json格式（object将被转换为json文本），默认为空。  - 上传时，data是表单项数组Array<[FormItem](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentformitem10)>。从API version 15开始，创建单个任务可以上传最多100个文件。默认为空。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| saveas | string | 否 | 是 | 保存下载文件的路径，包括如下几种：  - 相对路径，位于调用方的缓存路径下，如"./xxx/yyy/zzz.html"、"xxx/yyy/zzz.html"。  - internal协议路径，支持"internal://"及其子路径，internal为调用方（传入的context）对应路径，"internal://cache"对应context.cacheDir。如"internal://cache/path/to/file.txt"。  - 应用沙箱目录，只支持到base及其子目录下，如"/data/storage/el1/base/path/to/file.txt"。  - file协议路径，支持应用文件和用户文件，应用文件必须匹配应用包名，只支持到base及其子目录下，如"file://com.example.test/data/storage/el2/base/file.txt"。用户文件必须为调用方创建好的用户文件uri。  从API version 20开始，除[下载网络资源文件至用户文件](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-file-upload-download#下载网络资源文件至用户文件)外，其他可默认为调用方（即传入的context）对应的缓存路径。默认文件名从url的最后一个"/"后截取。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| network | [Network](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentnetwork10) | 否 | 是 | 网络选项，当前支持无线网络WIFI和蜂窝数据网络CELLULAR，默认为ANY（WIFI或CELLULAR）。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| metered | boolean | 否 | 是 | 是否允许在按流量计费的网络中工作，默认为false。  - true：是  - false：否  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| roaming | boolean | 否 | 是 | 是否允许在漫游网络中工作，默认为true。  - true：是  - false：否  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| retry | boolean | 否 | 是 | 是否为后台任务启用自动重试，仅应用于后台任务，默认为true。  - true：是  - false：否  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| redirect | boolean | 否 | 是 | 是否允许重定向，默认为true。  - true：是  - false：否  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| proxy12+ | string | 否 | 是 | 设置代理地址，其最大长度为512个字符，默认为空。  代理地址格式:"http://<domain or address>:<port>" |
| index | number | 否 | 是 | 任务的路径索引，通常情况下用于任务断点续传，默认为0。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| begins | number | 否 | 是 | 文件起点，单位为字节（B），通常情况下用于断点续传。默认值为0，取值为闭区间，表示从头开始传输。  - 下载时，请求读取服务器开始下载文件时的起点位置（HTTP协议中设置"Range"选项）。  - 上传时，读取需上传的文件的起点位置。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| ends | number | 否 | 是 | 文件终点，单位为字节（B），通常情况下用于断点续传。默认值为-1，取值为闭区间，表示传输到整个文件末尾结束。  - 下载时，请求读取服务器开始下载文件时的结束位置（HTTP协议中设置"Range"选项）。  - 上传时，读取需上传的文件的结束位置。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| gauge | boolean | 否 | 是 | 后台任务的过程进度通知策略，仅应用于后台任务，默认值为false。  - false：代表仅完成或失败的通知。  - true：发出每个进度已完成或失败的通知。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| precise | boolean | 否 | 是 | - 如果设置为true，在上传/下载无法获取文件大小时任务失败。  - 如果设置为false，将文件大小设置为-1时任务继续。  默认值为false。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| token | string | 否 | 是 | 任务令牌。查询带有token的任务需提供token并通过[request.agent.touch](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagenttouch10)查询，否则无法查询到指定任务。其最小为8个字节，最大为2048个字节。默认为空。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| priority11+ | number | 否 | 是 | 任务的优先级。前台任务的优先级比后台任务高。任务模式相同的情况下，该配置项的数字越小优先级越高，默认值为0。 |
| extras | object | 否 | 是 | 配置的附加功能，默认为空。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| multipart15+ | boolean | 否 | 是 | 是否使用单个请求进行上传，单个请求上传时必定使用multipart/form-data。  - false：每个文件使用一个请求传输。  - true：使用多文件单请求上传。  默认值为false。 |
| notification15+ | [Notification](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentnotification15) | 否 | 是 | 通知栏自定义设置。默认值为{}。 |
| minSpeed20+ | [MinSpeed](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentminspeed20) | 否 | 是 | 最低限速自定义设置，默认不启用最低限速。 |
| timeout20+ | [Timeout](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagenttimeout20) | 否 | 是 | 超时时间自定义设置，连接超时时间默认60秒，总超时时间默认604800秒（1周）。当retry参数为true时，[timeout](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagenttimeout20)事件会触发立即重试，导致[timeout](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagenttimeout20)在外部观察中被重试动作所掩盖，但内部[timeout](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagenttimeout20)条件已实际触发。若需显性观察[timeout](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagenttimeout20)事件，需关闭retry参数。 |

## request.agent.State10+

PhonePC/2in1TabletTVWearable

定义任务当前的状态。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

展开

| 名称 | 值 | 说明 |
| --- | --- | --- |
| INITIALIZED | 0x00 | 表示通过配置信息（[Config](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentconfig10)）创建的任务已初始化。 |
| WAITING | 0x10 | 表示任务缺少运行或重试的资源，又或是网络状态不匹配。 |
| RUNNING | 0x20 | 表示任务正在运行中。 |
| RETRYING | 0x21 | 表示任务至少失败一次，现在正在再次处理中。 |
| PAUSED | 0x30 | 表示任务暂停，通常后续会恢复任务。 |
| STOPPED | 0x31 | 表示任务停止。 |
| COMPLETED | 0x40 | 表示任务完成。 |
| FAILED | 0x41 | 表示任务失败。 |
| REMOVED | 0x50 | 表示任务移除。 |

## request.agent.Progress10+

PhonePC/2in1TabletTVWearable

任务进度的数据结构。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

展开

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| state | [State](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentstate10) | 是 | 否 | 任务当前的状态。 |
| index | number | 是 | 否 | 任务中当前正在处理的文件索引。 |
| processed | number | 是 | 否 | 任务中当前文件的已处理数据大小，单位为字节（B）。 |
| sizes | Array<number> | 是 | 否 | 任务中文件的大小，单位为字节（B）。在下载过程中，若服务器使用chunk方式传输导致无法从请求头中获取文件总大小时，sizes为 -1。 |
| extras | object | 是 | 是 | 交互的额外内容，例如：来自服务器的响应的header和body。默认值为空。 |

## request.agent.Faults10+

PhonePC/2in1TabletTVWearable

定义任务失败的原因。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

API version 12及以下版本，只支持串行的尝试连接域名相关ip，且不支持单个ip的连接时间控制，如果DNS返回的首个ip是阻塞的，可能会导致握手超时，进而引发TIMEOUT错误。

展开

| 名称 | 值 | 说明 |
| --- | --- | --- |
| OTHERS | 0xFF | 表示其他故障。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| DISCONNECTED | 0x00 | 表示网络断开连接。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| TIMEOUT | 0x10 | 表示任务超时。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| PROTOCOL | 0x20 | 表示协议错误，例如：服务器内部错误（500）、无法处理的数据区间（416）等。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| PARAM12+ | 0x30 | 表示参数错误，例如：url格式错误等。  **元服务API：** 从API version 12开始，该接口支持在元服务中使用。 |
| FSIO | 0x40 | 表示文件系统io错误，例如：打开/查找/读取/写入/关闭。  **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| DNS12+ | 0x50 | 表示DNS解析错误。  **元服务API：** 从API version 12开始，该接口支持在元服务中使用。 |
| TCP12+ | 0x60 | 表示TCP连接错误。  **元服务API：** 从API version 12开始，该接口支持在元服务中使用。 |
| SSL12+ | 0x70 | 表示SSL连接错误，例如：证书错误、证书校验失败错误等。  **元服务API：** 从API version 12开始，该接口支持在元服务中使用。 |
| REDIRECT12+ | 0x80 | 表示重定向错误。  **元服务API：** 从API version 12开始，该接口支持在元服务中使用。 |
| LOW\_SPEED20+ | 0x90 | 表示任务速度过低。 |

## request.agent.Filter10+

PhonePC/2in1TabletTVWearable

过滤条件。

**系统能力**：SystemCapability.Request.FileTransferAgent

展开

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| before | number | 否 | 是 | 结束的Unix时间戳（毫秒），默认为调用时刻。 |
| after | number | 否 | 是 | 开始的Unix时间戳（毫秒），默认值为调用时刻减24小时。 |
| state | [State](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentstate10) | 否 | 是 | 指定任务的状态。如果未填写，则查询所有任务。 |
| action | [Action](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentaction10) | 否 | 是 | 任务操作选项。  - UPLOAD表示上传任务。  - DOWNLOAD表示下载任务。  - 如果未填写，则查询所有任务。 |
| mode | [Mode](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentmode10) | 否 | 是 | 任务模式。  - FOREGROUND表示前台任务。  - BACKGROUND表示后台任务。  - 如果未填写，则查询所有任务。 |

## request.agent.TaskInfo10+

PhonePC/2in1TabletTVWearable

查询结果的任务信息数据结构，提供普通查询和系统查询，两种字段的可见范围不同。

**系统能力**：SystemCapability.Request.FileTransferAgent

展开

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| saveas | string | 是 | 是 | 保存下载文件的路径。 |
| url | string | 是 | 是 | 任务的url。  - 通过[request.agent.show](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentshow10-1)、[request.agent.touch](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagenttouch10-1)进行查询。 |
| data | string | Array<[FormItem](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentformitem10)> | 是 | 是 | 任务值。  - 通过[request.agent.show](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentshow10-1)、[request.agent.touch](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagenttouch10-1)进行查询。 |
| tid | string | 是 | 否 | 任务id。 |
| title | string | 是 | 否 | 任务标题。 |
| description | string | 是 | 否 | 任务描述。 |
| action | [Action](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentaction10) | 是 | 否 | 任务操作选项。  - UPLOAD表示上传任务。  - DOWNLOAD表示下载任务。 |
| mode | [Mode](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentmode10) | 是 | 否 | 任务模式。  - FOREGROUND表示前台任务。  - BACKGROUND表示后台任务。 |
| priority11+ | number | 是 | 否 | 任务配置中的优先级。前台任务的优先级比后台任务高。相同模式的任务，数字越小优先级越高。 |
| mimeType | string | 是 | 否 | 任务配置中的mimetype。 |
| progress | [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10) | 是 | 否 | 任务的过程进度。 |
| gauge | boolean | 是 | 否 | 后台任务的进度通知策略。  - false：代表仅完成或失败的通知。  - true，发出每个进度已完成或失败的通知。 |
| ctime | number | 是 | 否 | 创建任务的Unix时间戳（毫秒），由当前设备的系统生成。  说明：使用[request.agent.search](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentsearch10-1)进行查询时，该值需处于[after,before]区间内才可正常查询到任务id，before和after信息详见[Filter](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentfilter10)。 |
| mtime | number | 是 | 否 | 任务状态改变时的Unix时间戳（毫秒），由当前设备的系统生成。 |
| retry | boolean | 是 | 否 | 任务的重试开关，仅应用于后台任务。  - true：是  - false：否 |
| tries | number | 是 | 否 | 任务的尝试次数。 |
| faults | [Faults](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentfaults10) | 是 | 否 | 任务的失败原因。 |
| reason | string | 是 | 否 | 等待/失败/停止/暂停任务的原因。 |
| extras | object | 是 | 是 | 任务的额外部分。 |

## request.agent.HttpResponse12+

PhonePC/2in1TabletTVWearable

任务响应头的数据结构。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

展开

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| version | string | 是 | 否 | Http版本。 |
| statusCode | number | 是 | 否 | Http响应状态码。 |
| reason | string | 是 | 否 | Http响应原因。 |
| headers | Map<string, Array<string>> | 是 | 否 | Http响应头部。 |

## request.agent.Notification15+

PhonePC/2in1TabletTVWearable

通知栏自定义信息。

**系统能力**：SystemCapability.Request.FileTransferAgent

展开

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| title | string | 否 | 是 | 通知栏自定义标题。若不设置则使用默认显示方式。title长度上限为1024B。 |
| text | string | 否 | 是 | 通知栏自定义正文。若不设置则使用默认显示方式。text长度上限为3072B。 |
| visibility21+ | number | 否 | 是 | 设置任务的通知栏显示方式，通过[VISIBILITY常量](/consumer/cn/doc/harmonyos-references/js-apis-request#常量-1)的位运算方式决定显示方式，任务通知的显示方式，包括如下几种：  - 仅显示完成通知，参数为VISIBILITY\_COMPLETION或1，任务完成/失败后展示对应通知。  - 仅显示进度通知，参数为VISIBILITY\_PROGRESS或2，任务在进行中显示进度通知，当任务下载成功/失败后会直接退出进度通知，不会显示完成通知。  - 显示进度通知/完成通知，参数为VISIBILITY\_COMPLETION | VISIBILITY\_PROGRESS或3，任务在进行中显示进度通知，当任务下载成功/失败后会退出进度通知，并显示完成通知。  若不设置该参数，则根据gauge字段来判断；若无gauge字段，则仅显示完成通知。 |
| wantAgent22+ | [WantAgent](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-app-ability-wantagent) | 否 | 是 | 通知参数，用于实现点击任务通知后跳转的功能。默认值为空。 |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common, wantAgent, WantAgent } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let wantAgentInfo: wantAgent.WantAgentInfo = {
7. wants: [
8. {
9. deviceId: '',
10. bundleName: 'com.example.request',
11. abilityName: 'EntryAbility',
12. action: '',
13. entities: [],
14. uri: '',
15. parameters: {}
16. }
17. ],
18. actionType: wantAgent.OperationType.START_ABILITY,
19. requestCode: 0,
20. wantAgentFlags:[wantAgent.WantAgentFlags.CONSTANT_FLAG]
21. };
22. let config: request.agent.Config = {
23. action: request.agent.Action.DOWNLOAD,
24. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
25. title: 'taskOnNotification',
26. description: 'Sample code for event listening',
27. mode: request.agent.Mode.BACKGROUND,
28. overwrite: true,
29. method: "PUT",
30. saveas: "./",
31. network: request.agent.Network.ANY,
32. gauge: true,
33. notification: {
34. visibility: request.agent.VISIBILITY_COMPLETION | request.agent.VISIBILITY_PROGRESS,
35. wantAgent: await wantAgent.getWantAgent(wantAgentInfo),
36. }
37. };
38. let createOnCallback = (progress: request.agent.Progress) => {
39. console.info('download task progress.');
40. };
41. request.agent.create(context, config).then((task: request.agent.Task) => {
42. task.on('progress', createOnCallback);
43. console.info(`Succeeded in creating a download task. result: ${task.tid}`);
44. task.start();
45. }).catch((err: BusinessError) => {
46. console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
47. });
```

## request.agent.GroupConfig15+

PhonePC/2in1TabletTVWearable

下载任务分组配置选项。

**系统能力**：SystemCapability.Request.FileTransferAgent

展开

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| gauge | boolean | 否 | 是 | 后台任务的进度通知策略。  - true，显示进度、成功、失败通知。  - false，仅显示成功、失败通知。  默认为false。 |
| notification15+ | [Notification](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentnotification15) | 否 | 否 | 通知栏自定义设置。默认值为{} |

## request.agent.WaitingReason20+

PhonePC/2in1TabletTVWearable

枚举，定义任务等待的原因。

**系统能力**：SystemCapability.Request.FileTransferAgent

展开

| 名称 | 值 | 说明 |
| --- | --- | --- |
| TASK\_QUEUE\_FULL | 0x00 | 表示任务因任务队列已满而进入等待状态。 |
| NETWORK\_NOT\_MATCH | 0x01 | 表示任务因所需网络条件不满足而进入等待状态。 |
| APP\_BACKGROUND | 0x02 | 表示任务因应用长时间处于后台而进入等待状态。 |
| USER\_INACTIVATED | 0x03 | 表示任务因所属用户处于非激活状态而进入等待状态。 |

## request.agent.MinSpeed20+

PhonePC/2in1TabletTVWearable

任务的最低限速配置。若任务速度持续低于设定值并达到指定时长，则任务失败，失败原因为[LOW\_SPEED](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentfaults10)。

**系统能力**：SystemCapability.Request.FileTransferAgent

展开

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| speed | number | 否 | 否 | 任务最低速度，单位为字节每秒（B/s）。若任务速度持续低于该值达到指定时长，则任务失败。设置为0表示不启用最低速度限制。 |
| duration | number | 否 | 否 | 允许低于最低速度的持续时间，单位为秒。若任务速度持续低于设定值达到该时长，则任务失败。设置为0表示不启用最低速度限制。 |

## request.agent.Timeout20+

PhonePC/2in1TabletTVWearable

任务的超时配置。任务处于等待状态的时间不参与计算，上传下载任务会存在以下任务等待的原因:[WaitingReason20+](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentwaitingreason20)。

**系统能力**：SystemCapability.Request.FileTransferAgent

展开

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| connectionTimeout | number | 否 | 是 | 任务连接超时时间，单位为秒。连接超时是指客户端与服务器建立连接的最大耗时。若不设置则使用默认值60秒，允许设置的最小值为1秒。 |
| totalTimeout | number | 否 | 是 | 任务总超时时间，单位为秒。总超时包括建立连接、发送请求和接收响应的全部时间。未指定时使用默认值604800秒（1周）。允许设置的最小值为1秒，最大值为604800秒（1周）。 |

## request.agent.Task10+

PhonePC/2in1TabletTVWearable

上传或下载任务。使用该方法前需要先获取Task对象，promise形式通过[request.agent.create](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentcreate10-1)获取，callback形式通过[request.agent.create](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentcreate10)获取。

### 属性

PhonePC/2in1TabletTVWearable

包括任务id和任务的配置信息。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

Task对象及其挂载回调函数会在调用remove方法后释放并被系统自动回收。

展开

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| tid | string | 是 | 否 | 任务id，由系统自动生成且唯一。 |
| config | [Config](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentconfig10) | 否 | 否 | 任务的配置信息。 |

### on('progress')10+

PhonePC/2in1TabletTVWearable

on(event: 'progress', callback: (progress: [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10)) => void): void

订阅任务进度的事件，使用callback异步回调。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| event | string | 是 | 订阅的事件类型。  - 取值为'progress'，表示任务进度，任务进度有进展时触发该事件。 |
| callback | function | 是 | 回调函数，发生相关的事件时触发该回调方法。 |

回调函数的参数：

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| progress | [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10) | 是 | 表示任务的进度信息。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let attachments: Array<request.agent.FormItem> = [{
7. name: "taskOnTest",
8. value: {
9. filename: "taskOnTest.avi",
10. path: "./taskOnTest.avi",
11. }
12. }];
13. let config: request.agent.Config = {
14. action: request.agent.Action.UPLOAD,
15. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
16. title: 'taskOnTest',
17. description: 'Sample code for event listening',
18. mode: request.agent.Mode.FOREGROUND,
19. overwrite: false,
20. method: "PUT",
21. data: attachments,
22. saveas: "./",
23. network: request.agent.Network.CELLULAR,
24. metered: false,
25. roaming: true,
26. retry: true,
27. redirect: true,
28. index: 0,
29. begins: 0,
30. ends: -1,
31. gauge: false,
32. precise: false,
33. token: "it is a secret"
34. };
35. let createOnCallback = (progress: request.agent.Progress) => {
36. console.info('upload task progress.');
37. };
38. request.agent.create(context, config).then((task: request.agent.Task) => {
39. task.on('progress', createOnCallback);
40. console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
41. task.start();
42. }).catch((err: BusinessError) => {
43. console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
44. });
```

### on('completed')10+

PhonePC/2in1TabletTVWearable

on(event: 'completed', callback: (progress: [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10)) => void): void

订阅任务完成事件，使用callback异步回调。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| event | string | 是 | 订阅的事件类型。  - 取值为'completed'，表示任务完成，任务完成时触发该事件。 |
| callback | function | 是 | 回调函数，发生相关的事件时触发该回调方法。 |

回调函数的参数：

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| progress | [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10) | 是 | 表示任务的进度信息。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let attachments: Array<request.agent.FormItem> = [{
7. name: "taskOnTest",
8. value: {
9. filename: "taskOnTest.avi",
10. path: "./taskOnTest.avi",
11. }
12. }];
13. let config: request.agent.Config = {
14. action: request.agent.Action.UPLOAD,
15. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
16. title: 'taskOnTest',
17. description: 'Sample code for event listening',
18. mode: request.agent.Mode.FOREGROUND,
19. overwrite: false,
20. method: "PUT",
21. data: attachments,
22. saveas: "./",
23. network: request.agent.Network.CELLULAR,
24. metered: false,
25. roaming: true,
26. retry: true,
27. redirect: true,
28. index: 0,
29. begins: 0,
30. ends: -1,
31. gauge: false,
32. precise: false,
33. token: "it is a secret"
34. };
35. let createOnCallback = (progress: request.agent.Progress) => {
36. console.info('upload task completed.');
37. };
38. request.agent.create(context, config).then((task: request.agent.Task) => {
39. task.on('completed', createOnCallback);
40. console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
41. task.start();
42. }).catch((err: BusinessError) => {
43. console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
44. });
```

### on('failed')10+

PhonePC/2in1TabletTVWearable

on(event: 'failed', callback: (progress: [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10)) => void): void

订阅任务失败事件，使用callback异步回调。可通过调用[request.agent.show](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentshow10-1)查看错误原因。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| event | string | 是 | 订阅的事件类型。  - 取值为'failed'，表示任务失败，任务失败时触发该事件。 |
| callback | function | 是 | 回调函数，发生相关的事件时触发该回调方法。 |

回调函数的参数：

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| progress | [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10) | 是 | 表示任务的进度信息。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let attachments: Array<request.agent.FormItem> = [{
7. name: "taskOnTest",
8. value: {
9. filename: "taskOnTest.avi",
10. path: "./taskOnTest.avi",
11. }
12. }];
13. let config: request.agent.Config = {
14. action: request.agent.Action.UPLOAD,
15. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
16. title: 'taskOnTest',
17. description: 'Sample code for event listening',
18. mode: request.agent.Mode.FOREGROUND,
19. overwrite: false,
20. method: "PUT",
21. data: attachments,
22. saveas: "./",
23. network: request.agent.Network.CELLULAR,
24. metered: false,
25. roaming: true,
26. retry: true,
27. redirect: true,
28. index: 0,
29. begins: 0,
30. ends: -1,
31. gauge: false,
32. precise: false,
33. token: "it is a secret"
34. };
35. let createOnCallback = (progress: request.agent.Progress) => {
36. console.info('upload task failed.');
37. };
38. request.agent.create(context, config).then((task: request.agent.Task) => {
39. task.on('failed', createOnCallback);
40. console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
41. task.start();
42. }).catch((err: BusinessError) => {
43. console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
44. });
```

### on('pause')11+

PhonePC/2in1TabletTVWearable

on(event: 'pause', callback: (progress: [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10)) => void): void

订阅任务暂停事件，使用callback异步回调。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| event | string | 是 | 订阅的事件类型。  - 取值为'pause'，表示任务已暂停，任务暂停时触发该事件。 |
| callback | function | 是 | 回调函数，发生相关的事件时触发该回调方法。 |

回调函数的参数：

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| progress | [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10) | 是 | 表示任务的进度信息。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let attachments: Array<request.agent.FormItem> = [{
7. name: "taskOnTest",
8. value: {
9. filename: "taskOnTest.avi",
10. path: "./taskOnTest.avi",
11. }
12. }];
13. let config: request.agent.Config = {
14. action: request.agent.Action.UPLOAD,
15. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
16. title: 'taskOnTest',
17. description: 'Sample code for event listening',
18. mode: request.agent.Mode.FOREGROUND,
19. overwrite: false,
20. method: "POST",
21. data: attachments,
22. saveas: "./",
23. network: request.agent.Network.CELLULAR,
24. metered: false,
25. roaming: true,
26. retry: true,
27. redirect: true,
28. index: 0,
29. begins: 0,
30. ends: -1,
31. gauge: false,
32. precise: false,
33. token: "it is a secret"
34. };
35. let createOnCallback = (progress: request.agent.Progress) => {
36. console.info('upload task pause.');
37. };
38. request.agent.create(context, config).then(async (task: request.agent.Task) => {
39. task.on('pause', createOnCallback);
40. console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
41. task.start();
42. // 等待1秒再执行下一步操作，以防异步乱序
43. await new Promise<void>((resolve) => {
44. setTimeout(() => resolve(),1000)
45. })
46. task.pause();
47. }).catch((err: BusinessError) => {
48. console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
49. });
```

### on('resume')11+

PhonePC/2in1TabletTVWearable

on(event: 'resume', callback: (progress: [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10)) => void): void

订阅任务恢复事件，使用callback异步回调。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| event | string | 是 | 订阅的事件类型。  - 取值为'resume'，表示任务恢复，任务恢复时触发该事件。 |
| callback | function | 是 | 回调函数，发生相关的事件时触发该回调方法。 |

回调函数的参数：

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| progress | [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10) | 是 | 表示任务的进度信息。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let attachments: Array<request.agent.FormItem> = [{
7. name: "taskOnTest",
8. value: {
9. filename: "taskOnTest.avi",
10. path: "./taskOnTest.avi",
11. }
12. }];
13. let config: request.agent.Config = {
14. action: request.agent.Action.UPLOAD,
15. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
16. title: 'taskOnTest',
17. description: 'Sample code for event listening',
18. mode: request.agent.Mode.FOREGROUND,
19. overwrite: false,
20. method: "PUT",
21. data: attachments,
22. saveas: "./",
23. network: request.agent.Network.CELLULAR,
24. metered: false,
25. roaming: true,
26. retry: true,
27. redirect: true,
28. index: 0,
29. begins: 0,
30. ends: -1,
31. gauge: false,
32. precise: false,
33. token: "it is a secret"
34. };
35. let createOnCallback = (progress: request.agent.Progress) => {
36. console.info('upload task resume.');
37. };
38. request.agent.create(context, config).then(async (task: request.agent.Task) => {
39. task.on('resume', createOnCallback);
40. console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
41. task.start();
42. // 等待1秒再执行下一步操作，以防异步乱序
43. await new Promise<void>((resolve) => {
44. setTimeout(() => resolve(),1000)
45. })
46. task.pause();
47. // 等待1秒再执行下一步操作，以防异步乱序
48. await new Promise<void>((resolve) => {
49. setTimeout(() => resolve(),1000)
50. })
51. task.resume();
52. }).catch((err: BusinessError) => {
53. console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
54. });
```

### on('remove')11+

PhonePC/2in1TabletTVWearable

on(event: 'remove', callback: (progress: [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10)) => void): void

订阅任务移除事件，使用callback异步回调。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| event | string | 是 | 订阅的事件类型。  - 取值为'remove'，表示任务被移除，任务移除时触发该事件。 |
| callback | function | 是 | 回调函数，发生相关的事件时触发该回调方法。 |

回调函数的参数：

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| progress | [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10) | 是 | 表示任务的进度信息。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let attachments: Array<request.agent.FormItem> = [{
7. name: "taskOnTest",
8. value: {
9. filename: "taskOnTest.avi",
10. path: "./taskOnTest.avi",
11. }
12. }];
13. let config: request.agent.Config = {
14. action: request.agent.Action.UPLOAD,
15. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
16. title: 'taskOnTest',
17. description: 'Sample code for event listening',
18. mode: request.agent.Mode.FOREGROUND,
19. overwrite: false,
20. method: "PUT",
21. data: attachments,
22. saveas: "./",
23. network: request.agent.Network.CELLULAR,
24. metered: false,
25. roaming: true,
26. retry: true,
27. redirect: true,
28. index: 0,
29. begins: 0,
30. ends: -1,
31. gauge: false,
32. precise: false,
33. token: "it is a secret"
34. };
35. let createOnCallback = (progress: request.agent.Progress) => {
36. console.info('upload task remove.');
37. };
38. request.agent.create(context, config).then(async (task: request.agent.Task) => {
39. task.on('remove', createOnCallback);
40. console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
41. task.start();
42. // 等待1秒再执行下一步操作，以防异步乱序
43. await new Promise<void>((resolve) => {
44. setTimeout(() => resolve(),1000)
45. })
46. request.agent.remove(task.tid);
47. }).catch((err: BusinessError) => {
48. console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
49. });
```

### on('response')12+

PhonePC/2in1TabletTVWearable

on(event: 'response', callback: Callback<HttpResponse>): void

订阅任务响应头，使用callback异步回调。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| event | string | 是 | 订阅的事件类型。  - 取值为'response'，表示任务响应，请求接收到响应时触发该事件。 |
| callback | Callback<[HttpResponse](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagenthttpresponse12)> | 是 | 回调函数，发生相关的事件时触发该回调方法，返回任务响应头的数据结构。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let attachments: Array<request.agent.FormItem> = [{
7. name: "taskOnTest",
8. value: {
9. filename: "taskOnTest.avi",
10. path: "./taskOnTest.avi",
11. }
12. }];
13. let config: request.agent.Config = {
14. action: request.agent.Action.UPLOAD,
15. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
16. title: 'taskOnTest',
17. description: 'Sample code for event listening',
18. mode: request.agent.Mode.FOREGROUND,
19. overwrite: false,
20. method: "PUT",
21. data: attachments,
22. saveas: "./",
23. network: request.agent.Network.CELLULAR,
24. metered: false,
25. roaming: true,
26. retry: true,
27. redirect: true,
28. index: 0,
29. begins: 0,
30. ends: -1,
31. gauge: false,
32. precise: false,
33. token: "it is a secret"
34. };
35. let createOnCallback = (response: request.agent.HttpResponse) => {
36. console.info('upload task response.');
37. };
38. request.agent.create(context, config).then((task: request.agent.Task) => {
39. task.on('response', createOnCallback);
40. console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
41. task.start();
42. }).catch((err: BusinessError) => {
43. console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
44. });
```

### on('faultOccur')20+

PhonePC/2in1TabletTVWearable

on(event: 'faultOccur', callback: Callback<Faults>): void

订阅任务失败原因，使用callback形式返回结果。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| event | string | 是 | 订阅的事件类型。  - 取值为'faultOccur'，表示任务失败。 |
| callback | Callback<[Faults](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentfaults10)> | 是 | 发生相关的事件时触发该回调方法，返回任务失败的原因。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
5. let attachments: Array<request.agent.FormItem> = [{
6. name: "taskOnTest",
7. value: {
8. filename: "taskOnTest.avi",
9. mimeType: "application/octet-stream",
10. path: "./taskOnTest.avi",
11. }
12. }];
13. let config: request.agent.Config = {
14. action: request.agent.Action.UPLOAD,
15. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
16. title: 'taskOnTest',
17. description: 'Sample code for event listening',
18. mode: request.agent.Mode.FOREGROUND,
19. overwrite: false,
20. method: "PUT",
21. data: attachments,
22. saveas: "./",
23. network: request.agent.Network.CELLULAR,
24. metered: false,
25. roaming: true,
26. retry: true,
27. redirect: true,
28. index: 0,
29. begins: 0,
30. ends: -1,
31. gauge: false,
32. precise: false,
33. token: "it is a secret"
34. };
35. let faultOnCallback = (faults: request.agent.Faults) => {
36. console.info('upload task failed.');
37. };
38. request.agent.create(context, config).then((task: request.agent.Task) => {
39. task.on('faultOccur', faultOnCallback);
40. console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
41. task.start();
42. }).catch((err: BusinessError) => {
43. console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
44. });
```

### on('wait')20+

PhonePC/2in1TabletTVWearable

on(event: 'wait', callback: Callback<WaitingReason>): void

订阅任务等待原因，使用callback形式返回结果。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| event | string | 是 | 订阅的事件类型。  - 取值为'wait'，表示任务等待。 |
| callback | Callback<[WaitingReason](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentwaitingreason20)> | 是 | 发生相关的事件时触发该回调方法，返回任务等待的原因。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
5. let attachments: Array<request.agent.FormItem> = [{
6. name: "taskOnTest",
7. value: {
8. filename: "taskOnTest.avi",
9. mimeType: "application/octet-stream",
10. path: "./taskOnTest.avi",
11. }
12. }];
13. let config: request.agent.Config = {
14. action: request.agent.Action.UPLOAD,
15. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
16. title: 'taskOnTest',
17. description: 'Sample code for event listening',
18. mode: request.agent.Mode.FOREGROUND,
19. overwrite: false,
20. method: "PUT",
21. data: attachments,
22. saveas: "./",
23. network: request.agent.Network.CELLULAR,
24. metered: false,
25. roaming: true,
26. retry: true,
27. redirect: true,
28. index: 0,
29. begins: 0,
30. ends: -1,
31. gauge: false,
32. precise: false,
33. token: "it is a secret"
34. };
35. let waitOnCallback = (reason: request.agent.WaitingReason) => {
36. console.info('upload task waiting.');
37. };
38. request.agent.create(context, config).then((task: request.agent.Task) => {
39. task.on('wait', waitOnCallback);
40. console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
41. task.start();
42. }).catch((err: BusinessError) => {
43. console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
44. });
```

### off('progress')10+

PhonePC/2in1TabletTVWearable

off(event: 'progress', callback?: (progress: [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10)) => void): void

取消订阅任务进度事件。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| event | string | 是 | 取消订阅的事件类型。  - 取值为'progress'，表示任务进度。 |
| callback | function | 否 | 回调函数，发生相关的事件时触发该回调方法。若无此参数，则取消订阅的所有进度回调函数。 |

回调函数的参数：

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| progress | [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10) | 是 | 表示任务的进度信息。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let attachments: Array<request.agent.FormItem> = [{
7. name: "taskOffTest",
8. value: {
9. filename: "taskOffTest.avi",
10. path: "./taskOffTest.avi",
11. }
12. }];
13. let config: request.agent.Config = {
14. action: request.agent.Action.UPLOAD,
15. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
16. title: 'taskOffTest',
17. description: 'Sample code for event listening',
18. mode: request.agent.Mode.FOREGROUND,
19. overwrite: false,
20. method: "PUT",
21. data: attachments,
22. saveas: "./",
23. network: request.agent.Network.CELLULAR,
24. metered: false,
25. roaming: true,
26. retry: true,
27. redirect: true,
28. index: 0,
29. begins: 0,
30. ends: -1,
31. gauge: false,
32. precise: false,
33. token: "it is a secret"
34. };
35. let createOffCallback1 = (progress: request.agent.Progress) => {
36. console.info('upload task progress.');
37. };
38. let createOffCallback2 = (progress: request.agent.Progress) => {
39. console.info('upload task progress.');
40. };
41. request.agent.create(context, config).then((task: request.agent.Task) => {
42. task.on('progress', createOffCallback1);
43. task.on('progress', createOffCallback2);
44. // 表示取消createOffCallback1的订阅
45. task.off('progress', createOffCallback1);
46. // 表示取消订阅任务进度的所有回调
47. task.off('progress');
48. console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
49. task.start();
50. }).catch((err: BusinessError) => {
51. console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
52. });
```

### off('completed')10+

PhonePC/2in1TabletTVWearable

off(event: 'completed', callback?: (progress: [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10)) => void): void

取消订阅任务完成事件。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| event | string | 是 | 取消订阅的事件类型。  - 取值为'completed'，表示任务完成。 |
| callback | function | 否 | 回调函数，发生相关的事件时触发该回调方法。若无此参数，则取消订阅的所有完成回调函数。 |

回调函数的参数：

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| progress | [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10) | 是 | 表示任务的进度信息。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let attachments: Array<request.agent.FormItem> = [{
7. name: "taskOffTest",
8. value: {
9. filename: "taskOffTest.avi",
10. path: "./taskOffTest.avi",
11. }
12. }];
13. let config: request.agent.Config = {
14. action: request.agent.Action.UPLOAD,
15. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
16. title: 'taskOffTest',
17. description: 'Sample code for event listening',
18. mode: request.agent.Mode.FOREGROUND,
19. overwrite: false,
20. method: "PUT",
21. data: attachments,
22. saveas: "./",
23. network: request.agent.Network.CELLULAR,
24. metered: false,
25. roaming: true,
26. retry: true,
27. redirect: true,
28. index: 0,
29. begins: 0,
30. ends: -1,
31. gauge: false,
32. precise: false,
33. token: "it is a secret"
34. };
35. let createOffCallback1 = (progress: request.agent.Progress) => {
36. console.info('upload task completed.');
37. };
38. let createOffCallback2 = (progress: request.agent.Progress) => {
39. console.info('upload task completed.');
40. };
41. request.agent.create(context, config).then((task: request.agent.Task) => {
42. task.on('completed', createOffCallback1);
43. task.on('completed', createOffCallback2);
44. // 表示取消createOffCallback1的订阅
45. task.off('completed', createOffCallback1);
46. // 表示取消订阅任务完成的所有回调
47. task.off('completed');
48. console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
49. task.start();
50. }).catch((err: BusinessError) => {
51. console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
52. });
```

### off('failed')10+

PhonePC/2in1TabletTVWearable

off(event: 'failed', callback?: (progress: [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10)) => void): void

取消订阅任务失败事件。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| event | string | 是 | 取消订阅的事件类型。  - 取值为'failed'，表示任务失败。 |
| callback | function | 否 | 回调函数，发生相关的事件时触发该回调方法。若无此参数，则取消订阅的所有失败回调函数。 |

回调函数的参数：

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| progress | [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10) | 是 | 表示任务的进度信息 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let attachments: Array<request.agent.FormItem> = [{
7. name: "taskOffTest",
8. value: {
9. filename: "taskOffTest.avi",
10. path: "./taskOffTest.avi",
11. }
12. }];
13. let config: request.agent.Config = {
14. action: request.agent.Action.UPLOAD,
15. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
16. title: 'taskOffTest',
17. description: 'Sample code for event listening',
18. mode: request.agent.Mode.FOREGROUND,
19. overwrite: false,
20. method: "PUT",
21. data: attachments,
22. saveas: "./",
23. network: request.agent.Network.CELLULAR,
24. metered: false,
25. roaming: true,
26. retry: true,
27. redirect: true,
28. index: 0,
29. begins: 0,
30. ends: -1,
31. gauge: false,
32. precise: false,
33. token: "it is a secret"
34. };
35. let createOffCallback1 = (progress: request.agent.Progress) => {
36. console.info('upload task failed.');
37. };
38. let createOffCallback2 = (progress: request.agent.Progress) => {
39. console.info('upload task failed.');
40. };
41. request.agent.create(context, config).then((task: request.agent.Task) => {
42. task.on('failed', createOffCallback1);
43. task.on('failed', createOffCallback2);
44. // 表示取消createOffCallback1的订阅
45. task.off('failed', createOffCallback1);
46. // 表示取消订阅任务失败的所有回调
47. task.off('failed');
48. console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
49. task.start();
50. }).catch((err: BusinessError) => {
51. console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
52. });
```

### off('pause')11+

PhonePC/2in1TabletTVWearable

off(event: 'pause', callback?: (progress: [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10)) => void): void

取消订阅任务暂停事件。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| event | string | 是 | 取消订阅的事件类型。  - 取值为'pause'，表示任务暂停。 |
| callback | function | 否 | 回调函数，发生相关的事件时触发该回调方法。若无此参数，则取消订阅的所有暂停回调函数。 |

回调函数的参数：

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| progress | [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10) | 是 | 表示任务的进度信息。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let attachments: Array<request.agent.FormItem> = [{
7. name: "taskOffTest",
8. value: {
9. filename: "taskOffTest.avi",
10. path: "./taskOffTest.avi",
11. }
12. }];
13. let config: request.agent.Config = {
14. action: request.agent.Action.UPLOAD,
15. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
16. title: 'taskOffTest',
17. description: 'Sample code for event listening',
18. mode: request.agent.Mode.FOREGROUND,
19. overwrite: false,
20. method: "PUT",
21. data: attachments,
22. saveas: "./",
23. network: request.agent.Network.CELLULAR,
24. metered: false,
25. roaming: true,
26. retry: true,
27. redirect: true,
28. index: 0,
29. begins: 0,
30. ends: -1,
31. gauge: false,
32. precise: false,
33. token: "it is a secret"
34. };
35. let createOffCallback1 = (progress: request.agent.Progress) => {
36. console.info('upload task pause.');
37. };
38. let createOffCallback2 = (progress: request.agent.Progress) => {
39. console.info('upload task pause.');
40. };
41. request.agent.create(context, config).then((task: request.agent.Task) => {
42. task.on('pause', createOffCallback1);
43. task.on('pause', createOffCallback2);
44. // 表示取消createOffCallback1的订阅
45. task.off('pause', createOffCallback1);
46. // 表示取消订阅任务暂停的所有回调
47. task.off('pause');
48. console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
49. task.start();
50. }).catch((err: BusinessError) => {
51. console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
52. });
```

### off('resume')11+

PhonePC/2in1TabletTVWearable

off(event: 'resume', callback?: (progress: [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10)) => void): void

取消订阅任务恢复事件。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| event | string | 是 | 取消订阅的事件类型。  - 取值为'resume'，表示任务恢复。 |
| callback | function | 否 | 回调函数，发生相关的事件时触发该回调方法。若无此参数，则取消订阅的所有恢复回调函数。 |

回调函数的参数：

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| progress | [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10) | 是 | 表示任务的进度信息。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let attachments: Array<request.agent.FormItem> = [{
7. name: "taskOffTest",
8. value: {
9. filename: "taskOffTest.avi",
10. path: "./taskOffTest.avi",
11. }
12. }];
13. let config: request.agent.Config = {
14. action: request.agent.Action.UPLOAD,
15. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
16. title: 'taskOffTest',
17. description: 'Sample code for event listening',
18. mode: request.agent.Mode.FOREGROUND,
19. overwrite: false,
20. method: "PUT",
21. data: attachments,
22. saveas: "./",
23. network: request.agent.Network.CELLULAR,
24. metered: false,
25. roaming: true,
26. retry: true,
27. redirect: true,
28. index: 0,
29. begins: 0,
30. ends: -1,
31. gauge: false,
32. precise: false,
33. token: "it is a secret"
34. };
35. let createOffCallback1 = (progress: request.agent.Progress) => {
36. console.info('upload task resume.');
37. };
38. let createOffCallback2 = (progress: request.agent.Progress) => {
39. console.info('upload task resume.');
40. };
41. request.agent.create(context, config).then((task: request.agent.Task) => {
42. task.on('resume', createOffCallback1);
43. task.on('resume', createOffCallback2);
44. // 表示取消createOffCallback1的订阅
45. task.off('resume', createOffCallback1);
46. // 表示取消订阅任务恢复的所有回调
47. task.off('resume');
48. console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
49. task.start();
50. }).catch((err: BusinessError) => {
51. console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
52. });
```

### off('remove')11+

PhonePC/2in1TabletTVWearable

off(event: 'remove', callback?: (progress: [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10)) => void): void

取消订阅任务移除事件。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| event | string | 是 | 取消订阅的事件类型。  - 取值为'remove'，表示任务被移除。 |
| callback | function | 否 | 回调函数，发生相关的事件时触发该回调方法。若无此参数，则取消订阅的所有移除回调函数。 |

回调函数的参数：

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| progress | [Progress](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentprogress10) | 是 | 表示任务的进度信息。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let attachments: Array<request.agent.FormItem> = [{
7. name: "taskOffTest",
8. value: {
9. filename: "taskOffTest.avi",
10. path: "./taskOffTest.avi",
11. }
12. }];
13. let config: request.agent.Config = {
14. action: request.agent.Action.UPLOAD,
15. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
16. title: 'taskOffTest',
17. description: 'Sample code for event listening',
18. mode: request.agent.Mode.FOREGROUND,
19. overwrite: false,
20. method: "PUT",
21. data: attachments,
22. saveas: "./",
23. network: request.agent.Network.CELLULAR,
24. metered: false,
25. roaming: true,
26. retry: true,
27. redirect: true,
28. index: 0,
29. begins: 0,
30. ends: -1,
31. gauge: false,
32. precise: false,
33. token: "it is a secret"
34. };
35. let createOffCallback1 = (progress: request.agent.Progress) => {
36. console.info('upload task remove.');
37. };
38. let createOffCallback2 = (progress: request.agent.Progress) => {
39. console.info('upload task remove.');
40. };
41. request.agent.create(context, config).then((task: request.agent.Task) => {
42. task.on('remove', createOffCallback1);
43. task.on('remove', createOffCallback2);
44. // 表示取消createOffCallback1的订阅
45. task.off('remove', createOffCallback1);
46. // 表示取消订阅任务移除的所有回调
47. task.off('remove');
48. console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
49. task.start();
50. }).catch((err: BusinessError) => {
51. console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
52. });
```

### off('response')12+

PhonePC/2in1TabletTVWearable

off(event: 'response', callback?: Callback<HttpResponse>): void

取消订阅任务响应事件。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| event | string | 是 | 取消订阅的事件类型。  - 取值为'response'，表示任务响应。 |
| callback | Callback<[HttpResponse](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagenthttpresponse12)> | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 |

**错误码：**

以下错误码的详细介绍请参见[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let attachments: Array<request.agent.FormItem> = [{
7. name: "taskOffTest",
8. value: {
9. filename: "taskOffTest.avi",
10. path: "./taskOffTest.avi",
11. }
12. }];
13. let config: request.agent.Config = {
14. action: request.agent.Action.UPLOAD,
15. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
16. title: 'taskOffTest',
17. description: 'Sample code for event listening',
18. mode: request.agent.Mode.FOREGROUND,
19. overwrite: false,
20. method: "PUT",
21. data: attachments,
22. saveas: "./",
23. network: request.agent.Network.CELLULAR,
24. metered: false,
25. roaming: true,
26. retry: true,
27. redirect: true,
28. index: 0,
29. begins: 0,
30. ends: -1,
31. gauge: false,
32. precise: false,
33. token: "it is a secret"
34. };
35. let createOffCallback1 = (progress: request.agent.HttpResponse) => {
36. console.info('upload task response.');
37. };
38. let createOffCallback2 = (progress: request.agent.HttpResponse) => {
39. console.info('upload task response.');
40. };
41. request.agent.create(context, config).then((task: request.agent.Task) => {
42. task.on('response', createOffCallback1);
43. task.on('response', createOffCallback2);
44. // 表示取消createOffCallback1的订阅
45. task.off('response', createOffCallback1);
46. // 表示取消订阅任务移除的所有回调
47. task.off('response');
48. console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
49. task.start();
50. }).catch((err: BusinessError) => {
51. console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
52. });
```

### off('faultOccur')20+

PhonePC/2in1TabletTVWearable

off(event: 'faultOccur', callback?: Callback<Faults>): void

取消订阅任务失败原因相关的事件。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| event | string | 是 | 订阅的事件类型。  - 取值为'faultOccur'，表示任务失败。 |
| callback | Callback<[Faults](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentfaults10)> | 否 | 需要取消订阅的回调函数。若无此参数，则默认取消订阅当前类型的所有回调函数。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
5. let attachments: Array<request.agent.FormItem> = [{
6. name: "taskOffTest",
7. value: {
8. filename: "taskOffTest.avi",
9. mimeType: "application/octet-stream",
10. path: "./taskOffTest.avi",
11. }
12. }];
13. let config: request.agent.Config = {
14. action: request.agent.Action.UPLOAD,
15. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
16. title: 'taskOffTest',
17. description: 'Sample code for event listening',
18. mode: request.agent.Mode.FOREGROUND,
19. overwrite: false,
20. method: "PUT",
21. data: attachments,
22. saveas: "./",
23. network: request.agent.Network.CELLULAR,
24. metered: false,
25. roaming: true,
26. retry: true,
27. redirect: true,
28. index: 0,
29. begins: 0,
30. ends: -1,
31. gauge: false,
32. precise: false,
33. token: "it is a secret"
34. };
35. let faultOffCallback1 = (faults: request.agent.Faults) => {
36. console.info('upload task failed.');
37. };
38. let faultOffCallback2 = (faults: request.agent.Faults) => {
39. console.info('upload task failed.');
40. };
41. request.agent.create(context, config).then((task: request.agent.Task) => {
42. task.on('faultOccur', faultOffCallback1);
43. task.on('faultOccur', faultOffCallback2);
44. // 表示取消faultOffCallback1的订阅
45. task.off('faultOccur', faultOffCallback1);
46. // 表示取消订阅任务移除的所有回调
47. task.off('faultOccur');
48. console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
49. task.start();
50. }).catch((err: BusinessError) => {
51. console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
52. });
```

### off('wait')20+

PhonePC/2in1TabletTVWearable

off(event: 'wait', callback?: Callback<WaitingReason>): void

取消订阅任务等待原因相关的事件。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| event | string | 是 | 订阅的事件类型。  - 取值为'wait'，表示任务等待。 |
| callback | Callback<[WaitingReason](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentwaitingreason20)> | 否 | 需要取消订阅的回调函数。若无此参数，则默认取消订阅当前类型的所有回调函数。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
5. let attachments: Array<request.agent.FormItem> = [{
6. name: "taskOffTest",
7. value: {
8. filename: "taskOffTest.avi",
9. mimeType: "application/octet-stream",
10. path: "./taskOffTest.avi",
11. }
12. }];
13. let config: request.agent.Config = {
14. action: request.agent.Action.UPLOAD,
15. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
16. title: 'taskOffTest',
17. description: 'Sample code for event listening',
18. mode: request.agent.Mode.FOREGROUND,
19. overwrite: false,
20. method: "PUT",
21. data: attachments,
22. saveas: "./",
23. network: request.agent.Network.CELLULAR,
24. metered: false,
25. roaming: true,
26. retry: true,
27. redirect: true,
28. index: 0,
29. begins: 0,
30. ends: -1,
31. gauge: false,
32. precise: false,
33. token: "it is a secret"
34. };
35. let waitOffCallback1 = (reason: request.agent.WaitingReason) => {
36. console.info('upload task waiting.');
37. };
38. let waitOffCallback2 = (reason: request.agent.WaitingReason) => {
39. console.info('upload task waiting.');
40. };
41. request.agent.create(context, config).then((task: request.agent.Task) => {
42. task.on('wait', waitOffCallback1);
43. task.on('wait', waitOffCallback2);
44. // 表示取消waitOffCallback1的订阅
45. task.off('wait', waitOffCallback1);
46. // 表示取消订阅任务移除的所有回调
47. task.off('wait');
48. console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
49. task.start();
50. }).catch((err: BusinessError) => {
51. console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
52. });
```

### start10+

PhonePC/2in1TabletTVWearable

start(callback: AsyncCallback<void>): void

启动一个任务。使用callback异步回调。

以下状态的任务可以被启动：

1. 刚被request.agent.create接口创建的任务。
2. 使用request.agent.create接口创建的已经失败或者停止的下载任务。

**需要权限**：ohos.permission.INTERNET

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| callback | AsyncCallback<void> | 是 | 回调函数。当开启任务成功，err为undefined，否则为错误对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | Permission denied. |
| 13400003 | Task service ability error. |
| 21900007 | Operation with wrong task state. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let config: request.agent.Config = {
7. action: request.agent.Action.DOWNLOAD,
8. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
9. title: 'taskStartTest',
10. description: 'Sample code for start the download task',
11. mode: request.agent.Mode.BACKGROUND,
12. overwrite: false,
13. method: "GET",
14. data: "",
15. saveas: "./",
16. network: request.agent.Network.CELLULAR,
17. metered: false,
18. roaming: true,
19. retry: true,
20. redirect: true,
21. index: 0,
22. begins: 0,
23. ends: -1,
24. gauge: false,
25. precise: false,
26. token: "it is a secret"
27. };
28. request.agent.create(context, config).then((task: request.agent.Task) => {
29. task.start((err: BusinessError) => {
30. if (err) {
31. console.error(`Failed to start the download task, Code: ${err.code}, message: ${err.message}`);
32. return;
33. }
34. console.info(`Succeeded in starting a download task.`);
35. });
36. console.info(`Succeeded in creating a download task. result: ${task.tid}`);
37. }).catch((err: BusinessError) => {
38. console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
39. });
```

### start10+

PhonePC/2in1TabletTVWearable

start(): Promise<void>

启动一个任务。使用Promise异步回调。

以下状态的任务可以被启动：

1. 刚被request.agent.create接口创建的任务。
2. 使用request.agent.create接口创建的已经失败或者停止的下载任务。

**需要权限**：ohos.permission.INTERNET

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | Permission denied. |
| 13400003 | Task service ability error. |
| 21900007 | Operation with wrong task state. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let config: request.agent.Config = {
7. action: request.agent.Action.DOWNLOAD,
8. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
9. title: 'taskStartTest',
10. description: 'Sample code for start the download task',
11. mode: request.agent.Mode.BACKGROUND,
12. overwrite: false,
13. method: "GET",
14. data: "",
15. saveas: "./",
16. network: request.agent.Network.CELLULAR,
17. metered: false,
18. roaming: true,
19. retry: true,
20. redirect: true,
21. index: 0,
22. begins: 0,
23. ends: -1,
24. gauge: false,
25. precise: false,
26. token: "it is a secret"
27. };
28. request.agent.create(context, config).then((task: request.agent.Task) => {
29. task.start().then(() => {
30. console.info(`Succeeded in starting a download task.`);
31. }).catch((err: BusinessError) => {
32. console.error(`Failed to start the download task, Code: ${err.code}, message: ${err.message}`);
33. });
34. console.info(`Succeeded in creating a download task. result: ${task.tid}`);
35. }).catch((err: BusinessError) => {
36. console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
37. });
```

### pause10+

PhonePC/2in1TabletTVWearable

pause(callback: AsyncCallback<void>): void

暂停任务，可以暂停正在等待/正在运行/正在重试的任务，已暂停的任务可被[resume](/consumer/cn/doc/harmonyos-references/js-apis-request#resume10)恢复。使用callback异步回调。

**系统能力**：SystemCapability.Request.FileTransferAgent

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| callback | AsyncCallback<void> | 是 | 回调函数。当暂停任务成功，err为undefined，否则为错误对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 13400003 | Task service ability error. |
| 21900007 | Operation with wrong task state. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let config: request.agent.Config = {
7. action: request.agent.Action.DOWNLOAD,
8. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
9. title: 'taskPauseTest',
10. description: 'Sample code for pause the download task',
11. mode: request.agent.Mode.BACKGROUND,
12. overwrite: false,
13. method: "GET",
14. data: "",
15. saveas: "./",
16. network: request.agent.Network.CELLULAR,
17. metered: false,
18. roaming: true,
19. retry: true,
20. redirect: true,
21. index: 0,
22. begins: 0,
23. ends: -1,
24. gauge: false,
25. precise: false,
26. token: "it is a secret"
27. };
28. request.agent.create(context, config).then(async (task: request.agent.Task) => {
29. task.start();
30. // 等待1秒再执行下一步操作，以防异步乱序
31. await new Promise<void>((resolve) => {
32. setTimeout(() => resolve(),1000)
33. })
34. task.pause((err: BusinessError) => {
35. if (err) {
36. console.error(`Failed to pause the download task, Code: ${err.code}, message: ${err.message}`);
37. return;
38. }
39. console.info(`Succeeded in pausing a download task. `);
40. });
41. console.info(`Succeeded in creating a download task. result: ${task.tid}`);
42. }).catch((err: BusinessError) => {
43. console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
44. });
```

### pause10+

PhonePC/2in1TabletTVWearable

pause(): Promise<void>

暂停任务，可以暂停正在等待/正在运行/正在重试的任务，已暂停的任务可被[resume](/consumer/cn/doc/harmonyos-references/js-apis-request#resume10)恢复。使用Promise异步回调。

**系统能力**：SystemCapability.Request.FileTransferAgent

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 13400003 | Task service ability error. |
| 21900007 | Operation with wrong task state. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let config: request.agent.Config = {
7. action: request.agent.Action.DOWNLOAD,
8. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
9. title: 'taskPauseTest',
10. description: 'Sample code for pause the download task',
11. mode: request.agent.Mode.BACKGROUND,
12. overwrite: false,
13. method: "GET",
14. data: "",
15. saveas: "./",
16. network: request.agent.Network.CELLULAR,
17. metered: false,
18. roaming: true,
19. retry: true,
20. redirect: true,
21. index: 0,
22. begins: 0,
23. ends: -1,
24. gauge: false,
25. precise: false,
26. token: "it is a secret"
27. };
28. request.agent.create(context, config).then(async (task: request.agent.Task) => {
29. task.start();
30. // 等待1秒再执行下一步操作，以防异步乱序
31. await new Promise<void>((resolve) => {
32. setTimeout(() => resolve(),1000)
33. })
34. task.pause().then(() => {
35. console.info(`Succeeded in pausing a download task. `);
36. }).catch((err: BusinessError) => {
37. console.error(`Failed to pause the download task, Code: ${err.code}, message: ${err.message}`);
38. });
39. console.info(`Succeeded in creating a download task. result: ${task.tid}`);
40. }).catch((err: BusinessError) => {
41. console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
42. });
```

### resume10+

PhonePC/2in1TabletTVWearable

resume(callback: AsyncCallback<void>): void

重新启动任务，可以恢复被暂停的任务。使用callback异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.Request.FileTransferAgent

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| callback | AsyncCallback<void> | 是 | 回调函数。当重新启动任务成功，err为undefined，否则为错误对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | Permission denied. |
| 13400003 | Task service ability error. |
| 21900007 | Operation with wrong task state. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let config: request.agent.Config = {
7. action: request.agent.Action.DOWNLOAD,
8. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
9. title: 'taskResumeTest',
10. description: 'Sample code for resume the download task',
11. mode: request.agent.Mode.BACKGROUND,
12. overwrite: false,
13. method: "GET",
14. data: "",
15. saveas: "./",
16. network: request.agent.Network.CELLULAR,
17. metered: false,
18. roaming: true,
19. retry: true,
20. redirect: true,
21. index: 0,
22. begins: 0,
23. ends: -1,
24. gauge: false,
25. precise: false,
26. token: "it is a secret"
27. };
28. request.agent.create(context, config).then(async (task: request.agent.Task) => {
29. task.start();
30. // 等待1秒再执行下一步操作，以防异步乱序
31. await new Promise<void>((resolve) => {
32. setTimeout(() => resolve(),1000)
33. })
34. task.pause();
35. // 等待1秒再执行下一步操作，以防异步乱序
36. await new Promise<void>((resolve) => {
37. setTimeout(() => resolve(),1000)
38. })
39. task.resume((err: BusinessError) => {
40. if (err) {
41. console.error(`Failed to resume the download task, Code: ${err.code}, message: ${err.message}`);
42. return;
43. }
44. console.info(`Succeeded in resuming a download task. `);
45. });
46. console.info(`Succeeded in creating a download task. result: ${task.tid}`);
47. }).catch((err: BusinessError) => {
48. console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
49. });
```

### resume10+

PhonePC/2in1TabletTVWearable

resume(): Promise<void>

重新启动任务，可以恢复被暂停的任务。使用Promise异步回调。

**需要权限**：ohos.permission.INTERNET

**系统能力**：SystemCapability.Request.FileTransferAgent

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | Permission denied. |
| 13400003 | Task service ability error. |
| 21900007 | Operation with wrong task state. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let config: request.agent.Config = {
7. action: request.agent.Action.DOWNLOAD,
8. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
9. title: 'taskResumeTest',
10. description: 'Sample code for resume the download task',
11. mode: request.agent.Mode.BACKGROUND,
12. overwrite: false,
13. method: "GET",
14. data: "",
15. saveas: "./",
16. network: request.agent.Network.CELLULAR,
17. metered: false,
18. roaming: true,
19. retry: true,
20. redirect: true,
21. index: 0,
22. begins: 0,
23. ends: -1,
24. gauge: false,
25. precise: false,
26. token: "it is a secret"
27. };
28. request.agent.create(context, config).then(async (task: request.agent.Task) => {
29. task.start();
30. // 等待1秒再执行下一步操作，以防异步乱序
31. await new Promise<void>((resolve) => {
32. setTimeout(() => resolve(),1000)
33. })
34. task.pause();
35. // 等待1秒再执行下一步操作，以防异步乱序
36. await new Promise<void>((resolve) => {
37. setTimeout(() => resolve(),1000)
38. })
39. task.resume().then(() => {
40. console.info(`Succeeded in resuming a download task. `);
41. }).catch((err: BusinessError) => {
42. console.error(`Failed to resume the download task, Code: ${err.code}, message: ${err.message}`);
43. });
44. console.info(`Succeeded in creating a download task. result: ${task.tid}`);
45. }).catch((err: BusinessError) => {
46. console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
47. });
```

### stop10+

PhonePC/2in1TabletTVWearable

stop(callback: AsyncCallback<void>): void

停止任务，可以停止正在运行/正在等待/正在重试的任务，已停止的任务可被[start](/consumer/cn/doc/harmonyos-references/js-apis-request#start10)恢复。使用callback异步回调。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| callback | AsyncCallback<void> | 是 | 回调函数。当停止任务成功，err为undefined，否则为错误对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 13400003 | Task service ability error. |
| 21900007 | Operation with wrong task state. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let config: request.agent.Config = {
7. action: request.agent.Action.DOWNLOAD,
8. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
9. title: 'taskStopTest',
10. description: 'Sample code for stop the download task',
11. mode: request.agent.Mode.BACKGROUND,
12. overwrite: false,
13. method: "GET",
14. data: "",
15. saveas: "./",
16. network: request.agent.Network.CELLULAR,
17. metered: false,
18. roaming: true,
19. retry: true,
20. redirect: true,
21. index: 0,
22. begins: 0,
23. ends: -1,
24. gauge: false,
25. precise: false,
26. token: "it is a secret"
27. };
28. request.agent.create(context, config).then(async (task: request.agent.Task) => {
29. task.start();
30. // 等待1秒再执行下一步操作，以防异步乱序
31. await new Promise<void>((resolve) => {
32. setTimeout(() => resolve(),1000)
33. })
34. task.stop((err: BusinessError) => {
35. if (err) {
36. console.error(`Failed to stop the download task, Code: ${err.code}, message: ${err.message}`);
37. return;
38. }
39. console.info(`Succeeded in stopping a download task. `);
40. });
41. console.info(`Succeeded in creating a download task. result: ${task.tid}`);
42. }).catch((err: BusinessError) => {
43. console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
44. });
```

### stop10+

PhonePC/2in1TabletTVWearable

stop(): Promise<void>

停止任务，可以停止正在运行/正在等待/正在重试的任务，已停止的任务可被[start](/consumer/cn/doc/harmonyos-references/js-apis-request#start10)恢复。使用Promise异步回调。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 13400003 | Task service ability error. |
| 21900007 | Operation with wrong task state. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let config: request.agent.Config = {
7. action: request.agent.Action.DOWNLOAD,
8. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
9. title: 'taskStopTest',
10. description: 'Sample code for stop the download task',
11. mode: request.agent.Mode.BACKGROUND,
12. overwrite: false,
13. method: "GET",
14. data: "",
15. saveas: "./",
16. network: request.agent.Network.CELLULAR,
17. metered: false,
18. roaming: true,
19. retry: true,
20. redirect: true,
21. index: 0,
22. begins: 0,
23. ends: -1,
24. gauge: false,
25. precise: false,
26. token: "it is a secret"
27. };
28. request.agent.create(context, config).then(async (task: request.agent.Task) => {
29. task.start();
30. // 等待1秒再执行下一步操作，以防异步乱序
31. await new Promise<void>((resolve) => {
32. setTimeout(() => resolve(),1000)
33. })
34. task.stop().then(() => {
35. console.info(`Succeeded in stopping a download task. `);
36. }).catch((err: BusinessError) => {
37. console.error(`Failed to stop the download task, Code: ${err.code}, message: ${err.message}`);
38. });
39. console.info(`Succeeded in creating a download task. result: ${task.tid}`);
40. }).catch((err: BusinessError) => {
41. console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
42. });
```

### setMaxSpeed18+

PhonePC/2in1TabletTVWearable

setMaxSpeed(speed: number): Promise<void>

设置任务每秒能传输的字节数上限。使用Promise异步回调。

**系统能力**：SystemCapability.Request.FileTransferAgent

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| speed | number | 是 | 设置任务每秒能传输的字节数上限，单位为字节（B），最小值为16384字节，同时该值不得低于[MinSpeed](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentminspeed20)设置的最低速度。 |

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |
| 13400003 | Task service ability error. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let config: request.agent.Config = {
7. action: request.agent.Action.DOWNLOAD,
8. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
9. saveas: "./",
10. };
11. request.agent.create(context, config).then((task: request.agent.Task) => {
12. // 设置任务速度上限。
13. task.setMaxSpeed(10 * 1024 * 1024).then(() => {
14. console.info(`Succeeded in setting the max speed of the task. result: ${task.tid}`);
15. }).catch((err: BusinessError) => {
16. console.error(`Failed to set the max speed of the task. result: ${task.tid}`);
17. });
18. }).catch((err: BusinessError) => {
19. console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
20. });
```

## request.agent.create10+

PhonePC/2in1TabletTVWearable

create(context: BaseContext, config: Config, callback: AsyncCallback<Task>): void

创建需要上传或下载的任务，并将其排入队列。支持HTTP/HTTPS协议，使用callback异步回调。

**需要权限**：ohos.permission.INTERNET

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| context | [BaseContext](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-inner-application-basecontext) | 是 | 基于应用程序的上下文。 |
| config | [Config](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentconfig10) | 是 | 上传/下载任务的配置信息。 |
| callback | AsyncCallback<[Task](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagenttask10)> | 是 | 回调函数。当创建上传或下载任务成功，err为undefined，data为获取到的Task对象；否则为错误对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | Permission denied. |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |
| 13400001 | Invalid file or file system error. |
| 13400003 | Task service ability error. |
| 21900004 | The application task queue is full. |
| 21900005 | Operation with wrong task mode. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let attachments: Array<request.agent.FormItem> = [{
7. name: "createTest",
8. value: {
9. filename: "createTest.avi",
10. path: "./createTest.avi",
11. }
12. }];
13. let config: request.agent.Config = {
14. action: request.agent.Action.UPLOAD,
15. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
16. title: 'createTest',
17. description: 'Sample code for create task',
18. mode: request.agent.Mode.BACKGROUND,
19. overwrite: false,
20. method: "PUT",
21. data: attachments,
22. saveas: "./",
23. network: request.agent.Network.CELLULAR,
24. metered: false,
25. roaming: true,
26. retry: true,
27. redirect: true,
28. index: 0,
29. begins: 0,
30. ends: -1,
31. gauge: false,
32. precise: false,
33. token: "it is a secret"
34. };
35. request.agent.create(context, config, async (err: BusinessError, task: request.agent.Task) => {
36. if (err) {
37. console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
38. return;
39. }
40. console.info(`Succeeded in creating a download task. result: ${task.config}`);
41. await task.start();
42. // 用户需要手动调用remove从而结束task对象的生命周期
43. request.agent.remove(task.tid);
44. });
```

## request.agent.create10+

PhonePC/2in1TabletTVWearable

create(context: BaseContext, config: Config): Promise<Task>

创建需要上传或下载的任务，并将其排入队列。支持HTTP/HTTPS协议，使用Promise异步回调。

**需要权限**：ohos.permission.INTERNET

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

说明

示例中context的获取方式请参见[获取UIAbility的上下文信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiability-usage#获取uiability的上下文信息)。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| context | [BaseContext](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-inner-application-basecontext) | 是 | 基于应用程序的上下文。 |
| config | [Config](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentconfig10) | 是 | 上传/下载任务的配置信息。 |

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<[Task](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagenttask10)> | Promise对象。返回任务配置信息的Promise对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | Permission denied. |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |
| 13400001 | Invalid file or file system error. |
| 13400003 | Task service ability error. |
| 21900004 | The application task queue is full. |
| 21900005 | Operation with wrong task mode. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. let attachments: Array<request.agent.FormItem> = [{
7. name: "createTest",
8. value: {
9. filename: "createTest.avi",
10. path: "./createTest.avi",
11. }
12. }];
13. let config: request.agent.Config = {
14. action: request.agent.Action.UPLOAD,
15. url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
16. title: 'createTest',
17. description: 'Sample code for create task',
18. mode: request.agent.Mode.BACKGROUND,
19. overwrite: false,
20. method: "PUT",
21. data: attachments,
22. saveas: "./",
23. network: request.agent.Network.CELLULAR,
24. metered: false,
25. roaming: true,
26. retry: true,
27. redirect: true,
28. index: 0,
29. begins: 0,
30. ends: -1,
31. gauge: false,
32. precise: false,
33. token: "it is a secret"
34. };
35. request.agent.create(context, config).then(async (task: request.agent.Task) => {
36. console.info(`Succeeded in creating a download task. result: ${task.config}`);
37. await task.start();
38. // 用户需要手动调用remove从而结束task对象的生命周期
39. request.agent.remove(task.tid);
40. }).catch((err: BusinessError) => {
41. console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
42. });
```

## request.agent.getTask11+

PhonePC/2in1TabletTVWearable

getTask(context: BaseContext, id: string, token?: string): Promise<Task>

根据任务id查询任务。使用Promise异步回调。

**系统能力**：SystemCapability.Request.FileTransferAgent

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| context | [BaseContext](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-inner-application-basecontext) | 是 | 基于应用程序的上下文。 |
| id | string | 是 | 任务id。 |
| token | string | 否 | 任务查询token。默认值为空。 |

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<[Task](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagenttask10)> | Promise对象。返回任务配置信息的Promise对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |
| 13400003 | Task service ability error. |
| 21900006 | Task removed or not found. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. import { common } from '@kit.AbilityKit';

4. // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
5. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
6. request.agent.getTask(context, "123456").then((task: request.agent.Task) => {
7. console.info(`Succeeded in querying a task. result: ${task.tid}`);
8. }).catch((err: BusinessError) => {
9. console.error(`Failed to query a task, Code: ${err.code}, message: ${err.message}`);
10. });
```

## request.agent.remove10+

PhonePC/2in1TabletTVWearable

remove(id: string, callback: AsyncCallback<void>): void

移除属于调用方的指定任务，如果正在处理中，该任务将被迫停止。使用callback异步回调。在调用后任务对象和其回调函数会被释放。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | string | 是 | 任务id。 |
| callback | AsyncCallback<void> | 是 | 回调函数。当移除指定任务成功，err为undefined，否则为错误对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. |
| 13400003 | Task service ability error. |
| 21900006 | Task removed or not found. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';

3. request.agent.remove("123456", (err: BusinessError) => {
4. if (err) {
5. console.error(`Failed to remove a download task, Code: ${err.code}, message: ${err.message}`);
6. return;
7. }
8. console.info(`Succeeded in removing a download task.`);
9. });
```

## request.agent.remove10+

PhonePC/2in1TabletTVWearable

remove(id: string): Promise<void>

移除属于调用方的指定任务，如果正在处理中，该任务将被迫停止。使用Promise异步回调。在调用后任务对象和其回调函数会被释放。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力**：SystemCapability.Request.FileTransferAgent

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | string | 是 | 任务id。 |

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. |
| 13400003 | Task service ability error. |
| 21900006 | Task removed or not found. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';

3. request.agent.remove("123456").then(() => {
4. console.info(`Succeeded in removing a download task. `);
5. }).catch((err: BusinessError) => {
6. console.error(`Failed to remove a download task, Code: ${err.code}, message: ${err.message}`);
7. });
```

## request.agent.show10+

PhonePC/2in1TabletTVWearable

show(id: string, callback: AsyncCallback<TaskInfo>): void

根据任务id查询任务的详细信息。使用callback异步回调。

**系统能力**：SystemCapability.Request.FileTransferAgent

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | string | 是 | 任务id。 |
| callback | AsyncCallback<[TaskInfo](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagenttaskinfo10)> | 是 | 回调函数。当查询任务操作成功，err为undefined，data为查询到的任务TaskInfo信息；否则为错误对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. |
| 13400003 | Task service ability error. |
| 21900006 | Task removed or not found. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';

3. request.agent.show("123456", (err: BusinessError, taskInfo: request.agent.TaskInfo) => {
4. if (err) {
5. console.error(`Failed to show a upload task, Code: ${err.code}, message: ${err.message}`);
6. return;
7. }
8. console.info(`Succeeded in showing a upload task.`);
9. });
```

## request.agent.show10+

PhonePC/2in1TabletTVWearable

show(id: string): Promise<TaskInfo>

根据任务id查询任务的详细信息。使用Promise异步回调。

**系统能力**：SystemCapability.Request.FileTransferAgent

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | string | 是 | 任务id。 |

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<[TaskInfo](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagenttaskinfo10)> | Promise对象。返回任务详细信息TaskInfo的Promise对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. |
| 13400003 | Task service ability error. |
| 21900006 | Task removed or not found. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';

3. request.agent.show("123456").then((taskInfo: request.agent.TaskInfo) => {
4. console.info(`Succeeded in showing a upload task.`);
5. }).catch((err: BusinessError) => {
6. console.error(`Failed to show a upload task, Code: ${err.code}, message: ${err.message}`);
7. });
```

## request.agent.touch10+

PhonePC/2in1TabletTVWearable

touch(id: string, token: string, callback: AsyncCallback<TaskInfo>): void

根据任务id和token查询任务的详细信息。使用callback异步回调。

**系统能力**：SystemCapability.Request.FileTransferAgent

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | string | 是 | 任务id。 |
| token | string | 是 | 任务查询token。 |
| callback | AsyncCallback<[TaskInfo](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagenttaskinfo10)> | 是 | 回调函数。当查询任务操作成功，err为undefined，data为查询到的任务TaskInfo信息；否则为错误对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |
| 13400003 | Task service ability error. |
| 21900006 | Task removed or not found. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';

3. request.agent.touch("123456", "token", (err: BusinessError, taskInfo: request.agent.TaskInfo) => {
4. if (err) {
5. console.error(`Failed to touch a upload task, Code: ${err.code}, message: ${err.message}`);
6. return;
7. }
8. console.info(`Succeeded in touching a upload task.`);
9. });
```

## request.agent.touch10+

PhonePC/2in1TabletTVWearable

touch(id: string, token: string): Promise<TaskInfo>

根据任务id和token查询任务的详细信息。使用Promise异步回调。

**系统能力**：SystemCapability.Request.FileTransferAgent

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | string | 是 | 任务id。 |
| token | string | 是 | 任务查询token。 |

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<[TaskInfo](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagenttaskinfo10)> | Promise对象。返回任务详细信息TaskInfo的Promise对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |
| 13400003 | Task service ability error. |
| 21900006 | Task removed or not found. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';

3. request.agent.touch("123456", "token").then((taskInfo: request.agent.TaskInfo) => {
4. console.info(`Succeeded in touching a upload task. `);
5. }).catch((err: BusinessError) => {
6. console.error(`Failed to touch a upload task, Code: ${err.code}, message: ${err.message}`);
7. });
```

## request.agent.search10+

PhonePC/2in1TabletTVWearable

search(callback: AsyncCallback<Array<string>>): void

根据默认[Filter](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentfilter10)过滤条件查找任务id，即查询调用时刻至24小时前的所有任务的任务id。使用callback异步回调。

**系统能力**：SystemCapability.Request.FileTransferAgent

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| callback | AsyncCallback<Array<string>> | 是 | 回调函数。当根据过滤条件查找任务成功，err为undefined，data为满足条件的任务id；否则为错误对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Incorrect parameter type. 2. Parameter verification failed. |
| 13400003 | Task service ability error. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';

3. request.agent.search((err: BusinessError, data: Array<string>) => {
4. if (err) {
5. console.error(`Failed to search a upload task, Code: ${err.code}, message: ${err.message}`);
6. return;
7. }
8. console.info(`Succeeded in searching a upload task. `);
9. });
```

## request.agent.search10+

PhonePC/2in1TabletTVWearable

search(filter: Filter, callback: AsyncCallback<Array<string>>): void

根据[Filter](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentfilter10)过滤条件查找任务id。使用callback异步回调。

**系统能力**：SystemCapability.Request.FileTransferAgent

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| filter | [Filter](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentfilter10) | 是 | 过滤条件。 |
| callback | AsyncCallback<Array<string>> | 是 | 回调函数。当根据过滤条件查找任务成功，err为undefined，data为满足条件的任务id；否则为错误对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Incorrect parameter type. 2. Parameter verification failed. |
| 13400003 | Task service ability error. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';

3. let filter: request.agent.Filter = {
4. action: request.agent.Action.UPLOAD,
5. mode: request.agent.Mode.BACKGROUND
6. }
7. request.agent.search(filter, (err: BusinessError, data: Array<string>) => {
8. if (err) {
9. console.error(`Failed to search a upload task, Code: ${err.code}, message: ${err.message}`);
10. return;
11. }
12. console.info(`Succeeded in searching a upload task. `);
13. });
```

## request.agent.search10+

PhonePC/2in1TabletTVWearable

search(filter?: Filter): Promise<Array<string>>

根据[Filter](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentfilter10)过滤条件查找任务id。使用Promise异步回调。

**系统能力**：SystemCapability.Request.FileTransferAgent

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| filter | [Filter](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentfilter10) | 否 | 过滤条件。默认值为空。 |

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<Array<string>> | Promise对象。返回满足条件任务id的Promise对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Incorrect parameter type. 2. Parameter verification failed. |
| 13400003 | Task service ability error. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';

3. let filter: request.agent.Filter = {
4. action: request.agent.Action.UPLOAD,
5. mode: request.agent.Mode.BACKGROUND
6. }
7. request.agent.search(filter).then((data: Array<string>) => {
8. console.info(`Succeeded in searching a upload task. `);
9. }).catch((err: BusinessError) => {
10. console.error(`Failed to search a upload task, Code: ${err.code}, message: ${err.message}`);
11. });
```

## request.agent.createGroup15+

PhonePC/2in1TabletTVWearable

createGroup(config: GroupConfig): Promise<string>

根据[GroupConfig](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentgroupconfig15)分组条件创建分组，并返回分组id。使用Promise异步回调。

**系统能力**：SystemCapability.Request.FileTransferAgent

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| config | [GroupConfig15+](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentgroupconfig15) | 是 | 下载任务分组选项。 |

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<string> | Promise对象。返回创建完成的分组id。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |
| 13400003 | Task service ability error. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';

3. // 准备分组配置选项 GroupConfig 对象。
4. let config: request.agent.GroupConfig = {
5. notification: {},
6. };
7. // 调用 createGroup 接口创建分组。
8. request.agent.createGroup(config).then((gid: string) => {
9. console.info(`Succeeded in creating a download task group. `);
10. }).catch((err: BusinessError) => {
11. console.error(`Failed to create a download group, Code: ${err.code}, message: ${err.message}`);
12. });
```

## request.agent.attachGroup15+

PhonePC/2in1TabletTVWearable

attachGroup(gid: string, tids: string[]): Promise<void>

向指定分组id中绑定多个下载任务id。使用Promise异步回调。

如果任意一个任务id不满足添加条件，则所有列表中的任务都不会添加到分组中。

**系统能力**：SystemCapability.Request.FileTransferAgent

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| gid | string | 是 | 目标分组id。 |
| tids | string[] | 是 | 待绑定的任务id列表。 |

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |
| 13400003 | Task service ability error. |
| 21900005 | Operation with wrong task mode. |
| 21900006 | Task removed or not found. |
| 21900007 | Operation with wrong task state. |
| 21900008 | Group deleted or not found. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';

3. // 准备分组id和任务id列表。
4. let groupId: string = "123456789";
5. let taskIds: string[] = ["1111", "2222", "3333", "4444"];
6. // 调用 attachGroup 接口向分组中添加任务id列表。
7. request.agent.attachGroup(groupId, taskIds).then(() => {
8. console.info(`Succeeded in attaching tasks to the download task group.`);
9. }).catch((err: BusinessError) => {
10. console.error(`Failed to attach tasks to the download group, Code: ${err.code}, message: ${err.message}`);
11. });
```

## request.agent.deleteGroup15+

PhonePC/2in1TabletTVWearable

deleteGroup(gid: string): Promise<void>

移除指定分组，后续不能再往该分组中添加任务id。使用Promise异步回调。

当分组中的所有任务处于完成、失败或移除状态，并且分组被移除时，显示该分组的完成或失败通知。

**系统能力**：SystemCapability.Request.FileTransferAgent

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| gid | string | 是 | 目标分组id。与创建的任务分组ID保持一致，即使用[request.agent.createGroup](/consumer/cn/doc/harmonyos-references/js-apis-request#requestagentcreategroup15)接口成功创建任务分组时的返回值。 |

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |

**错误码：**

以下错误码的详细介绍请参见[上传下载错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-request)与[通用错误码说明文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |
| 13400003 | Task service ability error. |
| 21900008 | Group deleted or not found. |

**示例：**



```
1. import { BusinessError } from '@kit.BasicServicesKit';

3. // 准备分组id。
4. let groupId: string = "123456789";

6. // 调用 deleteGroup 接口移除分组。
7. request.agent.deleteGroup(groupId).then(() => {
8. console.info(`Succeeded in deleting the download task group.`);
9. }).catch((err: BusinessError) => {
10. console.error(`Failed to delete the download group, Code: ${err.code}, message: ${err.message}`);
11. });
```