@ohos.request (上传下载)

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

说明：

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

导入模块

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

常量

系统能力：SystemCapability.MiscServices.Download

说明：

网络类型：下载支持自定义网络类型，可以在DownloadConfig中通过networkType配置成以下网络类型。

下载任务错误码：下载on('fail')⁷⁺事件callback的错误参数、getTaskInfo⁹⁺返回值的failedReason字段取值。

下载任务暂停原因：下载相关getTaskInfo⁹⁺返回值的pausedReason字段取值。

下载任务状态码：下载相关getTaskInfo⁹⁺返回值的status字段取值。

名称	参数类型	数值	说明
EXCEPTION_PERMISSION⁹⁺	number	201	通用错误码：权限校验失败。
EXCEPTION_PARAMCHECK⁹⁺	number	401	通用错误码：参数检查失败。
EXCEPTION_UNSUPPORTED⁹⁺	number	801	通用错误码：该设备不支持此API。
EXCEPTION_FILEIO⁹⁺	number	13400001	特有错误码：文件操作异常。
EXCEPTION_FILEPATH⁹⁺	number	13400002	特有错误码：文件路径异常。
EXCEPTION_SERVICE⁹⁺	number	13400003	特有错误码：服务异常。
EXCEPTION_OTHERS⁹⁺	number	13499999	特有错误码：其他错误。
NETWORK_MOBILE⁶⁺	number	0x00000001	网络类型：使用蜂窝网络时允许下载的位标志。
NETWORK_WIFI⁶⁺	number	0x00010000	网络类型：使用WLAN时允许下载的位标志。
ERROR_CANNOT_RESUME⁷⁺	number	0	下载任务错误码：网络原因导致恢复下载失败。
ERROR_DEVICE_NOT_FOUND⁷⁺	number	1	下载任务错误码：找不到SD卡等存储设备。
ERROR_FILE_ALREADY_EXISTS⁷⁺	number	2	下载任务错误码：要下载的文件已存在，下载会话无法覆盖现有文件。
ERROR_FILE_ERROR⁷⁺	number	3	下载任务错误码：文件操作失败。
ERROR_HTTP_DATA_ERROR⁷⁺	number	4	下载任务错误码：HTTP传输失败。
ERROR_INSUFFICIENT_SPACE⁷⁺	number	5	下载任务错误码：存储空间不足。
ERROR_TOO_MANY_REDIRECTS⁷⁺	number	6	下载任务错误码：网络重定向过多导致的错误。
ERROR_UNHANDLED_HTTP_CODE⁷⁺	number	7	下载任务错误码：无法识别的HTTP代码。
ERROR_UNKNOWN⁷⁺	number	8	下载任务错误码：未知错误。例如：API version 12及以下版本，系统仅支持串行地尝试连接域名相关IP，不支持单个IP的连接时间控制。若DNS返回的首个IP被阻塞，可能会由于握手超时导致ERROR_UNKNOWN错误。
ERROR_OFFLINE⁹⁺	number	9	下载任务错误码：网络未连接。
ERROR_UNSUPPORTED_NETWORK_TYPE⁹⁺	number	10	下载任务错误码：网络类型不匹配。
PAUSED_QUEUED_FOR_WIFI⁷⁺	number	0	下载任务暂停原因：文件大小超过了使用蜂窝网络会话允许的最大值，下载被暂停并等待WLAN连接。
PAUSED_WAITING_FOR_NETWORK⁷⁺	number	1	下载任务暂停原因：网络问题导致下载暂停。例如：网络断开。
PAUSED_WAITING_TO_RETRY⁷⁺	number	2	下载任务暂停原因：网络错误导致下载会话将被重试。
PAUSED_BY_USER⁹⁺	number	3	下载任务暂停原因：用户暂停会话。
PAUSED_UNKNOWN⁷⁺	number	4	下载任务暂停原因：未知原因导致暂停下载。
SESSION_SUCCESSFUL⁷⁺	number	0	下载任务状态码：下载会话已完成。
SESSION_RUNNING⁷⁺	number	1	下载任务状态码：下载会话正在进行中。
SESSION_PENDING⁷⁺	number	2	下载任务状态码：下载会话正在被调度中。
SESSION_PAUSED⁷⁺	number	3	下载任务状态码：下载会话已暂停。
SESSION_FAILED⁷⁺	number	4	下载任务状态码：下载会话已失败，将不会重试。

request.uploadFile⁹⁺

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

创建并启动一个上传任务，使用Promise异步回调，支持HTTP协议。通过on('complete'|'fail')⁹⁺可获取任务上传时的成功信息或错误信息。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Upload

参数：

参数名	类型	必填	说明
context	BaseContext	是	基于应用程序的上下文。
config	UploadConfig	是	上传的配置信息。

返回值：

类型	说明
Promise<UploadTask>	使用Promise方式，异步返回上传任务UploadTask的Promise对象。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码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	bad file path

示例：

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

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

说明：

示例中context的获取方式请参见获取UIAbility的上下文信息。

request.uploadFile⁹⁺

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

创建并启动一个上传任务，使用callback异步回调，支持HTTP协议。通过on('complete'|'fail')⁹⁺可获取任务上传时的成功信息或错误信息。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Upload

参数：

参数名	类型	必填	说明
context	BaseContext	是	基于应用程序的上下文。
config	UploadConfig	是	上传的配置信息。
callback	AsyncCallback<UploadTask>	是	回调函数，异步返回UploadTask对象。当上传成功，err为undefined，data为获取到的UploadTask对象；否则为错误对象。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码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	bad file path

示例：

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

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

说明：

示例中context的获取方式请参见获取UIAbility的上下文信息。

request.upload^(deprecated)

upload(config: UploadConfig): Promise<UploadTask>

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

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

说明：

从API version 6 开始支持，从API version 9 开始废弃，建议使用request.uploadFile⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Upload

参数：

参数名	类型	必填	说明
config	UploadConfig	是	上传的配置信息。

返回值：

类型	说明
Promise<UploadTask>	使用Promise方式，异步返回上传任务UploadTask的Promise对象。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

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

request.upload^(deprecated)

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

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

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

说明：

从API version 6 开始支持，从API version 9 开始废弃，建议使用request.uploadFile⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Upload

参数：

参数名	类型	必填	说明
config	UploadConfig	是	上传的配置信息。
callback	AsyncCallback<UploadTask>	是	回调函数，异步返回UploadTask对象。当上传成功，err为undefined，data为获取到的UploadTask对象；否则为错误对象。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

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

UploadTask

上传任务，使用下列方法前，需要先获取UploadTask对象，promise形式通过request.uploadFile⁹⁺获取，callback形式通过request.uploadFile⁹⁺获取。

on('progress')

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）。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

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

on('headerReceive')⁷⁺

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

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

系统能力：SystemCapability.MiscServices.Upload

参数：

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

回调函数的参数：

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

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

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

on('complete' | 'fail')⁹⁺

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

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

系统能力：SystemCapability.MiscServices.Upload

参数：

参数名	类型	必填	说明
type	string	是	订阅的事件类型，支持的事件包括：`'complete'`\|`'fail'`。 - `'complete'`：表示上传任务完成，任务完成时触发该事件。 - `'fail'`：表示上传任务失败，任务失败时触发该事件。
callback	Callback<Array<TaskState>>	是	上传任务完成或失败的回调函数。返回上传任务的任务状态信息。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

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

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

off('progress')

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

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

系统能力：SystemCapability.MiscServices.Upload

参数：

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

回调函数的参数

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

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

let upProgressCallback1 = (uploadedSize: number, totalSize: number) => {
  console.info('Upload delete progress notification.' + 'totalSize:' + totalSize + 'uploadedSize:' + uploadedSize);
};
let upProgressCallback2 = (uploadedSize: number, totalSize: number) => {
  console.info('Upload delete progress notification.' + 'totalSize:' + totalSize + 'uploadedSize:' + uploadedSize);
};
uploadTask.on('progress', upProgressCallback1);
uploadTask.on('progress', upProgressCallback2);
//表示取消upProgressCallback1的订阅
uploadTask.off('progress', upProgressCallback1);
//表示取消订阅上传任务进度事件的所有回调
uploadTask.off('progress');

off('headerReceive')⁷⁺

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

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

系统能力：SystemCapability.MiscServices.Upload

参数：

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

回调函数的参数：

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

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

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

off('complete' | 'fail')⁹⁺

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

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

系统能力：SystemCapability.MiscServices.Upload

参数：

参数名	类型	必填	说明
type	string	是	取消订阅的事件类型。 - 取值为'complete'，表示上传任务完成。 - 取值为'fail'，表示上传任务失败。
callback	Callback<Array<TaskState>>	否	需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

let upCompleteCallback1 = (taskStates: Array<request.TaskState>) => {
  console.info('Upload delete complete notification.');
  for (let i = 0; i < taskStates.length; i++) {
    console.info('taskState:' + JSON.stringify(taskStates[i]));
  }
};
let upCompleteCallback2 = (taskStates: Array<request.TaskState>) => {
  console.info('Upload delete complete notification.');
  for (let i = 0; i < taskStates.length; i++) {
    console.info('taskState:' + JSON.stringify(taskStates[i]));
  }
};
uploadTask.on('complete', upCompleteCallback1);
uploadTask.on('complete', upCompleteCallback2);
//表示取消headerCallback1的订阅
uploadTask.off('complete', upCompleteCallback1);
//表示取消订阅上传任务完成的所有回调
uploadTask.off('complete');

let upFailCallback1 = (taskStates: Array<request.TaskState>) => {
  console.info('Upload delete fail notification.');
  for (let i = 0; i < taskStates.length; i++) {
    console.info('taskState:' + JSON.stringify(taskStates[i]));
  }
};
let upFailCallback2 = (taskStates: Array<request.TaskState>) => {
  console.info('Upload delete fail notification.');
  for (let i = 0; i < taskStates.length; i++) {
    console.info('taskState:' + JSON.stringify(taskStates[i]));
  }
};
uploadTask.on('fail', upFailCallback1);
uploadTask.on('fail', upFailCallback2);
//表示取消headerCallback1的订阅
uploadTask.off('fail', upFailCallback1);
//表示取消订阅上传任务失败的所有回调
uploadTask.off('fail');

delete⁹⁺

delete(): Promise<boolean>

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

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Upload

返回值：

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

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

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

说明：

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

delete⁹⁺

delete(callback: AsyncCallback<boolean>): void

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

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Upload

参数：

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

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

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

说明：

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

remove^(deprecated)

remove(): Promise<boolean>

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

说明：

从API Version 9开始不再维护，建议使用delete⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Upload

返回值：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

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

remove^(deprecated)

remove(callback: AsyncCallback<boolean>): void

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

说明：

从API Version 9开始不再维护，建议使用delete⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Upload

参数：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

uploadTask.remove((err, result) => {
  if (err) {
    console.error(`Failed to remove the upload task. Code: ${err.code}, message: ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in removing the upload task.');
  } else {
    console.error(`Failed to remove the upload task. Code: ${err.code}, message: ${err.message}`);
  }
});

UploadConfig⁶⁺

上传任务的配置信息。

系统能力：SystemCapability.MiscServices.Upload。

名称	类型	必填	说明
url	string	是	资源地址。从API 6到API 14，最大长度为2048个字符；从API 15开始，最大长度为8192个字符。支持HTTP拦截功能。
header	Object	是	添加要包含在上传请求中的HTTP或HTTPS标志头。
method	string	是	HTTP请求方法：POST、PUT，缺省为POST。使用POST新增资源，使用PUT修改资源。
index¹¹⁺	number	否	任务的路径索引，默认值为0。
begins¹¹⁺	number	否	上传任务开始时读取的文件起点。默认值为0，取值范围为闭区间，表示从头开始传输。
ends¹¹⁺	number	否	上传任务结束时读取的文件终点。默认值为-1，取值范围为闭区间，表示传输到整个文件末尾结束。
files	Array<File>	是	要上传的文件列表。文件以HTTP的multipart/form-data格式提交。
data	Array<RequestData>	是	请求的表单数据。

TaskState⁹⁺

上传任务的任务信息，是on('complete' | 'fail')⁹⁺和off('complete' | 'fail')⁹⁺接口的回调参数。

系统能力：SystemCapability.MiscServices.Upload。

名称	类型	必填	说明
path	string	是	文件路径。
responseCode	number	是	上传任务返回码。返回0表示上传任务成功，返回其它值表示上传任务失败，具体请参见message参数中的上传任务结果描述信息。此处推荐使用request.agent.create¹⁰⁺创建上传任务，并获取标准错误码处理异常分支。
message	string	是	上传任务结果描述信息。

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

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

File

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

UploadConfig⁶⁺中的表单数据。

系统能力：SystemCapability.MiscServices.Download。

名称	类型	必填	说明
name	string	是	表示表单元素的名称。
value	string	是	表示表单元素的值。

request.downloadFile⁹⁺

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

创建并启动一个下载任务，使用Promise异步回调，支持HTTP协议。通过on('complete'|'pause'|'remove')⁷⁺可以获取任务下载时的状态信息，包括任务完成、暂停或移除。通过on('fail')⁷⁺可以获取任务下载时的错误信息。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
context	BaseContext	是	基于应用程序的上下文。
config	DownloadConfig	是	下载的配置信息。

返回值：

类型	说明
Promise<DownloadTask>	使用Promise方式，异步返回下载任务DownloadTask的Promise对象。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码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	file operation error.
13400002	bad file path.
13400003	task service ability error.

示例：

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

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

说明：

示例中context的获取方式请参见获取UIAbility的上下文信息。

request.downloadFile⁹⁺

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

创建并启动一个下载任务，使用callback异步回调，支持HTTP协议。通过on('complete'|'pause'|'remove')⁷⁺可获取任务下载时的状态信息，包括任务完成、暂停或移除。通过on('fail')⁷⁺可获取任务下载时的错误信息。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
context	BaseContext	是	基于应用程序的上下文。
config	DownloadConfig	是	下载的配置信息。
callback	AsyncCallback<DownloadTask>	是	回调函数。当下载任务成功，err为undefined，data为获取到的DownloadTask对象；否则为错误对象。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码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	file operation error.
13400002	bad file path.
13400003	task service ability error.

示例：

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

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

说明：

示例中context的获取方式请参见获取UIAbility的上下文信息。

request.download^(deprecated)

download(config: DownloadConfig): Promise<DownloadTask>

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

说明：

从API version 6 开始支持，从API version 9 开始废弃，建议使用request.downloadFile⁹⁺替代。

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

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
config	DownloadConfig	是	下载的配置信息。

返回值：

类型	说明
Promise<DownloadTask>	使用Promise方式，异步返回下载任务DownloadTask的Promise对象。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

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

request.download^(deprecated)

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

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

说明：

从API version 6 开始支持，从API version 9 开始废弃，建议使用request.downloadFile⁹⁺替代。

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

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
config	DownloadConfig	是	下载的配置信息。
callback	AsyncCallback<DownloadTask>	是	回调函数。当下载任务成功，err为undefined，data为获取到的DownloadTask对象；否则为错误对象。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

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

DownloadTask

下载任务，使用下列方法前，需要先获取DownloadTask对象，promise形式通过request.downloadFile⁹⁺获取，callback形式通过request.downloadFile⁹⁺获取。

on('progress')

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。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

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

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

off('progress')

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。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

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

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

on('complete'|'pause'|'remove')⁷⁺

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

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

系统能力：SystemCapability.MiscServices.Download

参数：

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

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

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

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

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

  let removeCallback = () => {
    console.info('Download task remove.');
  };
  downloadTask.on('remove', removeCallback);
}).catch((err: BusinessError) => {
  console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}

off('complete'|'pause'|'remove')⁷⁺

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

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

系统能力：SystemCapability.MiscServices.Download

参数：

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

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

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

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

  let pauseCallback1 = () => {
    console.info('Download delete pause notification.');
  };
  let pauseCallback2 = () => {
    console.info('Download delete pause notification.');
  };
  downloadTask.on('pause', pauseCallback1);
  downloadTask.on('pause', pauseCallback2);
  //表示取消pauseCallback1的订阅
  downloadTask.off('pause', pauseCallback1);
  //表示取消订阅下载任务暂停的所有回调
  downloadTask.off('pause');

  let removeCallback1 = () => {
    console.info('Download delete remove notification.');
  };
  let removeCallback2 = () => {
    console.info('Download delete remove notification.');
  };
  downloadTask.on('remove', removeCallback1);
  downloadTask.on('remove', removeCallback2);
  //表示取消removeCallback1的订阅
  downloadTask.off('remove', removeCallback1);
  //表示取消订阅下载任务移除的所有回调
  downloadTask.off('remove');
}).catch((err: BusinessError) => {
  console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}

on('fail')⁷⁺

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

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

系统能力：SystemCapability.MiscServices.Download

参数：

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

回调函数的参数：

参数名	类型	必填	说明
err	number	是	下载失败的错误码，错误原因见下载任务的错误码。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

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

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

off('fail')⁷⁺

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

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

系统能力：SystemCapability.MiscServices.Download

参数：

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

回调函数的参数：

参数名	类型	必填	说明
err	number	是	下载失败的错误码，错误原因见下载任务的错误码。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
try {
// 需要手动将url替换为真实服务器的HTTP协议地址
request.downloadFile(context, { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
  let downloadTask: request.DownloadTask = data;
  let failCallback1 = (err: number) => {
    console.error(`Failed to download the task. Code: ${err}`);
  };
  let failCallback2 = (err: number) => {
    console.error(`Failed to download the task. Code: ${err}`);
  };
  downloadTask.on('fail', failCallback1);
  downloadTask.on('fail', failCallback2);
  //表示取消failCallback1的订阅
  downloadTask.off('fail', failCallback1);
  //表示取消订阅下载任务失败的所有回调
  downloadTask.off('fail');
}).catch((err: BusinessError) => {
  console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}

delete⁹⁺

delete(): Promise<boolean>

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

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

返回值：

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

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

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

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

说明：

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

delete⁹⁺

delete(callback: AsyncCallback<boolean>): void

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

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

参数：

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

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

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

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

说明：

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

getTaskInfo⁹⁺

getTaskInfo(): Promise<DownloadInfo>

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

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

返回值：

类型	说明
Promise<DownloadInfo>	Promise对象，返回DownloadInfo对象。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

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

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

说明：

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

getTaskInfo⁹⁺

getTaskInfo(callback: AsyncCallback<DownloadInfo>): void

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

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

参数：

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

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

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

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

说明：

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

getTaskMimeType⁹⁺

getTaskMimeType(): Promise<string>

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

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

返回值：

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

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

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

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

说明：

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

getTaskMimeType⁹⁺

getTaskMimeType(callback: AsyncCallback<string>): void

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

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

参数：

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

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

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

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

说明：

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

suspend⁹⁺

suspend(): Promise<boolean>

暂停下载正在运行中的任务，已暂停的任务可被restore恢复，使用Promise异步回调。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

返回值：

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

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

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

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

说明：

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

suspend⁹⁺

suspend(callback: AsyncCallback<boolean>): void

暂停下载正在运行中的任务，已暂停的任务可被restore恢复，使用callback异步回调。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

参数：

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

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

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

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

说明：

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

restore⁹⁺

restore(): Promise<boolean>

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

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

返回值：

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

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

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

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

说明：

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

restore⁹⁺

restore(callback: AsyncCallback<boolean>): void

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

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

参数：

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

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

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

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

说明：

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

remove^(deprecated)

remove(): Promise<boolean>

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

说明：

从API Version 9开始不再维护，建议使用delete⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

返回值：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

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

remove^(deprecated)

remove(callback: AsyncCallback<boolean>): void

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

说明：

从API Version 9开始不再维护，建议使用delete⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

参数：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

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

query^(deprecated)

query(): Promise<DownloadInfo>

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

说明：

从API Version 7开始支持，从API Version 9开始不再维护，建议使用getTaskInfo⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

返回值：

类型	说明
Promise<DownloadInfo>	Promise对象。返回DownloadInfo。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

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

query^(deprecated)

query(callback: AsyncCallback<DownloadInfo>): void

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

说明：

从API Version 7开始支持，从API Version 9开始不再维护，建议使用getTaskInfo⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

参数：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

downloadTask.query((err, downloadInfo)=>{
  if(err) {
    console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`);
  } else {
    console.info('Succeeded in querying the download task.');
  }
});

queryMimeType^(deprecated)

queryMimeType(): Promise<string>

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

说明：

从API Version 7开始支持，从API Version 9开始不再维护，建议使用getTaskMimeType⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

返回值：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

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

queryMimeType^(deprecated)

queryMimeType(callback: AsyncCallback<string>): void

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

说明：

从API Version 7开始支持，从API Version 9开始不再维护，建议使用getTaskMimeType⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

参数：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

downloadTask.queryMimeType((err, data)=>{
  if(err) {
    console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`);
  } else {
    console.info('Succeeded in querying the download mimeType.');
  }
});

pause^(deprecated)

pause(): Promise<void>

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

说明：

从API Version 7开始支持，从API Version 9开始不再维护，建议使用suspend⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

返回值：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

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

pause^(deprecated)

pause(callback: AsyncCallback<void>): void

说明：

从API version 7开始支持，从API version 9开始废弃，建议使用suspend⁹⁺替代。

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

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

参数：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

downloadTask.pause((err, result)=>{
  if(err) {
    console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in pausing the download task.');
});

resume^(deprecated)

resume(): Promise<void>

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

说明：

从API Version 7开始支持，从API Version 9开始不再维护，建议使用restore⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

返回值：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

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

resume^(deprecated)

resume(callback: AsyncCallback<void>): void

说明：

从API Version 7开始支持，从API Version 9开始不再维护，建议使用restore⁹⁺替代。

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

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.MiscServices.Download

参数：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
201	the permissions check fails

示例：

downloadTask.resume((err, result)=>{
  if (err) {
    console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in resuming the download task.');
});

DownloadConfig

下载任务的配置信息。

系统能力：SystemCapability.MiscServices.Download

名称	类型	必填	说明
url	string	是	资源地址。从API 6到API 14，最大长度为2048个字符；从API 15开始，最大长度为8192个字符。支持HTTP拦截功能。
header	Object	否	添加要包含在下载请求中的HTTPS标志头。
enableMetered	boolean	否	表示设置是否允许在按流量计费的连接下下载任务的配置信息。true表示允许，false表示不允许。默认值为false。说明： Wi-Fi为非计费网络，数据流量为计费网络。
enableRoaming	boolean	否	表示设置是否允许在漫游网络中下载任务的配置信息。true表示允许，false表示不允许。默认值为false。
description	string	否	设置下载会话的描述。默认值为空字符串。
filePath⁷⁺	string	否	设置下载路径。默认为调用方（即传入的context）对应的缓存路径。默认文件名从url的最后一个"/"后截取。 - FA模型下使用context获取应用存储路径。 - Stage模型下使用AbilityContext类获取文件路径。
networkType	number	否	设置允许下载的网络类型。默认值为NETWORK_MOBILE&NETWORK_WIFI。 - NETWORK_MOBILE：0x00000001 - NETWORK_WIFI：0x00010000
title	string	否	设置下载任务名称。
background⁹⁺	boolean	否	后台任务通知开关，启用后可在通知中显示下载状态。true表示启用，false表示禁用。默认值为false。

DownloadInfo⁷⁺

下载任务信息，getTaskInfo⁹⁺接口的回调参数。

系统能力：SystemCapability.MiscServices.Download

名称	类型	必填	说明
downloadId	number	是	下载任务id。
failedReason	number	是	下载失败原因，可以是任何下载任务的错误码常量。
fileName	string	是	下载的文件名。
filePath	string	是	存储文件的URI。
pausedReason	number	是	会话暂停的原因，可以是任何下载任务暂停原因常量。
status	number	是	下载状态码，可以是任何下载任务状态码常量。
targetURI	string	是	下载文件的URI。
downloadTitle	string	是	下载任务名称。
downloadTotalBytes	number	是	下载的文件的总大小，单位为字节（B）。
description	string	是	待下载任务的描述信息。
downloadedBytes	number	是	实时下载大小，单位为字节（B）。

Action¹⁰⁺

定义操作选项。

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

系统能力：SystemCapability.Request.FileTransferAgent

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

Mode¹⁰⁺

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

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

系统能力：SystemCapability.Request.FileTransferAgent

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

Network¹⁰⁺

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

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

系统能力：SystemCapability.Request.FileTransferAgent

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

BroadcastEvent¹¹⁺

定义自定义系统事件。用户可以使用公共事件接口获取该事件。上传下载 SA 具有 'ohos.permission.SEND_TASK_COMPLETE_EVENT' 该权限，用户可以配置事件的metadata指向的二级配置文件来拦截其他事件发送者。

调用CommonEventData类型传输公共事件相关数据，成员的内容填写和 CommonEventData 介绍的有所区别，其中CommonEventData.code表示任务的状态，目前为0x40 COMPLETE或0x41 FAILED；CommonEventData.data表示任务的taskId。

请参考静态订阅公共事件以获取事件配置信息和二级配置文件的配置方式。

系统能力：SystemCapability.Request.FileTransferAgent

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

FileSpec¹⁰⁺

表单项的文件信息。

系统能力：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替代。
contentType¹⁸⁺	string	否	文件内容类型，默认值为文件名后缀。该选项会被填写到HTTP表单指定的Content-Type字段中。
filename	string	否	文件名，默认值通过路径获取。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
extras	object	否	文件信息的附加内容，该参数不会体现在HTTP请求中。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。

FormItem¹⁰⁺

任务的表单项信息。

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

系统能力：SystemCapability.Request.FileTransferAgent

名称	类型	必填	说明
name	string	是	表单参数名。
value	string \| FileSpec \| Array<FileSpec>	是	表单参数值。

Config¹⁰⁺

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

系统能力：SystemCapability.Request.FileTransferAgent

名称	类型	必填	说明
action	Action	是	任务操作选项。 - UPLOAD表示上传任务。 - DOWNLOAD表示下载任务。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
url	string	是	资源地址。从API 6到API 14，最大长度为2048个字符；从API 15开始，最大长度为8192个字符。支持HTTP拦截功能。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
title	string	否	任务标题，其最大长度为256个字符，默认值为小写的 upload 或 download，与上面的 action 保持一致。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
description	string	否	任务的详细信息，其最大长度为1024个字符，默认值为空字符串。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
mode	Mode	否	任务模式，默认为后台任务。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
overwrite	boolean	否	下载过程中路径已存在时的解决方案选择，默认为false。 - true，覆盖已存在的文件。 - false，下载失败。原子化服务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>	否	- 下载时，data为字符串类型，通常情况下使用json格式（object将被转换为json文本），默认为空。 - 上传时，data是表单项数组Array<FormItem>。从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"。默认为调用方（即传入的context）对应的缓存路径。默认文件名从url的最后一个"/"后截取。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
network	Network	否	网络选项，当前支持无线网络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开始，该接口支持在原子化服务中使用。
proxy¹²⁺	string	否	设置代理地址，其最大长度为512个字符，默认为空。代理地址格式:"http://<domain or address>:<port>"
index	number	否	任务的路径索引，通常情况下用于任务断点续传，默认为0。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
begins	number	否	文件起点，通常情况下用于断点续传。默认值为0，取值为闭区间，表示从头开始传输。 - 下载时，请求读取服务器开始下载文件时的起点位置（HTTP协议中设置"Range"选项）。 - 上传时，读取需上传的文件的起点位置。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
ends	number	否	文件终点，通常情况下用于断点续传。默认值为-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查询，否则无法查询到指定任务。其最小为8个字节，最大为2048个字节。默认为空。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
priority¹¹⁺	number	否	任务的优先级。前台任务的优先级比后台任务高。任务模式相同的情况下，该配置项的数字越小优先级越高，默认值为0。
extras	object	否	配置的附加功能，默认为空。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
multipart¹⁵⁺	boolean	否	是否使用单个请求进行上传，单个请求上传时必定使用multipart/form-data。 - false：每个文件使用一个请求传输。 - true：使用多文件单请求上传。默认值为false。
notification¹⁵⁺	Notification	否	通知栏自定义设置。默认值为`{}`。

State¹⁰⁺

定义任务当前的状态。

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

系统能力：SystemCapability.Request.FileTransferAgent

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

Progress¹⁰⁺

任务进度的数据结构。

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

系统能力：SystemCapability.Request.FileTransferAgent

名称	类型	必填	说明
state	State	是	任务当前的状态。
index	number	是	任务中当前正在处理的文件索引。
processed	number	是	任务中当前文件的已处理数据大小，单位为字节（B）。
sizes	Array<number>	是	任务中文件的大小，单位为字节（B）。在下载过程中，若服务器使用chunk方式传输导致无法从请求头中获取文件总大小时，sizes为 -1。
extras	object	否	交互的额外内容，例如：来自服务器的响应的header和body。

Faults¹⁰⁺

定义任务失败的原因。

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

系统能力：SystemCapability.Request.FileTransferAgent

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

说明：

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

Filter¹⁰⁺

过滤条件。

系统能力：SystemCapability.Request.FileTransferAgent

名称	类型	必填	说明
before	number	否	结束的Unix时间戳（毫秒），默认为调用时刻。
after	number	否	开始的Unix时间戳（毫秒），默认值为调用时刻减24小时。
state	State	否	指定任务的状态。如果未填写，则查询所有任务。
action	Action	否	任务操作选项。 - UPLOAD表示上传任务。 - DOWNLOAD表示下载任务。 - 如果未填写，则查询所有任务。
mode	Mode	否	任务模式。 - FOREGROUND表示前台任务。 - BACKGROUND表示后台任务。 - 如果未填写，则查询所有任务。

TaskInfo¹⁰⁺

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

系统能力：SystemCapability.Request.FileTransferAgent

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

HttpResponse¹²⁺

任务响应头的数据结构。

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

系统能力：SystemCapability.Request.FileTransferAgent

名称	类型	必填	说明
version	string	是	Http版本。
statusCode	number	是	Http响应状态码。
reason	string	是	Http响应原因。
headers	Map<string, Array<string>>	是	Http响应头部。

Notification¹⁵⁺

通知栏自定义信息。

系统能力：SystemCapability.Request.FileTransferAgent

名称	类型	必填	说明
title	string	否	通知栏自定义标题。若不设置则使用默认显示方式。title长度上限为1024B。
text	string	否	通知栏自定义正文。若不设置则使用默认显示方式。text长度上限为3072B。

GroupConfig¹⁵⁺

下载任务分组配置选项。

系统能力：SystemCapability.Request.FileTransferAgent

名称	类型	必填	说明
gauge	boolean	否	后台任务的进度通知策略。 - true，显示进度、成功、失败通知。 - false，仅显示成功、失败通知。默认为false。
notification¹⁵⁺	Notification	是	通知栏自定义设置。默认值为`{}`

Task¹⁰⁺

上传或下载任务。使用该方法前需要先获取Task对象，promise形式通过request.agent.create¹⁰⁺获取，callback形式通过request.agent.create¹⁰⁺获取。

属性

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

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

系统能力：SystemCapability.Request.FileTransferAgent

名称	类型	必填	说明
tid	string	是	任务id，由系统自动生成且唯一。
config	Config	是	任务的配置信息。

说明：

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

on('progress')¹⁰⁺

on(event: 'progress', callback: (progress: Progress) => void): void

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

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

系统能力：SystemCapability.Request.FileTransferAgent

参数：

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

回调函数的参数：

参数名	类型	必填	说明
progress	Progress	是	表示任务的进度信息。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

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

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let attachments: Array<request.agent.FormItem> = [{
  name: "taskOnTest",
  value: {
    filename: "taskOnTest.avi",
    path: "./taskOnTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'taskOnTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOnCallback = (progress: request.agent.Progress) => {
  console.info('upload task progress.');
};
request.agent.create(context, config).then((task: request.agent.Task) => {
  task.on('progress', createOnCallback);
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
  task.start();
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

说明：

示例中context的获取方式请参见获取UIAbility的上下文信息。

on('completed')¹⁰⁺

on(event: 'completed', callback: (progress: Progress) => void): void

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

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

系统能力：SystemCapability.Request.FileTransferAgent

参数：

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

回调函数的参数：

参数名	类型	必填	说明
progress	Progress	是	表示任务的进度信息。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

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

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let attachments: Array<request.agent.FormItem> = [{
  name: "taskOnTest",
  value: {
    filename: "taskOnTest.avi",
    path: "./taskOnTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'taskOnTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOnCallback = (progress: request.agent.Progress) => {
  console.info('upload task completed.');
};
request.agent.create(context, config).then((task: request.agent.Task) => {
  task.on('completed', createOnCallback);
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
  task.start();
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

说明：

示例中context的获取方式请参见获取UIAbility的上下文信息。

on('failed')¹⁰⁺

on(event: 'failed', callback: (progress: Progress) => void): void

订阅任务失败事件，使用callback异步回调。可通过调用request.agent.show¹⁰⁺查看错误原因。

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

系统能力：SystemCapability.Request.FileTransferAgent

参数：

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

回调函数的参数：

参数名	类型	必填	说明
progress	Progress	是	表示任务的进度信息。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

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

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let attachments: Array<request.agent.FormItem> = [{
  name: "taskOnTest",
  value: {
    filename: "taskOnTest.avi",
    path: "./taskOnTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'taskOnTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOnCallback = (progress: request.agent.Progress) => {
  console.info('upload task failed.');
};
request.agent.create(context, config).then((task: request.agent.Task) => {
  task.on('failed', createOnCallback);
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
  task.start();
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

说明：

示例中context的获取方式请参见获取UIAbility的上下文信息。

on('pause')¹¹⁺

on(event: 'pause', callback: (progress: Progress) => void): void

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

系统能力：SystemCapability.Request.FileTransferAgent

参数：

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

回调函数的参数：

参数名	类型	必填	说明
progress	Progress	是	表示任务的进度信息。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let attachments: Array<request.agent.FormItem> = [{
  name: "taskOnTest",
  value: {
    filename: "taskOnTest.avi",
    path: "./taskOnTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'taskOnTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOnCallback = (progress: request.agent.Progress) => {
  console.info('upload task pause.');
};
request.agent.create(context, config).then((task: request.agent.Task) => {
  task.on('pause', createOnCallback);
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
  task.start();
  for(let t = Date.now(); Date.now() - t <= 1000;); // 等待1秒再执行下一步操作，以防异步乱序
  task.pause();
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

说明：

示例中context的获取方式请参见获取UIAbility的上下文信息。

on('resume')¹¹⁺

on(event: 'resume', callback: (progress: Progress) => void): void

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

系统能力：SystemCapability.Request.FileTransferAgent

参数：

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

回调函数的参数：

参数名	类型	必填	说明
progress	Progress	是	表示任务的进度信息。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let attachments: Array<request.agent.FormItem> = [{
  name: "taskOnTest",
  value: {
    filename: "taskOnTest.avi",
    path: "./taskOnTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'taskOnTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOnCallback = (progress: request.agent.Progress) => {
  console.info('upload task resume.');
};
request.agent.create(context, config).then((task: request.agent.Task) => {
  task.on('resume', createOnCallback);
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
  task.start();
  for(let t = Date.now(); Date.now() - t <= 1000;); // 等待1秒再执行下一步操作，以防异步乱序
  task.pause();
  for(let t = Date.now(); Date.now() - t <= 1000;); // 等待1秒再执行下一步操作，以防异步乱序
  task.resume();
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

说明：

示例中context的获取方式请参见获取UIAbility的上下文信息。

on('remove')¹¹⁺

on(event: 'remove', callback: (progress: Progress) => void): void

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

系统能力：SystemCapability.Request.FileTransferAgent

参数：

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

回调函数的参数：

参数名	类型	必填	说明
progress	Progress	是	表示任务的进度信息。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let attachments: Array<request.agent.FormItem> = [{
  name: "taskOnTest",
  value: {
    filename: "taskOnTest.avi",
    path: "./taskOnTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'taskOnTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOnCallback = (progress: request.agent.Progress) => {
  console.info('upload task remove.');
};
request.agent.create(context, config).then((task: request.agent.Task) => {
  task.on('remove', createOnCallback);
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
  task.start();
  for(let t = Date.now(); Date.now() - t <= 1000;); // 等待1秒再执行下一步操作，以防异步乱序
  request.agent.remove(task.tid);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

说明：

示例中context的获取方式请参见获取UIAbility的上下文信息。

on('response')¹²⁺

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

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

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

系统能力：SystemCapability.Request.FileTransferAgent

参数：

参数名	类型	必填	说明
event	string	是	订阅的事件类型。 - 取值为'response'，表示任务响应，请求接收到响应时触发该事件。
callback	Callback<HttpResponse>	是	回调函数，发生相关的事件时触发该回调方法，返回任务响应头的数据结构。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let attachments: Array<request.agent.FormItem> = [{
  name: "taskOnTest",
  value: {
    filename: "taskOnTest.avi",
    path: "./taskOnTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'taskOnTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOnCallback = (response: request.agent.HttpResponse) => {
  console.info('upload task response.');
};
request.agent.create(context, config).then((task: request.agent.Task) => {
  task.on('response', createOnCallback);
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
  task.start();
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

说明：

示例中context的获取方式请参见获取UIAbility的上下文信息。

off('progress')¹⁰⁺

off(event: 'progress', callback?: (progress: Progress) => void): void

取消订阅任务进度事件。

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

系统能力：SystemCapability.Request.FileTransferAgent

参数：

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

回调函数的参数：

参数名	类型	必填	说明
progress	Progress	是	表示任务的进度信息。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

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

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let attachments: Array<request.agent.FormItem> = [{
  name: "taskOffTest",
  value: {
    filename: "taskOffTest.avi",
    path: "./taskOffTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'taskOffTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOffCallback1 = (progress: request.agent.Progress) => {
  console.info('upload task progress.');
};
let createOffCallback2 = (progress: request.agent.Progress) => {
  console.info('upload task progress.');
};
request.agent.create(context, config).then((task: request.agent.Task) => {
  task.on('progress', createOffCallback1);
  task.on('progress', createOffCallback2);
  //表示取消createOffCallback1的订阅
  task.off('progress', createOffCallback1);
  //表示取消订阅任务进度的所有回调
  task.off('progress');
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
  task.start();
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

说明：

示例中context的获取方式请参见获取UIAbility的上下文信息。

off('completed')¹⁰⁺

off(event: 'completed', callback?: (progress: Progress) => void): void

取消订阅任务完成事件。

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

系统能力：SystemCapability.Request.FileTransferAgent

参数：

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

回调函数的参数：

参数名	类型	必填	说明
progress	Progress	是	表示任务的进度信息。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

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

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let attachments: Array<request.agent.FormItem> = [{
  name: "taskOffTest",
  value: {
    filename: "taskOffTest.avi",
    path: "./taskOffTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'taskOffTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOffCallback1 = (progress: request.agent.Progress) => {
  console.info('upload task completed.');
};
let createOffCallback2 = (progress: request.agent.Progress) => {
  console.info('upload task completed.');
};
request.agent.create(context, config).then((task: request.agent.Task) => {
  task.on('completed', createOffCallback1);
  task.on('completed', createOffCallback2);
  //表示取消createOffCallback1的订阅
  task.off('completed', createOffCallback1);
  //表示取消订阅任务完成的所有回调
  task.off('completed');
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
  task.start();
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

说明：

示例中context的获取方式请参见获取UIAbility的上下文信息。

off('failed')¹⁰⁺

off(event: 'failed', callback?: (progress: Progress) => void): void

取消订阅任务失败事件。

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

系统能力：SystemCapability.Request.FileTransferAgent

参数：

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

回调函数的参数：

参数名	类型	必填	说明
progress	Progress	是	表示任务的进度信息

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

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

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let attachments: Array<request.agent.FormItem> = [{
  name: "taskOffTest",
  value: {
    filename: "taskOffTest.avi",
    path: "./taskOffTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'taskOffTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOffCallback1 = (progress: request.agent.Progress) => {
  console.info('upload task failed.');
};
let createOffCallback2 = (progress: request.agent.Progress) => {
  console.info('upload task failed.');
};
request.agent.create(context, config).then((task: request.agent.Task) => {
  task.on('failed', createOffCallback1);
  task.on('failed', createOffCallback2);
  //表示取消createOffCallback1的订阅
  task.off('failed', createOffCallback1);
  //表示取消订阅任务失败的所有回调
  task.off('failed');
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
  task.start();
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

说明：

示例中context的获取方式请参见获取UIAbility的上下文信息。

off('pause')¹¹⁺

off(event: 'pause', callback?: (progress: Progress) => void): void

取消订阅任务暂停事件。

系统能力：SystemCapability.Request.FileTransferAgent

参数：

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

回调函数的参数：

参数名	类型	必填	说明
progress	Progress	是	表示任务的进度信息。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let attachments: Array<request.agent.FormItem> = [{
  name: "taskOffTest",
  value: {
    filename: "taskOffTest.avi",
    path: "./taskOffTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'taskOffTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOffCallback1 = (progress: request.agent.Progress) => {
  console.info('upload task pause.');
};
let createOffCallback2 = (progress: request.agent.Progress) => {
  console.info('upload task pause.');
};
request.agent.create(context, config).then((task: request.agent.Task) => {
  task.on('pause', createOffCallback1);
  task.on('pause', createOffCallback2);
  //表示取消createOffCallback1的订阅
  task.off('pause', createOffCallback1);
  //表示取消订阅任务暂停的所有回调
  task.off('pause');
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
  task.start();
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

说明：

示例中context的获取方式请参见获取UIAbility的上下文信息。

off('resume')¹¹⁺

off(event: 'resume', callback?: (progress: Progress) => void): void

取消订阅任务恢复事件。

系统能力：SystemCapability.Request.FileTransferAgent

参数：

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

回调函数的参数：

参数名	类型	必填	说明
progress	Progress	是	表示任务的进度信息。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let attachments: Array<request.agent.FormItem> = [{
  name: "taskOffTest",
  value: {
    filename: "taskOffTest.avi",
    path: "./taskOffTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'taskOffTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOffCallback1 = (progress: request.agent.Progress) => {
  console.info('upload task resume.');
};
let createOffCallback2 = (progress: request.agent.Progress) => {
  console.info('upload task resume.');
};
request.agent.create(context, config).then((task: request.agent.Task) => {
  task.on('resume', createOffCallback1);
  task.on('resume', createOffCallback2);
  //表示取消createOffCallback1的订阅
  task.off('resume', createOffCallback1);
  //表示取消订阅任务恢复的所有回调
  task.off('resume');
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
  task.start();
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

说明：

示例中context的获取方式请参见获取UIAbility的上下文信息。

off('remove')¹¹⁺

off(event: 'remove', callback?: (progress: Progress) => void): void

取消订阅任务移除事件。

系统能力：SystemCapability.Request.FileTransferAgent

参数：

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

回调函数的参数：

参数名	类型	必填	说明
progress	Progress	是	表示任务的进度信息。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let attachments: Array<request.agent.FormItem> = [{
  name: "taskOffTest",
  value: {
    filename: "taskOffTest.avi",
    path: "./taskOffTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'taskOffTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOffCallback1 = (progress: request.agent.Progress) => {
  console.info('upload task remove.');
};
let createOffCallback2 = (progress: request.agent.Progress) => {
  console.info('upload task remove.');
};
request.agent.create(context, config).then((task: request.agent.Task) => {
  task.on('remove', createOffCallback1);
  task.on('remove', createOffCallback2);
  //表示取消createOffCallback1的订阅
  task.off('remove', createOffCallback1);
  //表示取消订阅任务移除的所有回调
  task.off('remove');
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
  task.start();
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

说明：

示例中context的获取方式请参见获取UIAbility的上下文信息。

off('response')¹²⁺

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

取消订阅任务响应事件。

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

系统能力：SystemCapability.Request.FileTransferAgent

参数：

参数名	类型	必填	说明
event	string	是	取消订阅的事件类型。 - 取值为'response'，表示任务响应。
callback	Callback<HttpResponse>	否	需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let attachments: Array<request.agent.FormItem> = [{
  name: "taskOffTest",
  value: {
    filename: "taskOffTest.avi",
    path: "./taskOffTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'taskOffTest',
  description: 'Sample code for event listening',
  mode: request.agent.Mode.FOREGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
let createOffCallback1 = (progress: request.agent.HttpResponse) => {
  console.info('upload task response.');
};
let createOffCallback2 = (progress: request.agent.HttpResponse) => {
  console.info('upload task response.');
};
request.agent.create(context, config).then((task: request.agent.Task) => {
  task.on('response', createOffCallback1);
  task.on('response', createOffCallback2);
  //表示取消createOffCallback1的订阅
  task.off('response', createOffCallback1);
  //表示取消订阅任务移除的所有回调
  task.off('response');
  console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
  task.start();
}).catch((err: BusinessError) => {
  console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});

说明：

示例中context的获取方式请参见获取UIAbility的上下文信息。

start¹⁰⁺

start(callback: AsyncCallback<void>): void

启动一个任务，使用callback异步回调。
以下状态的任务可以被启动：

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

需要权限：ohos.permission.INTERNET

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

系统能力：SystemCapability.Request.FileTransferAgent

参数：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
201	Permission denied.
13400003	task service ability error.
21900007	task state error.

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let config: request.agent.Config = {
  action: request.agent.Action.DOWNLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'taskStartTest',
  description: 'Sample code for start the download task',
  mode: request.agent.Mode.BACKGROUND,
  overwrite: false,
  method: "GET",
  data: "",
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
request.agent.create(context, config).then((task: request.agent.Task) => {
  task.start((err: BusinessError) => {
    if (err) {
      console.error(`Failed to start the download task, Code: ${err.code}, message: ${err.message}`);
      return;
    }
    console.info(`Succeeded in starting a download task.`);
  });
  console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});

说明：

示例中context的获取方式请参见获取UIAbility的上下文信息。

start¹⁰⁺

start(): Promise<void>

启动一个任务，使用Promise异步回调。
以下状态的任务可以被启动：

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

需要权限：ohos.permission.INTERNET

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

系统能力：SystemCapability.Request.FileTransferAgent

返回值：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
201	Permission denied.
13400003	task service ability error.
21900007	task state error.

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let config: request.agent.Config = {
  action: request.agent.Action.DOWNLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'taskStartTest',
  description: 'Sample code for start the download task',
  mode: request.agent.Mode.BACKGROUND,
  overwrite: false,
  method: "GET",
  data: "",
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
request.agent.create(context, config).then((task: request.agent.Task) => {
  task.start().then(() => {
    console.info(`Succeeded in starting a download task.`);
  }).catch((err: BusinessError) => {
    console.error(`Failed to start the download task, Code: ${err.code}, message: ${err.message}`);
  });
  console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});

说明：

示例中context的获取方式请参见获取UIAbility的上下文信息。

pause¹⁰⁺

pause(callback: AsyncCallback<void>): void

暂停任务，可以暂停正在等待/正在运行/正在重试的任务，已暂停的任务可被resume恢复。使用callback异步回调。

系统能力：SystemCapability.Request.FileTransferAgent

参数：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码。

错误码ID	错误信息
13400003	task service ability error.
21900007	task state error.

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let config: request.agent.Config = {
  action: request.agent.Action.DOWNLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'taskPauseTest',
  description: 'Sample code for pause the download task',
  mode: request.agent.Mode.BACKGROUND,
  overwrite: false,
  method: "GET",
  data: "",
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
request.agent.create(context, config).then((task: request.agent.Task) => {
  task.start();
  for(let t = Date.now(); Date.now() - t <= 1000;); // 等待1秒再执行下一步操作，以防异步乱序
  task.pause((err: BusinessError) => {
    if (err) {
      console.error(`Failed to pause the download task, Code: ${err.code}, message: ${err.message}`);
      return;
    }
    console.info(`Succeeded in pausing a download task. `);
  });
  console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});

pause¹⁰⁺

pause(): Promise<void>

暂停任务，可以暂停正在等待/正在运行/正在重试的任务，已暂停的任务可被resume恢复。使用Promise异步回调。

系统能力：SystemCapability.Request.FileTransferAgent

返回值：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码。

错误码ID	错误信息
13400003	task service ability error.
21900007	task state error.

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let config: request.agent.Config = {
  action: request.agent.Action.DOWNLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'taskPauseTest',
  description: 'Sample code for pause the download task',
  mode: request.agent.Mode.BACKGROUND,
  overwrite: false,
  method: "GET",
  data: "",
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
request.agent.create(context, config).then((task: request.agent.Task) => {
  task.start();
  for(let t = Date.now(); Date.now() - t <= 1000;); // 等待1秒再执行下一步操作，以防异步乱序
  task.pause().then(() => {
    console.info(`Succeeded in pausing a download task. `);
  }).catch((err: BusinessError) => {
    console.error(`Failed to pause the download task, Code: ${err.code}, message: ${err.message}`);
  });
  console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});

resume¹⁰⁺

resume(callback: AsyncCallback<void>): void

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

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.Request.FileTransferAgent

参数：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
201	Permission denied.
13400003	task service ability error.
21900007	task state error.

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let config: request.agent.Config = {
  action: request.agent.Action.DOWNLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'taskResumeTest',
  description: 'Sample code for resume the download task',
  mode: request.agent.Mode.BACKGROUND,
  overwrite: false,
  method: "GET",
  data: "",
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
request.agent.create(context, config).then((task: request.agent.Task) => {
  task.start();
  for(let t = Date.now(); Date.now() - t <= 1000;); // 等待1秒再执行下一步操作，以防异步乱序
  task.pause();
  for(let t = Date.now(); Date.now() - t <= 1000;); // 等待1秒再执行下一步操作，以防异步乱序
  task.resume((err: BusinessError) => {
    if (err) {
      console.error(`Failed to resume the download task, Code: ${err.code}, message: ${err.message}`);
      return;
    }
    console.info(`Succeeded in resuming a download task. `);
  });
  console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});

resume¹⁰⁺

resume(): Promise<void>

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

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.Request.FileTransferAgent

返回值：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
201	Permission denied.
13400003	task service ability error.
21900007	task state error.

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let config: request.agent.Config = {
  action: request.agent.Action.DOWNLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'taskResumeTest',
  description: 'Sample code for resume the download task',
  mode: request.agent.Mode.BACKGROUND,
  overwrite: false,
  method: "GET",
  data: "",
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
request.agent.create(context, config).then((task: request.agent.Task) => {
  task.start();
  for(let t = Date.now(); Date.now() - t <= 1000;); // 等待1秒再执行下一步操作，以防异步乱序
  task.pause();
  for(let t = Date.now(); Date.now() - t <= 1000;); // 等待1秒再执行下一步操作，以防异步乱序
  task.resume().then(() => {
    console.info(`Succeeded in resuming a download task. `);
  }).catch((err: BusinessError) => {
    console.error(`Failed to resume the download task, Code: ${err.code}, message: ${err.message}`);
  });
  console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});

stop¹⁰⁺

stop(callback: AsyncCallback<void>): void

停止任务，可以停止正在运行/正在等待/正在重试的任务，已停止的任务可被start恢复。使用callback异步回调。

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

系统能力：SystemCapability.Request.FileTransferAgent

参数：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码。

错误码ID	错误信息
13400003	task service ability error.
21900007	task state error.

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let config: request.agent.Config = {
  action: request.agent.Action.DOWNLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'taskStopTest',
  description: 'Sample code for stop the download task',
  mode: request.agent.Mode.BACKGROUND,
  overwrite: false,
  method: "GET",
  data: "",
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
request.agent.create(context, config).then((task: request.agent.Task) => {
  task.start();
  for(let t = Date.now(); Date.now() - t <= 1000;); // 等待1秒再执行下一步操作，以防异步乱序
  task.stop((err: BusinessError) => {
    if (err) {
      console.error(`Failed to stop the download task, Code: ${err.code}, message: ${err.message}`);
      return;
    }
    console.info(`Succeeded in stopping a download task. `);
  });
  console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});

stop¹⁰⁺

stop(): Promise<void>

停止任务，可以停止正在运行/正在等待/正在重试的任务，已停止的任务可被start恢复。使用Promise异步回调。

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

系统能力：SystemCapability.Request.FileTransferAgent

返回值：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码。

错误码ID	错误信息
13400003	task service ability error.
21900007	task state error.

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let config: request.agent.Config = {
  action: request.agent.Action.DOWNLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'taskStopTest',
  description: 'Sample code for stop the download task',
  mode: request.agent.Mode.BACKGROUND,
  overwrite: false,
  method: "GET",
  data: "",
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
request.agent.create(context, config).then((task: request.agent.Task) => {
  task.start();
  for(let t = Date.now(); Date.now() - t <= 1000;); // 等待1秒再执行下一步操作，以防异步乱序
  task.stop().then(() => {
    console.info(`Succeeded in stopping a download task. `);
  }).catch((err: BusinessError) => {
    console.error(`Failed to stop the download task, Code: ${err.code}, message: ${err.message}`);
  });
  console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});

setMaxSpeed¹⁸⁺

setMaxSpeed(speed: number): Promise<void>

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

系统能力：SystemCapability.Request.FileTransferAgent

参数：

参数名	类型	必填	说明
speed	number	是	设置任务每秒能传输的字节数上限，单位为字节（B），最小值为16384字节。

返回值：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

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

示例：

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

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

request.agent.create¹⁰⁺

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

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

需要权限：ohos.permission.INTERNET

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

系统能力：SystemCapability.Request.FileTransferAgent

参数：

参数名	类型	必填	说明
config	Config	是	上传/下载任务的配置信息。
context	BaseContext	是	基于应用程序的上下文。
callback	AsyncCallback<Task>	是	回调函数。当创建上传或下载任务成功，err为undefined，data为获取到的Task对象；否则为错误对象。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
201	permission denied.
401	parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed.
13400001	file operation error.
13400003	task service ability error.
21900004	the application task queue is full.
21900005	task mode error.

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let attachments: Array<request.agent.FormItem> = [{
  name: "createTest",
  value: {
    filename: "createTest.avi",
    path: "./createTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'createTest',
  description: 'Sample code for create task',
  mode: request.agent.Mode.BACKGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
request.agent.create(context, config, async (err: BusinessError, task: request.agent.Task) => {
  if (err) {
    console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info(`Succeeded in creating a download task. result: ${task.config}`);
  await task.start();
  //用户需要手动调用remove从而结束task对象的生命周期
  request.agent.remove(task.tid);
});

说明：

示例中context的获取方式请参见获取UIAbility的上下文信息。

request.agent.create¹⁰⁺

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

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

需要权限：ohos.permission.INTERNET

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

系统能力：SystemCapability.Request.FileTransferAgent

参数：

参数名	类型	必填	说明
context	BaseContext	是	基于应用程序的上下文。
config	Config	是	上传/下载任务的配置信息。

返回值：

类型	说明
Promise<Task>	Promise对象。返回任务配置信息的Promise对象。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
201	permission denied.
401	parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed.
13400001	file operation error.
13400003	task service ability error.
21900004	the application task queue is full.
21900005	task mode error.

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let attachments: Array<request.agent.FormItem> = [{
  name: "createTest",
  value: {
    filename: "createTest.avi",
    path: "./createTest.avi",
  }
}];
let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'http://127.0.0.1', // 需要手动将url替换为真实服务器的HTTP协议地址
  title: 'createTest',
  description: 'Sample code for create task',
  mode: request.agent.Mode.BACKGROUND,
  overwrite: false,
  method: "PUT",
  data: attachments,
  saveas: "./",
  network: request.agent.Network.CELLULAR,
  metered: false,
  roaming: true,
  retry: true,
  redirect: true,
  index: 0,
  begins: 0,
  ends: -1,
  gauge: false,
  precise: false,
  token: "it is a secret"
};
request.agent.create(context, config).then(async (task: request.agent.Task) => {
  console.info(`Succeeded in creating a download task. result: ${task.config}`);
  await task.start();
  //用户需要手动调用remove从而结束task对象的生命周期
  request.agent.remove(task.tid);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});

说明：

示例中context的获取方式请参见获取UIAbility的上下文信息。

request.agent.getTask¹¹⁺

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

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

系统能力：SystemCapability.Request.FileTransferAgent

参数：

参数名	类型	必填	说明
context	BaseContext	是	基于应用程序的上下文。
id	string	是	任务id。
token	string	否	任务查询token。

返回值：

类型	说明
Promise<Task>	Promise对象。返回任务配置信息的Promise对象。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码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 not found.

示例：

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

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

request.agent.remove¹⁰⁺

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

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

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

系统能力：SystemCapability.Request.FileTransferAgent

参数：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
401	parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type.
13400003	task service ability error.
21900006	task not found.

示例：

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

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

request.agent.remove¹⁰⁺

remove(id: string): Promise<void>

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

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

系统能力：SystemCapability.Request.FileTransferAgent

参数：

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

返回值：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
401	parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type.
13400003	task service ability error.
21900006	task not found.

示例：

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

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

request.agent.show¹⁰⁺

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

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

系统能力：SystemCapability.Request.FileTransferAgent

参数：

参数名	类型	必填	说明
id	string	是	任务id。
callback	AsyncCallback<TaskInfo>	是	回调函数。当查询任务操作成功，err为undefined，data为查询到的任务TaskInfo信息；否则为错误对象。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
401	parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type.
13400003	task service ability error.
21900006	task not found.

示例：

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

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

request.agent.show¹⁰⁺

show(id: string): Promise<TaskInfo>

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

系统能力：SystemCapability.Request.FileTransferAgent

参数：

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

返回值：

类型	说明
Promise<TaskInfo>	Promise对象。返回任务详细信息TaskInfo的Promise对象。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
401	parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type.
13400003	task service ability error.
21900006	task not found.

示例：

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

request.agent.show("123456").then((taskInfo: request.agent.TaskInfo) => {
  console.info(`Succeeded in showing a upload task.`);
}).catch((err: BusinessError) => {
  console.error(`Failed to show a upload task, Code: ${err.code}, message: ${err.message}`);
});

request.agent.touch¹⁰⁺

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

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

系统能力：SystemCapability.Request.FileTransferAgent

参数：

参数名	类型	必填	说明
id	string	是	任务id。
token	string	是	任务查询token。
callback	AsyncCallback<TaskInfo>	是	回调函数。当查询任务操作成功，err为undefined，data为查询到的任务TaskInfo信息；否则为错误对象。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码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 not found.

示例：

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

request.agent.touch("123456", "token", (err: BusinessError, taskInfo: request.agent.TaskInfo) => {
  if (err) {
    console.error(`Failed to touch a upload task, Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info(`Succeeded in touching a upload task.`);
});

request.agent.touch¹⁰⁺

touch(id: string, token: string): Promise<TaskInfo>

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

系统能力：SystemCapability.Request.FileTransferAgent

参数：

参数名	类型	必填	说明
id	string	是	任务id。
token	string	是	任务查询token。

返回值：

类型	说明
Promise<TaskInfo>	Promise对象。返回任务详细信息TaskInfo的Promise对象。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码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 not found.

示例：

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

request.agent.touch("123456", "token").then((taskInfo: request.agent.TaskInfo) => {
  console.info(`Succeeded in touching a upload task. `);
}).catch((err: BusinessError) => {
  console.error(`Failed to touch a upload task, Code: ${err.code}, message: ${err.message}`);
});

request.agent.search¹⁰⁺

search(callback: AsyncCallback<Array<string>>): void

根据默认Filter过滤条件查找任务id，即查询调用时刻至24小时前的所有任务的任务id。使用callback异步回调。

系统能力：SystemCapability.Request.FileTransferAgent

参数：

参数名	类型	必填	说明
callback	AsyncCallback<Array<string>>	是	回调函数。当根据过滤条件查找任务成功，err为undefined，data为满足条件的任务id；否则为错误对象。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
401	parameter error. Possible causes: 1. Incorrect parameter type. 2. Parameter verification failed.
13400003	task service ability error.

示例：

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

request.agent.search((err: BusinessError, data: Array<string>) => {
  if (err) {
    console.error(`Failed to search a upload task, Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info(`Succeeded in searching a upload task. `);
});

request.agent.search¹⁰⁺

search(filter: Filter, callback: AsyncCallback<Array<string>>): void

根据Filter过滤条件查找任务id。使用callback异步回调。

系统能力：SystemCapability.Request.FileTransferAgent

参数：

参数名	类型	必填	说明
filter	Filter	是	过滤条件。
callback	AsyncCallback<Array<string>>	是	回调函数。当根据过滤条件查找任务成功，err为undefined，data为满足条件的任务id；否则为错误对象。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
401	parameter error. Possible causes: 1. Incorrect parameter type. 2. Parameter verification failed.
13400003	task service ability error.

示例：

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

let filter: request.agent.Filter = {
  action: request.agent.Action.UPLOAD,
  mode: request.agent.Mode.BACKGROUND
}
request.agent.search(filter, (err: BusinessError, data: Array<string>) => {
  if (err) {
    console.error(`Failed to search a upload task, Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info(`Succeeded in searching a upload task. `);
});

request.agent.search¹⁰⁺

search(filter?: Filter): Promise<Array<string>>

根据Filter过滤条件查找任务id。使用Promise异步回调。

系统能力：SystemCapability.Request.FileTransferAgent

参数：

参数名	类型	必填	说明
filter	Filter	否	过滤条件。

返回值：

类型	说明
Promise<Array<string>>	Promise对象。返回满足条件任务id的Promise对象。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
401	parameter error. Possible causes: 1. Incorrect parameter type. 2. Parameter verification failed.
13400003	task service ability error.

示例：

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

let filter: request.agent.Filter = {
  action: request.agent.Action.UPLOAD,
  mode: request.agent.Mode.BACKGROUND
}
request.agent.search(filter).then((data: Array<string>) => {
  console.info(`Succeeded in searching a upload task. `);
}).catch((err: BusinessError) => {
  console.error(`Failed to search a upload task, Code: ${err.code}, message: ${err.message}`);
});

request.agent.createGroup¹⁵⁺

createGroup(config: GroupConfig): Promise<string>

根据GroupConfig¹⁵⁺分组条件创建分组，并返回分组id。使用Promise异步回调。

系统能力：SystemCapability.Request.FileTransferAgent

参数：

参数名	类型	必填	说明
config	GroupConfig¹⁵⁺	是	下载任务分组选项。

返回值：

类型	说明
Promise<string>	Promise对象。返回创建完成的分组id。

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

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

示例：

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

// 准备分组配置选项 GroupConfig 对象。
let config: request.agent.GroupConfig = {
    notification: {},
};
// 调用 createGroup 接口创建分组。
request.agent.createGroup(config).then((gid: string) => {
  console.info(`Succeeded in creating a download task group. `);
}).catch((err: BusinessError) => {
  console.error(`Failed to create a download group, Code: ${err.code}, message: ${err.message}`);
});

request.agent.attachGroup¹⁵⁺

attachGroup(gid: string, tids: string[]): Promise<void>

向指定分组id中绑定多个下载任务id。使用Promise异步回调。

如果任意一个任务id不满足添加条件，则所有列表中的任务都不会添加到分组中。

系统能力：SystemCapability.Request.FileTransferAgent

参数：

参数名	类型	必填	说明
gid	string	是	目标分组id。
tids	string[]	是	待绑定的任务id列表。

返回值：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码ID	错误信息
401	parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed.
13400003	task service ability error
21900005	task mode error
21900006	task not found
21900007	task state error
21900008	group deleted or not found

示例：

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

// 准备分组id和任务id列表。
let groupId: string = "123456789";
let taskIds: string[] = ["1111", "2222", "3333", "4444"];
// 调用 attachGroup 接口向分组中添加任务id列表。
request.agent.attachGroup(groupId, taskIds).then(() => {
  console.info(`Succeeded in attaching tasks to the download task group.`);
}).catch((err: BusinessError) => {
  console.error(`Failed to attach tasks to the download group, Code: ${err.code}, message: ${err.message}`);
});

request.agent.deleteGroup¹⁵⁺

deleteGroup(gid: string): Promise<void>

移除指定分组，后续不能再往该分组中添加任务id。使用Promise异步回调。

当分组中的所有任务处于完成、失败或移除状态，并且分组被移除时，显示该分组的完成或失败通知。

系统能力：SystemCapability.Request.FileTransferAgent

参数：

参数名	类型	必填	说明
gid	string	是	目标分组id。

返回值：

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

错误码：

以下错误码的详细介绍请参见上传下载错误码与通用错误码说明文档。

错误码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

示例：

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

// 准备分组id。
let groupId: string = "123456789";

// 调用 deleteGroup 接口移除分组。
request.agent.deleteGroup(groupId).then(() => {
  console.info(`Succeeded in deleting the download task group.`);
}).catch((err: BusinessError) => {
  console.error(`Failed to delete the download group, Code: ${err.code}, message: ${err.message}`);
});

OpenHarmony/docs .gitee-modal { width: 500px !important; }

@ohos.request (上传下载)

导入模块

常量

request.uploadFile9+

request.uploadFile9+

request.upload(deprecated)

request.upload(deprecated)

UploadTask

on('progress')

on('headerReceive')7+

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

off('progress')

off('headerReceive')7+

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

delete9+

delete9+

remove(deprecated)

remove(deprecated)

UploadConfig6+

TaskState9+

File

RequestData

request.downloadFile9+

request.downloadFile9+

request.download(deprecated)

request.download(deprecated)

DownloadTask

on('progress')

off('progress')

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

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

on('fail')7+

off('fail')7+

delete9+

delete9+

getTaskInfo9+

getTaskInfo9+

getTaskMimeType9+

getTaskMimeType9+

suspend9+

suspend9+

restore9+

restore9+

remove(deprecated)

remove(deprecated)

query(deprecated)

query(deprecated)

queryMimeType(deprecated)

queryMimeType(deprecated)

pause(deprecated)

pause(deprecated)

resume(deprecated)

resume(deprecated)

DownloadConfig

DownloadInfo7+

Action10+

Mode10+

Network10+

BroadcastEvent11+

FileSpec10+

FormItem10+

Config10+

State10+

Progress10+

Faults10+

Filter10+

TaskInfo10+

HttpResponse12+

Notification15+

GroupConfig15+

Task10+

属性

on('progress')10+

on('completed')10+

on('failed')10+

on('pause')11+

on('resume')11+

on('remove')11+

on('response')12+

OpenHarmony/docs

request.uploadFile⁹⁺

request.uploadFile⁹⁺

request.upload^(deprecated)

request.upload^(deprecated)

on('headerReceive')⁷⁺

on('complete' | 'fail')⁹⁺

off('headerReceive')⁷⁺

off('complete' | 'fail')⁹⁺

delete⁹⁺

delete⁹⁺

remove^(deprecated)

remove^(deprecated)

UploadConfig⁶⁺

TaskState⁹⁺

request.downloadFile⁹⁺

request.downloadFile⁹⁺

request.download^(deprecated)

request.download^(deprecated)

on('complete'|'pause'|'remove')⁷⁺

off('complete'|'pause'|'remove')⁷⁺

on('fail')⁷⁺

off('fail')⁷⁺

delete⁹⁺

delete⁹⁺

getTaskInfo⁹⁺

getTaskInfo⁹⁺

getTaskMimeType⁹⁺

getTaskMimeType⁹⁺

suspend⁹⁺

suspend⁹⁺

restore⁹⁺

restore⁹⁺

remove^(deprecated)

remove^(deprecated)

query^(deprecated)

query^(deprecated)

queryMimeType^(deprecated)

queryMimeType^(deprecated)

pause^(deprecated)

pause^(deprecated)

resume^(deprecated)

resume^(deprecated)

DownloadInfo⁷⁺

Action¹⁰⁺

Mode¹⁰⁺

Network¹⁰⁺

BroadcastEvent¹¹⁺

FileSpec¹⁰⁺

FormItem¹⁰⁺

Config¹⁰⁺

State¹⁰⁺

Progress¹⁰⁺

Faults¹⁰⁺

Filter¹⁰⁺

TaskInfo¹⁰⁺

HttpResponse¹²⁺

Notification¹⁵⁺

GroupConfig¹⁵⁺

Task¹⁰⁺

on('progress')¹⁰⁺

on('completed')¹⁰⁺

on('failed')¹⁰⁺

on('pause')¹¹⁺

on('resume')¹¹⁺

on('remove')¹¹⁺

on('response')¹²⁺

off('progress')¹⁰⁺

off('completed')¹⁰⁺

off('failed')¹⁰⁺

off('pause')¹¹⁺

off('resume')¹¹⁺

off('remove')¹¹⁺

off('response')¹²⁺

start¹⁰⁺

start¹⁰⁺

pause¹⁰⁺

pause¹⁰⁺

resume¹⁰⁺

resume¹⁰⁺