1# @ohos.request (上传下载) 2 3request部件主要给应用提供上传下载文件、后台传输代理的基础能力。 4 5> **说明：** 6> 7> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9 10## 导入模块 11 12 13```js 14import { request } from '@kit.BasicServicesKit'; 15``` 16 17## 常量 18 19**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。 20 21> **说明：** 22> 23> **网络类型**：下载支持自定义网络类型，可以在[DownloadConfig](#downloadconfig)中通过networkType配置成以下网络类型。<br/> 24> 25> **下载任务错误码**：下载[on('fail')<sup>7+</sup>](#onfail7)事件callback的错误参数、[getTaskInfo<sup>9+</sup>](#gettaskinfo9)返回值的failedReason字段取值。<br/> 26> 27> **下载任务暂停原因**：下载相关[getTaskInfo<sup>9+</sup>](#gettaskinfo9)返回值的pausedReason字段取值。<br/> 28> 29> **下载任务状态码**：下载相关[getTaskInfo<sup>9+</sup>](#gettaskinfo9)返回值的status字段取值。 30 31| 名称 | 参数类型 | 数值 | 说明 | 32| -------- | -------- | -------- | -------- | 33| EXCEPTION_PERMISSION<sup>9+</sup> | number | 201 | 通用错误码：权限校验失败。 | 34| EXCEPTION_PARAMCHECK<sup>9+</sup> | number | 401 | 通用错误码：参数检查失败。 | 35| EXCEPTION_UNSUPPORTED<sup>9+</sup> | number | 801 | 通用错误码：该设备不支持此API。 | 36| EXCEPTION_FILEIO<sup>9+</sup> | number | 13400001 | 特有错误码：文件操作异常。 | 37| EXCEPTION_FILEPATH<sup>9+</sup> | number | 13400002 | 特有错误码：文件路径异常。 | 38| EXCEPTION_SERVICE<sup>9+</sup> | number | 13400003 | 特有错误码：服务异常。 | 39| EXCEPTION_OTHERS<sup>9+</sup> | number | 13499999 | 特有错误码：其他错误。 | 40| NETWORK_MOBILE<sup>6+</sup> | number | 0x00000001 | 网络类型：使用蜂窝网络时允许下载的位标志。 | 41| NETWORK_WIFI<sup>6+</sup> | number | 0x00010000 | 网络类型：使用WLAN时允许下载的位标志。 | 42| ERROR_CANNOT_RESUME<sup>7+</sup> | number | 0 | 下载任务错误码：网络原因导致恢复下载失败。 | 43| ERROR_DEVICE_NOT_FOUND<sup>7+</sup> | number | 1 | 下载任务错误码：找不到SD卡等存储设备。 | 44| ERROR_FILE_ALREADY_EXISTS<sup>7+</sup> | number | 2 | 下载任务错误码：要下载的文件已存在，下载会话不能覆盖现有文件。 | 45| ERROR_FILE_ERROR<sup>7+</sup> | number | 3 | 下载任务错误码：文件操作失败。 | 46| ERROR_HTTP_DATA_ERROR<sup>7+</sup> | number | 4 | 下载任务错误码：HTTP传输失败。 | 47| ERROR_INSUFFICIENT_SPACE<sup>7+</sup> | number | 5 | 下载任务错误码：存储空间不足。 | 48| ERROR_TOO_MANY_REDIRECTS<sup>7+</sup> | number | 6 | 下载任务错误码：网络重定向过多导致的错误。 | 49| ERROR_UNHANDLED_HTTP_CODE<sup>7+</sup> | number | 7 | 下载任务错误码：无法识别的HTTP代码。 | 50| ERROR_UNKNOWN<sup>7+</sup> | number | 8 | 下载任务错误码：未知错误。（例如API version 12及以下版本，只支持串行的尝试连接域名相关ip，且不支持单个ip的连接时间控制，如果DNS返回的首个ip是阻塞的，可能握手超时造成ERROR_UNKNOWN错误。） | 51| ERROR_OFFLINE<sup>9+</sup> | number | 9 | 下载任务错误码：网络未连接。 | 52| ERROR_UNSUPPORTED_NETWORK_TYPE<sup>9+</sup> | number | 10 | 下载任务错误码：网络类型不匹配。 | 53| PAUSED_QUEUED_FOR_WIFI<sup>7+</sup> | number | 0 | 下载任务暂停原因：下载被暂停并等待WLAN连接，因为文件大小超过了使用蜂窝网络的会话允许的最大值。 | 54| PAUSED_WAITING_FOR_NETWORK<sup>7+</sup> | number | 1 | 下载任务暂停原因：由于网络问题（例如网络断开）而暂停下载。 | 55| PAUSED_WAITING_TO_RETRY<sup>7+</sup> | number | 2 | 下载任务暂停原因：发生网络错误，将重试下载会话。 | 56| PAUSED_BY_USER<sup>9+</sup> | number | 3 | 下载任务暂停原因：用户暂停会话。 | 57| PAUSED_UNKNOWN<sup>7+</sup> | number | 4 | 下载任务暂停原因：未知原因导致暂停下载。 | 58| SESSION_SUCCESSFUL<sup>7+</sup> | number | 0 | 下载任务状态码：下载会话已完成。 | 59| SESSION_RUNNING<sup>7+</sup> | number | 1 | 下载任务状态码：下载会话正在进行中。 | 60| SESSION_PENDING<sup>7+</sup> | number | 2 | 下载任务状态码：正在调度下载会话。 | 61| SESSION_PAUSED<sup>7+</sup> | number | 3 | 下载任务状态码：下载会话已暂停。 | 62| SESSION_FAILED<sup>7+</sup> | number | 4 | 下载任务状态码：下载会话已失败，将不会重试。 | 63 64 65## request.uploadFile<sup>9+</sup> 66 67uploadFile(context: BaseContext, config: UploadConfig): Promise<UploadTask> 68 69上传，异步方法，使用promise形式返回结果，支持HTTP协议。通过[on('complete'|'fail')<sup>9+</sup>](#oncomplete--fail9)可获取任务上传时的错误信息。 70 71**需要权限**：ohos.permission.INTERNET 72 73**系统能力**：SystemCapability.MiscServices.Upload 74 75**参数：** 76 77 | 参数名 | 类型 | 必填 | 说明 | 78 | -------- | -------- | -------- | -------- | 79 | context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 80 | config | [UploadConfig](#uploadconfig6) | 是 | 上传的配置信息。 | 81 82 83**返回值：** 84 85 | 类型 | 说明 | 86 | -------- | -------- | 87 | Promise<[UploadTask](#uploadtask)> | 使用Promise方式，异步返回上传任务UploadTask的Promise对象。 | 88 89**错误码：** 90 91以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 92 93 | 错误码ID | 错误信息 | 94 | -------- | -------- | 95 | 201 | the permissions check fails | 96 | 401 | the parameters check fails.Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 97 | 13400002 | bad file path. | 98 99**示例：** 100 101 ```ts 102 import { BusinessError } from '@kit.BasicServicesKit'; 103 104 let uploadTask: request.UploadTask; 105 let uploadConfig: request.UploadConfig = { 106 url: 'http://www.example.com', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 107 header: { 'Accept': '*/*' }, 108 method: "POST", 109 files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], 110 data: [{ name: "name123", value: "123" }], 111 }; 112 try { 113 request.uploadFile(getContext(), uploadConfig).then((data: request.UploadTask) => { 114 uploadTask = data; 115 }).catch((err: BusinessError) => { 116 console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`); 117 }); 118 } catch (err) { 119 console.error(`Failed to request the upload. err: ${JSON.stringify(err)}`); 120 } 121 ``` 122 123> **说明：** 124> 125> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 126 127 128## request.uploadFile<sup>9+</sup> 129 130uploadFile(context: BaseContext, config: UploadConfig, callback: AsyncCallback<UploadTask>): void 131 132上传，异步方法，使用callback形式返回结果，支持HTTP协议。通过[on('complete'|'fail')<sup>9+</sup>](#oncomplete--fail9)可获取任务上传时的错误信息。 133 134**需要权限**：ohos.permission.INTERNET 135 136**系统能力**：SystemCapability.MiscServices.Upload 137 138**参数：** 139 140 | 参数名 | 类型 | 必填 | 说明 | 141 | -------- | -------- | -------- | -------- | 142 | context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 143 | config | [UploadConfig](#uploadconfig6) | 是 | 上传的配置信息。 | 144 | callback | AsyncCallback<[UploadTask](#uploadtask)> | 是 | 回调函数，异步返回UploadTask对象。当上传成功，err为undefined，data为获取到的UploadTask对象；否则为错误对象。 | 145 146**错误码：** 147 148以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 149 150 | 错误码ID | 错误信息 | 151 | -------- | -------- | 152 | 201 | the permissions check fails | 153 | 401 | the parameters check fails.Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 154 | 13400002 | bad file path. | 155 156**示例：** 157 158 ```ts 159 import { BusinessError } from '@kit.BasicServicesKit'; 160 161 let uploadTask: request.UploadTask; 162 let uploadConfig: request.UploadConfig = { 163 url: 'http://www.example.com', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 164 header: { 'Accept': '*/*' }, 165 method: "POST", 166 files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], 167 data: [{ name: "name123", value: "123" }], 168 }; 169 try { 170 request.uploadFile(getContext(), uploadConfig, (err: BusinessError, data: request.UploadTask) => { 171 if (err) { 172 console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`); 173 return; 174 } 175 uploadTask = data; 176 }); 177 } catch (err) { 178 console.error(`Failed to request the upload. err: ${JSON.stringify(err)}`); 179 } 180 ``` 181 182> **说明：** 183> 184> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 185 186## request.upload<sup>(deprecated)</sup> 187 188upload(config: UploadConfig): Promise<UploadTask> 189 190上传，异步方法，使用promise形式返回结果。 191 192**模型约束**：此接口仅可在FA模型下使用 193 194> **说明：** 195> 196> 从API Version 9开始不再维护，建议使用[request.uploadFile<sup>9+</sup>](#requestuploadfile9)替代。 197 198**需要权限**：ohos.permission.INTERNET 199 200**系统能力**：SystemCapability.MiscServices.Upload 201 202**参数：** 203 204 | 参数名 | 类型 | 必填 | 说明 | 205 | -------- | -------- | -------- | -------- | 206 | config | [UploadConfig](#uploadconfig6) | 是 | 上传的配置信息。 | 207 208**返回值：** 209 210 | 类型 | 说明 | 211 | -------- | -------- | 212 | Promise<[UploadTask](#uploadtask)> | 使用Promise方式，异步返回上传任务UploadTask的Promise对象。 | 213 214**错误码：** 215 216以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 217 218 | 错误码ID | 错误信息 | 219 | -------- | -------- | 220 | 201 | the permissions check fails | 221 222**示例：** 223 224 ```js 225 let uploadTask; 226 let uploadConfig = { 227 url: 'http://www.example.com', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 228 header: { 'Accept': '*/*' }, 229 method: "POST", 230 files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], 231 data: [{ name: "name123", value: "123" }], 232 }; 233 request.upload(uploadConfig).then((data) => { 234 uploadTask = data; 235 }).catch((err) => { 236 console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`); 237 }) 238 ``` 239 240 241## request.upload<sup>(deprecated)</sup> 242 243upload(config: UploadConfig, callback: AsyncCallback<UploadTask>): void 244 245上传，异步方法，使用callback形式返回结果。 246 247**模型约束**：此接口仅可在FA模型下使用 248 249> **说明：** 250> 251> 从API Version 9开始不再维护，建议使用[request.uploadFile<sup>9+</sup>](#requestuploadfile9-1)替代。 252 253**需要权限**：ohos.permission.INTERNET 254 255**系统能力**：SystemCapability.MiscServices.Upload 256 257**参数：** 258 259 | 参数名 | 类型 | 必填 | 说明 | 260 | -------- | -------- | -------- | -------- | 261 | config | [UploadConfig](#uploadconfig6) | 是 | 上传的配置信息。 | 262 | callback | AsyncCallback<[UploadTask](#uploadtask)> | 是 | 回调函数，异步返回UploadTask对象。当上传成功，err为undefined，data为获取到的UploadTask对象；否则为错误对象。 | 263 264**错误码：** 265 266以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 267 268 | 错误码ID | 错误信息 | 269 | -------- | -------- | 270 | 201 | the permissions check fails | 271 272**示例：** 273 274 ```js 275 let uploadTask; 276 let uploadConfig = { 277 url: 'http://www.example.com', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 278 header: { 'Accept': '*/*' }, 279 method: "POST", 280 files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], 281 data: [{ name: "name123", value: "123" }], 282 }; 283 request.upload(uploadConfig, (err, data) => { 284 if (err) { 285 console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`); 286 return; 287 } 288 uploadTask = data; 289 }); 290 ``` 291 292## UploadTask 293 294上传任务，使用下列方法前，需要先获取UploadTask对象，promise形式通过[request.uploadFile<sup>9+</sup>](#requestuploadfile9)获取，callback形式通过[request.uploadFile<sup>9+</sup>](#requestuploadfile9-1)获取。 295 296 297 298### on('progress') 299 300on(type: 'progress', callback:(uploadedSize: number, totalSize: number) => void): void 301 302订阅上传任务进度事件，异步方法，使用callback形式返回结果。 303 304> **说明：** 305> 306> 当应用处于后台时，为满足功耗性能要求，不支持调用此接口进行回调。 307 308**系统能力**：SystemCapability.MiscServices.Upload 309 310**参数：** 311 312 | 参数名 | 类型 | 必填 | 说明 | 313 | -------- | -------- | -------- | -------- | 314 | type | string | 是 | 订阅的事件类型，取值为'progress'（上传任务的进度信息）。 | 315 | callback | function | 是 | 上传任务进度的回调函数，返回已上传文件大小和上传文件总大小。 | 316 317 回调函数的参数 318 319| 参数名 | 类型 | 必填 | 说明 | 320| -------- | -------- | -------- | -------- | 321| uploadedSize | number | 是 | 当前已上传文件大小，单位为字节。 | 322| totalSize | number | 是 | 上传文件的总大小，单位为字节。 | 323 324**错误码：** 325 326以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 327 328 | 错误码ID | 错误信息 | 329 | -------- | -------- | 330 | 401 | the parameters check fails.Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 331 332**示例：** 333 334<!--code_no_check--> 335 ```ts 336 let upProgressCallback = (uploadedSize: number, totalSize: number) => { 337 console.info("upload totalSize:" + totalSize + " uploadedSize:" + uploadedSize); 338 }; 339 uploadTask.on('progress', upProgressCallback); 340 ``` 341 342 343### on('headerReceive')<sup>7+</sup> 344 345on(type: 'headerReceive', callback: (header: object) => void): void 346 347订阅上传任务HTTP响应事件，异步方法，使用callback形式返回结果。 348 349**系统能力**: SystemCapability.MiscServices.Upload 350 351**参数：** 352 353 | 参数名 | 类型 | 必填 | 说明 | 354 | -------- | -------- | -------- | -------- | 355 | type | string | 是 | 订阅的事件类型，取值为'headerReceive'（接收响应）。 | 356 | callback | function | 是 | HTTP Response事件的回调函数，返回响应请求内容。 | 357 358 回调函数的参数： 359 360| 参数名 | 类型 | 必填 | 说明 | 361| -------- | -------- | -------- | -------- | 362| header | object | 是 | HTTP Response。 | 363 364**错误码：** 365 366以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 367 368 | 错误码ID | 错误信息 | 369 | -------- | -------- | 370 | 401 | the parameters check fails.Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 371 372**示例：** 373 374<!--code_no_check--> 375 ```ts 376 let headerCallback = (headers: object) => { 377 console.info("upOnHeader headers:" + JSON.stringify(headers)); 378 }; 379 uploadTask.on('headerReceive', headerCallback); 380 ``` 381 382 383### on('complete' | 'fail')<sup>9+</sup> 384 385 on(type:'complete' | 'fail', callback: Callback<Array<TaskState>>): void; 386 387订阅上传任务完成或失败事件，异步方法，使用callback形式返回结果。 388 389**系统能力**：SystemCapability.MiscServices.Upload 390 391**参数：** 392 393 | 参数名 | 类型 | 必填 | 说明 | 394 | -------- | -------- | -------- | -------- | 395 | type | string | 是 | 订阅上传任务的回调类型，支持的事件包括：`'complete'`\|`'fail'`。<br/>\-`'complete'`:表示上传任务完成。 <br/>\-`'fail'`:表示上传任务失败。 396 | callback | Callback<Array<[TaskState](#taskstate9)>> | 是 | 上传任务完成或失败的回调函数。返回上传任务的任务状态信息。 | 397 398 399**错误码：** 400 401以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 402 403 | 错误码ID | 错误信息 | 404 | -------- | -------- | 405 | 401 | the parameters check fails.Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 406 407**示例：** 408 409<!--code_no_check--> 410 ```ts 411 let upCompleteCallback = (taskStates: Array<request.TaskState>) => { 412 for (let i = 0; i < taskStates.length; i++) { 413 console.info("upOnComplete taskState:" + JSON.stringify(taskStates[i])); 414 } 415 }; 416 uploadTask.on('complete', upCompleteCallback); 417 418 let upFailCallback = (taskStates: Array<request.TaskState>) => { 419 for (let i = 0; i < taskStates.length; i++) { 420 console.info("upOnFail taskState:" + JSON.stringify(taskStates[i])); 421 } 422 }; 423 uploadTask.on('fail', upFailCallback); 424 ``` 425 426 427### off('progress') 428 429off(type: 'progress', callback?: (uploadedSize: number, totalSize: number) => void): void 430 431取消订阅上传任务进度事件。 432 433**系统能力**：SystemCapability.MiscServices.Upload 434 435**参数：** 436 437 | 参数名 | 类型 | 必填 | 说明 | 438 | -------- | -------- | -------- | -------- | 439 | type | string | 是 | 取消订阅的事件类型，取值为'progress'（上传的进度信息）。 | 440 | callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 | 441 442回调函数的参数 443 444| 参数名 | 类型 | 必填 | 说明 | 445| -------- | -------- | -------- | -------- | 446| uploadedSize | number | 是 | 当前已上传文件大小，单位为字节。 | 447| totalSize | number | 是 | 上传文件的总大小，单位为字节。 | 448**错误码：** 449 450以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 451 452 | 错误码ID | 错误信息 | 453 | -------- | -------- | 454 | 401 | the parameters check fails.Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 455 456**示例：** 457 458<!--code_no_check--> 459 ```ts 460 let upProgressCallback1 = (uploadedSize: number, totalSize: number) => { 461 console.info('Upload delete progress notification.' + 'totalSize:' + totalSize + 'uploadedSize:' + uploadedSize); 462 }; 463 let upProgressCallback2 = (uploadedSize: number, totalSize: number) => { 464 console.info('Upload delete progress notification.' + 'totalSize:' + totalSize + 'uploadedSize:' + uploadedSize); 465 }; 466 uploadTask.on('progress', upProgressCallback1); 467 uploadTask.on('progress', upProgressCallback2); 468 //表示取消upProgressCallback1的订阅 469 uploadTask.off('progress', upProgressCallback1); 470 //表示取消订阅上传任务进度事件的所有回调 471 uploadTask.off('progress'); 472 ``` 473 474 475### off('headerReceive')<sup>7+</sup> 476 477off(type: 'headerReceive', callback?: (header: object) => void): void 478 479取消订阅上传任务HTTP响应事件。 480 481**系统能力**：SystemCapability.MiscServices.Upload 482 483**参数：** 484 485 | 参数名 | 类型 | 必填 | 说明 | 486 | -------- | -------- | -------- | -------- | 487 | type | string | 是 | 取消订阅的事件类型，取值为'headerReceive'（接收响应）。 | 488 | callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 | 489 490**错误码：** 491 492以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 493 494 | 错误码ID | 错误信息 | 495 | -------- | -------- | 496 | 401 | the parameters check fails.Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 497 498**示例：** 499 500<!--code_no_check--> 501 ```ts 502 let headerCallback1 = (header: object) => { 503 console.info(`Upload delete headerReceive notification. header: ${JSON.stringify(header)}`); 504 }; 505 let headerCallback2 = (header: object) => { 506 console.info(`Upload delete headerReceive notification. header: ${JSON.stringify(header)}`); 507 }; 508 uploadTask.on('headerReceive', headerCallback1); 509 uploadTask.on('headerReceive', headerCallback2); 510 //表示取消headerCallback1的订阅 511 uploadTask.off('headerReceive', headerCallback1); 512 //表示取消订阅上传任务HTTP标头事件的所有回调 513 uploadTask.off('headerReceive'); 514 ``` 515 516### off('complete' | 'fail')<sup>9+</sup> 517 518 off(type:'complete' | 'fail', callback?: Callback<Array<TaskState>>): void; 519 520取消订阅上传任务完成或失败事件。 521 522**系统能力**：SystemCapability.MiscServices.Upload 523 524**参数：** 525 526 | 参数名 | 类型 | 必填 | 说明 | 527 | -------- | -------- | -------- | -------- | 528 | type | string | 是 | 订阅的事件类型，取值为'complete'，表示上传任务完成；取值为'fail'，表示上传任务失败。| 529 | callback | Callback<Array<[TaskState](#taskstate9)>> | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 | 530 531**错误码：** 532 533以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 534 535 | 错误码ID | 错误信息 | 536 | -------- | -------- | 537 | 401 | the parameters check fails.Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 538 539**示例：** 540 541<!--code_no_check--> 542 ```ts 543 let upCompleteCallback1 = (taskStates: Array<request.TaskState>) => { 544 console.info('Upload delete complete notification.'); 545 for (let i = 0; i < taskStates.length; i++) { 546 console.info('taskState:' + JSON.stringify(taskStates[i])); 547 } 548 }; 549 let upCompleteCallback2 = (taskStates: Array<request.TaskState>) => { 550 console.info('Upload delete complete notification.'); 551 for (let i = 0; i < taskStates.length; i++) { 552 console.info('taskState:' + JSON.stringify(taskStates[i])); 553 } 554 }; 555 uploadTask.on('complete', upCompleteCallback1); 556 uploadTask.on('complete', upCompleteCallback2); 557 //表示取消headerCallback1的订阅 558 uploadTask.off('complete', upCompleteCallback1); 559 //表示取消订阅上传任务完成的所有回调 560 uploadTask.off('complete'); 561 562 let upFailCallback1 = (taskStates: Array<request.TaskState>) => { 563 console.info('Upload delete fail notification.'); 564 for (let i = 0; i < taskStates.length; i++) { 565 console.info('taskState:' + JSON.stringify(taskStates[i])); 566 } 567 }; 568 let upFailCallback2 = (taskStates: Array<request.TaskState>) => { 569 console.info('Upload delete fail notification.'); 570 for (let i = 0; i < taskStates.length; i++) { 571 console.info('taskState:' + JSON.stringify(taskStates[i])); 572 } 573 }; 574 uploadTask.on('fail', upFailCallback1); 575 uploadTask.on('fail', upFailCallback2); 576 //表示取消headerCallback1的订阅 577 uploadTask.off('fail', upFailCallback1); 578 //表示取消订阅上传任务失败的所有回调 579 uploadTask.off('fail'); 580 ``` 581 582### delete<sup>9+</sup> 583delete(): Promise<boolean> 584 585移除上传的任务，异步方法，使用promise形式返回结果。 586 587**需要权限**：ohos.permission.INTERNET 588 589**系统能力**：SystemCapability.MiscServices.Upload 590 591**返回值：** 592 593 | 类型 | 说明 | 594 | -------- | -------- | 595 | Promise<boolean> | 使用Promise方式异步回调，返回true表示移除上传任务成功；返回false表示移除上传任务失败。 | 596 597**错误码：** 598 599以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 600 601 | 错误码ID | 错误信息 | 602 | -------- | -------- | 603 | 201 | the permissions check fails | 604 605**示例：** 606 607<!--code_no_check--> 608 ```ts 609 uploadTask.delete().then((result: boolean) => { 610 console.info('Succeeded in deleting the upload task.'); 611 }).catch((err: BusinessError) => { 612 console.error(`Failed to delete the upload task. Code: ${err.code}, message: ${err.message}`); 613 }); 614 ``` 615 616> **说明：** 617> 618> 由于不存在401报错场景，在 api12 中 `401 the parameters check fails` 这个错误码被移除。 619 620 621### delete<sup>9+</sup> 622 623delete(callback: AsyncCallback<boolean>): void 624 625移除上传的任务，异步方法，使用callback形式返回结果。 626 627**需要权限**：ohos.permission.INTERNET 628 629**系统能力**：SystemCapability.MiscServices.Upload 630 631**参数：** 632 633 | 参数名 | 类型 | 必填 | 说明 | 634 | -------- | -------- | -------- | -------- | 635 | callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示异步返回移除任务成功；返回false表示异步返回移除任务失败。 | 636 637**错误码：** 638 639以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 640 641 | 错误码ID | 错误信息 | 642 | -------- | -------- | 643 | 201 | the permissions check fails | 644 645**示例：** 646 647<!--code_no_check--> 648 ```ts 649 uploadTask.delete((err: BusinessError, result: boolean) => { 650 if (err) { 651 console.error(`Failed to delete the upload task. Code: ${err.code}, message: ${err.message}`); 652 return; 653 } 654 console.info('Succeeded in deleting the upload task.'); 655 }); 656 ``` 657 658> **说明：** 659> 660> 由于不存在401报错场景，在 api12 中 `401 the parameters check fails` 这个错误码被移除。 661 662 663### remove<sup>(deprecated)</sup> 664 665remove(): Promise<boolean> 666 667移除上传的任务，异步方法，使用promise形式返回结果。 668 669> **说明：** 670> 671> 从API Version 9开始不再维护，建议使用[delete<sup>9+</sup>](#delete9)替代。 672 673**需要权限**：ohos.permission.INTERNET 674 675**系统能力**：SystemCapability.MiscServices.Upload 676 677**返回值：** 678 679 | 类型 | 说明 | 680 | -------- | -------- | 681 | Promise<boolean> | 使用Promise方式异步回调，返回true表示移除上传任务成功；返回false表示移除上传任务失败。 | 682 683**错误码：** 684 685以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 686 687 | 错误码ID | 错误信息 | 688 | -------- | -------- | 689 | 201 | the permissions check fails | 690 691**示例：** 692 693 ```js 694 uploadTask.remove().then((result) => { 695 console.info('Succeeded in removing the upload task.'); 696 }).catch((err) => { 697 console.error(`Failed to remove the upload task. Code: ${err.code}, message: ${err.message}`); 698 }); 699 ``` 700 701 702### remove<sup>(deprecated)</sup> 703 704remove(callback: AsyncCallback<boolean>): void 705 706移除上传的任务，异步方法，使用callback形式返回结果。 707 708> **说明：** 709> 710> 从API Version 9开始不再维护，建议使用[delete<sup>9+</sup>](#delete9-1)替代。 711 712**需要权限**：ohos.permission.INTERNET 713 714**系统能力**：SystemCapability.MiscServices.Upload 715 716**参数：** 717 718 | 参数名 | 类型 | 必填 | 说明 | 719 | -------- | -------- | -------- | -------- | 720 | callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示异步返回移除任务成功；返回false表示异步返回移除任务失败。 | 721 722**错误码：** 723 724以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 725 726 | 错误码ID | 错误信息 | 727 | -------- | -------- | 728 | 201 | the permissions check fails | 729 730**示例：** 731 732 ```js 733 uploadTask.remove((err, result) => { 734 if (err) { 735 console.error(`Failed to remove the upload task. Code: ${err.code}, message: ${err.message}`); 736 return; 737 } 738 if (result) { 739 console.info('Succeeded in removing the upload task.'); 740 } else { 741 console.error(`Failed to remove the upload task. Code: ${err.code}, message: ${err.message}`); 742 } 743 }); 744 ``` 745 746## UploadConfig<sup>6+</sup> 747上传任务的配置信息。 748 749**系统能力**：以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。 750 751| 名称 | 类型 | 必填 | 说明 | 752| -------- | -------- | -------- | -------- | 753| url | string | 是 | 资源地址，其最大长度为2048个字符。 | 754| header | Object | 是 | 添加要包含在上传请求中的HTTP或HTTPS标志头。 | 755| method | string | 是 | HTTP请求方法：POST、PUT，缺省为POST。使用PUT修改资源，使用POST新增资源。 | 756| index<sup>11+</sup> | number | 否 | 任务的路径索引，默认值为0。 | 757| begins<sup>11+</sup> | number | 否 | 在上传开始时读取的文件起点。默认值为0，取值为闭区间。| 758| ends<sup>11+</sup> | number | 否 | 在上传结束时读取的文件终点。默认值为-1，取值为闭区间。 | 759| files | Array<[File](#file)> | 是 | 要上传的文件列表。文件以 HTTP 的 multipart/form-data 格式提交。 | 760| data | Array<[RequestData](#requestdata)> | 是 | 请求的表单数据。 | 761 762## TaskState<sup>9+</sup> 763上传任务的任务信息，是[on('complete' | 'fail')<sup>9+</sup>](#oncomplete--fail9)和[off('complete' | 'fail')<sup>9+</sup>](#offcomplete--fail9)接口的回调参数。 764 765**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。 766 767| 名称 | 类型 | 必填 | 说明 | 768| -------- | -------- | -------- |-------------------------------------------------------------------------------------------------------------------------------------------| 769| path | string | 是 | 文件路径 | 770| responseCode | number | 是 | 上传任务返回值，0表示任务成功，其它返回码为失败，具体请查看message上传任务结果描述信息。此处推荐使用[request.agent.create<sup>10+</sup>](#requestagentcreate10-1)创建上传任务，并获取标准错误码处理异常分支。 | 771| message | string | 是 | 上传任务结果描述信息 | 772 773其中，responseCode包含的返回码值如下： 774 775| 返回码 | 具体信息 | 776|-----|------------------------------------| 777| 0 | 上传成功 | 778| 5 | 任务被主动暂停或停止 | 779| 6 | 任务所属应用被切换到后台或终止，导致前台任务被停止，请检查应用状态 | 780| 7 | 无网络，请检查设备是否处于联网状态 | 781| 8 | 网络类型不匹配，请检查当前网络类型和任务所需网络类型是否匹配 | 782| 10 | 创建HTTP请求失败，请检查参数是否正确或重试任务 | 783| 12 | 超时，请检查参数是否正确、检查网络，又或是重试任务 | 784| 13 | 连接失败，请检查参数是否正确、检查网络，又或是重试任务 | 785| 14 | 请求失败，请检查参数是否正确、检查网络，又或是重试任务 | 786| 15 | 上传失败，请检查参数是否正确、检查网络，又或是重试任务 | 787| 16 | 重定向失败，请检查参数是否正确、检查网络，又或是重试任务 | 788| 17 | 协议错误，服务器返回 4XX 或 5XX 状态码，请检查参数是否正确 | 789| 20 | 其他错误，请检查参数是否正确、检查网络，又或是重试任务 | 790 791## File 792[UploadConfig<sup>6+<sup>](#uploadconfig6)中的文件列表。 793 794**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。 795 796| 名称 | 类型 | 必填 | 说明 | 797| -------- | -------- | -------- | -------- | 798| filename | string | 是 | multipart提交时，请求头中的文件名。 | 799| name | string | 是 | multipart提交时，表单项目的名称，缺省为file。 | 800| uri | string | 是 | 文件的本地存储路径。<br/>仅支持"internal"协议类型，仅支持"internal://cache/"，即调用方（即传入的context）对应的缓存路径context.cacheDir。<br/>示例：internal://cache/path/to/file.txt | 801| type | string | 是 | 文件的内容类型，默认根据文件名或路径的后缀获取。 | 802 803 804## RequestData 805[UploadConfig<sup>6+<sup>](#uploadconfig6)中的表单数据。 806 807**系统能力**：以下各项对应的系统能力均为SystemCapability.MiscServices.Download。 808 809| 名称 | 类型 | 必填 | 说明 | 810| -------- | -------- | -------- | -------- | 811| name | string | 是 | 表示表单元素的名称。 | 812| value | string | 是 | 表示表单元素的值。 | 813 814## request.downloadFile<sup>9+</sup> 815 816downloadFile(context: BaseContext, config: DownloadConfig): Promise<DownloadTask> 817 818下载，异步方法，使用promise形式返回结果，支持HTTP协议。通过[on('complete'|'pause'|'remove')<sup>7+</sup>](#oncompletepauseremove7)可获取任务下载时的状态信息，包括任务完成、暂停或移除。通过[on('fail')<sup>7+</sup>](#onfail7)可获取任务下载时的错误信息。 819 820**需要权限**：ohos.permission.INTERNET 821 822**系统能力**：SystemCapability.MiscServices.Download 823 824**参数：** 825 826 | 参数名 | 类型 | 必填 | 说明 | 827 | -------- | -------- | -------- | -------- | 828 | context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 829 | config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | 830 831**返回值：** 832 833 | 类型 | 说明 | 834 | -------- | -------- | 835 | Promise<[DownloadTask](#downloadtask)> | 使用Promise方式，异步返回下载任务DownloadTask的Promise对象。 | 836 837**错误码：** 838 839以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 840 841 | 错误码ID | 错误信息 | 842 | -------- | -------- | 843 | 201 | the permissions check fails | 844 | 401 | the parameters check fails.Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 845 | 13400001 | file operation error. | 846 | 13400002 | bad file path. | 847 | 13400003 | task service ability error. | 848 849**示例：** 850 851 ```ts 852import { BusinessError } from '@kit.BasicServicesKit'; 853 854 try { 855 // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 856 request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => { 857 let downloadTask: request.DownloadTask = data; 858 }).catch((err: BusinessError) => { 859 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 860 }) 861 } catch (err) { 862 console.error(`Failed to request the download. err: ${JSON.stringify(err)}`); 863 } 864 ``` 865 866> **说明：** 867> 868> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 869 870 871## request.downloadFile<sup>9+</sup> 872 873downloadFile(context: BaseContext, config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void; 874 875下载，异步方法，使用callback形式返回结果，支持HTTP协议。通过[on('complete'|'pause'|'remove')<sup>7+</sup>](#oncompletepauseremove7)可获取任务下载时的状态信息，包括任务完成、暂停或移除。通过[on('fail')<sup>7+</sup>](#onfail7)可获取任务下载时的错误信息。 876 877**需要权限**：ohos.permission.INTERNET 878 879**系统能力**：SystemCapability.MiscServices.Download 880 881**参数：** 882 883 | 参数名 | 类型 | 必填 | 说明 | 884 | -------- | -------- | -------- | -------- | 885 | context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 886 | config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | 887 | callback | AsyncCallback<[DownloadTask](#downloadtask)> | 是 | 回调函数。当下载任务成功，err为undefined，data为获取到的DownloadTask对象；否则为错误对象。 | 888 889**错误码：** 890 891以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 892 893 | 错误码ID | 错误信息 | 894 | -------- | -------- | 895 | 201 | the permissions check fails | 896 | 401 | the parameters check fails.Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 897 | 13400001 | file operation error. | 898 | 13400002 | bad file path. | 899 | 13400003 | task service ability error. | 900 901**示例：** 902 903 ```ts 904import { BusinessError } from '@kit.BasicServicesKit'; 905 906 try { 907 // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 908 request.downloadFile(getContext(), { 909 url: 'https://xxxx/xxxxx.hap', 910 filePath: 'xxx/xxxxx.hap' 911 }, (err: BusinessError, data: request.DownloadTask) => { 912 if (err) { 913 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 914 return; 915 } 916 let downloadTask: request.DownloadTask = data; 917 }); 918 } catch (err) { 919 console.error(`Failed to request the download. err: ${JSON.stringify(err)}`); 920 } 921 ``` 922 923> **说明：** 924> 925> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 926 927## request.download<sup>(deprecated)</sup> 928 929download(config: DownloadConfig): Promise<DownloadTask> 930 931下载，异步方法，使用promise形式返回结果。 932 933> **说明：** 934> 935> 从API Version 9开始不再维护，建议使用[request.downloadFile<sup>9+</sup>](#requestdownloadfile9)替代。 936 937**模型约束**：此接口仅可在FA模型下使用 938 939**需要权限**：ohos.permission.INTERNET 940 941**系统能力**：SystemCapability.MiscServices.Download 942 943**参数：** 944 945 | 参数名 | 类型 | 必填 | 说明 | 946 | -------- | -------- | -------- | -------- | 947 | config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | 948 949**返回值：** 950 951 | 类型 | 说明 | 952 | -------- | -------- | 953 | Promise<[DownloadTask](#downloadtask)> | 使用Promise方式，异步返回下载任务DownloadTask的Promise对象。 | 954 955**错误码：** 956 957以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 958 959 | 错误码ID | 错误信息 | 960 | -------- | -------- | 961 | 201 | the permissions check fails | 962 963**示例：** 964 965 ```js 966 let downloadTask; 967 // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 968 request.download({ url: 'https://xxxx/xxxx.hap' }).then((data) => { 969 downloadTask = data; 970 }).catch((err) => { 971 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 972 }) 973 ``` 974 975 976## request.download<sup>(deprecated)</sup> 977 978download(config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void 979 980下载，异步方法，使用callback形式返回结果。 981 982> **说明：** 983> 984> 从API Version 9开始不再维护，建议使用[request.downloadFile<sup>9+</sup>](#requestdownloadfile9-1)替代。 985 986**模型约束**：此接口仅可在FA模型下使用 987 988**需要权限**：ohos.permission.INTERNET 989 990**系统能力**：SystemCapability.MiscServices.Download 991 992**参数：** 993 994 | 参数名 | 类型 | 必填 | 说明 | 995 | -------- | -------- | -------- | -------- | 996 | config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | 997 | callback | AsyncCallback<[DownloadTask](#downloadtask)> | 是 | 回调函数。当下载任务成功，err为undefined，data为获取到的DownloadTask对象；否则为错误对象。 | 998 999**错误码：** 1000 1001以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 1002 1003| 错误码ID | 错误信息 | 1004 | -------- | -------- | 1005| 201 | the permissions check fails | 1006 1007**示例：** 1008 1009 ```js 1010 let downloadTask; 1011 // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 1012 request.download({ url: 'https://xxxx/xxxxx.hap', 1013 filePath: 'xxx/xxxxx.hap'}, (err, data) => { 1014 if (err) { 1015 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 1016 return; 1017 } 1018 downloadTask = data; 1019 }); 1020 ``` 1021 1022## DownloadTask 1023 1024下载任务，使用下列方法前，需要先获取DownloadTask对象，promise形式通过[request.downloadFile<sup>9+</sup>](#requestdownloadfile9)获取，callback形式通过[request.downloadFile<sup>9+</sup>](#requestdownloadfile9-1)获取。 1025 1026 1027### on('progress') 1028 1029on(type: 'progress', callback:(receivedSize: number, totalSize: number) => void): void 1030 1031订阅下载任务进度事件，异步方法，使用callback形式返回结果。 1032 1033> **说明：** 1034> 1035> 当应用处于后台时，为满足功耗性能要求，不支持调用此接口进行回调。 1036 1037**系统能力**：SystemCapability.MiscServices.Download 1038 1039**参数：** 1040 1041 | 参数名 | 类型 | 必填 | 说明 | 1042 | -------- | -------- | -------- | -------- | 1043 | type | string | 是 | 订阅的事件类型，取值为'progress'（下载的进度信息）。 | 1044 | callback | function | 是 | 下载任务进度的回调函数，返回已上传文件大小和上传文件总大小。 | 1045 1046 回调函数的参数： 1047 1048| 参数名 | 类型 | 必填 | 说明 | 1049| -------- | -------- | -------- |-------------------------------------------------------------------------| 1050| receivedSize | number | 是 | 当前下载的进度，单位为字节。 | 1051| totalSize | number | 是 | 下载文件的总大小，单位为字节。在下载过程中，若服务器使用 chunk 方式传输导致无法从请求头中获取文件总大小时，totalSize 为 -1。 | 1052 1053**错误码：** 1054 1055以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1056 1057 | 错误码ID | 错误信息 | 1058 | -------- | -------- | 1059 | 401 | the parameters check fails.Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 1060 1061**示例：** 1062 1063 ```ts 1064import { BusinessError } from '@kit.BasicServicesKit'; 1065 1066 try { 1067 // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 1068 request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => { 1069 let downloadTask: request.DownloadTask = data; 1070 let progressCallback = (receivedSize: number, totalSize: number) => { 1071 console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize); 1072 }; 1073 downloadTask.on('progress', progressCallback); 1074 }).catch((err: BusinessError) => { 1075 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 1076 }) 1077 } catch (err) { 1078 console.error(`Failed to request the download. err: ${JSON.stringify(err)}`); 1079 } 1080 ``` 1081 1082 1083### off('progress') 1084 1085off(type: 'progress', callback?: (receivedSize: number, totalSize: number) => void): void 1086 1087取消订阅下载任务进度事件。 1088 1089**系统能力**：SystemCapability.MiscServices.Download 1090 1091**参数：** 1092 1093 | 参数名 | 类型 | 必填 | 说明 | 1094 | -------- | -------- | -------- | -------- | 1095 | type | string | 是 | 取消订阅的事件类型，取值为'progress'（下载的进度信息）。 | 1096 | callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 | 1097 1098 回调函数的参数： 1099 1100| 参数名 | 类型 | 必填 | 说明 | 1101| -------- | -------- | -------- |-------------------------------------------------------------------------| 1102| receivedSize | number | 是 | 当前下载的进度，单位为字节。 | 1103| totalSize | number | 是 | 下载文件的总大小，单位为字节。在下载过程中，若服务器使用 chunk 方式传输导致无法从请求头中获取文件总大小时，totalSize 为 -1。 | 1104 1105**错误码：** 1106 1107以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1108 1109 | 错误码ID | 错误信息 | 1110 | -------- | -------- | 1111 | 401 | the parameters check fails.Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 1112 1113**示例：** 1114 1115 ```ts 1116import { BusinessError } from '@kit.BasicServicesKit'; 1117 1118try { 1119 // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 1120 request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => { 1121 let downloadTask: request.DownloadTask = data; 1122 let progressCallback1 = (receivedSize: number, totalSize: number) => { 1123 console.info('Download delete progress notification.' + 'receivedSize:' + receivedSize + 'totalSize:' + totalSize); 1124 }; 1125 let progressCallback2 = (receivedSize: number, totalSize: number) => { 1126 console.info('Download delete progress notification.' + 'receivedSize:' + receivedSize + 'totalSize:' + totalSize); 1127 }; 1128 downloadTask.on('progress', progressCallback1); 1129 downloadTask.on('progress', progressCallback2); 1130 //表示取消progressCallback1的订阅 1131 downloadTask.off('progress', progressCallback1); 1132 //表示取消订阅下载任务进度事件的所有回调 1133 downloadTask.off('progress'); 1134 }).catch((err: BusinessError) => { 1135 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 1136 }) 1137} catch (err) { 1138 console.error(`Failed to request the download. err: ${JSON.stringify(err)}`); 1139} 1140 ``` 1141 1142 1143### on('complete'|'pause'|'remove')<sup>7+</sup> 1144 1145on(type: 'complete'|'pause'|'remove', callback:() => void): void 1146 1147订阅下载任务相关的事件，异步方法，使用callback形式返回。 1148 1149**系统能力**: SystemCapability.MiscServices.Download 1150 1151**参数：** 1152 1153 | 参数名 | 类型 | 必填 | 说明 | 1154 | -------- | -------- | -------- | -------- | 1155 | type | string | 是 | 订阅的事件类型。<br>- 取值为'complete'，表示下载任务完成；<br/>- 取值为'pause'，表示下载任务暂停；<br/>- 取值为'remove'，表示下载任务移除。 | 1156 | callback | function | 是 | 下载任务相关的回调函数。| 1157 1158**错误码：** 1159 1160以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1161 1162 | 错误码ID | 错误信息 | 1163 | -------- | -------- | 1164 | 401 | the parameters check fails.Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 1165 1166**示例：** 1167 1168 ```ts 1169import { BusinessError } from '@kit.BasicServicesKit'; 1170 1171try { 1172 // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 1173 request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => { 1174 let downloadTask: request.DownloadTask = data; 1175 let completeCallback = () => { 1176 console.info('Download task completed.'); 1177 }; 1178 downloadTask.on('complete', completeCallback); 1179 1180 let pauseCallback = () => { 1181 console.info('Download task pause.'); 1182 }; 1183 downloadTask.on('pause', pauseCallback); 1184 1185 let removeCallback = () => { 1186 console.info('Download task remove.'); 1187 }; 1188 downloadTask.on('remove', removeCallback); 1189 }).catch((err: BusinessError) => { 1190 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 1191 }) 1192} catch (err) { 1193 console.error(`Failed to request the download. err: ${JSON.stringify(err)}`); 1194} 1195 ``` 1196 1197 1198### off('complete'|'pause'|'remove')<sup>7+</sup> 1199 1200off(type: 'complete'|'pause'|'remove', callback?: () => void): void 1201 1202取消订阅下载任务相关的事件。 1203 1204**系统能力**：SystemCapability.MiscServices.Download 1205 1206**参数：** 1207 1208 | 参数名 | 类型 | 必填 | 说明 | 1209 | -------- | -------- | -------- | -------- | 1210 | type | string | 是 | 取消订阅的事件类型。<br/>- 取值为'complete'，表示下载任务完成；<br/>- 取值为'pause'，表示下载任务暂停；<br/>- 取值为'remove'，表示下载任务移除。 | 1211 | callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 | 1212 1213**错误码：** 1214 1215以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1216 1217 | 错误码ID | 错误信息 | 1218 | -------- | -------- | 1219 | 401 | the parameters check fails.Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 1220 1221**示例：** 1222 1223 ```ts 1224import { BusinessError } from '@kit.BasicServicesKit'; 1225 1226try { 1227 // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 1228 request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => { 1229 let downloadTask: request.DownloadTask = data; 1230 let completeCallback1 = () => { 1231 console.info('Download delete complete notification.'); 1232 }; 1233 let completeCallback2 = () => { 1234 console.info('Download delete complete notification.'); 1235 }; 1236 downloadTask.on('complete', completeCallback1); 1237 downloadTask.on('complete', completeCallback2); 1238 //表示取消completeCallback1的订阅 1239 downloadTask.off('complete', completeCallback1); 1240 //表示取消订阅下载任务完成的所有回调 1241 downloadTask.off('complete'); 1242 1243 let pauseCallback1 = () => { 1244 console.info('Download delete pause notification.'); 1245 }; 1246 let pauseCallback2 = () => { 1247 console.info('Download delete pause notification.'); 1248 }; 1249 downloadTask.on('pause', pauseCallback1); 1250 downloadTask.on('pause', pauseCallback2); 1251 //表示取消pauseCallback1的订阅 1252 downloadTask.off('pause', pauseCallback1); 1253 //表示取消订阅下载任务暂停的所有回调 1254 downloadTask.off('pause'); 1255 1256 let removeCallback1 = () => { 1257 console.info('Download delete remove notification.'); 1258 }; 1259 let removeCallback2 = () => { 1260 console.info('Download delete remove notification.'); 1261 }; 1262 downloadTask.on('remove', removeCallback1); 1263 downloadTask.on('remove', removeCallback2); 1264 //表示取消removeCallback1的订阅 1265 downloadTask.off('remove', removeCallback1); 1266 //表示取消订阅下载任务移除的所有回调 1267 downloadTask.off('remove'); 1268 }).catch((err: BusinessError) => { 1269 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 1270 }) 1271} catch (err) { 1272 console.error(`Failed to request the download. err: ${JSON.stringify(err)}`); 1273} 1274 1275 ``` 1276 1277 1278### on('fail')<sup>7+</sup> 1279 1280on(type: 'fail', callback: (err: number) => void): void 1281 1282订阅下载任务失败事件，异步方法，使用callback形式返回结果。 1283 1284**系统能力**：SystemCapability.MiscServices.Download 1285 1286**参数：** 1287 1288 | 参数名 | 类型 | 必填 | 说明 | 1289 | -------- | -------- | -------- | -------- | 1290 | type | string | 是 | 订阅的事件类型，取值为'fail'（下载失败）。 | 1291 | callback | function | 是 | 下载失败的回调函数。 | 1292 1293 回调函数的参数： 1294 1295| 参数名 | 类型 | 必填 | 说明 | 1296| -------- | -------- | -------- | -------- | 1297| err | number | 是 | 下载失败的错误码，错误原因见[下载任务的错误码](#常量)。 | 1298 1299**错误码：** 1300 1301以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1302 1303 | 错误码ID | 错误信息 | 1304 | -------- | -------- | 1305 | 401 | the parameters check fails.Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 1306 1307**示例：** 1308 1309 ```ts 1310import { BusinessError } from '@kit.BasicServicesKit'; 1311 1312try { 1313 // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 1314 request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => { 1315 let downloadTask: request.DownloadTask = data; 1316 let failCallback = (err: number) => { 1317 console.error(`Failed to download the task. Code: ${err}`); 1318 }; 1319 downloadTask.on('fail', failCallback); 1320 }).catch((err: BusinessError) => { 1321 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 1322 }) 1323} catch (err) { 1324 console.error(`Failed to request the download. err: ${JSON.stringify(err)}`); 1325} 1326 ``` 1327 1328 1329### off('fail')<sup>7+</sup> 1330 1331off(type: 'fail', callback?: (err: number) => void): void 1332 1333取消订阅下载任务失败事件。 1334 1335**系统能力**：SystemCapability.MiscServices.Download 1336 1337**参数：** 1338 1339 | 参数名 | 类型 | 必填 | 说明 | 1340 | -------- | -------- | -------- | -------- | 1341 | type | string | 是 | 取消订阅的事件类型，取值为'fail'（下载失败）。 | 1342 | callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 | 1343 1344**错误码：** 1345 1346以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1347 1348 | 错误码ID | 错误信息 | 1349 | -------- | -------- | 1350 | 401 | the parameters check fails.Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 1351 1352**示例：** 1353 1354 ```ts 1355import { BusinessError } from '@kit.BasicServicesKit'; 1356 1357try { 1358 // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 1359 request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => { 1360 let downloadTask: request.DownloadTask = data; 1361 let failCallback1 = (err: number) => { 1362 console.error(`Failed to download the task. Code: ${err}`); 1363 }; 1364 let failCallback2 = (err: number) => { 1365 console.error(`Failed to download the task. Code: ${err}`); 1366 }; 1367 downloadTask.on('fail', failCallback1); 1368 downloadTask.on('fail', failCallback2); 1369 //表示取消failCallback1的订阅 1370 downloadTask.off('fail', failCallback1); 1371 //表示取消订阅下载任务失败的所有回调 1372 downloadTask.off('fail'); 1373 }).catch((err: BusinessError) => { 1374 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 1375 }) 1376} catch (err) { 1377 console.error(`Failed to request the download. err: ${JSON.stringify(err)}`); 1378} 1379 ``` 1380 1381### delete<sup>9+</sup> 1382 1383delete(): Promise<boolean> 1384 1385移除下载的任务，异步方法，使用promise形式返回结果。 1386 1387**需要权限**：ohos.permission.INTERNET 1388 1389**系统能力**：SystemCapability.MiscServices.Download 1390 1391**返回值：** 1392 1393 | 类型 | 说明 | 1394 | -------- | -------- | 1395 | Promise<boolean> | 使用promise方式异步回调，返回true表示移除下载任务成功；返回false表示移除下载任务失败。 | 1396 1397**错误码：** 1398 1399以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1400 1401 | 错误码ID | 错误信息 | 1402 | -------- | -------- | 1403 | 201 | the permissions check fails | 1404 1405**示例：** 1406 1407 ```ts 1408import { BusinessError } from '@kit.BasicServicesKit'; 1409 1410try { 1411 // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 1412 request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => { 1413 let downloadTask: request.DownloadTask = data; 1414 downloadTask.delete().then((result: boolean) => { 1415 console.info('Succeeded in removing the download task.'); 1416 }).catch((err: BusinessError) => { 1417 console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`); 1418 }); 1419 }).catch((err: BusinessError) => { 1420 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 1421 }) 1422} catch (err) { 1423 console.error(`Failed to request the download. err: ${JSON.stringify(err)}`); 1424} 1425 ``` 1426 1427> **说明：** 1428> 1429> 由于不存在401报错场景，在 api12 中 `401 the parameters check fails` 这个错误码被移除。 1430 1431 1432### delete<sup>9+</sup> 1433 1434delete(callback: AsyncCallback<boolean>): void 1435 1436移除下载的任务，异步方法，使用callback形式返回结果。 1437 1438**需要权限**：ohos.permission.INTERNET 1439 1440**系统能力**：SystemCapability.MiscServices.Download 1441 1442**参数：** 1443 1444 | 参数名 | 类型 | 必填 | 说明 | 1445 | -------- | -------- | -------- | -------- | 1446 | callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示异步返回移除任务是否成功；返回false表示异步返回移除任务失败。 | 1447 1448**错误码：** 1449 1450以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1451 1452 | 错误码ID | 错误信息 | 1453 | -------- | -------- | 1454 | 201 | the permissions check fails | 1455 1456**示例：** 1457 1458 ```ts 1459import { BusinessError } from '@kit.BasicServicesKit'; 1460 1461try { 1462 // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 1463 request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => { 1464 let downloadTask: request.DownloadTask = data; 1465 downloadTask.delete((err: BusinessError, result: boolean) => { 1466 if (err) { 1467 console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`); 1468 return; 1469 } 1470 console.info('Succeeded in removing the download task.'); 1471 }); 1472 }).catch((err: BusinessError) => { 1473 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 1474 }) 1475} catch (err) { 1476 console.error(`Failed to request the download. err: ${JSON.stringify(err)}`); 1477} 1478 ``` 1479 1480> **说明：** 1481> 1482> 由于不存在401报错场景，在 api12 中 `401 the parameters check fails` 这个错误码被移除。 1483 1484 1485### getTaskInfo<sup>9+</sup> 1486 1487getTaskInfo(): Promise<DownloadInfo> 1488 1489查询下载任务的信息，异步方法，使用promise形式返回DownloadInfo里的信息。 1490 1491**需要权限**：ohos.permission.INTERNET 1492 1493**系统能力**：SystemCapability.MiscServices.Download 1494 1495**返回值：** 1496 1497 | 类型 | 说明 | 1498 | -------- | -------- | 1499 | Promise<[DownloadInfo](#downloadinfo7)> | 使用promise方式，异步返回下载任务信息DownloadInfo的Promise对象。 | 1500 1501**错误码：** 1502 1503以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1504 1505 | 错误码ID | 错误信息 | 1506 | -------- | -------- | 1507 | 201 | the permissions check fails | 1508 1509**示例：** 1510 1511 ```ts 1512import { BusinessError } from '@kit.BasicServicesKit'; 1513 1514try { 1515 // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 1516 request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => { 1517 let downloadTask: request.DownloadTask = data; 1518 downloadTask.getTaskInfo().then((downloadInfo: request.DownloadInfo) => { 1519 console.info('Succeeded in querying the download task') 1520 }).catch((err: BusinessError) => { 1521 console.error(`Failed to query the download task. Code: ${err.code}, message: ${err.message}`) 1522 }); 1523 }).catch((err: BusinessError) => { 1524 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 1525 }) 1526} catch (err) { 1527 console.error(`Failed to request the download. err: ${JSON.stringify(err)}`); 1528} 1529 ``` 1530 1531> **说明：** 1532> 1533> 由于不存在401报错场景，在 api12 中 `401 the parameters check fails` 这个错误码被移除。 1534 1535 1536### getTaskInfo<sup>9+</sup> 1537 1538getTaskInfo(callback: AsyncCallback<DownloadInfo>): void 1539 1540查询下载的任务，异步方法，使用callback形式返回结果。 1541 1542**需要权限**：ohos.permission.INTERNET 1543 1544**系统能力**：SystemCapability.MiscServices.Download 1545 1546**参数：** 1547 1548 | 参数名 | 类型 | 必填 | 说明 | 1549 | -------- | -------- | -------- | -------- | 1550 | callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | 是 | 回调函数。当查询下载任务操作成功，err为undefined，data为获取到的DownloadInfo对象；否则为错误对象。 | 1551 1552**错误码：** 1553 1554以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1555 1556 | 错误码ID | 错误信息 | 1557 | -------- | -------- | 1558 | 201 | the permissions check fails | 1559 1560**示例：** 1561 1562 ```ts 1563import { BusinessError } from '@kit.BasicServicesKit'; 1564 1565try { 1566 // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 1567 request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => { 1568 let downloadTask: request.DownloadTask = data; 1569 downloadTask.getTaskInfo((err: BusinessError, downloadInfo: request.DownloadInfo) => { 1570 if (err) { 1571 console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`); 1572 } else { 1573 console.info('Succeeded in querying the download mimeType'); 1574 } 1575 }); 1576 }).catch((err: BusinessError) => { 1577 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 1578 }) 1579} catch (err) { 1580 console.error(`Failed to request the download. err: ${JSON.stringify(err)}`); 1581} 1582 ``` 1583 1584> **说明：** 1585> 1586> 由于不存在401报错场景，在 api12 中 `401 the parameters check fails` 这个错误码被移除。 1587 1588 1589### getTaskMimeType<sup>9+</sup> 1590 1591getTaskMimeType(): Promise<string> 1592 1593查询下载的任务的MimeType(HTTP中表示资源的媒体类型)，异步方法，使用promise形式返回结果。 1594 1595**需要权限**：ohos.permission.INTERNET 1596 1597**系统能力**：SystemCapability.MiscServices.Download 1598 1599**返回值：** 1600 1601 | 类型 | 说明 | 1602 | -------- | -------- | 1603 | Promise<string> | 使用promise方式，异步返回下载任务的MimeType的Promise对象。 | 1604 1605**错误码：** 1606 1607以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1608 1609 | 错误码ID | 错误信息 | 1610 | -------- | -------- | 1611 | 201 | the permissions check fails | 1612 1613**示例：** 1614 1615 ```ts 1616import { BusinessError } from '@kit.BasicServicesKit'; 1617 1618try { 1619 // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 1620 request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => { 1621 let downloadTask: request.DownloadTask = data; 1622 downloadTask.getTaskMimeType().then((data: string) => { 1623 console.info('Succeeded in querying the download MimeType'); 1624 }).catch((err: BusinessError) => { 1625 console.error(`Failed to query the download MimeType. Code: ${err.code}, message: ${err.message}`) 1626 }); 1627 }).catch((err: BusinessError) => { 1628 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 1629 }) 1630} catch (err) { 1631 console.error(`Failed to request the download. err: ${JSON.stringify(err)}`); 1632} 1633 ``` 1634 1635> **说明：** 1636> 1637> 由于不存在401报错场景，在 api12 中 `401 the parameters check fails` 这个错误码被移除。 1638 1639 1640### getTaskMimeType<sup>9+</sup> 1641 1642getTaskMimeType(callback: AsyncCallback<string>): void; 1643 1644查询下载的任务的 MimeType，异步方法，使用callback形式返回结果。 1645 1646**需要权限**：ohos.permission.INTERNET 1647 1648**系统能力**：SystemCapability.MiscServices.Download 1649 1650**参数：** 1651 1652 | 参数名 | 类型 | 必填 | 说明 | 1653 | -------- | -------- | -------- | -------- | 1654 | callback | AsyncCallback<string> | 是 | 回调函数。当查询下载任务MimeType成功，err为undefined，data为获取到的下载任务的MimeType对象；否则为错误对象。 | 1655 1656**错误码：** 1657 1658以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1659 1660 | 错误码ID | 错误信息 | 1661 | -------- | -------- | 1662 | 201 | the permissions check fails | 1663 1664**示例：** 1665 1666 ```ts 1667import { BusinessError } from '@kit.BasicServicesKit'; 1668 1669try { 1670 // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 1671 request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => { 1672 let downloadTask: request.DownloadTask = data; 1673 downloadTask.getTaskMimeType((err: BusinessError, data: string) => { 1674 if (err) { 1675 console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`); 1676 } else { 1677 console.info('Succeeded in querying the download mimeType'); 1678 } 1679 }); 1680 }).catch((err: BusinessError) => { 1681 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 1682 }) 1683} catch (err) { 1684 console.error(`Failed to request the download. err: ${JSON.stringify(err)}`); 1685} 1686 ``` 1687 1688> **说明：** 1689> 1690> 由于不存在401报错场景，在 api12 中 `401 the parameters check fails` 这个错误码被移除。 1691 1692 1693### suspend<sup>9+</sup> 1694 1695suspend(): Promise<boolean> 1696 1697暂停下载任务，异步方法，使用promise形式返回结果。 1698 1699**需要权限**：ohos.permission.INTERNET 1700 1701**系统能力**：SystemCapability.MiscServices.Download 1702 1703**返回值：** 1704 1705 | 类型 | 说明 | 1706 | -------- | -------- | 1707 | Promise<boolean> | 使用promise方式异步回调，返回true表示暂停下载任务成功；返回false表示暂停下载任务失败。 | 1708 1709**错误码：** 1710 1711以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1712 1713 | 错误码ID | 错误信息 | 1714 | -------- | -------- | 1715 | 201 | the permissions check fails | 1716 1717**示例：** 1718 1719 ```ts 1720import { BusinessError } from '@kit.BasicServicesKit'; 1721 1722try { 1723 // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 1724 request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => { 1725 let downloadTask: request.DownloadTask = data; 1726 downloadTask.suspend().then((result: boolean) => { 1727 console.info('Succeeded in pausing the download task.'); 1728 }).catch((err: BusinessError) => { 1729 console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`); 1730 }); 1731 }).catch((err: BusinessError) => { 1732 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 1733 }) 1734} catch (err) { 1735 console.error(`Failed to request the download. err: ${JSON.stringify(err)}`); 1736} 1737 ``` 1738 1739> **说明：** 1740> 1741> 由于不存在401报错场景，在 api12 中 `401 the parameters check fails` 这个错误码被移除。 1742 1743 1744### suspend<sup>9+</sup> 1745 1746suspend(callback: AsyncCallback<boolean>): void 1747 1748暂停下载任务，异步方法，使用callback形式返回结果。 1749 1750**需要权限**：ohos.permission.INTERNET 1751 1752**系统能力**：SystemCapability.MiscServices.Download 1753 1754**参数：** 1755 1756 | 参数名 | 类型 | 必填 | 说明 | 1757 | -------- | -------- | -------- | -------- | 1758 | callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示暂停下载任务成功；返回false表示暂停下载任务失败。 | 1759 1760**错误码：** 1761 1762以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1763 1764 | 错误码ID | 错误信息 | 1765 | -------- | -------- | 1766 | 201 | the permissions check fails | 1767 1768**示例：** 1769 1770 ```ts 1771import { BusinessError } from '@kit.BasicServicesKit'; 1772 1773try { 1774 // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 1775 request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => { 1776 let downloadTask: request.DownloadTask = data; 1777 downloadTask.suspend((err: BusinessError, result: boolean) => { 1778 if (err) { 1779 console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`); 1780 return; 1781 } 1782 console.info('Succeeded in pausing the download task.'); 1783 }); 1784 }).catch((err: BusinessError) => { 1785 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 1786 }) 1787} catch (err) { 1788 console.error(`Failed to request the download. err: ${JSON.stringify(err)}`); 1789} 1790 ``` 1791 1792> **说明：** 1793> 1794> 由于不存在401报错场景，在 api12 中 `401 the parameters check fails` 这个错误码被移除。 1795 1796 1797### restore<sup>9+</sup> 1798 1799restore(): Promise<boolean> 1800 1801重新启动暂停的下载任务，异步方法，使用promise形式返回结果。 1802 1803**需要权限**：ohos.permission.INTERNET 1804 1805**系统能力**：SystemCapability.MiscServices.Download 1806 1807**返回值：** 1808 1809 | 类型 | 说明 | 1810 | -------- | -------- | 1811 | Promise<boolean> | 使用promise方式异步回调，返回true表示重新启动已暂停的下载任务成功；返回false表示重新启动下载任务失败。 | 1812 1813**错误码：** 1814 1815以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1816 1817 | 错误码ID | 错误信息 | 1818 | -------- | -------- | 1819 | 201 | the permissions check fails | 1820 1821**示例：** 1822 1823 ```ts 1824import { BusinessError } from '@kit.BasicServicesKit'; 1825 1826try { 1827 // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 1828 request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => { 1829 let downloadTask: request.DownloadTask = data; 1830 downloadTask.restore().then((result: boolean) => { 1831 console.info('Succeeded in resuming the download task.') 1832 }).catch((err: BusinessError) => { 1833 console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`); 1834 }); 1835 }).catch((err: BusinessError) => { 1836 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 1837 }) 1838} catch (err) { 1839 console.error(`Failed to request the download. err: ${JSON.stringify(err)}`); 1840} 1841 ``` 1842 1843> **说明：** 1844> 1845> 由于不存在401报错场景，在 api12 中 `401 the parameters check fails` 这个错误码被移除。 1846 1847 1848### restore<sup>9+</sup> 1849 1850restore(callback: AsyncCallback<boolean>): void 1851 1852重新启动暂停的下载任务，异步方法，使用callback形式返回结果。 1853 1854**需要权限**：ohos.permission.INTERNET 1855 1856**系统能力**：SystemCapability.MiscServices.Download 1857 1858**参数：** 1859 1860 | 参数名 | 类型 | 必填 | 说明 | 1861 | -------- | -------- | -------- | -------- | 1862 | callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示重新启动已暂停的下载任务成功；返回false表示重新启动下载任务失败。 | 1863 1864**错误码：** 1865 1866以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1867 1868 | 错误码ID | 错误信息 | 1869 | -------- | -------- | 1870 | 201 | the permissions check fails | 1871 1872**示例：** 1873 1874 ```ts 1875import { BusinessError } from '@kit.BasicServicesKit'; 1876 1877try { 1878 // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 1879 request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => { 1880 let downloadTask: request.DownloadTask = data; 1881 downloadTask.restore((err: BusinessError, result: boolean) => { 1882 if (err) { 1883 console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`); 1884 return; 1885 } 1886 console.info('Succeeded in resuming the download task.'); 1887 }); 1888 }).catch((err: BusinessError) => { 1889 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 1890 }) 1891} catch (err) { 1892 console.error(`Failed to request the download. err: ${JSON.stringify(err)}`); 1893} 1894 ``` 1895 1896> **说明：** 1897> 1898> 由于不存在401报错场景，在 api12 中 `401 the parameters check fails` 这个错误码被移除。 1899 1900 1901### remove<sup>(deprecated)</sup> 1902 1903remove(): Promise<boolean> 1904 1905移除下载的任务，异步方法，使用promise形式返回结果。 1906 1907> **说明：** 1908> 1909> 从API Version 9开始不再维护，建议使用[delete<sup>9+</sup>](#delete9-2)替代。 1910 1911**需要权限**：ohos.permission.INTERNET 1912 1913**系统能力**：SystemCapability.MiscServices.Download 1914 1915**返回值：** 1916 1917 | 类型 | 说明 | 1918 | -------- | -------- | 1919 | Promise<boolean> | 使用promise方式异步回调，返回true表示移除下载任务成功；返回false表示移除下载任务失败。 | 1920 1921**错误码：** 1922 1923以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 1924 1925 | 错误码ID | 错误信息 | 1926 | -------- | -------- | 1927 | 201 | the permissions check fails | 1928 1929**示例：** 1930 1931 ```js 1932 downloadTask.remove().then((result) => { 1933 console.info('Succeeded in removing the download task.'); 1934 }).catch ((err) => { 1935 console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`); 1936 }); 1937 ``` 1938 1939 1940### remove<sup>(deprecated)</sup> 1941 1942remove(callback: AsyncCallback<boolean>): void 1943 1944移除下载的任务，异步方法，使用callback形式返回结果。 1945 1946> **说明：** 1947> 1948> 从API Version 9开始不再维护，建议使用[delete<sup>9+</sup>](#delete9-3)替代。 1949 1950**需要权限**：ohos.permission.INTERNET 1951 1952**系统能力**：SystemCapability.MiscServices.Download 1953 1954**参数：** 1955 1956 | 参数名 | 类型 | 必填 | 说明 | 1957 | -------- | -------- | -------- | -------- | 1958 | callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示移除下载任务成功；返回false表示移除下载任务失败。 | 1959 1960**错误码：** 1961 1962以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 1963 1964 | 错误码ID | 错误信息 | 1965 | -------- | -------- | 1966 | 201 | the permissions check fails | 1967 1968**示例：** 1969 1970 ```js 1971 downloadTask.remove((err, result)=>{ 1972 if(err) { 1973 console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`); 1974 return; 1975 } 1976 console.info('Succeeded in removing the download task.'); 1977 }); 1978 ``` 1979 1980 1981### query<sup>(deprecated)</sup> 1982 1983query(): Promise<DownloadInfo> 1984 1985查询下载任务，异步方法，使用promise形式返回DownloadInfo里的信息。 1986 1987> **说明：** 1988> 1989> 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[getTaskInfo<sup>9+</sup>](#gettaskinfo9)替代。 1990 1991**需要权限**：ohos.permission.INTERNET 1992 1993**系统能力**：SystemCapability.MiscServices.Download 1994 1995**返回值：** 1996 1997 | 类型 | 说明 | 1998 | -------- | -------- | 1999 | Promise<[DownloadInfo](#downloadinfo7)> | 使用promise方式，异步返回下载任务信息DownloadInfo的Promise对象。 | 2000 2001**错误码：** 2002 2003以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 2004 2005 | 错误码ID | 错误信息 | 2006 | -------- | -------- | 2007 | 201 | the permissions check fails | 2008 2009**示例：** 2010 2011 ```js 2012 downloadTask.query().then((downloadInfo) => { 2013 console.info('Succeeded in querying the download task.') 2014 }) .catch((err) => { 2015 console.error(`Failed to query the download task. Code: ${err.code}, message: ${err.message}`) 2016 }); 2017 ``` 2018 2019 2020### query<sup>(deprecated)</sup> 2021 2022query(callback: AsyncCallback<DownloadInfo>): void 2023 2024查询下载的任务，异步方法，使用callback形式返回结果。 2025 2026> **说明：** 2027> 2028> 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[getTaskInfo<sup>9+</sup>](#gettaskinfo9-1)替代。 2029 2030**需要权限**：ohos.permission.INTERNET 2031 2032**系统能力**：SystemCapability.MiscServices.Download 2033 2034**参数：** 2035 2036 | 参数名 | 类型 | 必填 | 说明 | 2037 | -------- | -------- | -------- | -------- | 2038 | callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | 是 | 回调函数。当查询下载任务成功，err为undefined，data为获取到的DownloadInfo对象；否则为错误对象。 | 2039 2040**错误码：** 2041 2042以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 2043 2044 | 错误码ID | 错误信息 | 2045 | -------- | -------- | 2046 | 201 | the permissions check fails | 2047 2048**示例：** 2049 2050 ```js 2051 downloadTask.query((err, downloadInfo)=>{ 2052 if(err) { 2053 console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`); 2054 } else { 2055 console.info('Succeeded in querying the download task.'); 2056 } 2057 }); 2058 ``` 2059 2060 2061### queryMimeType<sup>(deprecated)</sup> 2062 2063queryMimeType(): Promise<string> 2064 2065查询下载的任务的MimeType，异步方法，使用promise形式返回结果。 2066 2067> **说明：** 2068> 2069> 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[getTaskMimeType<sup>9+</sup>](#gettaskmimetype9)替代。 2070 2071**需要权限**：ohos.permission.INTERNET 2072 2073**系统能力**：SystemCapability.MiscServices.Download 2074 2075**返回值：** 2076 2077 | 类型 | 说明 | 2078 | -------- | -------- | 2079 | Promise<string> | 使用promise方式，异步返回下载任务的MimeType的Promise对象。 | 2080 2081**错误码：** 2082 2083以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 2084 2085 | 错误码ID | 错误信息 | 2086 | -------- | -------- | 2087 | 201 | the permissions check fails | 2088 2089**示例：** 2090 2091 ```js 2092 downloadTask.queryMimeType().then((data) => { 2093 console.info('Succeeded in querying the download MimeType.'); 2094 }).catch((err) => { 2095 console.error(`Failed to query the download MimeType. Code: ${err.code}, message: ${err.message}`) 2096 }); 2097 ``` 2098 2099 2100### queryMimeType<sup>(deprecated)</sup> 2101 2102queryMimeType(callback: AsyncCallback<string>): void; 2103 2104查询下载的任务的MimeType，异步方法，使用callback形式返回结果。 2105 2106> **说明：** 2107> 2108> 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[getTaskMimeType<sup>9+</sup>](#gettaskmimetype9-1)替代。 2109 2110**需要权限**：ohos.permission.INTERNET 2111 2112**系统能力**：SystemCapability.MiscServices.Download 2113 2114**参数：** 2115 2116 | 参数名 | 类型 | 必填 | 说明 | 2117 | -------- | -------- | -------- | -------- | 2118 | callback | AsyncCallback<string> | 是 | 回调函数。当查询下载任务的MimeType成功，err为undefined，data为获取到的任务MimeType对象；否则为错误对象。 | 2119 2120**错误码：** 2121 2122以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 2123 2124 | 错误码ID | 错误信息 | 2125 | -------- | -------- | 2126 | 201 | the permissions check fails | 2127 2128**示例：** 2129 2130 ```js 2131 downloadTask.queryMimeType((err, data)=>{ 2132 if(err) { 2133 console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`); 2134 } else { 2135 console.info('Succeeded in querying the download mimeType.'); 2136 } 2137 }); 2138 ``` 2139 2140 2141### pause<sup>(deprecated)</sup> 2142 2143pause(): Promise<void> 2144 2145暂停下载任务，异步方法，使用promise形式返回结果。 2146 2147> **说明：** 2148> 2149> 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[suspend<sup>9+</sup>](#suspend9)替代。 2150 2151**需要权限**：ohos.permission.INTERNET 2152 2153**系统能力**：SystemCapability.MiscServices.Download 2154 2155**返回值：** 2156 2157 | 类型 | 说明 | 2158 | -------- | -------- | 2159 | Promise<void> | Promise对象。无返回结果的Promise对象。 | 2160 2161**错误码：** 2162 2163以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 2164 2165 | 错误码ID | 错误信息 | 2166 | -------- | -------- | 2167 | 201 | the permissions check fails | 2168 2169**示例：** 2170 2171 ```js 2172 downloadTask.pause().then((result) => { 2173 console.info('Succeeded in pausing the download task.'); 2174 }).catch((err) => { 2175 console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`); 2176 }); 2177 ``` 2178 2179 2180### pause<sup>(deprecated)</sup> 2181 2182pause(callback: AsyncCallback<void>): void 2183 2184> **说明：** 2185> 2186> 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[suspend<sup>9+</sup>](#suspend9-1)替代。 2187 2188暂停下载任务，异步方法，使用callback形式返回结果。 2189 2190**需要权限**：ohos.permission.INTERNET 2191 2192**系统能力**：SystemCapability.MiscServices.Download 2193 2194**参数：** 2195 2196 | 参数名 | 类型 | 必填 | 说明 | 2197 | -------- | -------- | -------- | -------- | 2198 | callback | AsyncCallback<void> | 是 | 回调函数。当暂停下载任务成功，err为undefined，否则为错误对象。 | 2199 2200**错误码：** 2201 2202以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 2203 2204 | 错误码ID | 错误信息 | 2205 | -------- | -------- | 2206 | 201 | the permissions check fails | 2207 2208**示例：** 2209 2210 ```js 2211 downloadTask.pause((err, result)=>{ 2212 if(err) { 2213 console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`); 2214 return; 2215 } 2216 console.info('Succeeded in pausing the download task.'); 2217 }); 2218 ``` 2219 2220 2221### resume<sup>(deprecated)</sup> 2222 2223resume(): Promise<void> 2224 2225重新启动暂停的下载任务，异步方法，使用promise形式返回结果。 2226 2227> **说明：** 2228> 2229> 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[restore<sup>9+</sup>](#restore9)替代。 2230 2231**需要权限**：ohos.permission.INTERNET 2232 2233**系统能力**：SystemCapability.MiscServices.Download 2234 2235**返回值：** 2236 2237 | 类型 | 说明 | 2238 | -------- | -------- | 2239 | Promise<void> | Promise对象。无返回结果的Promise对象。 | 2240 2241**错误码：** 2242 2243以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 2244 2245 | 错误码ID | 错误信息 | 2246 | -------- | -------- | 2247 | 201 | the permissions check fails | 2248 2249**示例：** 2250 2251 ```js 2252 downloadTask.resume().then((result) => { 2253 console.info('Succeeded in resuming the download task.') 2254 }).catch((err) => { 2255 console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`); 2256 }); 2257 ``` 2258 2259 2260### resume<sup>(deprecated)</sup> 2261 2262resume(callback: AsyncCallback<void>): void 2263 2264> **说明：** 2265> 2266> 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[restore<sup>9+</sup>](#restore9-1)替代。 2267 2268重新启动暂停的下载任务，异步方法，使用callback形式返回结果。 2269 2270**需要权限**：ohos.permission.INTERNET 2271 2272**系统能力**：SystemCapability.MiscServices.Download 2273 2274**参数：** 2275 2276 | 参数名 | 类型 | 必填 | 说明 | 2277 | -------- | -------- | -------- | -------- | 2278 | callback | AsyncCallback<void> | 是 | 回调函数。当重新启动已暂停的下载任务成功，err为undefined，否则为错误对象。 | 2279 2280**错误码：** 2281 2282以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 2283 2284 | 错误码ID | 错误信息 | 2285 | -------- | -------- | 2286 | 201 | the permissions check fails | 2287 2288**示例：** 2289 2290 ```js 2291 downloadTask.resume((err, result)=>{ 2292 if (err) { 2293 console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`); 2294 return; 2295 } 2296 console.info('Succeeded in resuming the download task.'); 2297 }); 2298 ``` 2299 2300 2301## DownloadConfig 2302下载任务的配置信息。 2303 2304**系统能力**：SystemCapability.MiscServices.Download 2305 2306| 名称 | 类型 | 必填 | 说明 | 2307| -------- | -------- | -------- | -------- | 2308| url | string | 是 | 资源地址，其最大长度为2048个字符。 | 2309| header | Object | 否 | 添加要包含在下载请求中的HTTPS标志头。| 2310| enableMetered | boolean | 否 | 设置是否允许在按流量计费的连接下下载(默认使用false)。Wi-Fi为非计费网络，数据流量为计费网络。<br/>- true：是<br/>- false：否 | 2311| enableRoaming | boolean | 否 | 设置是否允许在漫游网络中下载(默认使用false)。 <br/>- true：是<br/>- false：否| 2312| description | string | 否 | 设置下载会话的描述。 | 2313| filePath<sup>7+</sup> | string | 否 | 设置下载路径。默认为调用方（即传入的context）对应的缓存路径。默认文件名从url的最后一个"/"后截取。<br/>- FA模型下使用[context](../apis-ability-kit/js-apis-inner-app-context.md#contextgetcachedir) 获取应用存储路径。<br/>- Stage模型下使用[AbilityContext](../apis-ability-kit/js-apis-inner-application-context.md) 类获取文件路径。| 2314| networkType | number | 否 | 设置允许下载的网络类型(默认使用NETWORK_MOBILE&NETWORK_WIFI)。<br/>- NETWORK_MOBILE：0x00000001<br/>- NETWORK_WIFI：0x00010000| 2315| title | string | 否 | 设置下载任务名称。 | 2316| background<sup>9+</sup> | boolean | 否 | 后台任务通知开关，开启后可在通知中显示下载状态(默认使用false)。 | 2317 2318 2319## DownloadInfo<sup>7+</sup> 2320下载任务信息，[getTaskInfo<sup>9+</sup>](#gettaskinfo9)接口的回调参数。 2321 2322**系统能力**：SystemCapability.MiscServices.Download 2323 2324| 名称 | 类型 |必填 | 说明 | 2325| -------- | -------- | -------- | -------- | 2326| downloadId | number |是 | 下载任务ID。 | 2327| failedReason | number|是 | 下载失败原因，可以是任何[下载任务的错误码](#常量)常量。 | 2328| fileName | string |是| 下载的文件名。 | 2329| filePath | string |是| 存储文件的URI。 | 2330| pausedReason | number |是| 会话暂停的原因，可以是任何[下载任务暂停原因](#常量)常量。 | 2331| status | number |是| 下载状态码，可以是任何[下载任务状态码](#常量)常量。 | 2332| targetURI | string |是| 下载文件的URI。 | 2333| downloadTitle | string |是| 下载任务名称。 | 2334| downloadTotalBytes | number |是| 下载的文件的总大小，单位为字节。 | 2335| description | string |是| 待下载任务的描述信息。 | 2336| downloadedBytes | number |是| 实时下载大小，单位为字节。 | 2337 2338## Action<sup>10+</sup> 2339 2340定义操作选项。 2341 2342**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2343 2344**系统能力**：SystemCapability.Request.FileTransferAgent 2345 2346| 名称 | 值 |说明 | 2347| -------- | -------- |-------- | 2348| DOWNLOAD | 0 |表示下载任务。 | 2349| UPLOAD | 1 |表示上传任务。 | 2350 2351 2352## Mode<sup>10+</sup> 2353定义模式选项。<br> 2354前端任务在应用切换到后台一段时间后失败/暂停；后台任务不受影响。 2355 2356**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2357 2358**系统能力**：SystemCapability.Request.FileTransferAgent 2359 2360| 名称 | 值 |说明 | 2361| -------- | -------- |-------- | 2362| BACKGROUND | 0 |表示后台任务。 | 2363| FOREGROUND | 1 |表示前端任务。 | 2364 2365## Network<sup>10+</sup> 2366 2367定义网络选项。<br> 2368网络不满足设置条件时，未执行的任务等待执行，执行中的任务失败/暂停。 2369 2370**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2371 2372**系统能力**：SystemCapability.Request.FileTransferAgent 2373 2374| 名称 | 值 |说明 | 2375| -------- | -------- |-------- | 2376| ANY | 0 |表示不限网络类型。 | 2377| WIFI | 1 |表示无线网络。 | 2378| CELLULAR | 2 |表示蜂窝数据网络。 | 2379 2380## BroadcastEvent<sup>11+</sup> 2381 2382定义自定义系统事件。用户可以使用公共事件接口获取该事件。 2383上传下载 SA 具有 'ohos.permission.SEND_TASK_COMPLETE_EVENT' 该权限，用户可以配置事件的 metadata 指向的二级配置文件来拦截其他事件发送者。 2384 2385使用 CommonEventData 类型传输公共事件相关数据。成员的内容填写和 [CommonEventData介绍](js-apis-inner-commonEvent-commonEventData.md) 介绍的有所区别，其中 CommonEventData.code 表示任务的状态，目前为 0x40 COMPLETE 或 0x41 FAILED; CommonEventData.data 表示任务的 taskId。 2386 2387<!--Del--> 2388事件配置信息请参考[静态订阅公共事件](../../basic-services/common-event/common-event-static-subscription.md)。<!--DelEnd--> 2389 2390**系统能力**：SystemCapability.Request.FileTransferAgent 2391 2392| 名称 | 值 | 说明 | 2393| -------- | ------- |-----------| 2394| COMPLETE | 'ohos.request.event.COMPLETE' | 表示任务完成事件。 | 2395 2396## FileSpec<sup>10+</sup> 2397表单项的文件信息。 2398 2399**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2400 2401**系统能力**：SystemCapability.Request.FileTransferAgent 2402 2403| 名称 | 类型 | 必填 | 说明 | 2404| -------- | -------- | -------- | -------- | 2405| path | string | 是 | 文件路径：<br/>-相对路径，位于调用方的缓存路径下，如"./xxx/yyy/zzz.html"、"xxx/yyy/zzz.html"。<br/>-internal协议路径，支持"internal://"及其子路径，internal为调用方（即传入的context）对应路径，"internal://cache"对应context.cacheDir。如"internal://cache/path/to/file.txt"。<br/>-应用沙箱目录，只支持到base及其子目录下，如"/data/storage/el1/base/path/to/file.txt"。<br/>-file协议路径，必须匹配应用包名，只支持到base及其子目录下，如"file://com.example.test/data/storage/el2/base/file.txt"。<br/>-用户公共文件，如"file://media/Photo/path/to/file.img"。仅支持前端任务。 | 2406| mimeType | string | 否 | 文件的mimetype通过文件名获取。 | 2407| filename | string | 否 | 文件名，默认值通过路径获取。 | 2408| extras | object | 否 | 文件信息的附加内容，该参数不会体现在HTTP请求中。 | 2409 2410 2411## FormItem<sup>10+</sup> 2412任务的表单项信息。 2413 2414**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2415 2416**系统能力**：SystemCapability.Request.FileTransferAgent 2417 2418| 名称 | 类型 | 必填 | 说明 | 2419| -------- | -------- | -------- | -------- | 2420| name | string | 是 | 表单参数名。 | 2421| value | string \| [FileSpec](#filespec10) \| Array<[FileSpec](#filespec10)> | 是 | 表单参数值。 | 2422 2423 2424## Config<sup>10+</sup> 2425上传/下载任务的配置信息。 2426 2427**系统能力**：SystemCapability.Request.FileTransferAgent 2428 2429| 名称 | 类型 | 必填 | 说明 | 2430| -------- | -------- | -------- | -------- | 2431| action | [Action](#action10) | 是 | 任务操作选项。<br/>-UPLOAD表示上传任务。<br/>-DOWNLOAD表示下载任务。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2432| url | string | 是 | 资源地址，其最大长度为2048个字符。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2433| title | string | 否 | 任务标题，其最大长度为256个字符，默认值为小写的 upload 或 download，与上面的 action 保持一致。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2434| description | string | 否 | 任务的详细信息，其最大长度为1024个字符，默认值为空字符串。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2435| mode | [Mode](#mode10) | 否 | 任务模式,默认为后台任务。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2436| overwrite | boolean | 否 | 下载过程中路径已存在时的解决方案选择，默认为false。<br/>- true，覆盖已存在的文件。<br/>- false，下载失败。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2437| method | string | 否 | 上传或下载的HTTP标准方法，包括GET、POST和PUT，不区分大小写。<br/>-上传时，使用PUT或POST，默认值为PUT。<br/>-下载时，使用GET或POST，默认值为GET。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2438| headers | object | 否 | 添加要包含在任务中的HTTP协议标志头。<br/>-对于上传请求，默认的Content-Type为"multipart/form-data"。<br/>-对于下载请求，默认的Content-Type为"application/json"。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2439| data | string \| Array<[FormItem](#formitem10)> | 否 | -下载时，data为字符串类型，通常使用json(object将被转换为json文本)，默认为空。<br/>-上传时，data是表单项数组Array<[FormItem](#formitem10)>，默认为空。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2440| saveas | string | 否 | 保存下载文件的路径，包括如下几种：<br/>-相对路径，位于调用方的缓存路径下，如"./xxx/yyy/zzz.html"、"xxx/yyy/zzz.html"。<br/>-internal协议路径，支持"internal://"及其子路径，internal为调用方（即传入的context）对应路径，"internal://cache"对应context.cacheDir。如"internal://cache/path/to/file.txt"。<br/>-应用沙箱目录，只支持到base及其子目录下，如"/data/storage/el1/base/path/to/file.txt"。<br/>-file协议路径，必须匹配应用包名，只支持到base及其子目录下，如"file://com.example.test/data/storage/el2/base/file.txt"。<br/>默认为调用方（即传入的context）对应的缓存路径。默认文件名从url的最后一个"/"后截取。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2441| network | [Network](#network10) | 否 | 网络选项，当前支持无线网络WIFI和蜂窝数据网络CELLULAR，默认为ANY（WIFI或CELLULAR）。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2442| metered | boolean | 否 | 是否允许在按流量计费的网络中工作，默认为false。<br/>-true：是 <br/>-false：否<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2443| roaming | boolean | 否 | 是否允许在漫游网络中工作，默认为true。<br/>-true：是 <br/>-false：否<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2444| retry | boolean | 否 | 是否为后台任务启用自动重试，仅应用于后台任务，默认为true。<br/>-true：是 <br/>-false：否<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2445| redirect | boolean | 否 | 是否允许重定向，默认为true。<br/>-true：是 <br/>-false：否<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2446| proxy<sup>12+</sup> | string | 否 | 设置代理地址，其最大长度为512个字符，默认为空。<br/>代理地址格式:"http://\<domain or address\>:\<port\>" | 2447| index | number | 否 | 任务的路径索引，通常用于任务断点续传，默认为0。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2448| begins | number | 否 | 文件起点，通常用于断点续传。默认值为0，取值为闭区间。<br/>-下载时，请求读取服务器开始下载文件时的起点位置（http协议中设置"Range"选项）。<br/>-上传时，在上传开始时读取。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2449| ends | number | 否 | 文件终点，通常用于断点续传。默认值为-1，取值为闭区间。<br/>-下载时，请求读取服务器开始下载文件时的结束位置（http协议中设置"Range"选项）。<br/>-上传时，在上传时结束读取。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2450| gauge | boolean | 否 | 后台任务的过程进度通知策略，仅应用于后台任务，默认值为false。<br/>-false：代表仅完成或失败的通知。<br/>-true，发出每个进度已完成或失败的通知。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2451| precise | boolean | 否 | -如果设置为true，在上传/下载无法获取文件大小时任务失败。<br/>-如果设置为false，将文件大小设置为-1时任务继续。<br/>默认值为false。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2452| token | string | 否 | 当创建了一个带有token的任务后，token则为正常查询期间必须提供的，否则将无法通过查询进行检索。其最小为8个字节，最大为2048个字节。默认为空。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2453| priority<sup>11+</sup> | number | 否 | 任务的优先级。任务模式相同的情况下，该配置项的数字越小优先级越高，默认值为0。 | 2454| extras | object | 否 | 配置的附加功能，默认为空。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2455 2456## State<sup>10+</sup> 2457 2458定义任务当前的状态。 2459 2460**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2461 2462**系统能力**：SystemCapability.Request.FileTransferAgent 2463 2464| 名称 | 值 |说明 | 2465| -------- | -------- |-------- | 2466| INITIALIZED | 0x00 |通过配置信息（[Config](#config10)）创建初始化任务。 | 2467| WAITING | 0x10 |表示任务缺少运行或重试的资源与网络状态不匹配。 | 2468| RUNNING | 0x20 |表示正在处理的任务。 | 2469| RETRYING | 0x21 |表示任务至少失败一次，现在正在再次处理中。 | 2470| PAUSED | 0x30 |表示任务暂停，通常后续会恢复任务。 | 2471| STOPPED | 0x31 |表示任务停止。 | 2472| COMPLETED | 0x40 |表示任务完成。 | 2473| FAILED | 0x41 |表示任务失败。 | 2474| REMOVED | 0x50 |表示任务移除。 | 2475 2476 2477## Progress<sup>10+</sup> 2478任务进度的数据结构。 2479 2480**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2481 2482**系统能力**：SystemCapability.Request.FileTransferAgent 2483 2484| 名称 | 类型 | 必填 | 说明 | 2485| -------- | -------- | -------- |---------------------------------------------------------------------| 2486| state | [State](#state10) | 是 | 任务当前的状态。 | 2487| index | number | 是 | 任务中当前正在处理的文件索引。 | 2488| processed | number | 是 | 任务中当前文件的已处理数据大小，单位为字节。 | 2489| sizes | Array<number> | 是 | 任务中文件的大小，单位为字节。在下载过程中，若服务器使用 chunk 方式传输导致无法从请求头中获取文件总大小时，sizes 为 -1。 | 2490| extras | object | 否 | 交互的额外内容，例如来自服务器的响应的header和body。 | 2491 2492 2493## Faults<sup>10+</sup> 2494 2495定义任务失败的原因。 2496 2497**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2498 2499**系统能力**：SystemCapability.Request.FileTransferAgent 2500 2501| 名称 | 值 | 说明 | 2502| -------- | -------- |--------------------------------------------------------------------------------| 2503| OTHERS | 0xFF | 表示其他故障。 | 2504| DISCONNECTED | 0x00 | 表示网络断开连接。 | 2505| TIMEOUT | 0x10 | 表示任务超时。 | 2506| PROTOCOL | 0x20 | 表示协议错误，例如:服务器内部错误（500）、无法处理的数据区间（416）等。 | 2507| PARAM<sup>12+</sup> | 0x30 | 表示参数错误，例如url格式错误等。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2508| FSIO | 0x40 | 表示文件系统io错误，例如打开/查找/读取/写入/关闭。 | 2509| DNS<sup>12+</sup> | 0x50 | 表示DNS解析错误。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2510| TCP<sup>12+</sup> | 0x60 | 表示TCP连接错误。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2511| SSL<sup>12+</sup> | 0x70 | 表示SSL连接错误，例如证书错误、证书校验失败错误等。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2512| REDIRECT<sup>12+</sup> | 0x80 | 表示重定向错误。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2513 2514> **说明：** 2515> 2516> API version 12及以下版本，只支持串行的尝试连接域名相关ip，且不支持单个ip的连接时间控制，如果DNS返回的首个ip是阻塞的，可能握手超时造成TIMEOUT错误。 2517 2518## Filter<sup>10+</sup> 2519过滤条件。 2520 2521**系统能力**：SystemCapability.Request.FileTransferAgent 2522 2523| 名称 | 类型 | 必填 | 说明 | 2524| -------- | -------- | -------- | -------- | 2525| before | number | 否 | 结束的Unix时间戳（毫秒），默认为调用时刻。 | 2526| after | number | 否 | 开始的Unix时间戳（毫秒），默认值为调用时刻减24小时。 | 2527| state | [State](#state10) | 否 | 指定任务的状态。 | 2528| action | [Action](#action10) | 否 | 任务操作选项。<br/>-UPLOAD表示上传任务。<br/>-DOWNLOAD表示下载任务。 | 2529| mode | [Mode](#mode10) | 否 | 任务模式。<br/>-FOREGROUND表示前端任务。<br/>-BACKGROUND表示后台任务。<br/>-如果未填写，则查询所有任务。 | 2530 2531## TaskInfo<sup>10+</sup> 2532查询结果的任务信息数据结构，提供普通查询和系统查询，两种字段的可见范围不同。 2533 2534**系统能力**：SystemCapability.Request.FileTransferAgent 2535 2536| 名称 | 类型 | 必填 | 说明 | 2537| -------- | -------- | -------- | -------- | 2538| saveas | string | 否 | 保存下载文件的路径。 | 2539| url | string | 否 | 任务的url。<br/>- 通过[request.agent.show<sup>10+</sup>](#requestagentshow10-1)、[request.agent.touch<sup>10+</sup>](#requestagenttouch10-1)进行查询。 | 2540| data | string \| Array<[FormItem](#formitem10)> | 否 | 任务值。<br/>- 通过[request.agent.show<sup>10+</sup>](#requestagentshow10-1)、[request.agent.touch<sup>10+</sup>](#requestagenttouch10-1)。 | 2541| tid | string | 是 | 任务id。 | 2542| title | string | 是 | 任务标题。 | 2543| description | string | 是 | 任务描述。 | 2544| action | [Action](#action10) | 是 | 任务操作选项。<br/>-UPLOAD表示上传任务。<br/>-DOWNLOAD表示下载任务。 | 2545| mode | [Mode](#mode10) | 是 | 指定任务模式。<br/>-FOREGROUND表示前端任务。<br/>-BACKGROUND表示后台任务。 | 2546| priority<sup>11+</sup> | number | 是 | 任务配置中的优先级。前端任务的优先级比后台任务高。相同模式的任务，数字越小优先级越高。 | 2547| mimeType | string | 是 | 任务配置中的mimetype。 | 2548| progress | [Progress](#progress10) | 是 | 任务的过程进度。 | 2549| gauge | boolean | 是 | 后台任务的进度通知策略。 | 2550| ctime | number | 是 | 创建任务的Unix时间戳（毫秒），由当前设备的系统生成。<br/>说明：使用[request.agent.search<sup>10+</sup>](#requestagentsearch10-1)进行查询时，该值需处于[after,before]区间内才可正常查询到任务id，before和after信息详见[Filter](#filter10)。 2551| mtime | number | 是 | 任务状态改变时的Unix时间戳（毫秒），由当前设备的系统生成。| 2552| retry | boolean | 是 | 任务的重试开关，仅应用于后台任务。 | 2553| tries | number | 是 | 任务的尝试次数。 | 2554| faults | [Faults](#faults10) | 是 | 任务的失败原因。| 2555| reason | string | 是 | 等待/失败/停止/暂停任务的原因。| 2556| extras | object | 否 | 任务的额外部分。| 2557 2558 2559## HttpResponse<sup>12+</sup> 2560任务响应头的数据结构。 2561 2562**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2563 2564**系统能力**：SystemCapability.Request.FileTransferAgent 2565 2566| 名称 | 类型 | 必填 | 说明 | 2567| -------- | -------- | -------- | -------- | 2568| version | string | 是 | Http版本。 | 2569| statusCode | number | 是 | Http响应状态码。 | 2570| reason | string | 是 | Http响应原因。| 2571| headers | Map<string, Array<string>> | 是 | Http响应头部。 | 2572 2573## Task<sup>10+</sup> 2574上传或下载任务。使用该方法前需要先获取Task对象，promise形式通过[request.agent.create<sup>10+</sup>](#requestagentcreate10-1)获取，callback形式通过[request.agent.create<sup>10+</sup>](#requestagentcreate10)获取。 2575 2576### 属性 2577包括任务id和任务的配置信息。 2578 2579**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2580 2581**系统能力**：SystemCapability.Request.FileTransferAgent 2582 2583| 名称 | 类型 | 必填 | 说明 | 2584| -------- | -------- | -------- | -------- | 2585| tid | string | 是 | 任务id，在系统上是唯一的，由系统自动生成。 | 2586| config | [Config](#config10) | 是 | 任务的配置信息。 | 2587 2588> **说明：** 2589> 2590> Task对象及其挂载回调函数会在调用remove方法后释放并被系统自动回收。 2591 2592### on('progress')<sup>10+</sup> 2593 2594on(event: 'progress', callback: (progress: [Progress](#progress10)) => void): void 2595 2596订阅任务进度的事件，异步方法，使用callback形式返回结果。 2597 2598**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2599 2600**系统能力**：SystemCapability.Request.FileTransferAgent 2601 2602**参数：** 2603 2604 | 参数名 | 类型 | 必填 | 说明 | 2605 | -------- | -------- | -------- | -------- | 2606 | event | string | 是 | 订阅的事件类型。<br>- 取值为'progress'，表示任务进度。 | 2607 | callback | function | 是 | 发生相关的事件时触发该回调方法，返回任务进度的数据结构。| 2608 2609**错误码：** 2610 2611以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 2612 2613 | 错误码ID | 错误信息 | 2614 | -------- | -------- | 2615 | 401 | Parameter error. Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 2616 2617**示例：** 2618 2619 ```ts 2620 import { BusinessError } from '@kit.BasicServicesKit'; 2621 2622 let attachments: Array<request.agent.FormItem> = [{ 2623 name: "taskOnTest", 2624 value: { 2625 filename: "taskOnTest.avi", 2626 mimeType: "application/octet-stream", 2627 path: "./taskOnTest.avi", 2628 } 2629 }]; 2630 let config: request.agent.Config = { 2631 action: request.agent.Action.UPLOAD, 2632 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 2633 title: 'taskOnTest', 2634 description: 'Sample code for event listening', 2635 mode: request.agent.Mode.FOREGROUND, 2636 overwrite: false, 2637 method: "PUT", 2638 data: attachments, 2639 saveas: "./", 2640 network: request.agent.Network.CELLULAR, 2641 metered: false, 2642 roaming: true, 2643 retry: true, 2644 redirect: true, 2645 index: 0, 2646 begins: 0, 2647 ends: -1, 2648 gauge: false, 2649 precise: false, 2650 token: "it is a secret" 2651 }; 2652 let createOnCallback = (progress: request.agent.Progress) => { 2653 console.info('upload task progress.'); 2654 }; 2655 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2656 task.on('progress', createOnCallback); 2657 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2658 task.start(); 2659 }).catch((err: BusinessError) => { 2660 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2661 }); 2662 ``` 2663 2664> **说明：** 2665> 2666> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 2667 2668### on('completed')<sup>10+</sup> 2669 2670on(event: 'completed', callback: (progress: [Progress](#progress10)) => void): void 2671 2672订阅任务完成事件，异步方法，使用callback形式返回结果。 2673 2674**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2675 2676**系统能力**：SystemCapability.Request.FileTransferAgent 2677 2678**参数：** 2679 2680 | 参数名 | 类型 | 必填 | 说明 | 2681 | -------- | -------- | -------- | -------- | 2682 | event | string | 是 | 订阅的事件类型。<br>- 取值为'completed'，表示任务完成。 | 2683 | callback | function | 是 | 发生相关的事件时触发该回调方法，返回任务进度的数据结构。 | 2684 2685**错误码：** 2686 2687以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 2688 2689 | 错误码ID | 错误信息 | 2690 | -------- | -------- | 2691 | 401 | Parameter error. Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 2692 2693**示例：** 2694 2695 ```ts 2696 import { BusinessError } from '@kit.BasicServicesKit'; 2697 2698 let attachments: Array<request.agent.FormItem> = [{ 2699 name: "taskOnTest", 2700 value: { 2701 filename: "taskOnTest.avi", 2702 mimeType: "application/octet-stream", 2703 path: "./taskOnTest.avi", 2704 } 2705 }]; 2706 let config: request.agent.Config = { 2707 action: request.agent.Action.UPLOAD, 2708 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 2709 title: 'taskOnTest', 2710 description: 'Sample code for event listening', 2711 mode: request.agent.Mode.FOREGROUND, 2712 overwrite: false, 2713 method: "PUT", 2714 data: attachments, 2715 saveas: "./", 2716 network: request.agent.Network.CELLULAR, 2717 metered: false, 2718 roaming: true, 2719 retry: true, 2720 redirect: true, 2721 index: 0, 2722 begins: 0, 2723 ends: -1, 2724 gauge: false, 2725 precise: false, 2726 token: "it is a secret" 2727 }; 2728 let createOnCallback = (progress: request.agent.Progress) => { 2729 console.info('upload task completed.'); 2730 }; 2731 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2732 task.on('completed', createOnCallback); 2733 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2734 task.start(); 2735 }).catch((err: BusinessError) => { 2736 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2737 }); 2738 ``` 2739 2740> **说明：** 2741> 2742> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 2743 2744### on('failed')<sup>10+</sup> 2745 2746on(event: 'failed', callback: (progress: [Progress](#progress10)) => void): void 2747 2748订阅任务失败事件，异步方法，使用callback形式返回结果。可通过调用[request.agent.show<sup>10+</sup>](#requestagentshow10-1)查看错误原因。 2749 2750**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2751 2752**系统能力**：SystemCapability.Request.FileTransferAgent 2753 2754**参数：** 2755 2756 | 参数名 | 类型 | 必填 | 说明 | 2757 | -------- | -------- | -------- | -------- | 2758 | event | string | 是 | 订阅的事件类型。<br>- 取值为'failed'，表示任务失败。 | 2759 | callback | function | 是 | 发生相关的事件时触发该回调方法，返回任务进度的数据结构。 | 2760 2761**错误码：** 2762 2763以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 2764 2765 | 错误码ID | 错误信息 | 2766 | -------- | -------- | 2767 | 401 | Parameter error. Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 2768 2769**示例：** 2770 2771 ```ts 2772 import { BusinessError } from '@kit.BasicServicesKit'; 2773 2774 let attachments: Array<request.agent.FormItem> = [{ 2775 name: "taskOnTest", 2776 value: { 2777 filename: "taskOnTest.avi", 2778 mimeType: "application/octet-stream", 2779 path: "./taskOnTest.avi", 2780 } 2781 }]; 2782 let config: request.agent.Config = { 2783 action: request.agent.Action.UPLOAD, 2784 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 2785 title: 'taskOnTest', 2786 description: 'Sample code for event listening', 2787 mode: request.agent.Mode.FOREGROUND, 2788 overwrite: false, 2789 method: "PUT", 2790 data: attachments, 2791 saveas: "./", 2792 network: request.agent.Network.CELLULAR, 2793 metered: false, 2794 roaming: true, 2795 retry: true, 2796 redirect: true, 2797 index: 0, 2798 begins: 0, 2799 ends: -1, 2800 gauge: false, 2801 precise: false, 2802 token: "it is a secret" 2803 }; 2804 let createOnCallback = (progress: request.agent.Progress) => { 2805 console.info('upload task failed.'); 2806 }; 2807 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2808 task.on('failed', createOnCallback); 2809 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2810 task.start(); 2811 }).catch((err: BusinessError) => { 2812 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2813 }); 2814 ``` 2815 2816> **说明：** 2817> 2818> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 2819 2820### on('pause')<sup>11+</sup> 2821 2822on(event: 'pause', callback: (progress: [Progress](#progress10)) => void): void 2823 2824订阅任务暂停事件，异步方法，使用callback形式返回结果。 2825 2826**系统能力**：SystemCapability.Request.FileTransferAgent 2827 2828**参数：** 2829 2830 | 参数名 | 类型 | 必填 | 说明 | 2831 | -------- | -------- | -------- | -------- | 2832 | event | string | 是 | 订阅的事件类型。<br>- 取值为'pause'，表示任务暂停。 | 2833 | callback | function | 是 | 发生相关的事件时触发该回调方法，返回任务进度的数据结构。 | 2834 2835**错误码：** 2836 2837以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 2838 2839 | 错误码ID | 错误信息 | 2840 | -------- | -------- | 2841 | 401 | Parameter error. Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 2842 2843**示例：** 2844 2845 ```ts 2846 import { BusinessError } from '@kit.BasicServicesKit'; 2847 2848 let attachments: Array<request.agent.FormItem> = [{ 2849 name: "taskOnTest", 2850 value: { 2851 filename: "taskOnTest.avi", 2852 mimeType: "application/octet-stream", 2853 path: "./taskOnTest.avi", 2854 } 2855 }]; 2856 let config: request.agent.Config = { 2857 action: request.agent.Action.UPLOAD, 2858 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 2859 title: 'taskOnTest', 2860 description: 'Sample code for event listening', 2861 mode: request.agent.Mode.FOREGROUND, 2862 overwrite: false, 2863 method: "PUT", 2864 data: attachments, 2865 saveas: "./", 2866 network: request.agent.Network.CELLULAR, 2867 metered: false, 2868 roaming: true, 2869 retry: true, 2870 redirect: true, 2871 index: 0, 2872 begins: 0, 2873 ends: -1, 2874 gauge: false, 2875 precise: false, 2876 token: "it is a secret" 2877 }; 2878 let createOnCallback = (progress: request.agent.Progress) => { 2879 console.info('upload task pause.'); 2880 }; 2881 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2882 task.on('pause', createOnCallback); 2883 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2884 task.start(); 2885 }).catch((err: BusinessError) => { 2886 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2887 }); 2888 ``` 2889 2890> **说明：** 2891> 2892> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 2893 2894### on('resume')<sup>11+</sup> 2895 2896on(event: 'resume', callback: (progress: [Progress](#progress10)) => void): void 2897 2898订阅任务恢复事件，异步方法，使用callback形式返回结果。 2899 2900**系统能力**：SystemCapability.Request.FileTransferAgent 2901 2902**参数：** 2903 2904 | 参数名 | 类型 | 必填 | 说明 | 2905 | -------- | -------- | -------- | -------- | 2906 | event | string | 是 | 订阅的事件类型。<br>- 取值为'resume'，表示任务恢复。 | 2907 | callback | function | 是 | 发生相关的事件时触发该回调方法，返回任务进度的数据结构。 | 2908 2909**错误码：** 2910 2911以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 2912 2913 | 错误码ID | 错误信息 | 2914 | -------- | -------- | 2915 | 401 | Parameter error. Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 2916 2917**示例：** 2918 2919 ```ts 2920 import { BusinessError } from '@kit.BasicServicesKit'; 2921 2922 let attachments: Array<request.agent.FormItem> = [{ 2923 name: "taskOnTest", 2924 value: { 2925 filename: "taskOnTest.avi", 2926 mimeType: "application/octet-stream", 2927 path: "./taskOnTest.avi", 2928 } 2929 }]; 2930 let config: request.agent.Config = { 2931 action: request.agent.Action.UPLOAD, 2932 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 2933 title: 'taskOnTest', 2934 description: 'Sample code for event listening', 2935 mode: request.agent.Mode.FOREGROUND, 2936 overwrite: false, 2937 method: "PUT", 2938 data: attachments, 2939 saveas: "./", 2940 network: request.agent.Network.CELLULAR, 2941 metered: false, 2942 roaming: true, 2943 retry: true, 2944 redirect: true, 2945 index: 0, 2946 begins: 0, 2947 ends: -1, 2948 gauge: false, 2949 precise: false, 2950 token: "it is a secret" 2951 }; 2952 let createOnCallback = (progress: request.agent.Progress) => { 2953 console.info('upload task resume.'); 2954 }; 2955 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2956 task.on('resume', createOnCallback); 2957 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2958 task.start(); 2959 }).catch((err: BusinessError) => { 2960 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2961 }); 2962 ``` 2963 2964> **说明：** 2965> 2966> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 2967 2968### on('remove')<sup>11+</sup> 2969 2970on(event: 'remove', callback: (progress: [Progress](#progress10)) => void): void 2971 2972订阅任务删除事件，异步方法，使用callback形式返回结果。 2973 2974**系统能力**：SystemCapability.Request.FileTransferAgent 2975 2976**参数：** 2977 2978 | 参数名 | 类型 | 必填 | 说明 | 2979 | -------- | -------- | -------- | -------- | 2980 | event | string | 是 | 订阅的事件类型。<br>- 取值为'remove'，表示任务删除。 | 2981 | callback | function | 是 | 发生相关的事件时触发该回调方法，返回任务进度的数据结构。 | 2982 2983**错误码：** 2984 2985以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 2986 2987 | 错误码ID | 错误信息 | 2988 | -------- | -------- | 2989 | 401 | Parameter error. Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 2990 2991**示例：** 2992 2993 ```ts 2994 import { BusinessError } from '@kit.BasicServicesKit'; 2995 2996 let attachments: Array<request.agent.FormItem> = [{ 2997 name: "taskOnTest", 2998 value: { 2999 filename: "taskOnTest.avi", 3000 mimeType: "application/octet-stream", 3001 path: "./taskOnTest.avi", 3002 } 3003 }]; 3004 let config: request.agent.Config = { 3005 action: request.agent.Action.UPLOAD, 3006 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 3007 title: 'taskOnTest', 3008 description: 'Sample code for event listening', 3009 mode: request.agent.Mode.FOREGROUND, 3010 overwrite: false, 3011 method: "PUT", 3012 data: attachments, 3013 saveas: "./", 3014 network: request.agent.Network.CELLULAR, 3015 metered: false, 3016 roaming: true, 3017 retry: true, 3018 redirect: true, 3019 index: 0, 3020 begins: 0, 3021 ends: -1, 3022 gauge: false, 3023 precise: false, 3024 token: "it is a secret" 3025 }; 3026 let createOnCallback = (progress: request.agent.Progress) => { 3027 console.info('upload task remove.'); 3028 }; 3029 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3030 task.on('remove', createOnCallback); 3031 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 3032 task.start(); 3033 }).catch((err: BusinessError) => { 3034 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 3035 }); 3036 ``` 3037 3038> **说明：** 3039> 3040> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 3041 3042### on('response')<sup>12+</sup> 3043 3044on(event: 'response', callback: Callback<HttpResponse>): void 3045 3046订阅任务响应头，异步方法，使用callback形式返回结果。 3047 3048**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3049 3050**系统能力**：SystemCapability.Request.FileTransferAgent 3051 3052**参数：** 3053 3054 | 参数名 | 类型 | 必填 | 说明 | 3055 | -------- | -------- | -------- | -------- | 3056 | event | string | 是 | 订阅的事件类型。<br>- 取值为'response'，表示任务响应。 | 3057 | callback | function | 是 | 发生相关的事件时触发该回调方法，返回任务响应头的数据结构。 | 3058 3059**错误码：** 3060 3061以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 3062 3063 | 错误码ID | 错误信息 | 3064 | -------- | -------- | 3065 | 401 | Parameter error. Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 3066 3067**示例：** 3068 3069 ```ts 3070 import { BusinessError } from '@kit.BasicServicesKit'; 3071 3072 let attachments: Array<request.agent.FormItem> = [{ 3073 name: "taskOnTest", 3074 value: { 3075 filename: "taskOnTest.avi", 3076 mimeType: "application/octet-stream", 3077 path: "./taskOnTest.avi", 3078 } 3079 }]; 3080 let config: request.agent.Config = { 3081 action: request.agent.Action.UPLOAD, 3082 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 3083 title: 'taskOnTest', 3084 description: 'Sample code for event listening', 3085 mode: request.agent.Mode.FOREGROUND, 3086 overwrite: false, 3087 method: "PUT", 3088 data: attachments, 3089 saveas: "./", 3090 network: request.agent.Network.CELLULAR, 3091 metered: false, 3092 roaming: true, 3093 retry: true, 3094 redirect: true, 3095 index: 0, 3096 begins: 0, 3097 ends: -1, 3098 gauge: false, 3099 precise: false, 3100 token: "it is a secret" 3101 }; 3102 let createOnCallback = (response: request.agent.HttpResponse) => { 3103 console.info('upload task response.'); 3104 }; 3105 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3106 task.on('response', createOnCallback); 3107 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 3108 task.start(); 3109 }).catch((err: BusinessError) => { 3110 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 3111 }); 3112 ``` 3113 3114> **说明：** 3115> 3116> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 3117 3118### off('progress')<sup>10+</sup> 3119 3120off(event: 'progress', callback?: (progress: [Progress](#progress10)) => void): void 3121 3122取消订阅任务进度事件。 3123 3124**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3125 3126**系统能力**：SystemCapability.Request.FileTransferAgent 3127 3128**参数：** 3129 3130 | 参数名 | 类型 | 必填 | 说明 | 3131 | -------- | -------- | -------- | -------- | 3132 | event | string | 是 | 订阅的事件类型。<br>- 取值为'progress'，表示任务进度。 | 3133 | callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 | 3134 3135**错误码：** 3136 3137以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 3138 3139 | 错误码ID | 错误信息 | 3140 | -------- | -------- | 3141 | 401 | Parameter error. Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 3142 3143**示例：** 3144 3145 ```ts 3146 import { BusinessError } from '@kit.BasicServicesKit'; 3147 3148 let attachments: Array<request.agent.FormItem> = [{ 3149 name: "taskOffTest", 3150 value: { 3151 filename: "taskOffTest.avi", 3152 mimeType: "application/octet-stream", 3153 path: "./taskOffTest.avi", 3154 } 3155 }]; 3156 let config: request.agent.Config = { 3157 action: request.agent.Action.UPLOAD, 3158 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 3159 title: 'taskOffTest', 3160 description: 'Sample code for event listening', 3161 mode: request.agent.Mode.FOREGROUND, 3162 overwrite: false, 3163 method: "PUT", 3164 data: attachments, 3165 saveas: "./", 3166 network: request.agent.Network.CELLULAR, 3167 metered: false, 3168 roaming: true, 3169 retry: true, 3170 redirect: true, 3171 index: 0, 3172 begins: 0, 3173 ends: -1, 3174 gauge: false, 3175 precise: false, 3176 token: "it is a secret" 3177 }; 3178 let createOffCallback1 = (progress: request.agent.Progress) => { 3179 console.info('upload task progress.'); 3180 }; 3181 let createOffCallback2 = (progress: request.agent.Progress) => { 3182 console.info('upload task progress.'); 3183 }; 3184 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3185 task.on('progress', createOffCallback1); 3186 task.on('progress', createOffCallback2); 3187 //表示取消createOffCallback1的订阅 3188 task.off('progress', createOffCallback1); 3189 //表示取消订阅任务进度的所有回调 3190 task.off('progress'); 3191 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 3192 task.start(); 3193 }).catch((err: BusinessError) => { 3194 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 3195 }); 3196 ``` 3197 3198> **说明：** 3199> 3200> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 3201 3202### off('completed')<sup>10+</sup> 3203 3204off(event: 'completed', callback?: (progress: [Progress](#progress10)) => void): void 3205 3206取消订阅任务完成事件。 3207 3208**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3209 3210**系统能力**：SystemCapability.Request.FileTransferAgent 3211 3212**参数：** 3213 3214 | 参数名 | 类型 | 必填 | 说明 | 3215 | -------- | -------- | -------- | -------- | 3216 | event | string | 是 | 订阅的事件类型。<br>- 取值为'completed'，表示任务完成。 | 3217 | callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 | 3218 3219**错误码：** 3220 3221以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 3222 3223 | 错误码ID | 错误信息 | 3224 | -------- | -------- | 3225 | 401 | Parameter error. Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 3226 3227**示例：** 3228 3229 ```ts 3230 import { BusinessError } from '@kit.BasicServicesKit'; 3231 3232 let attachments: Array<request.agent.FormItem> = [{ 3233 name: "taskOffTest", 3234 value: { 3235 filename: "taskOffTest.avi", 3236 mimeType: "application/octet-stream", 3237 path: "./taskOffTest.avi", 3238 } 3239 }]; 3240 let config: request.agent.Config = { 3241 action: request.agent.Action.UPLOAD, 3242 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 3243 title: 'taskOffTest', 3244 description: 'Sample code for event listening', 3245 mode: request.agent.Mode.FOREGROUND, 3246 overwrite: false, 3247 method: "PUT", 3248 data: attachments, 3249 saveas: "./", 3250 network: request.agent.Network.CELLULAR, 3251 metered: false, 3252 roaming: true, 3253 retry: true, 3254 redirect: true, 3255 index: 0, 3256 begins: 0, 3257 ends: -1, 3258 gauge: false, 3259 precise: false, 3260 token: "it is a secret" 3261 }; 3262 let createOffCallback1 = (progress: request.agent.Progress) => { 3263 console.info('upload task completed.'); 3264 }; 3265 let createOffCallback2 = (progress: request.agent.Progress) => { 3266 console.info('upload task completed.'); 3267 }; 3268 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3269 task.on('completed', createOffCallback1); 3270 task.on('completed', createOffCallback2); 3271 //表示取消createOffCallback1的订阅 3272 task.off('completed', createOffCallback1); 3273 //表示取消订阅任务完成的所有回调 3274 task.off('completed'); 3275 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 3276 task.start(); 3277 }).catch((err: BusinessError) => { 3278 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 3279 }); 3280 ``` 3281 3282> **说明：** 3283> 3284> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 3285 3286### off('failed')<sup>10+</sup> 3287 3288off(event: 'failed', callback?: (progress: [Progress](#progress10)) => void): void 3289 3290取消订阅任务失败事件。 3291 3292**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3293 3294**系统能力**：SystemCapability.Request.FileTransferAgent 3295 3296**参数：** 3297 3298 | 参数名 | 类型 | 必填 | 说明 | 3299 | -------- | -------- | -------- | -------- | 3300 | event | string | 是 | 订阅的事件类型。<br>- 取值为'failed'，表示任务失败。 | 3301 | callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 | 3302 3303**错误码：** 3304 3305以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 3306 3307 | 错误码ID | 错误信息 | 3308 | -------- | -------- | 3309 | 401 | Parameter error. Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 3310 3311**示例：** 3312 3313 ```ts 3314 import { BusinessError } from '@kit.BasicServicesKit'; 3315 3316 let attachments: Array<request.agent.FormItem> = [{ 3317 name: "taskOffTest", 3318 value: { 3319 filename: "taskOffTest.avi", 3320 mimeType: "application/octet-stream", 3321 path: "./taskOffTest.avi", 3322 } 3323 }]; 3324 let config: request.agent.Config = { 3325 action: request.agent.Action.UPLOAD, 3326 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 3327 title: 'taskOffTest', 3328 description: 'Sample code for event listening', 3329 mode: request.agent.Mode.FOREGROUND, 3330 overwrite: false, 3331 method: "PUT", 3332 data: attachments, 3333 saveas: "./", 3334 network: request.agent.Network.CELLULAR, 3335 metered: false, 3336 roaming: true, 3337 retry: true, 3338 redirect: true, 3339 index: 0, 3340 begins: 0, 3341 ends: -1, 3342 gauge: false, 3343 precise: false, 3344 token: "it is a secret" 3345 }; 3346 let createOffCallback1 = (progress: request.agent.Progress) => { 3347 console.info('upload task failed.'); 3348 }; 3349 let createOffCallback2 = (progress: request.agent.Progress) => { 3350 console.info('upload task failed.'); 3351 }; 3352 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3353 task.on('failed', createOffCallback1); 3354 task.on('failed', createOffCallback2); 3355 //表示取消createOffCallback1的订阅 3356 task.off('failed', createOffCallback1); 3357 //表示取消订阅任务失败的所有回调 3358 task.off('failed'); 3359 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 3360 task.start(); 3361 }).catch((err: BusinessError) => { 3362 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 3363 }); 3364 ``` 3365 3366> **说明：** 3367> 3368> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 3369 3370### off('pause')<sup>11+</sup> 3371 3372off(event: 'pause', callback?: (progress: [Progress](#progress10)) => void): void 3373 3374取消订阅任务暂停事件。 3375 3376**系统能力**：SystemCapability.Request.FileTransferAgent 3377 3378**参数：** 3379 3380 | 参数名 | 类型 | 必填 | 说明 | 3381 | -------- | -------- | -------- | -------- | 3382 | event | string | 是 | 订阅的事件类型。<br>- 取值为'pause'，表示任务暂停。 | 3383 | callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 | 3384 3385**错误码：** 3386 3387以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 3388 3389 | 错误码ID | 错误信息 | 3390 | -------- | -------- | 3391 | 401 | Parameter error. Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 3392 3393**示例：** 3394 3395 ```ts 3396 import { BusinessError } from '@kit.BasicServicesKit'; 3397 3398 let attachments: Array<request.agent.FormItem> = [{ 3399 name: "taskOffTest", 3400 value: { 3401 filename: "taskOffTest.avi", 3402 mimeType: "application/octet-stream", 3403 path: "./taskOffTest.avi", 3404 } 3405 }]; 3406 let config: request.agent.Config = { 3407 action: request.agent.Action.UPLOAD, 3408 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 3409 title: 'taskOffTest', 3410 description: 'Sample code for event listening', 3411 mode: request.agent.Mode.FOREGROUND, 3412 overwrite: false, 3413 method: "PUT", 3414 data: attachments, 3415 saveas: "./", 3416 network: request.agent.Network.CELLULAR, 3417 metered: false, 3418 roaming: true, 3419 retry: true, 3420 redirect: true, 3421 index: 0, 3422 begins: 0, 3423 ends: -1, 3424 gauge: false, 3425 precise: false, 3426 token: "it is a secret" 3427 }; 3428 let createOffCallback1 = (progress: request.agent.Progress) => { 3429 console.info('upload task pause.'); 3430 }; 3431 let createOffCallback2 = (progress: request.agent.Progress) => { 3432 console.info('upload task pause.'); 3433 }; 3434 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3435 task.on('pause', createOffCallback1); 3436 task.on('pause', createOffCallback2); 3437 //表示取消createOffCallback1的订阅 3438 task.off('pause', createOffCallback1); 3439 //表示取消订阅任务暂停的所有回调 3440 task.off('pause'); 3441 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 3442 task.start(); 3443 }).catch((err: BusinessError) => { 3444 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 3445 }); 3446 ``` 3447 3448> **说明：** 3449> 3450> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 3451 3452### off('resume')<sup>11+</sup> 3453 3454off(event: 'resume', callback?: (progress: [Progress](#progress10)) => void): void 3455 3456取消订阅任务恢复事件。 3457 3458**系统能力**：SystemCapability.Request.FileTransferAgent 3459 3460**参数：** 3461 3462 | 参数名 | 类型 | 必填 | 说明 | 3463 | -------- | -------- | -------- | -------- | 3464 | event | string | 是 | 订阅的事件类型。<br>- 取值为'resume'，表示任务恢复。 | 3465 | callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 | 3466 3467**错误码：** 3468 3469以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 3470 3471 | 错误码ID | 错误信息 | 3472 | -------- | -------- | 3473 | 401 | Parameter error. Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 3474 3475**示例：** 3476 3477 ```ts 3478 import { BusinessError } from '@kit.BasicServicesKit'; 3479 3480 let attachments: Array<request.agent.FormItem> = [{ 3481 name: "taskOffTest", 3482 value: { 3483 filename: "taskOffTest.avi", 3484 mimeType: "application/octet-stream", 3485 path: "./taskOffTest.avi", 3486 } 3487 }]; 3488 let config: request.agent.Config = { 3489 action: request.agent.Action.UPLOAD, 3490 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 3491 title: 'taskOffTest', 3492 description: 'Sample code for event listening', 3493 mode: request.agent.Mode.FOREGROUND, 3494 overwrite: false, 3495 method: "PUT", 3496 data: attachments, 3497 saveas: "./", 3498 network: request.agent.Network.CELLULAR, 3499 metered: false, 3500 roaming: true, 3501 retry: true, 3502 redirect: true, 3503 index: 0, 3504 begins: 0, 3505 ends: -1, 3506 gauge: false, 3507 precise: false, 3508 token: "it is a secret" 3509 }; 3510 let createOffCallback1 = (progress: request.agent.Progress) => { 3511 console.info('upload task resume.'); 3512 }; 3513 let createOffCallback2 = (progress: request.agent.Progress) => { 3514 console.info('upload task resume.'); 3515 }; 3516 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3517 task.on('resume', createOffCallback1); 3518 task.on('resume', createOffCallback2); 3519 //表示取消createOffCallback1的订阅 3520 task.off('resume', createOffCallback1); 3521 //表示取消订阅任务恢复的所有回调 3522 task.off('resume'); 3523 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 3524 task.start(); 3525 }).catch((err: BusinessError) => { 3526 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 3527 }); 3528 ``` 3529 3530> **说明：** 3531> 3532> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 3533 3534### off('remove')<sup>11+</sup> 3535 3536off(event: 'remove', callback?: (progress: [Progress](#progress10)) => void): void 3537 3538取消订阅任务删除事件。 3539 3540**系统能力**：SystemCapability.Request.FileTransferAgent 3541 3542**参数：** 3543 3544 | 参数名 | 类型 | 必填 | 说明 | 3545 | -------- | -------- | -------- | -------- | 3546 | event | string | 是 | 订阅的事件类型。<br>- 取值为'remove'，表示任务删除。 | 3547 | callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 | 3548 3549**错误码：** 3550 3551以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 3552 3553 | 错误码ID | 错误信息 | 3554 | -------- | -------- | 3555 | 401 | Parameter error. Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 3556 3557**示例：** 3558 3559 ```ts 3560 import { BusinessError } from '@kit.BasicServicesKit'; 3561 3562 let attachments: Array<request.agent.FormItem> = [{ 3563 name: "taskOffTest", 3564 value: { 3565 filename: "taskOffTest.avi", 3566 mimeType: "application/octet-stream", 3567 path: "./taskOffTest.avi", 3568 } 3569 }]; 3570 let config: request.agent.Config = { 3571 action: request.agent.Action.UPLOAD, 3572 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 3573 title: 'taskOffTest', 3574 description: 'Sample code for event listening', 3575 mode: request.agent.Mode.FOREGROUND, 3576 overwrite: false, 3577 method: "PUT", 3578 data: attachments, 3579 saveas: "./", 3580 network: request.agent.Network.CELLULAR, 3581 metered: false, 3582 roaming: true, 3583 retry: true, 3584 redirect: true, 3585 index: 0, 3586 begins: 0, 3587 ends: -1, 3588 gauge: false, 3589 precise: false, 3590 token: "it is a secret" 3591 }; 3592 let createOffCallback1 = (progress: request.agent.Progress) => { 3593 console.info('upload task remove.'); 3594 }; 3595 let createOffCallback2 = (progress: request.agent.Progress) => { 3596 console.info('upload task remove.'); 3597 }; 3598 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3599 task.on('remove', createOffCallback1); 3600 task.on('remove', createOffCallback2); 3601 //表示取消createOffCallback1的订阅 3602 task.off('remove', createOffCallback1); 3603 //表示取消订阅任务移除的所有回调 3604 task.off('remove'); 3605 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 3606 task.start(); 3607 }).catch((err: BusinessError) => { 3608 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 3609 }); 3610 ``` 3611 3612> **说明：** 3613> 3614> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 3615 3616### off('response')<sup>12+</sup> 3617 3618off(event: 'response', callback?: Callback<HttpResponse>): void 3619 3620取消订阅任务响应头。 3621 3622**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3623 3624**系统能力**：SystemCapability.Request.FileTransferAgent 3625 3626**参数：** 3627 3628 | 参数名 | 类型 | 必填 | 说明 | 3629 | -------- | -------- | -------- | -------- | 3630 | event | string | 是 | 订阅的事件类型。<br>- 取值为'response'，表示任务响应。 | 3631 | callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 | 3632 3633**错误码：** 3634 3635以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 3636 3637 | 错误码ID | 错误信息 | 3638 | -------- | -------- | 3639 | 401 | Parameter error. Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 3640 3641**示例：** 3642 3643 ```ts 3644 import { BusinessError } from '@kit.BasicServicesKit'; 3645 3646 let attachments: Array<request.agent.FormItem> = [{ 3647 name: "taskOffTest", 3648 value: { 3649 filename: "taskOffTest.avi", 3650 mimeType: "application/octet-stream", 3651 path: "./taskOffTest.avi", 3652 } 3653 }]; 3654 let config: request.agent.Config = { 3655 action: request.agent.Action.UPLOAD, 3656 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 3657 title: 'taskOffTest', 3658 description: 'Sample code for event listening', 3659 mode: request.agent.Mode.FOREGROUND, 3660 overwrite: false, 3661 method: "PUT", 3662 data: attachments, 3663 saveas: "./", 3664 network: request.agent.Network.CELLULAR, 3665 metered: false, 3666 roaming: true, 3667 retry: true, 3668 redirect: true, 3669 index: 0, 3670 begins: 0, 3671 ends: -1, 3672 gauge: false, 3673 precise: false, 3674 token: "it is a secret" 3675 }; 3676 let createOffCallback1 = (progress: request.agent.HttpResponse) => { 3677 console.info('upload task response.'); 3678 }; 3679 let createOffCallback2 = (progress: request.agent.HttpResponse) => { 3680 console.info('upload task response.'); 3681 }; 3682 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3683 task.on('response', createOffCallback1); 3684 task.on('response', createOffCallback2); 3685 //表示取消createOffCallback1的订阅 3686 task.off('response', createOffCallback1); 3687 //表示取消订阅任务移除的所有回调 3688 task.off('response'); 3689 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 3690 task.start(); 3691 }).catch((err: BusinessError) => { 3692 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 3693 }); 3694 ``` 3695 3696> **说明：** 3697> 3698> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 3699 3700### start<sup>10+</sup> 3701 3702start(callback: AsyncCallback<void>): void 3703 3704以下状态的任务可以被启动： 37051. 刚被 request.agent.create 接口创建的任务 37062. 使用 request.agent.create 接口创建的已经失败或者停止的下载任务 3707 3708**需要权限**：ohos.permission.INTERNET 3709 3710**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3711 3712**系统能力**：SystemCapability.Request.FileTransferAgent 3713 3714**参数：** 3715 3716 | 参数名 | 类型 | 必填 | 说明 | 3717 | -------- | -------- | -------- | -------- | 3718 | callback | function | 是 | 回调函数。当开启任务成功，err为undefined，否则为错误对象。 | 3719 3720**错误码：** 3721 3722以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 3723 3724 | 错误码ID | 错误信息 | 3725 | -------- | -------- | 3726 | 201 | Permission denied. | 3727 | 13400003 | task service ability error. | 3728 | 21900007 | task state error. | 3729 3730**示例：** 3731 3732 ```ts 3733 import { BusinessError } from '@kit.BasicServicesKit'; 3734 3735 let config: request.agent.Config = { 3736 action: request.agent.Action.DOWNLOAD, 3737 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 3738 title: 'taskStartTest', 3739 description: 'Sample code for start the download task', 3740 mode: request.agent.Mode.BACKGROUND, 3741 overwrite: false, 3742 method: "GET", 3743 data: "", 3744 saveas: "./", 3745 network: request.agent.Network.CELLULAR, 3746 metered: false, 3747 roaming: true, 3748 retry: true, 3749 redirect: true, 3750 index: 0, 3751 begins: 0, 3752 ends: -1, 3753 gauge: false, 3754 precise: false, 3755 token: "it is a secret" 3756 }; 3757 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3758 task.start((err: BusinessError) => { 3759 if (err) { 3760 console.error(`Failed to start the download task, Code: ${err.code}, message: ${err.message}`); 3761 return; 3762 } 3763 console.info(`Succeeded in starting a download task.`); 3764 }); 3765 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 3766 }).catch((err: BusinessError) => { 3767 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 3768 }); 3769 ``` 3770 3771> **说明：** 3772> 3773> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 3774 3775### start<sup>10+</sup> 3776 3777start(): Promise<void> 3778 3779以下状态的任务可以被启动： 37801. 刚被request.agent.create 接口创建的任务 37812. 使用request.agent.create 接口创建的已经失败或者停止的下载任务 3782 3783**需要权限**：ohos.permission.INTERNET 3784 3785**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3786 3787**系统能力**：SystemCapability.Request.FileTransferAgent 3788 3789**返回值：** 3790 3791| 类型 | 说明 | 3792| ------------------- | ------------------------- | 3793| Promise<void> | Promise对象。无返回结果的Promise对象。 | 3794 3795**错误码：** 3796 3797以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 3798 3799 | 错误码ID | 错误信息 | 3800 | -------- | -------- | 3801 | 201 | Permission denied. | 3802 | 13400003 | task service ability error. | 3803 | 21900007 | task state error. | 3804 3805**示例：** 3806 3807 ```ts 3808 import { BusinessError } from '@kit.BasicServicesKit'; 3809 3810 let config: request.agent.Config = { 3811 action: request.agent.Action.DOWNLOAD, 3812 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 3813 title: 'taskStartTest', 3814 description: 'Sample code for start the download task', 3815 mode: request.agent.Mode.BACKGROUND, 3816 overwrite: false, 3817 method: "GET", 3818 data: "", 3819 saveas: "./", 3820 network: request.agent.Network.CELLULAR, 3821 metered: false, 3822 roaming: true, 3823 retry: true, 3824 redirect: true, 3825 index: 0, 3826 begins: 0, 3827 ends: -1, 3828 gauge: false, 3829 precise: false, 3830 token: "it is a secret" 3831 }; 3832 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3833 task.start().then(() => { 3834 console.info(`Succeeded in starting a download task.`); 3835 }).catch((err: BusinessError) => { 3836 console.error(`Failed to start the download task, Code: ${err.code}, message: ${err.message}`); 3837 }); 3838 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 3839 }).catch((err: BusinessError) => { 3840 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 3841 }); 3842 ``` 3843 3844> **说明：** 3845> 3846> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 3847 3848### pause<sup>10+</sup> 3849 3850pause(callback: AsyncCallback<void>): void 3851 3852暂停任务，可以暂停正在等待/正在运行/正在重试的任务。使用callback异步回调。 3853 3854**系统能力**：SystemCapability.Request.FileTransferAgent 3855 3856**参数：** 3857 3858 | 参数名 | 类型 | 必填 | 说明 | 3859 | -------- | -------- | -------- | -------- | 3860 | callback | function | 是 | 回调函数。当暂停任务成功，err为undefined，否则为错误对象。 | 3861 3862**错误码：** 3863 3864以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)。 3865 3866 | 错误码ID | 错误信息 | 3867 | -------- | -------- | 3868 | 13400003 | task service ability error. | 3869 | 21900007 | task state error. | 3870 3871**示例：** 3872 3873 ```ts 3874 import { BusinessError } from '@kit.BasicServicesKit'; 3875 3876 let config: request.agent.Config = { 3877 action: request.agent.Action.DOWNLOAD, 3878 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 3879 title: 'taskPauseTest', 3880 description: 'Sample code for pause the download task', 3881 mode: request.agent.Mode.BACKGROUND, 3882 overwrite: false, 3883 method: "GET", 3884 data: "", 3885 saveas: "./", 3886 network: request.agent.Network.CELLULAR, 3887 metered: false, 3888 roaming: true, 3889 retry: true, 3890 redirect: true, 3891 index: 0, 3892 begins: 0, 3893 ends: -1, 3894 gauge: false, 3895 precise: false, 3896 token: "it is a secret" 3897 }; 3898 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3899 task.start(); 3900 for(let t = Date.now(); Date.now() - t <= 1000;); // 等待1秒再执行下一步操作，以防异步乱序 3901 task.pause((err: BusinessError) => { 3902 if (err) { 3903 console.error(`Failed to pause the download task, Code: ${err.code}, message: ${err.message}`); 3904 return; 3905 } 3906 console.info(`Succeeded in pausing a download task. `); 3907 }); 3908 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 3909 }).catch((err: BusinessError) => { 3910 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 3911 }); 3912 ``` 3913 3914### pause<sup>10+</sup> 3915 3916pause(): Promise<void> 3917 3918暂停任务，可以暂停正在等待/正在运行/正在重试的任务。使用Promise异步回调。 3919 3920**系统能力**：SystemCapability.Request.FileTransferAgent 3921 3922**返回值：** 3923 3924| 类型 | 说明 | 3925| ------------------- | ------------------------- | 3926| Promise<void> | Promise对象。无返回结果的Promise对象。 | 3927 3928**错误码：** 3929 3930以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)。 3931 3932 | 错误码ID | 错误信息 | 3933 | -------- | -------- | 3934 | 13400003 | task service ability error. | 3935 | 21900007 | task state error. | 3936 3937**示例：** 3938 3939 ```ts 3940 import { BusinessError } from '@kit.BasicServicesKit'; 3941 3942 let config: request.agent.Config = { 3943 action: request.agent.Action.DOWNLOAD, 3944 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 3945 title: 'taskPauseTest', 3946 description: 'Sample code for pause the download task', 3947 mode: request.agent.Mode.BACKGROUND, 3948 overwrite: false, 3949 method: "GET", 3950 data: "", 3951 saveas: "./", 3952 network: request.agent.Network.CELLULAR, 3953 metered: false, 3954 roaming: true, 3955 retry: true, 3956 redirect: true, 3957 index: 0, 3958 begins: 0, 3959 ends: -1, 3960 gauge: false, 3961 precise: false, 3962 token: "it is a secret" 3963 }; 3964 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3965 task.start(); 3966 for(let t = Date.now(); Date.now() - t <= 1000;); // 等待1秒再执行下一步操作，以防异步乱序 3967 task.pause().then(() => { 3968 console.info(`Succeeded in pausing a download task. `); 3969 }).catch((err: BusinessError) => { 3970 console.error(`Failed to pause the download task, Code: ${err.code}, message: ${err.message}`); 3971 }); 3972 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 3973 }).catch((err: BusinessError) => { 3974 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 3975 }); 3976 ``` 3977 3978### resume<sup>10+</sup> 3979 3980resume(callback: AsyncCallback<void>): void 3981 3982重新启动任务，可以恢复暂停的任务。使用callback异步回调。 3983 3984**需要权限**：ohos.permission.INTERNET 3985 3986**系统能力**：SystemCapability.Request.FileTransferAgent 3987 3988**参数：** 3989 3990 | 参数名 | 类型 | 必填 | 说明 | 3991 | -------- | -------- | -------- | -------- | 3992 | callback | function | 是 | 回调函数。当重新启动任务成功，err为undefined，否则为错误对象。 | 3993 3994**错误码：** 3995 3996以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 3997 3998 | 错误码ID | 错误信息 | 3999 | -------- | -------- | 4000 | 201 | Permission denied. | 4001 | 13400003 | task service ability error. | 4002 | 21900007 | task state error. | 4003 4004**示例：** 4005 4006 ```ts 4007 import { BusinessError } from '@kit.BasicServicesKit'; 4008 4009 let config: request.agent.Config = { 4010 action: request.agent.Action.DOWNLOAD, 4011 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 4012 title: 'taskResumeTest', 4013 description: 'Sample code for resume the download task', 4014 mode: request.agent.Mode.BACKGROUND, 4015 overwrite: false, 4016 method: "GET", 4017 data: "", 4018 saveas: "./", 4019 network: request.agent.Network.CELLULAR, 4020 metered: false, 4021 roaming: true, 4022 retry: true, 4023 redirect: true, 4024 index: 0, 4025 begins: 0, 4026 ends: -1, 4027 gauge: false, 4028 precise: false, 4029 token: "it is a secret" 4030 }; 4031 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 4032 task.start(); 4033 for(let t = Date.now(); Date.now() - t <= 1000;); // 等待1秒再执行下一步操作，以防异步乱序 4034 task.pause(); 4035 for(let t = Date.now(); Date.now() - t <= 1000;); // 等待1秒再执行下一步操作，以防异步乱序 4036 task.resume((err: BusinessError) => { 4037 if (err) { 4038 console.error(`Failed to resume the download task, Code: ${err.code}, message: ${err.message}`); 4039 return; 4040 } 4041 console.info(`Succeeded in resuming a download task. `); 4042 }); 4043 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 4044 }).catch((err: BusinessError) => { 4045 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 4046 }); 4047 ``` 4048 4049### resume<sup>10+</sup> 4050 4051resume(): Promise<void> 4052 4053重新启动任务，可以恢复暂停的任务。使用Promise异步回调。 4054 4055**需要权限**：ohos.permission.INTERNET 4056 4057**系统能力**：SystemCapability.Request.FileTransferAgent 4058 4059**返回值：** 4060 4061| 类型 | 说明 | 4062| ------------------- | ------------------------- | 4063| Promise<void> | Promise对象。无返回结果的Promise对象。 | 4064 4065**错误码：** 4066 4067以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 4068 4069 | 错误码ID | 错误信息 | 4070 | -------- | -------- | 4071 | 201 | Permission denied. | 4072 | 13400003 | task service ability error. | 4073 | 21900007 | task state error. | 4074 4075**示例：** 4076 4077 ```ts 4078 import { BusinessError } from '@kit.BasicServicesKit'; 4079 4080 let config: request.agent.Config = { 4081 action: request.agent.Action.DOWNLOAD, 4082 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 4083 title: 'taskResumeTest', 4084 description: 'Sample code for resume the download task', 4085 mode: request.agent.Mode.BACKGROUND, 4086 overwrite: false, 4087 method: "GET", 4088 data: "", 4089 saveas: "./", 4090 network: request.agent.Network.CELLULAR, 4091 metered: false, 4092 roaming: true, 4093 retry: true, 4094 redirect: true, 4095 index: 0, 4096 begins: 0, 4097 ends: -1, 4098 gauge: false, 4099 precise: false, 4100 token: "it is a secret" 4101 }; 4102 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 4103 task.start(); 4104 for(let t = Date.now(); Date.now() - t <= 1000;); // 等待1秒再执行下一步操作，以防异步乱序 4105 task.pause(); 4106 for(let t = Date.now(); Date.now() - t <= 1000;); // 等待1秒再执行下一步操作，以防异步乱序 4107 task.resume().then(() => { 4108 console.info(`Succeeded in resuming a download task. `); 4109 }).catch((err: BusinessError) => { 4110 console.error(`Failed to resume the download task, Code: ${err.code}, message: ${err.message}`); 4111 }); 4112 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 4113 }).catch((err: BusinessError) => { 4114 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 4115 }); 4116 ``` 4117 4118### stop<sup>10+</sup> 4119 4120stop(callback: AsyncCallback<void>): void 4121 4122停止任务，可以停止正在运行/正在等待/正在重试的任务。使用callback异步回调。 4123 4124**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4125 4126**系统能力**：SystemCapability.Request.FileTransferAgent 4127 4128**参数：** 4129 4130 | 参数名 | 类型 | 必填 | 说明 | 4131 | -------- | -------- | -------- | -------- | 4132 | callback | function | 是 | 回调函数。当停止任务成功，err为undefined，否则为错误对象。 | 4133 4134**错误码：** 4135 4136以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)。 4137 4138 | 错误码ID | 错误信息 | 4139 | -------- | -------- | 4140 | 13400003 | task service ability error. | 4141 | 21900007 | task state error. | 4142 4143**示例：** 4144 4145 ```ts 4146 import { BusinessError } from '@kit.BasicServicesKit'; 4147 4148 let config: request.agent.Config = { 4149 action: request.agent.Action.DOWNLOAD, 4150 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 4151 title: 'taskStopTest', 4152 description: 'Sample code for stop the download task', 4153 mode: request.agent.Mode.BACKGROUND, 4154 overwrite: false, 4155 method: "GET", 4156 data: "", 4157 saveas: "./", 4158 network: request.agent.Network.CELLULAR, 4159 metered: false, 4160 roaming: true, 4161 retry: true, 4162 redirect: true, 4163 index: 0, 4164 begins: 0, 4165 ends: -1, 4166 gauge: false, 4167 precise: false, 4168 token: "it is a secret" 4169 }; 4170 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 4171 task.start(); 4172 for(let t = Date.now(); Date.now() - t <= 1000;); // 等待1秒再执行下一步操作，以防异步乱序 4173 task.stop((err: BusinessError) => { 4174 if (err) { 4175 console.error(`Failed to stop the download task, Code: ${err.code}, message: ${err.message}`); 4176 return; 4177 } 4178 console.info(`Succeeded in stopping a download task. `); 4179 }); 4180 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 4181 }).catch((err: BusinessError) => { 4182 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 4183 }); 4184 ``` 4185 4186 4187### stop<sup>10+</sup> 4188 4189stop(): Promise<void> 4190 4191停止任务，可以停止正在运行/正在等待/正在重试的任务。使用Promise异步回调。 4192 4193**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4194 4195**系统能力**：SystemCapability.Request.FileTransferAgent 4196 4197**返回值：** 4198 4199| 类型 | 说明 | 4200| ------------------- | ------------------------- | 4201| Promise<void> | Promise对象。无返回结果的Promise对象。 | 4202 4203**错误码：** 4204 4205以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)。 4206 4207 | 错误码ID | 错误信息 | 4208 | -------- | -------- | 4209 | 13400003 | task service ability error. | 4210 | 21900007 | task state error. | 4211 4212**示例：** 4213 4214 ```ts 4215 import { BusinessError } from '@kit.BasicServicesKit'; 4216 4217 let config: request.agent.Config = { 4218 action: request.agent.Action.DOWNLOAD, 4219 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 4220 title: 'taskStopTest', 4221 description: 'Sample code for stop the download task', 4222 mode: request.agent.Mode.BACKGROUND, 4223 overwrite: false, 4224 method: "GET", 4225 data: "", 4226 saveas: "./", 4227 network: request.agent.Network.CELLULAR, 4228 metered: false, 4229 roaming: true, 4230 retry: true, 4231 redirect: true, 4232 index: 0, 4233 begins: 0, 4234 ends: -1, 4235 gauge: false, 4236 precise: false, 4237 token: "it is a secret" 4238 }; 4239 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 4240 task.start(); 4241 for(let t = Date.now(); Date.now() - t <= 1000;); // 等待1秒再执行下一步操作，以防异步乱序 4242 task.stop().then(() => { 4243 console.info(`Succeeded in stopping a download task. `); 4244 }).catch((err: BusinessError) => { 4245 console.error(`Failed to stop the download task, Code: ${err.code}, message: ${err.message}`); 4246 }); 4247 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 4248 }).catch((err: BusinessError) => { 4249 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 4250 }); 4251 ``` 4252 4253## request.agent.create<sup>10+</sup> 4254 4255create(context: BaseContext, config: Config, callback: AsyncCallback<Task>): void 4256 4257创建要上传或下载的任务，并将其排入队列。支持HTTP协议，使用callback异步回调。 4258 4259 4260**需要权限**：ohos.permission.INTERNET 4261 4262**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4263 4264**系统能力**：SystemCapability.Request.FileTransferAgent 4265 4266**参数：** 4267 4268 | 参数名 | 类型 | 必填 | 说明 | 4269 | -------- | -------- | -------- | -------- | 4270 | config | [Config](#config10) | 是 | 上传/下载任务的配置信息。 | 4271 | context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 4272 | callback | AsyncCallback<[Task](#task10)> | 是 | 回调函数。当创建上传或下载任务成功，err为undefined，data为获取到的Task对象；否则为错误对象。 | 4273 4274**错误码：** 4275 4276以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 4277 4278 | 错误码ID | 错误信息 | 4279 | -------- | -------- | 4280 | 201 | permission denied. | 4281 | 401 | parameter error. Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 4282 | 13400001 | file operation error. | 4283 | 13400003 | task service ability error. | 4284 | 21900004 | the application task queue is full. | 4285 | 21900005 | task mode error. | 4286 4287**示例：** 4288 4289 ```ts 4290 import { BusinessError } from '@kit.BasicServicesKit'; 4291 4292 let attachments: Array<request.agent.FormItem> = [{ 4293 name: "createTest", 4294 value: { 4295 filename: "createTest.avi", 4296 mimeType: "application/octet-stream", 4297 path: "./createTest.avi", 4298 } 4299 }]; 4300 let config: request.agent.Config = { 4301 action: request.agent.Action.UPLOAD, 4302 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 4303 title: 'createTest', 4304 description: 'Sample code for create task', 4305 mode: request.agent.Mode.BACKGROUND, 4306 overwrite: false, 4307 method: "PUT", 4308 data: attachments, 4309 saveas: "./", 4310 network: request.agent.Network.CELLULAR, 4311 metered: false, 4312 roaming: true, 4313 retry: true, 4314 redirect: true, 4315 index: 0, 4316 begins: 0, 4317 ends: -1, 4318 gauge: false, 4319 precise: false, 4320 token: "it is a secret" 4321 }; 4322 request.agent.create(getContext(), config, async (err: BusinessError, task: request.agent.Task) => { 4323 if (err) { 4324 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 4325 return; 4326 } 4327 console.info(`Succeeded in creating a download task. result: ${task.config}`); 4328 await task.start(); 4329 //用户需要手动调用remove从而结束task对象的生命周期 4330 request.agent.remove(task.tid); 4331 }); 4332 ``` 4333 4334> **说明：** 4335> 4336> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 4337 4338## request.agent.create<sup>10+</sup> 4339 4340create(context: BaseContext, config: Config): Promise<Task> 4341 4342创建要上传或下载的任务，并将其排入队列。支持HTTP协议，使用Promise异步回调。 4343 4344 4345**需要权限**：ohos.permission.INTERNET 4346 4347**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4348 4349**系统能力**：SystemCapability.Request.FileTransferAgent 4350 4351**参数：** 4352 4353 | 参数名 | 类型 | 必填 | 说明 | 4354 | -------- | -------- | -------- | -------- | 4355 | context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 4356 | config | [Config](#config10) | 是 | 上传/下载任务的配置信息。 | 4357 4358**返回值：** 4359 4360| 类型 | 说明 | 4361| ------------------- | ------------------------- | 4362| Promise<[Task](#task10)> | Promise对象。返回任务配置信息的Promise对象。 | 4363 4364**错误码：** 4365 4366以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 4367 4368 | 错误码ID | 错误信息 | 4369 | -------- | -------- | 4370 | 201 | permission denied. | 4371 | 401 | parameter error. Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 4372 | 13400001 | file operation error. | 4373 | 13400003 | task service ability error. | 4374 | 21900004 | the application task queue is full. | 4375 | 21900005 | task mode error. | 4376 4377**示例：** 4378 4379 ```ts 4380 import { BusinessError } from '@kit.BasicServicesKit'; 4381 4382 let attachments: Array<request.agent.FormItem> = [{ 4383 name: "createTest", 4384 value: { 4385 filename: "createTest.avi", 4386 mimeType: "application/octet-stream", 4387 path: "./createTest.avi", 4388 } 4389 }]; 4390 let config: request.agent.Config = { 4391 action: request.agent.Action.UPLOAD, 4392 url: 'http://127.0.0.1', // 需要手动将 url 替换为真实服务器的 HTTP 协议地址 4393 title: 'createTest', 4394 description: 'Sample code for create task', 4395 mode: request.agent.Mode.BACKGROUND, 4396 overwrite: false, 4397 method: "PUT", 4398 data: attachments, 4399 saveas: "./", 4400 network: request.agent.Network.CELLULAR, 4401 metered: false, 4402 roaming: true, 4403 retry: true, 4404 redirect: true, 4405 index: 0, 4406 begins: 0, 4407 ends: -1, 4408 gauge: false, 4409 precise: false, 4410 token: "it is a secret" 4411 }; 4412 request.agent.create(getContext(), config).then(async (task: request.agent.Task) => { 4413 console.info(`Succeeded in creating a download task. result: ${task.config}`); 4414 await task.start(); 4415 //用户需要手动调用remove从而结束task对象的生命周期 4416 request.agent.remove(task.tid); 4417 }).catch((err: BusinessError) => { 4418 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 4419 }); 4420 ``` 4421 4422> **说明：** 4423> 4424> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 4425 4426## request.agent.getTask<sup>11+</sup> 4427 4428getTask(context: BaseContext, id: string, token?: string): Promise<Task> 4429 4430根据任务id查询任务。使用Promise异步回调。 4431 4432**系统能力**：SystemCapability.Request.FileTransferAgent 4433 4434**参数：** 4435 4436 | 参数名 | 类型 | 必填 | 说明 | 4437 | -------- | -------- | -------- | -------- | 4438 | context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 4439 | id | string | 是 | 任务id。 | 4440 | token | string | 否 | 任务查询token。 | 4441 4442**返回值：** 4443 4444| 类型 | 说明 | 4445| ------------------- | ------------------------- | 4446| Promise<[Task](#task10)> | Promise对象。返回任务配置信息的Promise对象。 | 4447 4448**错误码：** 4449 4450以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 4451 4452 | 错误码ID | 错误信息 | 4453 | -------- | -------- | 4454 | 401 | parameter error. Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 4455 | 13400003 | task service ability error. | 4456 | 21900006 | task not found. | 4457 4458**示例：** 4459 4460 ```ts 4461 import { BusinessError } from '@kit.BasicServicesKit'; 4462 4463 request.agent.getTask(getContext(), "123456").then((task: request.agent.Task) => { 4464 console.info(`Succeeded in querying a task. result: ${task.tid}`); 4465 }).catch((err: BusinessError) => { 4466 console.error(`Failed to query a task, Code: ${err.code}, message: ${err.message}`); 4467 }); 4468 ``` 4469 4470## request.agent.remove<sup>10+</sup> 4471 4472remove(id: string, callback: AsyncCallback<void>): void 4473 4474移除属于调用方的指定任务，如果正在处理中，该任务将被迫停止。使用callback异步回调。在调用后任务对象和其回调函数会被释放。 4475 4476**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4477 4478**系统能力**：SystemCapability.Request.FileTransferAgent 4479 4480**参数：** 4481 4482 | 参数名 | 类型 | 必填 | 说明 | 4483 | -------- | -------- | -------- | -------- | 4484 | id | string | 是 | 任务id。 | 4485 | callback | AsyncCallback<void> | 是 | 回调函数。当删除指定任务成功，err为undefined，否则为错误对象。 | 4486 4487**错误码：** 4488 4489以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 4490 4491 | 错误码ID | 错误信息 | 4492 | -------- | -------- | 4493 | 401 | parameter error. Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type | 4494 | 13400003 | task service ability error. | 4495 | 21900006 | task not found. | 4496 4497**示例：** 4498 4499 ```ts 4500 import { BusinessError } from '@kit.BasicServicesKit'; 4501 4502 request.agent.remove("123456", (err: BusinessError) => { 4503 if (err) { 4504 console.error(`Failed to removing a download task, Code: ${err.code}, message: ${err.message}`); 4505 return; 4506 } 4507 console.info(`Succeeded in creating a download task.`); 4508 }); 4509 ``` 4510 4511 4512## request.agent.remove<sup>10+</sup> 4513 4514remove(id: string): Promise<void> 4515 4516移除属于调用方的指定任务，如果正在处理中，该任务将被迫停止。使用Promise异步回调。在调用后任务对象和其回调函数会被释放。 4517 4518**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4519 4520**系统能力**：SystemCapability.Request.FileTransferAgent 4521 4522**参数：** 4523 4524 | 参数名 | 类型 | 必填 | 说明 | 4525 | -------- | -------- | -------- | -------- | 4526 | id | string | 是 | 任务id。 | 4527 4528**返回值：** 4529 4530| 类型 | 说明 | 4531| ------------------- | ------------------------- | 4532| Promise<void> | Promise对象。无返回结果的Promise对象。 | 4533 4534**错误码：** 4535 4536以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 4537 4538 | 错误码ID | 错误信息 | 4539 | -------- | -------- | 4540 | 401 | parameter error. Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type | 4541 | 13400003 | task service ability error. | 4542 | 21900006 | task not found. | 4543 4544**示例：** 4545 4546 ```ts 4547 import { BusinessError } from '@kit.BasicServicesKit'; 4548 4549 request.agent.remove("123456").then(() => { 4550 console.info(`Succeeded in removing a download task. `); 4551 }).catch((err: BusinessError) => { 4552 console.error(`Failed to remove a download task, Code: ${err.code}, message: ${err.message}`); 4553 }); 4554 ``` 4555 4556 4557## request.agent.show<sup>10+</sup> 4558 4559show(id: string, callback: AsyncCallback<TaskInfo>): void 4560 4561根据任务id查询任务的详细信息。使用callback异步回调。 4562 4563**系统能力**：SystemCapability.Request.FileTransferAgent 4564 4565**参数：** 4566 4567 | 参数名 | 类型 | 必填 | 说明 | 4568 | -------- | -------- | -------- | -------- | 4569 | id | string | 是 | 任务id。 | 4570 | callback | AsyncCallback<[TaskInfo](#taskinfo10)> | 是 | 回调函数。当查询任务操作成功，err为undefined，data为查询到的任务TaskInfo信息；否则为错误对象。 | 4571 4572**错误码：** 4573以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 4574 4575 | 错误码ID | 错误信息 | 4576 | -------- | -------- | 4577 | 401 | parameter error. Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type | 4578 | 13400003 | task service ability error. | 4579 | 21900006 | task not found. | 4580 4581**示例：** 4582 4583 ```ts 4584 import { BusinessError } from '@kit.BasicServicesKit'; 4585 4586 request.agent.show("123456", (err: BusinessError, taskInfo: request.agent.TaskInfo) => { 4587 if (err) { 4588 console.error(`Failed to show a upload task, Code: ${err.code}, message: ${err.message}`); 4589 return; 4590 } 4591 console.info(`Succeeded in showing a upload task.`); 4592 }); 4593 ``` 4594 4595 4596## request.agent.show<sup>10+</sup> 4597 4598show(id: string): Promise<TaskInfo> 4599 4600根据任务id查询任务的详细信息。使用Promise异步回调。 4601 4602**系统能力**：SystemCapability.Request.FileTransferAgent 4603 4604**参数：** 4605 4606 | 参数名 | 类型 | 必填 | 说明 | 4607 | -------- | -------- | -------- | -------- | 4608 | id | string | 是 | 任务id。 | 4609 4610**返回值：** 4611 4612| 类型 | 说明 | 4613| ------------------- | ------------------------- | 4614| Promise<[TaskInfo](#taskinfo10)> | Promise对象。返回任务详细信息TaskInfo的Promise对象。 | 4615 4616**错误码：** 4617以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 4618 4619 | 错误码ID | 错误信息 | 4620 | -------- | -------- | 4621 | 401 | parameter error. Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type | 4622 | 13400003 | task service ability error. | 4623 | 21900006 | task not found. | 4624 4625**示例：** 4626 4627 ```ts 4628 import { BusinessError } from '@kit.BasicServicesKit'; 4629 4630 request.agent.show("123456").then((taskInfo: request.agent.TaskInfo) => { 4631 console.info(`Succeeded in showing a upload task.`); 4632 }).catch((err: BusinessError) => { 4633 console.error(`Failed to show a upload task, Code: ${err.code}, message: ${err.message}`); 4634 }); 4635 ``` 4636 4637 4638## request.agent.touch<sup>10+</sup> 4639 4640touch(id: string, token: string, callback: AsyncCallback<TaskInfo>): void 4641 4642根据任务id和token查询任务的详细信息。使用callback异步回调。 4643 4644**系统能力**：SystemCapability.Request.FileTransferAgent 4645 4646**参数：** 4647 4648 | 参数名 | 类型 | 必填 | 说明 | 4649 | -------- | -------- | -------- | -------- | 4650 | id | string | 是 | 任务id。 | 4651 | token | string | 是 | 任务查询token。 | 4652 | callback | AsyncCallback<[TaskInfo](#taskinfo10)> | 是 | 回调函数。当查询任务操作成功，err为undefined，data为查询到的任务TaskInfo信息；否则为错误对象。 | 4653 4654**错误码：** 4655以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 4656 4657 | 错误码ID | 错误信息 | 4658 | -------- | -------- | 4659 | 401 | parameter error. Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 4660 | 13400003 | task service ability error. | 4661 | 21900006 | task not found. | 4662 4663**示例：** 4664 4665 ```ts 4666 import { BusinessError } from '@kit.BasicServicesKit'; 4667 4668 request.agent.touch("123456", "token", (err: BusinessError, taskInfo: request.agent.TaskInfo) => { 4669 if (err) { 4670 console.error(`Failed to touch a upload task, Code: ${err.code}, message: ${err.message}`); 4671 return; 4672 } 4673 console.info(`Succeeded in touching a upload task.`); 4674 }); 4675 ``` 4676 4677 4678## request.agent.touch<sup>10+</sup> 4679 4680touch(id: string, token: string): Promise<TaskInfo> 4681 4682根据任务id和token查询任务的详细信息。使用Promise异步回调。 4683 4684**系统能力**：SystemCapability.Request.FileTransferAgent 4685 4686**参数：** 4687 4688 | 参数名 | 类型 | 必填 | 说明 | 4689 | -------- | -------- | -------- | -------- | 4690 | id | string | 是 | 任务id。 | 4691 | token | string | 是 | 任务查询token。 | 4692 4693**返回值：** 4694 4695| 类型 | 说明 | 4696| ------------------- | ------------------------- | 4697| Promise<[TaskInfo](#taskinfo10)> | Promise对象。返回任务详细信息TaskInfo的Promise对象。 | 4698 4699**错误码：** 4700以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 4701 4702 | 错误码ID | 错误信息 | 4703 | -------- | -------- | 4704 | 401 | parameter error. Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed | 4705 | 13400003 | task service ability error. | 4706 | 21900006 | task not found. | 4707 4708**示例：** 4709 4710 ```ts 4711 import { BusinessError } from '@kit.BasicServicesKit'; 4712 4713 request.agent.touch("123456", "token").then((taskInfo: request.agent.TaskInfo) => { 4714 console.info(`Succeeded in touching a upload task. `); 4715 }).catch((err: BusinessError) => { 4716 console.error(`Failed to touch a upload task, Code: ${err.code}, message: ${err.message}`); 4717 }); 4718 ``` 4719 4720## request.agent.search<sup>10+</sup> 4721 4722search(callback: AsyncCallback<Array<string>>): void 4723 4724根据默认[Filter](#filter10)过滤条件查找任务id。使用callback异步回调。 4725 4726**系统能力**：SystemCapability.Request.FileTransferAgent 4727 4728**参数：** 4729 4730 | 参数名 | 类型 | 必填 | 说明 | 4731 | -------- | -------- | -------- | -------- | 4732 | callback | AsyncCallback<Array<string>> | 是 | 回调函数。当根据过滤条件查找任务成功，err为undefined，data为满足条件的任务id；否则为错误对象。 | 4733 4734**错误码：** 4735以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 4736 4737 | 错误码ID | 错误信息 | 4738 | -------- | -------- | 4739 | 401 | parameter error. Possible causes: 1. Incorrect parameter type 2. Parameter verification failed | 4740 | 13400003 | task service ability error. | 4741 4742**示例：** 4743 4744 ```ts 4745 import { BusinessError } from '@kit.BasicServicesKit'; 4746 4747 request.agent.search((err: BusinessError, data: Array<string>) => { 4748 if (err) { 4749 console.error(`Failed to search a upload task, Code: ${err.code}, message: ${err.message}`); 4750 return; 4751 } 4752 console.info(`Succeeded in searching a upload task. `); 4753 }); 4754 ``` 4755 4756## request.agent.search<sup>10+</sup> 4757 4758search(filter: Filter, callback: AsyncCallback<Array<string>>): void 4759 4760根据[Filter](#filter10)过滤条件查找任务id。使用callback异步回调。 4761 4762**系统能力**：SystemCapability.Request.FileTransferAgent 4763 4764**参数：** 4765 4766 | 参数名 | 类型 | 必填 | 说明 | 4767 | -------- | -------- | -------- | -------- | 4768 | filter | [Filter](#filter10) | 是 | 过滤条件。 | 4769 | callback | AsyncCallback<Array<string>> | 是 | 回调函数。当根据过滤条件查找任务成功，err为undefined，data为满足条件的任务id；否则为错误对象。 | 4770 4771**错误码：** 4772以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 4773 4774 | 错误码ID | 错误信息 | 4775 | -------- | -------- | 4776 | 401 | parameter error. Possible causes: 1. Incorrect parameter type 2. Parameter verification failed | 4777 | 13400003 | task service ability error. | 4778 4779**示例：** 4780 4781 ```ts 4782 import { BusinessError } from '@kit.BasicServicesKit'; 4783 4784 let filter: request.agent.Filter = { 4785 action: request.agent.Action.UPLOAD, 4786 mode: request.agent.Mode.BACKGROUND 4787 } 4788 request.agent.search(filter, (err: BusinessError, data: Array<string>) => { 4789 if (err) { 4790 console.error(`Failed to search a upload task, Code: ${err.code}, message: ${err.message}`); 4791 return; 4792 } 4793 console.info(`Succeeded in searching a upload task. `); 4794 }); 4795 ``` 4796 4797 4798## request.agent.search<sup>10+</sup> 4799 4800search(filter?: Filter): Promise<Array<string>> 4801 4802根据[Filter](#filter10)过滤条件查找任务id。使用Promise异步回调。 4803 4804**系统能力**：SystemCapability.Request.FileTransferAgent 4805 4806**参数：** 4807 4808 | 参数名 | 类型 | 必填 | 说明 | 4809 | -------- | -------- | -------- | -------- | 4810 | filter | [Filter](#filter10) | 否 | 过滤条件。 | 4811 4812**返回值：** 4813 4814| 类型 | 说明 | 4815| ------------------- | ------------------------- | 4816| Promise<Array<string>> | Promise对象。返回满足条件任务id的Promise对象。 | 4817 4818**错误码：** 4819以下错误码的详细介绍请参见[上传下载错误码](errorcode-request.md)与[通用错误码说明文档](../errorcode-universal.md)。 4820 4821 | 错误码ID | 错误信息 | 4822 | -------- | -------- | 4823 | 401 | parameter error. Possible causes: 1. Incorrect parameter type 2. Parameter verification failed | 4824 | 13400003 | task service ability error. | 4825 4826**示例：** 4827 4828 ```ts 4829 import { BusinessError } from '@kit.BasicServicesKit'; 4830 4831 let filter: request.agent.Filter = { 4832 action: request.agent.Action.UPLOAD, 4833 mode: request.agent.Mode.BACKGROUND 4834 } 4835 request.agent.search(filter).then((data: Array<string>) => { 4836 console.info(`Succeeded in searching a upload task. `); 4837 }).catch((err: BusinessError) => { 4838 console.error(`Failed to search a upload task, Code: ${err.code}, message: ${err.message}`); 4839 }); 4840 ``` 4841 4842 4843 4844
