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