1# @ohos.request (Upload and Download) 2 3The **request** module provides applications with basic upload, download, and background transmission agent capabilities. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9 10## Modules to Import 11 12 13```js 14import request from '@ohos.request'; 15``` 16 17## Constants 18 19**Required permissions**: ohos.permission.INTERNET 20 21**System capability**: SystemCapability.MiscServices.Download 22 23### Network Types 24You can set **networkType** in [DownloadConfig](#downloadconfig) to specify the network type for the download service. 25 26| Name| Type| Value| Description| 27| -------- | -------- | -------- | -------- | 28| NETWORK_MOBILE | number | 0x00000001 | Whether download is allowed on a mobile network.| 29| NETWORK_WIFI | number | 0x00010000 | Whether download is allowed on a WLAN.| 30 31### Download Error Codes 32The table below lists the values of **err** in the callback of [on('fail')<sup>7+</sup>](#onfail7) and the values of **failedReason** returned by [getTaskInfo<sup>9+</sup>](#gettaskinfo9). 33 34| Name| Type| Value| Description| 35| -------- | -------- | -------- | -------- | 36| ERROR_CANNOT_RESUME<sup>7+</sup> | number | 0 | Failure to resume the download due to network errors.| 37| ERROR_DEVICE_NOT_FOUND<sup>7+</sup> | number | 1 | Failure to find a storage device such as a memory card.| 38| ERROR_FILE_ALREADY_EXISTS<sup>7+</sup> | number | 2 | Failure to download the file because it already exists.| 39| ERROR_FILE_ERROR<sup>7+</sup> | number | 3 | File operation failure.| 40| ERROR_HTTP_DATA_ERROR<sup>7+</sup> | number | 4 | HTTP transmission failure.| 41| ERROR_INSUFFICIENT_SPACE<sup>7+</sup> | number | 5 | Insufficient storage space.| 42| ERROR_TOO_MANY_REDIRECTS<sup>7+</sup> | number | 6 | Error caused by too many network redirections.| 43| ERROR_UNHANDLED_HTTP_CODE<sup>7+</sup> | number | 7 | Unidentified HTTP code.| 44| ERROR_UNKNOWN<sup>7+</sup> | number | 8 | Unknown error.| 45| ERROR_OFFLINE<sup>9+</sup> | number | 9 | No network connection.| 46| ERROR_UNSUPPORTED_NETWORK_TYPE<sup>9+</sup> | number | 10 | Network type mismatch.| 47 48 49### Causes of Download Pause 50The table below lists the values of **pausedReason** returned by [getTaskInfo<sup>9+</sup>](#gettaskinfo9). 51 52| Name| Type| Value| Description| 53| -------- | -------- | -------- | -------- | 54| PAUSED_QUEUED_FOR_WIFI<sup>7+</sup> | number | 0 | Download paused and queuing for a WLAN connection, because the file size exceeds the maximum value allowed by a mobile network session.| 55| PAUSED_WAITING_FOR_NETWORK<sup>7+</sup> | number | 1 | Download paused due to a network connection problem, for example, network disconnection.| 56| PAUSED_WAITING_TO_RETRY<sup>7+</sup> | number | 2 | Download paused and then retried.| 57| PAUSED_BY_USER<sup>9+</sup> | number | 3 | The user paused the session.| 58| PAUSED_UNKNOWN<sup>7+</sup> | number | 4 | Download paused due to unknown reasons.| 59 60### Download Task Status Codes 61The table below lists the values of **status** returned by [getTaskInfo<sup>9+</sup>](#gettaskinfo9). 62 63| Name| Type| Value| Description| 64| -------- | -------- | -------- | -------- | 65| SESSION_SUCCESSFUL<sup>7+</sup> | number | 0 | Successful download.| 66| SESSION_RUNNING<sup>7+</sup> | number | 1 | Download in progress.| 67| SESSION_PENDING<sup>7+</sup> | number | 2 | Download pending.| 68| SESSION_PAUSED<sup>7+</sup> | number | 3 | Download paused.| 69| SESSION_FAILED<sup>7+</sup> | number | 4 | Download failure without retry.| 70 71 72## request.uploadFile<sup>9+</sup> 73 74uploadFile(context: BaseContext, config: UploadConfig): Promise<UploadTask> 75 76Uploads files. This API uses a promise to return the result. You can use [on('complete'|'fail')<sup>9+</sup>](#oncomplete--fail9) to obtain the upload error information. 77 78**Required permissions**: ohos.permission.INTERNET 79 80**System capability**: SystemCapability.MiscServices.Upload 81 82**Parameters** 83 84 | Name| Type| Mandatory| Description| 85 | -------- | -------- | -------- | -------- | 86 | context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes| Application-based context.| 87 | config | [UploadConfig](#uploadconfig6) | Yes| Upload configurations.| 88 89 90**Return value** 91 92 | Type| Description| 93 | -------- | -------- | 94 | Promise<[UploadTask](#uploadtask)> | Promise used to return the upload task.| 95 96**Error codes** 97 98For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 99 100 | ID| Error Message| 101 | -------- | -------- | 102 | 13400002 | bad file path. | 103 104**Example** 105 106 ```ts 107 let uploadTask: request.UploadTask; 108 let uploadConfig: request.UploadConfig = { 109 url: 'http://www.example.com', // Replace the example with the actual server address. 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> **NOTE** 127> 128> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 129 130 131## request.uploadFile<sup>9+</sup> 132 133uploadFile(context: BaseContext, config: UploadConfig, callback: AsyncCallback<UploadTask>): void 134 135Uploads files. This API uses an asynchronous callback to return the result. You can use [on('complete'|'fail')<sup>9+</sup>](#oncomplete--fail9) to obtain the upload error information. 136 137**Required permissions**: ohos.permission.INTERNET 138 139**System capability**: SystemCapability.MiscServices.Upload 140 141**Parameters** 142 143 | Name| Type| Mandatory| Description| 144 | -------- | -------- | -------- | -------- | 145 | context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes| Application-based context.| 146 | config | [UploadConfig](#uploadconfig6) | Yes| Upload configurations.| 147 | callback | AsyncCallback<[UploadTask](#uploadtask)> | Yes| Callback used to return the **UploadTask** object.| 148 149**Error codes** 150 151For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 152 153 | ID| Error Message| 154 | -------- | -------- | 155 | 13400002 | bad file path. | 156 157**Example** 158 159 ```ts 160 let uploadTask: request.UploadTask; 161 let uploadConfig: request.UploadConfig = { 162 url: 'http://www.example.com', // Replace the example with the actual server address. 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> **NOTE** 182> 183> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 184 185## request.upload<sup>(deprecated)</sup> 186 187upload(config: UploadConfig): Promise<UploadTask> 188 189Uploads files. This API uses a promise to return the result. 190 191**Model restriction**: This API can be used only in the FA model. 192 193> **NOTE** 194> 195> This API is deprecated since API version 9. You are advised to use [request.uploadFile<sup>9+</sup>](#requestuploadfile9) instead. 196 197**Required permissions**: ohos.permission.INTERNET 198 199**System capability**: SystemCapability.MiscServices.Upload 200 201**Parameters** 202 203 | Name| Type| Mandatory| Description| 204 | -------- | -------- | -------- | -------- | 205 | config | [UploadConfig](#uploadconfig6) | Yes| Upload configurations.| 206 207**Return value** 208 209 | Type| Description| 210 | -------- | -------- | 211 | Promise<[UploadTask](#uploadtask)> | Promise used to return the upload task.| 212 213**Example** 214 215 ```js 216 let uploadTask; 217 let uploadConfig = { 218 url: 'http://www.example.com', // Replace the example with the actual server address. 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 236Uploads files. This API uses an asynchronous callback to return the result. 237 238**Model restriction**: This API can be used only in the FA model. 239 240> **NOTE** 241> 242> This API is deprecated since API version 9. You are advised to use [request.uploadFile<sup>9+</sup>](#requestuploadfile9-1) instead. 243 244**Required permissions**: ohos.permission.INTERNET 245 246**System capability**: SystemCapability.MiscServices.Upload 247 248**Parameters** 249 250 | Name| Type| Mandatory| Description| 251 | -------- | -------- | -------- | -------- | 252 | config | [UploadConfig](#uploadconfig6) | Yes| Upload configurations.| 253 | callback | AsyncCallback<[UploadTask](#uploadtask)> | Yes| Callback used to return the **UploadTask** object.| 254 255**Example** 256 257 ```js 258 let uploadTask; 259 let uploadConfig = { 260 url: 'http://www.example.com', // Replace the example with the actual server address. 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 277Implements file uploads. Before using any APIs of this class, you must obtain an **UploadTask** object through [request.uploadFile<sup>9+</sup>](#requestuploadfile9) in promise mode or [request.uploadFile<sup>9+</sup>](#requestuploadfile9-1) in callback mode. 278 279 280 281### on('progress') 282 283on(type: 'progress', callback:(uploadedSize: number, totalSize: number) => void): void 284 285Subscribes to upload progress events. This API uses a callback to return the result asynchronously. 286 287> **NOTE** 288> 289> To maintain a balance between power consumption and performance, this API cannot be called when the application is running in the background. 290 291**Required permissions**: ohos.permission.INTERNET 292 293**System capability**: SystemCapability.MiscServices.Upload 294 295**Parameters** 296 297 | Name| Type| Mandatory| Description| 298 | -------- | -------- | -------- | -------- | 299 | type | string | Yes| Type of the event to subscribe to. The value is **'progress'** (upload progress).| 300 | callback | function | Yes| Callback for the upload progress event.| 301 302 Parameters of the callback function 303 304| Name| Type| Mandatory| Description| 305| -------- | -------- | -------- | -------- | 306| uploadedSize | number | Yes| Size of the uploaded files, in bytes.| 307| totalSize | number | Yes| Total size of the files to upload, in bytes.| 308 309**Example** 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 323Subscribes to HTTP header events for the upload task. This API uses a callback to return the result asynchronously. 324 325**Required permissions**: ohos.permission.INTERNET 326 327**System capability**: SystemCapability.MiscServices.Upload 328 329**Parameters** 330 331 | Name| Type| Mandatory| Description| 332 | -------- | -------- | -------- | -------- | 333 | type | string | Yes| Type of the event to subscribe to. The value is **'headerReceive'** (response header).| 334 | callback | function | Yes| Callback for the HTTP Response Header event.| 335 336 Parameters of the callback function 337 338| Name| Type| Mandatory| Description| 339| -------- | -------- | -------- | -------- | 340| header | object | Yes| HTTP Response Header.| 341 342**Example** 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 356Subscribes to upload completion or failure events. This API uses a callback to return the result asynchronously. 357 358**Required permissions**: ohos.permission.INTERNET 359 360**System capability**: SystemCapability.MiscServices.Upload 361 362**Parameters** 363 364 | Name| Type| Mandatory| Description| 365 | -------- | -------- | -------- | -------- | 366 | type | string | Yes| Type of the event to subscribe to. The value **'complete'** means the upload completion event, and **'fail'** means the upload failure event.| 367 | callback | Callback<Array<TaskState>> | Yes| Callback used to return the result.| 368 369 Parameters of the callback function 370 371| Name| Type| Mandatory| Description| 372| -------- | -------- | -------- | -------- | 373| taskstates | Array<[TaskState](#taskstate9)> | Yes| Upload result.| 374 375**Example** 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 398Unsubscribes from upload progress events. 399 400**Required permissions**: ohos.permission.INTERNET 401 402**System capability**: SystemCapability.MiscServices.Upload 403 404**Parameters** 405 406 | Name| Type| Mandatory| Description| 407 | -------- | -------- | -------- | -------- | 408 | type | string | Yes| Type of the event to unsubscribe from. The value is **'progress'** (upload progress).| 409 | callback | function | No| Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered.<br>**uploadedSize**: size of the uploaded files, in B.<br>**totalSize**: Total size of the files to upload, in B.| 410 411**Example** 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 // Unsubscribe from upProgressCallback1. 423 uploadTask.off('progress', upProgressCallback1); 424 // Unsubscribe from all callbacks of upload progress events. 425 uploadTask.off('progress'); 426 ``` 427 428 429### off('headerReceive')<sup>7+</sup> 430 431off(type: 'headerReceive', callback?: (header: object) => void): void 432 433This interface is used to unsubscribe from the HTTP header event of an upload task. 434 435**Required permissions**: ohos.permission.INTERNET 436 437**System capability**: SystemCapability.MiscServices.Upload 438 439**Parameters** 440 441 | Name| Type| Mandatory| Description| 442 | -------- | -------- | -------- | -------- | 443 | type | string | Yes| Type of the event to unsubscribe from. The value is **'headerReceive'** (response header).| 444 | callback | function | No| Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered.| 445 446**Example** 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 // Unsubscribe from headerCallback1. 458 uploadTask.off('headerReceive', headerCallback1); 459 // Unsubscribe from all callbacks of the HTTP header events for the upload task. 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 467Unsubscribes from upload completion or failure events. 468 469**Required permissions**: ohos.permission.INTERNET 470 471**System capability**: SystemCapability.MiscServices.Upload 472 473**Parameters** 474 475 | Name| Type| Mandatory| Description| 476 | -------- | -------- | -------- | -------- | 477 | type | string | Yes| Type of the event to subscribe to. The value **'complete'** means the upload completion event, and **'fail'** means the upload failure event.| 478 | callback | Callback<Array<TaskState>> | No| Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered.| 479 480**Example** 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 // Unsubscribe from headerCallback1. 498 uploadTask.off('complete', upCompleteCallback1); 499 // Unsubscribe from all callbacks of the upload completion events. 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 // Unsubscribe from headerCallback1. 517 uploadTask.off('fail', upFailCallback1); 518 // Unsubscribe from all callbacks of the upload failure events. 519 uploadTask.off('fail'); 520 ``` 521 522### delete<sup>9+</sup> 523delete(): Promise<boolean> 524 525Deletes this upload task. This API uses a promise to return the result. 526 527**Required permissions**: ohos.permission.INTERNET 528 529**System capability**: SystemCapability.MiscServices.Upload 530 531**Return value** 532 533 | Type| Description| 534 | -------- | -------- | 535 | Promise<boolean> | Promise used to return the result. The value **true** indicates that the operation is successful, and the value **false** indicates the opposite.| 536 537**Example** 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 552Deletes this upload task. This API uses an asynchronous callback to return the result. 553 554**Required permissions**: ohos.permission.INTERNET 555 556**System capability**: SystemCapability.MiscServices.Upload 557 558**Parameters** 559 560 | Name| Type| Mandatory| Description| 561 | -------- | -------- | -------- | -------- | 562 | callback | AsyncCallback<boolean> | Yes| Callback used to return the result. The value **true** indicates that the operation is successful, and the value **false** indicates the opposite.| 563 564**Example** 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 581Removes this upload task. This API uses a promise to return the result. 582 583> **NOTE** 584> 585> This API is deprecated since API version 9. You are advised to use [delete<sup>9+</sup>](#delete9) instead. 586 587**Required permissions**: ohos.permission.INTERNET 588 589**System capability**: SystemCapability.MiscServices.Upload 590 591**Return value** 592 593 | Type| Description| 594 | -------- | -------- | 595 | Promise<boolean> | Promise used to return the result. The value **true** indicates that the operation is successful, and the value **false** indicates the opposite.| 596 597**Example** 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 612Removes this upload task. This API uses an asynchronous callback to return the result. 613 614> **NOTE** 615> 616> This API is deprecated since API version 9. You are advised to use [delete<sup>9+</sup>](#delete9-1) instead. 617 618**Required permissions**: ohos.permission.INTERNET 619 620**System capability**: SystemCapability.MiscServices.Upload 621 622**Parameters** 623 624 | Name| Type| Mandatory| Description| 625 | -------- | -------- | -------- | -------- | 626 | callback | AsyncCallback<boolean> | Yes| Callback used to return the result. The value **true** indicates that the operation is successful, and the value **false** indicates the opposite.| 627 628**Example** 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> 645Describes the configuration of an upload task. 646 647**Required permissions**: ohos.permission.INTERNET 648 649**System capability**: SystemCapability.MiscServices.Upload 650 651| Name| Type| Mandatory| Description| 652| -------- | -------- | -------- | -------- | 653| url | string | Yes| Resource URL.| 654| header | Object | Yes| HTTP or HTTPS header added to an upload request.| 655| method | string | Yes| Request method, which can be **'POST'** or **'PUT'**. The default value is **'POST'**.| 656| index<sup>11+</sup> | number | No| Path index of the task. The default value is **0**.| 657| begins<sup>11+</sup> | number | No| File start point to read when the task begins. The default value is **0**. The value is a closed interval.| 658| ends<sup>11+</sup> | number | No| File start point to read when the task ends. The default value is **-1**. The value is a closed interval.| 659| files | Array<[File](#file)> | Yes| List of files to upload, which is submitted through **multipart/form-data**.| 660| data | Array<[RequestData](#requestdata)> | Yes| Form data in the request body.| 661 662## TaskState<sup>9+</sup> 663Implements a **TaskState** object, which is the callback parameter of the [on('complete' | 'fail')<sup>9+</sup>](#oncomplete--fail9) and [off('complete' | 'fail')<sup>9+</sup>](#offcomplete--fail9) APIs. 664 665**Required permissions**: ohos.permission.INTERNET 666 667**System capability**: SystemCapability.MiscServices.Upload 668 669| Name| Type| Mandatory| Description| 670| -------- | -------- | -------- | -------- | 671| path | string | Yes| File path.| 672| responseCode | number | Yes| Return value of an upload task. The value **0** means that the task is successful, and other values means that the task fails. For details about the task result, see **message**.| 673| message | string | Yes| Description of the upload task result.| 674 675## File 676Defines the file list in [UploadConfig<sup>6+<sup>](#uploadconfig6). 677 678**Required permissions**: ohos.permission.INTERNET 679 680**System capability**: SystemCapability.MiscServices.Download 681 682| Name| Type| Mandatory| Description| 683| -------- | -------- | -------- | -------- | 684| filename | string | Yes| File name in the header when **multipart** is used.| 685| name | string | Yes| Name of a form item when **multipart** is used. The default value is **file**.| 686| uri | string | Yes| Local path for storing files.<br>Only the **internal** protocol is currently supported. **internal://cache/** is the private directory of the application and is mandatory. Example:<br>internal://cache/path/to/file.txt | 687| type | string | Yes| Type of the file content. By default, the type is obtained based on the extension of the file name or URI.| 688 689 690## RequestData 691Defines the form data in [UploadConfig<sup>6+<sup>](#uploadconfig6). 692 693**Required permissions**: ohos.permission.INTERNET 694 695**System capability**: SystemCapability.MiscServices.Download 696 697| Name| Type| Mandatory| Description| 698| -------- | -------- | -------- | -------- | 699| name | string | Yes| Name of a form element.| 700| value | string | Yes| Value of a form element.| 701 702## request.downloadFile<sup>9+</sup> 703 704downloadFile(context: BaseContext, config: DownloadConfig): Promise<DownloadTask> 705 706Downloads files. This API uses a promise to return the result. You can use [on('complete'|'pause'|'remove')<sup>7+</sup>](#oncompletepauseremove7) to obtain the download task state, which can be completed, paused, or removed. You can also use [on('fail')<sup>7+</sup>](#onfail7) to obtain the task download error information. 707 708 709**Required permissions**: ohos.permission.INTERNET 710 711**System capability**: SystemCapability.MiscServices.Download 712 713**Parameters** 714 715 | Name| Type| Mandatory| Description| 716 | -------- | -------- | -------- | -------- | 717 | context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes| Application-based context.| 718 | config | [DownloadConfig](#downloadconfig) | Yes| Download configuration.| 719 720**Return value** 721 722 | Type| Description| 723 | -------- | -------- | 724 | Promise<[DownloadTask](#downloadtask)> | Promise used to return the download task.| 725 726**Error codes** 727 728For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 729 730 | ID| Error Message| 731 | -------- | -------- | 732 | 13400001 | file operation error. | 733 | 13400002 | bad file path. | 734 | 13400003 | task service ability error. | 735 736**Example** 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> **NOTE** 753> 754> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 755 756 757## request.downloadFile<sup>9+</sup> 758 759downloadFile(context: BaseContext, config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void; 760 761Downloads files. This API uses an asynchronous callback to return the result. You can use [on('complete'|'pause'|'remove')<sup>7+</sup>](#oncompletepauseremove7) to obtain the download task state, which can be completed, paused, or removed. You can also use [on('fail')<sup>7+</sup>](#onfail7) to obtain the task download error information. 762 763 764**Required permissions**: ohos.permission.INTERNET 765 766**System capability**: SystemCapability.MiscServices.Download 767 768**Parameters** 769 770 | Name| Type| Mandatory| Description| 771 | -------- | -------- | -------- | -------- | 772 | context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes| Application-based context.| 773 | config | [DownloadConfig](#downloadconfig) | Yes| Download configuration.| 774 | callback | AsyncCallback<[DownloadTask](#downloadtask)> | Yes| Callback used to return the download task.| 775 776**Error codes** 777 778For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 779 780 | ID| Error Message| 781 | -------- | -------- | 782 | 13400001 | file operation error. | 783 | 13400002 | bad file path. | 784 | 13400003 | task service ability error. | 785 786**Example** 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> **NOTE** 808> 809> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 810 811## request.download<sup>(deprecated)</sup> 812 813download(config: DownloadConfig): Promise<DownloadTask> 814 815Downloads files. This API uses a promise to return the result. 816 817> **NOTE** 818> 819> This API is deprecated since API version 9. You are advised to use [request.downloadFile<sup>9+</sup>](#requestdownloadfile9) instead. 820 821**Model restriction**: This API can be used only in the FA model. 822 823**Required permissions**: ohos.permission.INTERNET 824 825**System capability**: SystemCapability.MiscServices.Download 826 827**Parameters** 828 829 | Name| Type| Mandatory| Description| 830 | -------- | -------- | -------- | -------- | 831 | config | [DownloadConfig](#downloadconfig) | Yes| Download configuration.| 832 833**Return value** 834 835 | Type| Description| 836 | -------- | -------- | 837 | Promise<[DownloadTask](#downloadtask)> | Promise used to return the download task.| 838 839**Example** 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 855Downloads files. This API uses an asynchronous callback to return the result. 856 857> **NOTE** 858> 859> This API is deprecated since API version 9. You are advised to use [request.downloadFile<sup>9+</sup>](#requestdownloadfile9-1) instead. 860 861**Model restriction**: This API can be used only in the FA model. 862 863**Required permissions**: ohos.permission.INTERNET 864 865**System capability**: SystemCapability.MiscServices.Download 866 867**Parameters** 868 869 | Name| Type| Mandatory| Description| 870 | -------- | -------- | -------- | -------- | 871 | config | [DownloadConfig](#downloadconfig) | Yes| Download configuration.| 872 | callback | AsyncCallback<[DownloadTask](#downloadtask)> | Yes| Callback used to return the download task.| 873 874**Example** 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 890Implements file downloads. Before using any APIs of this class, you must obtain a **DownloadTask** object through [request.downloadFile<sup>9+</sup>](#requestdownloadfile9) in promise mode or [request.downloadFile<sup>9+</sup>](#requestdownloadfile9-1) in callback mode. 891 892 893### on('progress') 894 895on(type: 'progress', callback:(receivedSize: number, totalSize: number) => void): void 896 897Subscribes to download progress events. This API uses a callback to return the result asynchronously. 898 899> **NOTE** 900> 901> To maintain a balance between power consumption and performance, this API cannot be called when the application is running in the background. 902 903**Required permissions**: ohos.permission.INTERNET 904 905**System capability**: SystemCapability.MiscServices.Download 906 907**Parameters** 908 909 | Name| Type| Mandatory| Description| 910 | -------- | -------- | -------- | -------- | 911 | type | string | Yes| Type of the event to subscribe to. The value is **'progress'** (download progress).| 912 | callback | function | Yes| Callback used to return the result.| 913 914 Parameters of the callback function 915 916| Name| Type| Mandatory| Description| 917| -------- | -------- | -------- | -------- | 918| receivedSize | number | Yes| Size of the downloaded files, in bytes.| 919| totalSize | number | Yes| Total size of the files to download, in bytes.| 920 921**Example** 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 946Unsubscribes from download progress events. 947 948**Required permissions**: ohos.permission.INTERNET 949 950**System capability**: SystemCapability.MiscServices.Download 951 952**Parameters** 953 954 | Name| Type| Mandatory| Description| 955 | -------- | -------- | -------- | -------- | 956 | type | string | Yes| Type of the event to unsubscribe from. The value is **'progress'** (download progress).| 957 | callback | function | No| Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered.<br>**receivedSize**: size of the downloaded files.<br>**totalSize**: total size of the files to download.| 958 959**Example** 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 // Unsubscribe from progressCallback1. 976 downloadTask.off('progress', progressCallback1); 977 // Unsubscribe from all callbacks of download progress events. 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 992Subscribes to download events. This API uses a callback to return the result asynchronously. 993 994**Required permissions**: ohos.permission.INTERNET 995 996**System capability**: SystemCapability.MiscServices.Download 997 998**Parameters** 999 1000 | Name| Type| Mandatory| Description| 1001 | -------- | -------- | -------- | -------- | 1002 | type | string | Yes| Type of the event to subscribe to.<br>- **'complete'**: download task completion event.<br>- **'pause'**: download task pause event.<br>- **'remove'**: download task removal event.| 1003 | callback | function | Yes| Callback used to return the result.| 1004 1005**Example** 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 1040Unsubscribes from download events. 1041 1042**Required permissions**: ohos.permission.INTERNET 1043 1044**System capability**: SystemCapability.MiscServices.Download 1045 1046**Parameters** 1047 1048 | Name| Type| Mandatory| Description| 1049 | -------- | -------- | -------- | -------- | 1050 | type | string | Yes| Type of the event to unsubscribe from.<br>- **'complete'**: download task completion event.<br>- **'pause'**: download task pause event.<br>- **'remove'**: download task removal event.| 1051 | callback | function | No| Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered.| 1052 1053**Example** 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 // Unsubscribe from completeCallback1. 1070 downloadTask.off('complete', completeCallback1); 1071 // Unsubscribe from all callbacks of the download completion events. 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 // Unsubscribe from pauseCallback1. 1083 downloadTask.off('pause', pauseCallback1); 1084 // Unsubscribe from all callbacks of the download pause events. 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 // Unsubscribe from removeCallback1. 1096 downloadTask.off('remove', removeCallback1); 1097 // Unsubscribe from all callbacks of the download removal events. 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 1113Subscribes to download failure events. This API uses a callback to return the result asynchronously. 1114 1115**Required permissions**: ohos.permission.INTERNET 1116 1117**System capability**: SystemCapability.MiscServices.Download 1118 1119**Parameters** 1120 1121 | Name| Type| Mandatory| Description| 1122 | -------- | -------- | -------- | -------- | 1123 | type | string | Yes| Type of the event to subscribe to. The value is **'fail'** (download failure).| 1124 | callback | function | Yes| Callback for the download task failure event.| 1125 1126 Parameters of the callback function 1127 1128| Name| Type| Mandatory| Description| 1129| -------- | -------- | -------- | -------- | 1130| err | number | Yes| Error code of the download failure. For details about the error codes, see [Download Error Codes](#download-error-codes).| 1131 1132**Example** 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 1157Unsubscribes from download failure events. 1158 1159**Required permissions**: ohos.permission.INTERNET 1160 1161**System capability**: SystemCapability.MiscServices.Download 1162 1163**Parameters** 1164 1165 | Name| Type| Mandatory| Description| 1166 | -------- | -------- | -------- | -------- | 1167 | type | string | Yes| Type of the event to unsubscribe from. The value is **'fail'** (download failure).| 1168 | callback | function | No| Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered.| 1169 1170**Example** 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 // Unsubscribe from failCallback1. 1187 downloadTask.off('fail', failCallback1); 1188 // Unsubscribe from all callbacks of the download failure events. 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 1202Deletes this download task. This API uses a promise to return the result. 1203 1204**Required permissions**: ohos.permission.INTERNET 1205 1206**System capability**: SystemCapability.MiscServices.Download 1207 1208**Return value** 1209 1210 | Type| Description| 1211 | -------- | -------- | 1212 | Promise<boolean> | Promise used to return the result. The value **true** indicates that the operation is successful, and the value **false** indicates the opposite.| 1213 1214**Example** 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 1240Deletes this download task. This API uses an asynchronous callback to return the result. 1241 1242**Required permissions**: ohos.permission.INTERNET 1243 1244**System capability**: SystemCapability.MiscServices.Download 1245 1246**Parameters** 1247 1248 | Name| Type| Mandatory| Description| 1249 | -------- | -------- | -------- | -------- | 1250 | callback | AsyncCallback<boolean> | Yes| Callback used to return the result. The value **true** indicates that the operation is successful, and the value **false** indicates the opposite.| 1251 1252**Example** 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 1280Obtains the information about this download task. This API uses a promise to return the result. 1281 1282**Required permissions**: ohos.permission.INTERNET 1283 1284**System capability**: SystemCapability.MiscServices.Download 1285 1286**Return value** 1287 1288 | Type| Description| 1289 | -------- | -------- | 1290 | Promise<[DownloadInfo](#downloadinfo7)> | Promise used to return the download task information.| 1291 1292**Example** 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 1318Obtains the information about this download task. This API uses an asynchronous callback to return the result. 1319 1320**Required permissions**: ohos.permission.INTERNET 1321 1322**System capability**: SystemCapability.MiscServices.Download 1323 1324**Parameters** 1325 1326 | Name| Type| Mandatory| Description| 1327 | -------- | -------- | -------- | -------- | 1328 | callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | Yes| Callback used to return the download task information.| 1329 1330**Example** 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 1358Obtains the **MimeType** of this download task. This API uses a promise to return the result. 1359 1360**Required permissions**: ohos.permission.INTERNET 1361 1362**System capability**: SystemCapability.MiscServices.Download 1363 1364**Return value** 1365 1366 | Type| Description| 1367 | -------- | -------- | 1368 | Promise<string> | Promise used to return the **MimeType** of the download task.| 1369 1370**Example** 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 1396Obtains the **MimeType** of this download task. This API uses an asynchronous callback to return the result. 1397 1398**Required permissions**: ohos.permission.INTERNET 1399 1400**System capability**: SystemCapability.MiscServices.Download 1401 1402**Parameters** 1403 1404 | Name| Type| Mandatory| Description| 1405 | -------- | -------- | -------- | -------- | 1406 | callback | AsyncCallback<string> | Yes| Callback used to return the **MimeType** of the download task.| 1407 1408**Example** 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 1436Pauses this download task. This API uses a promise to return the result. 1437 1438**Required permissions**: ohos.permission.INTERNET 1439 1440**System capability**: SystemCapability.MiscServices.Download 1441 1442**Return value** 1443 1444 | Type| Description| 1445 | -------- | -------- | 1446 | Promise<boolean> | Promise used to return the result.| 1447 1448**Example** 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 1474Pauses this download task. This API uses an asynchronous callback to return the result. 1475 1476**Required permissions**: ohos.permission.INTERNET 1477 1478**System capability**: SystemCapability.MiscServices.Download 1479 1480**Parameters** 1481 1482 | Name| Type| Mandatory| Description| 1483 | -------- | -------- | -------- | -------- | 1484 | callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| 1485 1486**Example** 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 1514Resumes this download task. This API uses a promise to return the result. 1515 1516**Required permissions**: ohos.permission.INTERNET 1517 1518**System capability**: SystemCapability.MiscServices.Download 1519 1520**Return value** 1521 1522 | Type| Description| 1523 | -------- | -------- | 1524 | Promise<boolean> | Promise used to return the result.| 1525 1526**Example** 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 1552Resumes this download task. This API uses an asynchronous callback to return the result. 1553 1554**Required permissions**: ohos.permission.INTERNET 1555 1556**System capability**: SystemCapability.MiscServices.Download 1557 1558**Parameters** 1559 1560 | Name| Type| Mandatory| Description| 1561 | -------- | -------- | -------- | -------- | 1562 | callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| 1563 1564**Example** 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 1592Removes this download task. This API uses a promise to return the result. 1593 1594> **NOTE** 1595> 1596> This API is deprecated since API version 9. You are advised to use [delete<sup>9+</sup>](#delete9-2) instead. 1597 1598**Required permissions**: ohos.permission.INTERNET 1599 1600**System capability**: SystemCapability.MiscServices.Download 1601 1602**Return value** 1603 1604 | Type| Description| 1605 | -------- | -------- | 1606 | Promise<boolean> | Promise used to return the result.| 1607 1608**Example** 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 1623Removes this download task. This API uses an asynchronous callback to return the result. 1624 1625> **NOTE** 1626> 1627> This API is deprecated since API version 9. You are advised to use [delete<sup>9+</sup>](#delete9-3) instead. 1628 1629**Required permissions**: ohos.permission.INTERNET 1630 1631**System capability**: SystemCapability.MiscServices.Download 1632 1633**Parameters** 1634 1635 | Name| Type| Mandatory| Description| 1636 | -------- | -------- | -------- | -------- | 1637 | callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| 1638 1639**Example** 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 1656Queries this download task. This API uses a promise to return the result. 1657 1658> **NOTE** 1659> 1660> This API is supported since API version 7 and is deprecated since API version 9. You are advised to use [getTaskInfo<sup>9+</sup>](#gettaskinfo9) instead. 1661 1662**Required permissions**: ohos.permission.INTERNET 1663 1664**System capability**: SystemCapability.MiscServices.Download 1665 1666**Return value** 1667 1668 | Type| Description| 1669 | -------- | -------- | 1670 | Promise<[DownloadInfo](#downloadinfo7)> | Promise used to return the download task information.| 1671 1672**Example** 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 1687Queries this download task. This API uses an asynchronous callback to return the result. 1688 1689> **NOTE** 1690> 1691> This API is supported since API version 7 and is deprecated since API version 9. You are advised to use [getTaskInfo<sup>9+</sup>](#gettaskinfo9-1) instead. 1692 1693**Required permissions**: ohos.permission.INTERNET 1694 1695**System capability**: SystemCapability.MiscServices.Download 1696 1697**Parameters** 1698 1699 | Name| Type| Mandatory| Description| 1700 | -------- | -------- | -------- | -------- | 1701 | callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | Yes| Callback used to return the download task information.| 1702 1703**Example** 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 1720Queries the **MimeType** of this download task. This API uses a promise to return the result. 1721 1722> **NOTE** 1723> 1724> This API is supported since API version 7 and is deprecated since API version 9. You are advised to use [getTaskMimeType<sup>9+</sup>](#gettaskmimetype9) instead. 1725 1726**Required permissions**: ohos.permission.INTERNET 1727 1728**System capability**: SystemCapability.MiscServices.Download 1729 1730**Return value** 1731 1732 | Type| Description| 1733 | -------- | -------- | 1734 | Promise<string> | Promise used to return the **MimeType** of the download task.| 1735 1736**Example** 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 1751Queries the **MimeType** of this download task. This API uses an asynchronous callback to return the result. 1752 1753> **NOTE** 1754> 1755> This API is supported since API version 7 and is deprecated since API version 9. You are advised to use [getTaskMimeType<sup>9+</sup>](#gettaskmimetype9-1) instead. 1756 1757**Required permissions**: ohos.permission.INTERNET 1758 1759**System capability**: SystemCapability.MiscServices.Download 1760 1761**Parameters** 1762 1763 | Name| Type| Mandatory| Description| 1764 | -------- | -------- | -------- | -------- | 1765 | callback | AsyncCallback<string> | Yes| Callback used to return the **MimeType** of the download task.| 1766 1767**Example** 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 1784Pauses this download task. This API uses a promise to return the result. 1785 1786> **NOTE** 1787> 1788> This API is supported since API version 7 and is deprecated since API version 9. You are advised to use [suspend<sup>9+</sup>](#suspend9) instead. 1789 1790**Required permissions**: ohos.permission.INTERNET 1791 1792**System capability**: SystemCapability.MiscServices.Download 1793 1794**Return value** 1795 1796 | Type| Description| 1797 | -------- | -------- | 1798 | Promise<void> | Promise used to return the result.| 1799 1800**Example** 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> **NOTE** 1816> 1817> This API is supported since API version 7 and is deprecated since API version 9. You are advised to use [suspend<sup>9+</sup>](#suspend9-1) instead. 1818 1819Pauses this download task. This API uses an asynchronous callback to return the result. 1820 1821**Required permissions**: ohos.permission.INTERNET 1822 1823**System capability**: SystemCapability.MiscServices.Download 1824 1825**Parameters** 1826 1827 | Name| Type| Mandatory| Description| 1828 | -------- | -------- | -------- | -------- | 1829 | callback | AsyncCallback<void> | Yes| Callback used to return the result.| 1830 1831**Example** 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 1848Resumes this download task. This API uses a promise to return the result. 1849 1850> **NOTE** 1851> 1852> This API is supported since API version 7 and is deprecated since API version 9. You are advised to use [restore<sup>9+</sup>](#restore9) instead. 1853 1854**Required permissions**: ohos.permission.INTERNET 1855 1856**System capability**: SystemCapability.MiscServices.Download 1857 1858**Return value** 1859 1860 | Type| Description| 1861 | -------- | -------- | 1862 | Promise<void> | Promise used to return the result.| 1863 1864**Example** 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> **NOTE** 1880> 1881> This API is supported since API version 7 and is deprecated since API version 9. You are advised to use [restore<sup>9+</sup>](#restore9-1) instead. 1882 1883Resumes this download task. This API uses an asynchronous callback to return the result. 1884 1885**Required permissions**: ohos.permission.INTERNET 1886 1887**System capability**: SystemCapability.MiscServices.Download 1888 1889**Parameters** 1890 1891 | Name| Type| Mandatory| Description| 1892 | -------- | -------- | -------- | -------- | 1893 | callback | AsyncCallback<void> | Yes| Callback used to return the result.| 1894 1895**Example** 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 1909Defines the download task configuration. 1910 1911**Required permissions**: ohos.permission.INTERNET 1912 1913**System capability**: SystemCapability.MiscServices.Download 1914 1915| Name| Type| Mandatory| Description| 1916| -------- | -------- | -------- | -------- | 1917| url | string | Yes| Resource URL.| 1918| header | Object | No| HTTPS flag header to be included in the download request.<br>The **X-TLS-Version** parameter in **header** specifies the TLS version to be used. If this parameter is not set, the CURL_SSLVERSION_TLSv1_2 version is used. Available options are as follows:<br>CURL_SSLVERSION_TLSv1_0<br>CURL_SSLVERSION_TLSv1_1<br>CURL_SSLVERSION_TLSv1_2<br>CURL_SSLVERSION_TLSv1_3<br>The **X-Cipher-List** parameter in **header** specifies the cipher suite list to be used. If this parameter is not specified, the secure cipher suite list is used. Available options are as follows:<br>- The TLS 1.2 cipher suite list includes the following ciphers:<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>- The TLS 1.3 cipher suite list includes the following ciphers:<br>TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_CCM_SHA256<br>- The TLS 1.3 cipher suite list adds the Chinese national cryptographic algorithm:<br>TLS_SM4_GCM_SM3,TLS_SM4_CCM_SM3 | 1919| enableMetered | boolean | No| Whether download is allowed on a metered connection. The default value is **false**. In general cases, a mobile data connection is metered, while a Wi-Fi connection is not.<br>- **true**: allowed<br>- **false**: not allowed| 1920| enableRoaming | boolean | No| Whether download is allowed on a roaming network. The default value is **false**.<br>- **true**: allowed<br>- **false**: not allowed| 1921| description | string | No| Description of the download session.| 1922| filePath<sup>7+</sup> | string | No| Path where the downloaded file is stored.<br>- In the FA model, use [context](../apis-ability-kit/js-apis-inner-app-context.md#contextgetcachedir) to obtain the application storage path.<br>- In the stage model, use [AbilityContext](../apis-ability-kit/js-apis-inner-application-context.md) to obtain the application storage path.| 1923| networkType | number | No| Network type allowed for the download. The default value is **NETWORK_MOBILE and NETWORK_WIFI**.<br>- NETWORK_MOBILE: 0x00000001<br>- NETWORK_WIFI: 0x00010000| 1924| title | string | No| Download task name.| 1925| background<sup>9+</sup> | boolean | No| Whether to enable background task notification so that the download status is displayed in the notification panel. The default value is false.| 1926 1927 1928## DownloadInfo<sup>7+</sup> 1929Defines the download task information, which is the callback parameter of the [getTaskInfo<sup>9+</sup>](#gettaskinfo9) API. 1930 1931**Required permissions**: ohos.permission.INTERNET 1932 1933**System capability**: SystemCapability.MiscServices.Download 1934 1935| Name| Type|Mandatory| Description| 1936| -------- | -------- | -------- | -------- | 1937| downloadId | number |Yes| ID of the download task.| 1938| failedReason | number|Yes| Cause of the download failure. The value can be any constant in [Download Error Codes](#download-error-codes).| 1939| fileName | string |Yes| Name of the downloaded file.| 1940| filePath | string |Yes| URI of the saved file.| 1941| pausedReason | number |Yes| Cause of download pause. The value can be any constant in [Causes of Download Pause](#causes-of-download-pause).| 1942| status | number |Yes| Download task status code. The value can be any constant in [Download Task Status Codes](#download-task-status-codes).| 1943| targetURI | string |Yes| URI of the downloaded file.| 1944| downloadTitle | string |Yes| Name of the download task.| 1945| downloadTotalBytes | number |Yes| Total size of the files to download, in bytes.| 1946| description | string |Yes| Description of the download task.| 1947| downloadedBytes | number |Yes| Size of the files downloaded, in bytes.| 1948 1949## Action<sup>10+</sup> 1950 1951Defines action options. 1952 1953**System capability**: SystemCapability.Request.FileTransferAgent 1954 1955| Name| Value|Description| 1956| -------- | -------- |-------- | 1957| DOWNLOAD | 0 |Download.| 1958| UPLOAD | 1 |Upload.| 1959 1960 1961## Mode<sup>10+</sup> 1962Defines mode options.<br> 1963After an application is switched to the background for a period of time, background tasks are not affected but foreground tasks will fail or pause. 1964 1965**System capability**: SystemCapability.Request.FileTransferAgent 1966 1967| Name| Value|Description| 1968| -------- | -------- |-------- | 1969| BACKGROUND | 0 |Background task.| 1970| FOREGROUND | 1 |Foreground task.| 1971 1972## Network<sup>10+</sup> 1973 1974Defines network options.<br> 1975If the network does not meet the preset conditions, the tasks that have not been executed will await for execution, and the tasks that are being executed will fail or pause. 1976 1977**System capability**: SystemCapability.Request.FileTransferAgent 1978 1979| Name| Value|Description| 1980| -------- | -------- |-------- | 1981| ANY | 0 |Network of any type.| 1982| WIFI | 1 |Wi-Fi network.| 1983| CELLULAR | 2 |Cellular data network.| 1984 1985## BroadcastEvent<sup>11+</sup> 1986 1987Defines a custom system event. You can use a common event API to obtain the event. 1988The upload and download SA has the **ohos.permission.SEND_TASK_COMPLETE_EVENT** permission. You can configure the level-2 configuration file to which the metadata of an event points to intercept other event senders. 1989 1990You can use the **CommonEventData** type to transmit data related to common events. The members in **CommonEventData** are different from those described in [CommonEventData](js-apis-inner-commonEvent-commonEventData.md). Specifically, **CommonEventData.code** indicates the task status, which is **0x40 COMPLETE** or **0x41 FAILED**, and **CommonEventData.data** indicates the task ID. 1991 1992For details about event configuration information, see [Subscribing to Common Events in Static Mode](../../application-models/common-event-static-subscription.md). 1993 1994**System capability**: SystemCapability.Request.FileTransferAgent 1995 1996| Name| Value| Description | 1997| -------- | ------- |-----------| 1998| COMPLETE | 'ohos.request.event.COMPLETE' | Task completion event.| 1999 2000## FileSpec<sup>10+</sup> 2001Provides the file information of a table item. 2002 2003**System capability**: SystemCapability.Request.FileTransferAgent 2004 2005| Name| Type| Mandatory| Description| 2006| -------- | -------- | -------- | -------- | 2007| path | string | Yes| Relative path in the cache folder of the invoker.| 2008| mimeType | string | No| MIME type of the file, which is obtained from the file name.| 2009| filename | string | No| File name. The default value is obtained from the file path.| 2010| extras | Object | No| Additional information of the file.| 2011 2012 2013## FormItem<sup>10+</sup> 2014Describes the form item of a task. 2015 2016**System capability**: SystemCapability.Request.FileTransferAgent 2017 2018| Name| Type| Mandatory| Description| 2019| -------- | -------- | -------- | -------- | 2020| name | string | Yes| Form parameter name.| 2021| value | string \| [FileSpec](#filespec10) \| Array<[FileSpec](#filespec10)> | Yes| Form parameter value.| 2022 2023 2024## Config<sup>10+</sup> 2025Provides the configuration information of an upload or download task. 2026 2027**System capability**: SystemCapability.Request.FileTransferAgent 2028 2029| Name| Type| Mandatory| Description| 2030| -------- | -------- | -------- | -------- | 2031| action | [Action](#action10) | Yes| Task action.<br>- **UPLOAD**<br>- **DOWNLOAD**| 2032| url | string | Yes| Resource URL. The value contains a maximum of 2048 characters.| 2033| title | string | No| Task title. The value contains a maximum of 256 characters. The default value is **upload** or **download** in lowercase. Set the value to that of **action**.| 2034| description | string | No| Task description. The value contains a maximum of 1024 characters. The default value is a null string.| 2035| mode | [Mode](#mode10) | No| Task mode. The default mode is background.| 2036| overwrite | boolean | No| Whether to overwrite an existing file during the download. The default value is **false**.<br>- **true**: Overwrite the existing file.<br>- **false**: Do not overwrite the existing file. In this case, the download fails.| 2037| method | string | No| Standard HTTP method for the task. The value can be **GET**, **POST**, or **PUT**, which is case-insensitive.<br>- If the task is an upload, use **PUT** or **POST**. The default value is **PUT**.<br>- If the task is a download, use **GET** or **POST**. The default value is **GET**.| 2038| headers | object | No| HTTP headers to be included in the task.<br>- If the task is an upload, the default **Content-Type** is **multipart/form-data**.<br>- If the task is a download, the default **Content-Type** is **application/json**.| 2039| data | string \| Array<[FormItem](#formitem10)> | No| Task data.<br>- If the task is a download, the value is a string, typically in JSON format (an object will be converted to a JSON string); the default value is null.<br>- If the task is an upload, the value is Array<[FormItem](#formitem10)>; the default value is null.| 2040| saveas | string | No| Path for storing downloaded files. The options are as follows:<br>- Relative path in the cache folder of the invoker, for example, **"./xxx/yyy/zzz.html"** and **"xxx/yyy/zzz.html"**.<br>- URI (applicable when the application has the permission to access the URI), for example, **"datashare://bundle/xxx/yyy/zzz.html"**. This option is not supported currently.<br>The default value is a relative path in the cache folder of the application.| 2041| network | [Network](#network10) | No| Network used for the task. The default value is **ANY** (Wi-Fi or cellular).| 2042| metered | boolean | No| Whether the task is allowed on a metered connection. The default value is **false**.<br>- **true**: task allowed on a metered connection.<br>- **false**: task not allowed on a metered connection.| 2043| roaming | boolean | No| Whether the task is allowed on a roaming network. The default value is **true**.<br>- **true**: task allowed on a roaming network.<br>- **false**: task not allowed on a roaming network.| 2044| retry | boolean | No| Whether automatic retry is enabled for the task. This parameter is only applicable to background tasks. The default value is **true**.<br>- **true**: automatic retry enabled for the task.<br>- **-false**: automatic retry not enabled for the task.| 2045| redirect | boolean | No| Whether redirection is allowed. The default value is **true**.<br>- **true**: redirection allowed.<br>- **false**: redirection not allowed.| 2046| index | number | No| Path index of the task. It is usually used for resumable downloads. The default value is **0**.| 2047| begins | number | No| File start point of the task. It is usually used for resumable downloads. The default value is **0**. The value is a closed interval.<br>- If the task is a download, the value is obtained by sending an HTTP range request to read the start position when the server starts to download files.<br>- If the task is an upload, the value is obtained at the beginning of the upload.| 2048| ends | number | No| File end point of the task. It is usually used for resumable downloads. The default value is **-1**. The value is a closed interval.<br>- If the task is a download, the value is obtained by sending an HTTP range request to read the end position when the server starts to download files.<br>- If the task is an upload, the value is obtained at the end of the upload.| 2049| gauge | boolean | No| Whether to send progress notifications. This parameter applies only to background tasks. The default value is **false**.<br>- **false**: Progress notifications are not sent. This means that a notification is sent only to indicate the result of the total task.<br>- **true**: Progress notifications are sent to indicate the result of each file.| 2050| precise | boolean | No| - If this parameter is set to **true**, the task fails when the file size cannot be obtained.<br>- If this parameter is set to **false**, the task continues when the file size is set to **-1**.<br>The default value is **false**.| 2051| token | string | No| Token of the task. If the task has a token configured, this token is required for query of the task. The value contains 8 to 2048 bytes. This parameter is left empty by default.| 2052| priority<sup>11+</sup> | number | No| Priority of the task. For tasks in the same mode, a smaller value indicates a higher priority.<br>Default value: **0**| 2053| extras | object | No| Additional information of the task. This parameter is left empty by default.| 2054 2055## State<sup>10+</sup> 2056 2057Defines the current task status. 2058 2059**System capability**: SystemCapability.Request.FileTransferAgent 2060 2061| Name| Value|Description| 2062| -------- | -------- |-------- | 2063| INITIALIZED | 0x00 |The task is initialized based on the configuration specified in [Config](#config10).| 2064| WAITING | 0x10 |The task lacks resources for running or the resources for retries do not match the network status.| 2065| RUNNING | 0x20 |The task is being executed.| 2066| RETRYING | 0x21 |The task has failed at least once and is being executed again.| 2067| PAUSED | 0x30 |The task is suspended and will be resumed later.| 2068| STOPPED | 0x31 |The task is stopped.| 2069| COMPLETED | 0x40 |The task is complete.| 2070| FAILED | 0x41 |The task fails.| 2071| REMOVED | 0x50 |The task is removed.| 2072 2073 2074## Progress<sup>10+</sup> 2075Describes the data structure of the task progress. 2076 2077**System capability**: SystemCapability.Request.FileTransferAgent 2078 2079| Name| Type| Mandatory| Description| 2080| -------- | -------- | -------- | -------- | 2081| state | [State](#state10) | Yes| Current task status.| 2082| index | number | Yes| Index of the file that is being processed in the task.| 2083| processed | number | Yes| Size of processed data in the current file in the task, in bytes.| 2084| sizes | Array<number> | Yes| Size of files in the task, in bytes.| 2085| extras | object | No| Extra information of the task, for example, the header and body of the response from the server.| 2086 2087 2088## Faults<sup>10+</sup> 2089 2090Defines the cause of a task failure. 2091 2092**System capability**: SystemCapability.Request.FileTransferAgent 2093 2094| Name| Value|Description| 2095| -------- | -------- |-------- | 2096| OTHERS | 0xFF |Other fault.| 2097| DISCONNECTED | 0x00 |Network disconnection.| 2098| TIMEOUT | 0x10 |Timeout.| 2099| PROTOCOL | 0x20 |Protocol error, for example, an internal server error (500) or a data range that cannot be processed (416).| 2100| FSIO | 0x40 |File system I/O error, for example, an error that occurs during the open, search, read, write, or close operation.| 2101 2102 2103## Filter<sup>10+</sup> 2104Defines the filter criteria. 2105 2106**System capability**: SystemCapability.Request.FileTransferAgent 2107 2108| Name| Type| Mandatory| Description| 2109| -------- | -------- | -------- | -------- | 2110| before | number | No| Unix timestamp of the end time, in milliseconds. The default value is the invoking time.| 2111| after | number | No| Unix timestamp of the start time, in milliseconds. The default value is the invoking time minus 24 hours.| 2112| state | [State](#state10) | No| Task state.| 2113| action | [Action](#action10) | No| Task action.<br>- **UPLOAD**<br>- **DOWNLOAD**| 2114| mode | [Mode](#mode10) | No| Task mode.<br>- **FOREGROUND**: foreground task.<br>- **BACKGROUND**: background task.<br>- No value: All tasks are queried.| 2115 2116## TaskInfo<sup>10+</sup> 2117Defines the data structure of the task information for query. The fields available vary depending on the query type. 2118 2119**System capability**: SystemCapability.Request.FileTransferAgent 2120 2121| Name| Type| Mandatory| Description| 2122| -------- | -------- | -------- | -------- | 2123| saveas | string | No| Path for storing downloaded files. The options are as follows:<br>- Relative path in the cache folder of the invoker, for example, **"./xxx/yyy/zzz.html"** and **"xxx/yyy/zzz.html"**.<br>- URI (applicable when the application has the permission to access the URI), for example, **"datashare://bundle/xxx/yyy/zzz.html"**. This option is not supported currently.<br>The default value is a relative path in the cache folder of the application.| 2124| url | string | No| Task URL.<br>It can be obtained through [request.agent.show<sup>10+</sup>](#requestagentshow10-1) or [request.agent.touch<sup>10+</sup>](#requestagenttouch10-1).| 2125| data | string \| Array<[FormItem](#formitem10)> | No| Task value.<br>It can be obtained through [request.agent.show<sup>10+</sup>](#requestagentshow10-1) or [request.agent.touch<sup>10+</sup>](#requestagenttouch10-1).| 2126| tid | string | Yes| Task ID.| 2127| title | string | Yes| Task title.| 2128| description | string | Yes| Task description.| 2129| action | [Action](#action10) | Yes| Task action.<br>- **UPLOAD**<br>- **DOWNLOAD**| 2130| mode | [Mode](#mode10) | Yes| Task mode.<br>- **FOREGROUND**: foreground task.<br>- **BACKGROUND**: background task.| 2131| priority<sup>11+</sup> | number | No| Task priority. The priority of a foreground task is higher than that of a background task. For tasks in the same mode, a smaller value indicates a higher priority.| 2132| mimeType | string | Yes| MIME type in the task configuration.| 2133| progress | [Progress](#progress10) | Yes| Task progress.| 2134| gauge | boolean | Yes| Whether to send progress notifications. This parameter applies only to background tasks.| 2135| ctime | number | Yes| Unix timestamp when the task is created, in milliseconds. The value is generated by the system of the current device.<br>Note: When [request.agent.search<sup>10+</sup>](#requestagentsearch10-1) is used for query, this value must be within the range of [after,before] for the task ID to be obtained. For details about **before** and **after**, see [Filter](#filter10). 2136| mtime | number | Yes| Unix timestamp when the task state changes, in milliseconds. The value is generated by the system of the current device.| 2137| retry | boolean | Yes| Whether automatic retry is enabled for the task. This parameter applies only to background tasks.| 2138| tries | number | Yes| Number of retries of the task.| 2139| faults | [Faults](#faults10) | Yes| Failure cause of the task.<br>- **OTHERS**: other fault.<br>- **DISCONNECT**: network disconnection.<br>- **TIMEOUT**: timeout.<br>- **PROTOCOL**: protocol error.<br>- **FSIO**: file system I/O error.| 2140| reason | string | Yes| Reason why the task is waiting, failed, stopped, or paused.| 2141| extras | string | No| Extra information of the task| 2142 2143 2144## Task<sup>10+</sup> 2145Implements an upload or download task. Before using this API, you must obtain a **Task** object, from a promise through [request.agent.create<sup>10+</sup>](#requestagentcreate10-1) or from a callback through [request.agent.create<sup>10+</sup>](#requestagentcreate10). 2146 2147### Attributes 2148Task attributes include the task ID and task configuration. 2149 2150**System capability**: SystemCapability.Request.FileTransferAgent 2151 2152| Name| Type| Mandatory| Description| 2153| -------- | -------- | -------- | -------- | 2154| tid | string | Yes| Task ID, which is unique in the system and is automatically generated by the system.| 2155| config | [Config](#config10) | Yes| Task configuration.| 2156 2157 2158### on('progress')<sup>10+</sup> 2159 2160on(event: 'progress', callback: (progress: Progress) => void): void 2161 2162Subscribes to task progress changes. This API uses a callback to return the result asynchronously. 2163 2164**System capability**: SystemCapability.Request.FileTransferAgent 2165 2166**Parameters** 2167 2168 | Name| Type| Mandatory| Description| 2169 | -------- | -------- | -------- | -------- | 2170 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'progress'**, indicating the task progress.| 2171 | callback | function | Yes| Callback used to return the data structure of the task progress.| 2172 2173**Error codes** 2174 2175For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 2176 2177 | ID| Error Message| 2178 | -------- | -------- | 2179 | 21900005 | task mode error. | 2180 2181**Example** 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> **NOTE** 2226> 2227> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 2228 2229### on('completed')<sup>10+</sup> 2230 2231on(event: 'completed', callback: (progress: Progress) => void): void 2232 2233Subscribes to task completion events. This API uses a callback to return the result asynchronously. 2234 2235**System capability**: SystemCapability.Request.FileTransferAgent 2236 2237**Parameters** 2238 2239 | Name| Type| Mandatory| Description| 2240 | -------- | -------- | -------- | -------- | 2241 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'completed'**, indicating task completion.| 2242 | callback | function | Yes| Callback used to return the data structure of the task progress.| 2243 2244**Error codes** 2245 2246For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 2247 2248 | ID| Error Message| 2249 | -------- | -------- | 2250 | 21900005 | task mode error. | 2251 2252**Example** 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> **NOTE** 2297> 2298> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 2299 2300### on('failed')<sup>10+</sup> 2301 2302on(event: 'failed', callback: (progress: Progress) => void): void 2303 2304Subscribes to task failure events. This API uses a callback to return the result asynchronously. 2305 2306**System capability**: SystemCapability.Request.FileTransferAgent 2307 2308**Parameters** 2309 2310 | Name| Type| Mandatory| Description| 2311 | -------- | -------- | -------- | -------- | 2312 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'failed'**, indicating task failure.| 2313 | callback | function | Yes| Callback used to return the data structure of the task progress.| 2314 2315**Error codes** 2316 2317For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 2318 2319 | ID| Error Message| 2320 | -------- | -------- | 2321 | 21900005 | task mode error. | 2322 2323**Example** 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> **NOTE** 2368> 2369> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 2370 2371### on('pause')<sup>11+</sup> 2372 2373on(event: 'pause', callback: (progress: Progress) => void): void 2374 2375Subscribes to task pause events. This API uses a callback to return the result asynchronously. 2376 2377**System capability**: SystemCapability.Request.FileTransferAgent 2378 2379**Parameters** 2380 2381 | Name| Type| Mandatory| Description| 2382 | -------- | -------- | -------- | -------- | 2383 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'pause'**, indicating task pause.| 2384 | callback | function | Yes| Callback used to return the data structure of the task progress.| 2385 2386**Error codes** 2387 2388For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 2389 2390**Example** 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> **NOTE** 2435> 2436> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 2437 2438### on('resume')<sup>11+</sup> 2439 2440on(event: 'resume', callback: (progress: Progress) => void): void 2441 2442Subscribes to task resume events. This API uses a callback to return the result asynchronously. 2443 2444**System capability**: SystemCapability.Request.FileTransferAgent 2445 2446**Parameters** 2447 2448 | Name| Type| Mandatory| Description| 2449 | -------- | -------- | -------- | -------- | 2450 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'resume'**, indicating task resume.| 2451 | callback | function | Yes| Callback used to return the data structure of the task progress.| 2452 2453**Error codes** 2454 2455For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 2456 2457**Example** 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> **NOTE** 2502> 2503> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 2504 2505### on('remove')<sup>11+</sup> 2506 2507on(event: 'remove', callback: (progress: Progress) => void): void 2508 2509Subscribes to task removal events. This API uses a callback to return the result asynchronously. 2510 2511**System capability**: SystemCapability.Request.FileTransferAgent 2512 2513**Parameters** 2514 2515 | Name| Type| Mandatory| Description| 2516 | -------- | -------- | -------- | -------- | 2517 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'remove'**, indicating task removal.| 2518 | callback | function | Yes| Callback used to return the data structure of the task progress.| 2519 2520**Error codes** 2521 2522For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 2523 2524**Example** 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> **NOTE** 2569> 2570> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 2571 2572### off('progress')<sup>10+</sup> 2573 2574off(event: 'progress', callback?: (progress: Progress) => void): void 2575 2576Unsubscribes from task progress events. 2577 2578**System capability**: SystemCapability.Request.FileTransferAgent 2579 2580**Parameters** 2581 2582 | Name| Type| Mandatory| Description| 2583 | -------- | -------- | -------- | -------- | 2584 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'progress'**, indicating the task progress.| 2585 | callback | function | No| Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered.| 2586 2587**Error codes** 2588 2589For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 2590 2591 | ID| Error Message| 2592 | -------- | -------- | 2593 | 21900005 | task mode error. | 2594 2595**Example** 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 // Unsubscribe from createOffCallback1. 2638 task.off('progress', createOffCallback1); 2639 // Unsubscribe from all callbacks of task progress changes. 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> **NOTE** 2648> 2649> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 2650 2651### off('completed')<sup>10+</sup> 2652 2653off(event: 'completed', callback?: (progress: Progress) => void): void 2654 2655Unsubscribes from task completion events. 2656 2657**System capability**: SystemCapability.Request.FileTransferAgent 2658 2659**Parameters** 2660 2661 | Name| Type| Mandatory| Description| 2662 | -------- | -------- | -------- | -------- | 2663 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'completed'**, indicating task completion.| 2664 | callback | function | No| Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered.| 2665 2666**Error codes** 2667 2668For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 2669 2670 | ID| Error Message| 2671 | -------- | -------- | 2672 | 21900005 | task mode error. | 2673 2674**Example** 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 // Unsubscribe from createOffCallback1. 2717 task.off('completed', createOffCallback1); 2718 // Unsubscribe from all callbacks of the task completion events. 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> **NOTE** 2727> 2728> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 2729 2730### off('failed')<sup>10+</sup> 2731 2732off(event: 'failed', callback?: (progress: Progress) => void): void 2733 2734Unsubscribes from task failure events. 2735 2736**System capability**: SystemCapability.Request.FileTransferAgent 2737 2738**Parameters** 2739 2740 | Name| Type| Mandatory| Description| 2741 | -------- | -------- | -------- | -------- | 2742 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'failed'**, indicating task failure.| 2743 | callback | function | No| Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered.| 2744 2745**Error codes** 2746 2747For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 2748 2749 | ID| Error Message| 2750 | -------- | -------- | 2751 | 21900005 | task mode error. | 2752 2753**Example** 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 // Unsubscribe from createOffCallback1. 2796 task.off('failed', createOffCallback1); 2797 // Unsubscribe from all callbacks of the task failure events. 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> **NOTE** 2806> 2807> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 2808 2809### off('pause')<sup>11+</sup> 2810 2811off(event: 'pause', callback?: (progress: Progress) => void): void 2812 2813Unsubscribes from the foreground task pause event. 2814 2815**System capability**: SystemCapability.Request.FileTransferAgent 2816 2817**Parameters** 2818 2819 | Name| Type| Mandatory| Description| 2820 | -------- | -------- | -------- | -------- | 2821 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'pause'**, indicating task pause.| 2822 | callback | function | No| Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered.| 2823 2824**Error codes** 2825 2826For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 2827 2828**Example** 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 // Unsubscribe from createOffCallback1. 2871 task.off('pause', createOffCallback1); 2872 // Unsubscribe from all callbacks of the foreground task pause event. 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> **NOTE** 2881> 2882> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 2883 2884### off('resume')<sup>11+</sup> 2885 2886off(event: 'resume', callback?: (progress: Progress) => void): void 2887 2888Unsubscribes from the foreground task resume event. 2889 2890**System capability**: SystemCapability.Request.FileTransferAgent 2891 2892**Parameters** 2893 2894 | Name| Type| Mandatory| Description| 2895 | -------- | -------- | -------- | -------- | 2896 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'resume'**, indicating task resume.| 2897 | callback | function | No| Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered.| 2898 2899**Error codes** 2900 2901For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 2902 2903**Example** 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 // Unsubscribe from createOffCallback1. 2946 task.off('resume', createOffCallback1); 2947 // Unsubscribe from all callbacks of the foreground task resume event. 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> **NOTE** 2956> 2957> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 2958 2959### off('remove')<sup>11+</sup> 2960 2961off(event: 'remove', callback?: (progress: Progress) => void): void 2962 2963Unsubscribes from the task removal event. 2964 2965**System capability**: SystemCapability.Request.FileTransferAgent 2966 2967**Parameters** 2968 2969 | Name| Type| Mandatory| Description| 2970 | -------- | -------- | -------- | -------- | 2971 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'remove'**, indicating task removal.| 2972 | callback | function | No| Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered.| 2973 2974**Error codes** 2975 2976For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 2977 2978**Example** 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 // Unsubscribe from createOffCallback1. 3021 task.off('remove', createOffCallback1); 3022 // Unsubscribe from all callbacks of the task removal event. 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> **NOTE** 3031> 3032> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 3033 3034### start<sup>10+</sup> 3035 3036start(callback: AsyncCallback<void>): void 3037 3038Starts this task. This API cannot be used to start an initialized task. This API uses an asynchronous callback to return the result. 3039 3040**Required permissions**: ohos.permission.INTERNET 3041 3042**System capability**: SystemCapability.Request.FileTransferAgent 3043 3044**Parameters** 3045 3046 | Name| Type| Mandatory| Description| 3047 | -------- | -------- | -------- | -------- | 3048 | callback | function | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 3049 3050**Error codes** 3051 3052For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 3053 3054 | ID| Error Message| 3055 | -------- | -------- | 3056 | 13400003 | task service ability error. | 3057 | 21900007 | task state error. | 3058 3059**Example** 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> **NOTE** 3099> 3100> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 3101 3102### start<sup>10+</sup> 3103 3104start(): Promise<void> 3105 3106Starts this task. This API cannot be used to start an initialized task. This API uses a promise to return the result. 3107 3108**Required permissions**: ohos.permission.INTERNET 3109 3110**System capability**: SystemCapability.Request.FileTransferAgent 3111 3112**Return value** 3113 3114| Type | Description | 3115| ------------------- | ------------------------- | 3116| Promise<void> | Promise that returns no value.| 3117 3118**Error codes** 3119 3120For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 3121 3122 | ID| Error Message| 3123 | -------- | -------- | 3124 | 13400003 | task service ability error. | 3125 | 21900007 | task state error. | 3126 3127**Example** 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> **NOTE** 3165> 3166> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 3167 3168### pause<sup>10+</sup> 3169 3170pause(callback: AsyncCallback<void>): void 3171 3172Pauses this task. This API can be used to pause a background task that is waiting, running, or retrying. This API uses an asynchronous callback to return the result. 3173 3174**System capability**: SystemCapability.Request.FileTransferAgent 3175 3176**Parameters** 3177 3178 | Name| Type| Mandatory| Description| 3179 | -------- | -------- | -------- | -------- | 3180 | callback | function | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 3181 3182**Error codes** 3183 3184For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 3185 3186 | ID| Error Message| 3187 | -------- | -------- | 3188 | 13400003 | task service ability error. | 3189 | 21900005 | task mode error. | 3190 | 21900007 | task state error. | 3191 3192**Example** 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> **NOTE** 3232> 3233> The error code **21900005 task mode error** is removed from API version 11. 3234 3235### pause<sup>10+</sup> 3236 3237pause(): Promise<void> 3238 3239Pauses this task. This API can be used to pause a background task that is waiting, running, or retrying. This API uses a promise to return the result. 3240 3241**System capability**: SystemCapability.Request.FileTransferAgent 3242 3243**Return value** 3244 3245| Type | Description | 3246| ------------------- | ------------------------- | 3247| Promise<void> | Promise that returns no value.| 3248 3249**Error codes** 3250 3251For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 3252 3253 | ID| Error Message| 3254 | -------- | -------- | 3255 | 13400003 | task service ability error. | 3256 | 21900005 | task mode error. | 3257 | 21900007 | task state error. | 3258 3259**Example** 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> **NOTE** 3297> 3298> The error code **21900005 task mode error** is removed from API version 11. 3299 3300### resume<sup>10+</sup> 3301 3302resume(callback: AsyncCallback<void>): void 3303 3304Resumes this task. This API can be used to resume a paused background task. This API uses an asynchronous callback to return the result. 3305 3306**Required permissions**: ohos.permission.INTERNET 3307 3308**System capability**: SystemCapability.Request.FileTransferAgent 3309 3310**Parameters** 3311 3312 | Name| Type| Mandatory| Description| 3313 | -------- | -------- | -------- | -------- | 3314 | callback | function | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 3315 3316**Error codes** 3317 3318For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 3319 3320 | ID| Error Message| 3321 | -------- | -------- | 3322 | 13400003 | task service ability error. | 3323 | 21900005 | task mode error. | 3324 | 21900007 | task state error. | 3325 3326**Example** 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> **NOTE** 3366> 3367> The error code **21900005 task mode error** is removed from API version 11. 3368 3369 3370### resume<sup>10+</sup> 3371 3372resume(): Promise<void> 3373 3374Resumes this task. This API can be used to resume a paused background task. This API uses a promise to return the result. 3375 3376**Required permissions**: ohos.permission.INTERNET 3377 3378**System capability**: SystemCapability.Request.FileTransferAgent 3379 3380**Return value** 3381 3382| Type | Description | 3383| ------------------- | ------------------------- | 3384| Promise<void> | Promise that returns no value.| 3385 3386**Error codes** 3387 3388For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 3389 3390 | ID| Error Message| 3391 | -------- | -------- | 3392 | 13400003 | task service ability error. | 3393 | 21900005 | task mode error. | 3394 | 21900007 | task state error. | 3395 3396**Example** 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> **NOTE** 3434> 3435> The error code **21900005 task mode error** is removed from API version 11. 3436 3437 3438### stop<sup>10+</sup> 3439 3440stop(callback: AsyncCallback<void>): void 3441 3442Stops this task. This API can be used to stop a running, waiting, or retrying task. This API uses an asynchronous callback to return the result. 3443 3444**System capability**: SystemCapability.Request.FileTransferAgent 3445 3446**Parameters** 3447 3448 | Name| Type| Mandatory| Description| 3449 | -------- | -------- | -------- | -------- | 3450 | callback | function | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 3451 3452**Error codes** 3453 3454For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 3455 3456 | ID| Error Message| 3457 | -------- | -------- | 3458 | 13400003 | task service ability error. | 3459 | 21900007 | task state error. | 3460 3461**Example** 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 3505Stops this task. This API can be used to stop a running, waiting, or retrying task. This API uses a promise to return the result. 3506 3507**System capability**: SystemCapability.Request.FileTransferAgent 3508 3509**Return value** 3510 3511| Type | Description | 3512| ------------------- | ------------------------- | 3513| Promise<void> | Promise that returns no value.| 3514 3515**Error codes** 3516 3517For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 3518 3519 | ID| Error Message| 3520 | -------- | -------- | 3521 | 13400003 | task service ability error. | 3522 | 21900007 | task state error. | 3523 3524**Example** 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 3565Creates an upload or download task and adds it to the queue. An application can create a maximum of 10 unfinished tasks. This API uses an asynchronous callback to return the result. 3566 3567 3568**Required permissions**: ohos.permission.INTERNET 3569 3570**System capability**: SystemCapability.Request.FileTransferAgent 3571 3572**Parameters** 3573 3574 | Name| Type| Mandatory| Description| 3575 | -------- | -------- | -------- | -------- | 3576 | config | [Config](#config10) | Yes| Task configuration.| 3577 | context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes| Application-based context.| 3578 | callback | AsyncCallback<[Task](#task10)> | Yes| Callback used to return the configuration about the created task.| 3579 3580**Error codes** 3581 3582For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 3583 3584 | ID| Error Message| 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**Example** 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> **NOTE** 3634> 3635> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 3636 3637## request.agent.create<sup>10+</sup> 3638 3639create(context: BaseContext, config: Config): Promise<Task> 3640 3641Creates an upload or download task and adds it to the queue. An application can create a maximum of 10 unfinished tasks. This API uses a promise to return the result. 3642 3643 3644**Required permissions**: ohos.permission.INTERNET 3645 3646**System capability**: SystemCapability.Request.FileTransferAgent 3647 3648**Parameters** 3649 3650 | Name| Type| Mandatory| Description| 3651 | -------- | -------- | -------- | -------- | 3652 | context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes| Application-based context.| 3653 | config | [Config](#config10) | Yes| Task configuration.| 3654 3655**Return value** 3656 3657| Type | Description | 3658| ------------------- | ------------------------- | 3659| Promise<[Task](#task10)> | Promise used to return the configuration about the created task.| 3660 3661**Error codes** 3662 3663For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 3664 3665 | ID| Error Message| 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**Example** 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> **NOTE** 3713> 3714> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). 3715 3716## request.agent.getTask<sup>11+</sup> 3717 3718getTask(context: BaseContext, id: string, token?: string): Promise<Task> 3719 3720Obtains task information based on the task ID. This API uses a promise to return the result. 3721 3722**System capability**: SystemCapability.Request.FileTransferAgent 3723 3724**Parameters** 3725 3726 | Name| Type| Mandatory| Description| 3727 | -------- | -------- | -------- | -------- | 3728 | context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes| Application-based context.| 3729 | id | string | Yes| Task ID.| 3730 | token | string | No| Token for task query.| 3731 3732**Return value** 3733 3734| Type | Description | 3735| ------------------- | ------------------------- | 3736| Promise<[Task](#task10)> | Promise used to return the configuration about the created task.| 3737 3738**Error codes** 3739 3740For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 3741 3742 | ID| Error Message| 3743 | -------- | -------- | 3744 | 13400003 | task service ability error. | 3745 | 21900006 | task not found error. | 3746 3747**Example** 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 3761Removes a specified task of the invoker. If the task is being executed, the task is forced to stop. This API uses an asynchronous callback to return the result. 3762 3763**System capability**: SystemCapability.Request.FileTransferAgent 3764 3765**Parameters** 3766 3767 | Name| Type| Mandatory| Description| 3768 | -------- | -------- | -------- | -------- | 3769 | id | string | Yes| Task ID.| 3770 | callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 3771 3772**Error codes** 3773 3774For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 3775 3776 | ID| Error Message| 3777 | -------- | -------- | 3778 | 13400003 | task service ability error. | 3779 | 21900006 | task not found error. | 3780 3781**Example** 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 3798Removes a specified task of the invoker. If the task is being executed, the task is forced to stop. This API uses a promise to return the result. 3799 3800**System capability**: SystemCapability.Request.FileTransferAgent 3801 3802**Parameters** 3803 3804 | Name| Type| Mandatory| Description| 3805 | -------- | -------- | -------- | -------- | 3806 | id | string | Yes| Task ID.| 3807 3808**Return value** 3809 3810| Type | Description | 3811| ------------------- | ------------------------- | 3812| Promise<void> | Promise that returns no value.| 3813 3814**Error codes** 3815 3816For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 3817 3818 | ID| Error Message| 3819 | -------- | -------- | 3820 | 13400003 | task service ability error. | 3821 | 21900006 | task not found error. | 3822 3823**Example** 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 3838Queries a task details based on the task ID. This API uses an asynchronous callback to return the result. 3839 3840**System capability**: SystemCapability.Request.FileTransferAgent 3841 3842**Parameters** 3843 3844 | Name| Type| Mandatory| Description| 3845 | -------- | -------- | -------- | -------- | 3846 | id | string | Yes| Task ID.| 3847 | callback | AsyncCallback<[TaskInfo](#taskinfo10)> | Yes| Callback used to return task details.| 3848 3849**Error codes** 3850For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 3851 3852 | ID| Error Message| 3853 | -------- | -------- | 3854 | 13400003 | task service ability error. | 3855 | 21900006 | task not found error. | 3856 3857**Example** 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 3874Queries a task details based on the task ID. This API uses a promise to return the result. 3875 3876**System capability**: SystemCapability.Request.FileTransferAgent 3877 3878**Parameters** 3879 3880 | Name| Type| Mandatory| Description| 3881 | -------- | -------- | -------- | -------- | 3882 | id | string | Yes| Task ID.| 3883 3884**Return value** 3885 3886| Type | Description | 3887| ------------------- | ------------------------- | 3888| Promise<[TaskInfo](#taskinfo10)> | Promise Promise used to return task details.| 3889 3890**Error codes** 3891For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 3892 3893 | ID| Error Message| 3894 | -------- | -------- | 3895 | 13400003 | task service ability error. | 3896 | 21900006 | task not found error. | 3897 3898**Example** 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 3913Queries the task details based on the task ID and token. This API uses an asynchronous callback to return the result. 3914 3915**System capability**: SystemCapability.Request.FileTransferAgent 3916 3917**Parameters** 3918 3919 | Name| Type| Mandatory| Description| 3920 | -------- | -------- | -------- | -------- | 3921 | id | string | Yes| Task ID.| 3922 | token | string | Yes| Token for task query.| 3923 | callback | AsyncCallback<[TaskInfo](#taskinfo10)> | Yes| Callback used to return task details.| 3924 3925**Error codes** 3926For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 3927 3928 | ID| Error Message| 3929 | -------- | -------- | 3930 | 13400003 | task service ability error. | 3931 | 21900006 | task not found error. | 3932 3933**Example** 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 3950Queries the task details based on the task ID and token. This API uses a promise to return the result. 3951 3952**System capability**: SystemCapability.Request.FileTransferAgent 3953 3954**Parameters** 3955 3956 | Name| Type| Mandatory| Description| 3957 | -------- | -------- | -------- | -------- | 3958 | id | string | Yes| Task ID.| 3959 | token | string | Yes| Token for task query.| 3960 3961**Return value** 3962 3963| Type | Description | 3964| ------------------- | ------------------------- | 3965| Promise<[TaskInfo](#taskinfo10)> | Promise Promise used to return task details.| 3966 3967**Error codes** 3968For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 3969 3970 | ID| Error Message| 3971 | -------- | -------- | 3972 | 13400003 | task service ability error. | 3973 | 21900006 | task not found error. | 3974 3975**Example** 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 3989Searches for task IDs based on [Filter](#filter10). This API uses an asynchronous callback to return the result. 3990 3991**System capability**: SystemCapability.Request.FileTransferAgent 3992 3993**Parameters** 3994 3995 | Name| Type| Mandatory| Description| 3996 | -------- | -------- | -------- | -------- | 3997 | callback | AsyncCallback<Array<string>> | Yes| Callback used to return task ID matches.| 3998 3999**Error codes** 4000For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 4001 4002 | ID| Error Message| 4003 | -------- | -------- | 4004 | 13400003 | task service ability error. | 4005 4006**Example** 4007 4008 ```ts 4009 request.agent.search((err: BusinessError, data: Array<string>) => { 4010 if (err) { 4011 console.error(`Upload task search failed. Code: ${err.code}, message: ${err.message}`); 4012 return; 4013 } 4014 console.info(`Upload task search succeeded. `); 4015 }); 4016 ``` 4017 4018## request.agent.search<sup>10+</sup> 4019 4020search(filter: Filter, callback: AsyncCallback<Array<string>>): void 4021 4022Searches for task IDs based on [Filter](#filter10). This API uses an asynchronous callback to return the result. 4023 4024**System capability**: SystemCapability.Request.FileTransferAgent 4025 4026**Parameters** 4027 4028 | Name| Type| Mandatory| Description| 4029 | -------- | -------- | -------- | -------- | 4030 | filter | [Filter](#filter10) | Yes| Filter criteria.| 4031 | callback | AsyncCallback<Array<string>> | Yes| Callback used to return task ID matches.| 4032 4033**Error codes** 4034For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 4035 4036 | ID| Error Message| 4037 | -------- | -------- | 4038 | 13400003 | task service ability error. | 4039 4040**Example** 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(`Upload task search failed. Code: ${err.code}, message: ${err.message}`); 4051 return; 4052 } 4053 console.info(`Upload task search succeeded. `); 4054 }); 4055 ``` 4056 4057 4058## request.agent.search<sup>10+</sup> 4059 4060search(filter?: Filter): Promise<Array<string>> 4061 4062Searches for task IDs based on [Filter](#filter10). This API uses a promise to return the result. 4063 4064**System capability**: SystemCapability.Request.FileTransferAgent 4065 4066**Parameters** 4067 4068 | Name| Type| Mandatory| Description| 4069 | -------- | -------- | -------- | -------- | 4070 | filter | [Filter](#filter10) | No| Filter criteria.| 4071 4072**Return value** 4073 4074| Type | Description | 4075| ------------------- | ------------------------- | 4076| Promise<Array<string>> | Promise Promise used to return task ID matches.| 4077 4078**Error codes** 4079For details about the error codes, see [Upload and Download Error Codes](./errorcode-request.md). 4080 4081 | ID| Error Message| 4082 | -------- | -------- | 4083 | 13400003 | task service ability error. | 4084 4085**Example** 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(`Upload task search succeeded. `); 4095 }).catch((err: BusinessError) => { 4096 console.error(`Upload task search failed. Code: ${err.code}, message: ${err.message}`); 4097 }); 4098 ``` 4099
