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](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](../errorcodes/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](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](../errorcodes/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](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](../errorcodes/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](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](../errorcodes/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](js-apis-inner-app-context.md#contextgetcachedir) to obtain the application storage path.<br>- In the stage model, use [AbilityContext](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| bundle | string | No| Bundle name of the application.<br>**System API**: This is a system API.| 2111| before | number | No| Unix timestamp of the end time, in milliseconds. The default value is the invoking time.| 2112| after | number | No| Unix timestamp of the start time, in milliseconds. The default value is the invoking time minus 24 hours.| 2113| state | [State](#state10) | No| Task state.| 2114| action | [Action](#action10) | No| Task action.<br>- **UPLOAD**<br>- **DOWNLOAD**| 2115| mode | [Mode](#mode10) | No| Task mode.<br>- **FOREGROUND**: foreground task.<br>- **BACKGROUND**: background task.<br>- No value: All tasks are queried.| 2116 2117## TaskInfo<sup>10+</sup> 2118Defines the data structure of the task information for query. The fields available vary depending on the query type. 2119 2120**System capability**: SystemCapability.Request.FileTransferAgent 2121 2122| Name| Type| Mandatory| Description| 2123| -------- | -------- | -------- | -------- | 2124| uid | string | No| UID of the application. It is only available for query by system applications.<br>**System API**: This is a system API.| 2125| bundle | string | No| Bundle name of the application. It is only available for query by system applications.<br>**System API**: This is a system API.| 2126| 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.| 2127| url | string | No| Task URL.<br>- It can be obtained through [request.agent.show<sup>10+</sup>](#requestagentshow10-1), [request.agent.touch<sup>10+</sup>](#requestagenttouch10-1), or [request.agent.query<sup>10+</sup>](#requestagentquery10-1). When [request.agent.query<sup>10+</sup>](#requestagentquery10-1) is used, an empty string is returned.| 2128| data | string \| Array<[FormItem](#formitem10)> | No| Task value.<br>- It can be obtained through [request.agent.show<sup>10+</sup>](#requestagentshow10-1), [request.agent.touch<sup>10+</sup>](#requestagenttouch10-1), or [request.agent.query<sup>10+</sup>](#requestagentquery10-1). When [request.agent.query<sup>10+</sup>](#requestagentquery10-1) is used, an empty string is returned.| 2129| tid | string | Yes| Task ID.| 2130| title | string | Yes| Task title.| 2131| description | string | Yes| Task description.| 2132| action | [Action](#action10) | Yes| Task action.<br>- **UPLOAD**<br>- **DOWNLOAD**| 2133| mode | [Mode](#mode10) | Yes| Task mode.<br>- **FOREGROUND**: foreground task.<br>- **BACKGROUND**: background task.| 2134| 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.| 2135| mimeType | string | Yes| MIME type in the task configuration.| 2136| progress | [Progress](#progress10) | Yes| Task progress.| 2137| gauge | boolean | Yes| Whether to send progress notifications. This parameter applies only to background tasks.| 2138| 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). 2139| mtime | number | Yes| Unix timestamp when the task state changes, in milliseconds. The value is generated by the system of the current device.| 2140| retry | boolean | Yes| Whether automatic retry is enabled for the task. This parameter applies only to background tasks.| 2141| tries | number | Yes| Number of retries of the task.| 2142| 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.| 2143| reason | string | Yes| Reason why the task is waiting, failed, stopped, or paused.| 2144| extras | string | No| Extra information of the task| 2145 2146 2147## Task<sup>10+</sup> 2148Implements 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). 2149 2150### Attributes 2151Task attributes include the task ID and task configuration. 2152 2153**System capability**: SystemCapability.Request.FileTransferAgent 2154 2155| Name| Type| Mandatory| Description| 2156| -------- | -------- | -------- | -------- | 2157| tid | string | Yes| Task ID, which is unique in the system and is automatically generated by the system.| 2158| config | [Config](#config10) | Yes| Task configuration.| 2159 2160 2161### on('progress')<sup>10+</sup> 2162 2163on(event: 'progress', callback: (progress: Progress) => void): void 2164 2165Subscribes to task progress changes. This API uses a callback to return the result asynchronously. 2166 2167**System capability**: SystemCapability.Request.FileTransferAgent 2168 2169**Parameters** 2170 2171 | Name| Type| Mandatory| Description| 2172 | -------- | -------- | -------- | -------- | 2173 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'progress'**, indicating the task progress.| 2174 | callback | function | Yes| Callback used to return the data structure of the task progress.| 2175 2176**Error codes** 2177 2178For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 2179 2180 | ID| Error Message| 2181 | -------- | -------- | 2182 | 21900005 | task mode error. | 2183 2184**Example** 2185 2186 ```ts 2187 let attachments: Array<request.agent.FormItem> = [{ 2188 name: "taskOnTest", 2189 value: { 2190 filename: "taskOnTest.avi", 2191 mimeType: "application/octet-stream", 2192 path: "./taskOnTest.avi", 2193 } 2194 }]; 2195 let config: request.agent.Config = { 2196 action: request.agent.Action.UPLOAD, 2197 url: 'http://127.0.0.1', 2198 title: 'taskOnTest', 2199 description: 'Sample code for event listening', 2200 mode: request.agent.Mode.FOREGROUND, 2201 overwrite: false, 2202 method: "PUT", 2203 data: attachments, 2204 saveas: "./", 2205 network: request.agent.Network.CELLULAR, 2206 metered: false, 2207 roaming: true, 2208 retry: true, 2209 redirect: true, 2210 index: 0, 2211 begins: 0, 2212 ends: -1, 2213 gauge: false, 2214 precise: false, 2215 token: "it is a secret" 2216 }; 2217 let createOnCallback = (progress: request.agent.Progress) => { 2218 console.info('upload task progress.'); 2219 }; 2220 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2221 task.on('progress', createOnCallback); 2222 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2223 }).catch((err: BusinessError) => { 2224 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2225 }); 2226 ``` 2227 2228> **NOTE** 2229> 2230> 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). 2231 2232### on('completed')<sup>10+</sup> 2233 2234on(event: 'completed', callback: (progress: Progress) => void): void 2235 2236Subscribes to task completion events. This API uses a callback to return the result asynchronously. 2237 2238**System capability**: SystemCapability.Request.FileTransferAgent 2239 2240**Parameters** 2241 2242 | Name| Type| Mandatory| Description| 2243 | -------- | -------- | -------- | -------- | 2244 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'completed'**, indicating task completion.| 2245 | callback | function | Yes| Callback used to return the data structure of the task progress.| 2246 2247**Error codes** 2248 2249For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 2250 2251 | ID| Error Message| 2252 | -------- | -------- | 2253 | 21900005 | task mode error. | 2254 2255**Example** 2256 2257 ```ts 2258 let attachments: Array<request.agent.FormItem> = [{ 2259 name: "taskOnTest", 2260 value: { 2261 filename: "taskOnTest.avi", 2262 mimeType: "application/octet-stream", 2263 path: "./taskOnTest.avi", 2264 } 2265 }]; 2266 let config: request.agent.Config = { 2267 action: request.agent.Action.UPLOAD, 2268 url: 'http://127.0.0.1', 2269 title: 'taskOnTest', 2270 description: 'Sample code for event listening', 2271 mode: request.agent.Mode.FOREGROUND, 2272 overwrite: false, 2273 method: "PUT", 2274 data: attachments, 2275 saveas: "./", 2276 network: request.agent.Network.CELLULAR, 2277 metered: false, 2278 roaming: true, 2279 retry: true, 2280 redirect: true, 2281 index: 0, 2282 begins: 0, 2283 ends: -1, 2284 gauge: false, 2285 precise: false, 2286 token: "it is a secret" 2287 }; 2288 let createOnCallback = (progress: request.agent.Progress) => { 2289 console.info('upload task completed.'); 2290 }; 2291 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2292 task.on('completed', createOnCallback); 2293 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2294 }).catch((err: BusinessError) => { 2295 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2296 }); 2297 ``` 2298 2299> **NOTE** 2300> 2301> 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). 2302 2303### on('failed')<sup>10+</sup> 2304 2305on(event: 'failed', callback: (progress: Progress) => void): void 2306 2307Subscribes to task failure events. This API uses a callback to return the result asynchronously. 2308 2309**System capability**: SystemCapability.Request.FileTransferAgent 2310 2311**Parameters** 2312 2313 | Name| Type| Mandatory| Description| 2314 | -------- | -------- | -------- | -------- | 2315 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'failed'**, indicating task failure.| 2316 | callback | function | Yes| Callback used to return the data structure of the task progress.| 2317 2318**Error codes** 2319 2320For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 2321 2322 | ID| Error Message| 2323 | -------- | -------- | 2324 | 21900005 | task mode error. | 2325 2326**Example** 2327 2328 ```ts 2329 let attachments: Array<request.agent.FormItem> = [{ 2330 name: "taskOnTest", 2331 value: { 2332 filename: "taskOnTest.avi", 2333 mimeType: "application/octet-stream", 2334 path: "./taskOnTest.avi", 2335 } 2336 }]; 2337 let config: request.agent.Config = { 2338 action: request.agent.Action.UPLOAD, 2339 url: 'http://127.0.0.1', 2340 title: 'taskOnTest', 2341 description: 'Sample code for event listening', 2342 mode: request.agent.Mode.FOREGROUND, 2343 overwrite: false, 2344 method: "PUT", 2345 data: attachments, 2346 saveas: "./", 2347 network: request.agent.Network.CELLULAR, 2348 metered: false, 2349 roaming: true, 2350 retry: true, 2351 redirect: true, 2352 index: 0, 2353 begins: 0, 2354 ends: -1, 2355 gauge: false, 2356 precise: false, 2357 token: "it is a secret" 2358 }; 2359 let createOnCallback = (progress: request.agent.Progress) => { 2360 console.info('upload task failed.'); 2361 }; 2362 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2363 task.on('failed', createOnCallback); 2364 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2365 }).catch((err: BusinessError) => { 2366 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2367 }); 2368 ``` 2369 2370> **NOTE** 2371> 2372> 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). 2373 2374### on('pause')<sup>11+</sup> 2375 2376on(event: 'pause', callback: (progress: Progress) => void): void 2377 2378Subscribes to task pause events. This API uses a callback to return the result asynchronously. 2379 2380**System capability**: SystemCapability.Request.FileTransferAgent 2381 2382**Parameters** 2383 2384 | Name| Type| Mandatory| Description| 2385 | -------- | -------- | -------- | -------- | 2386 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'pause'**, indicating task pause.| 2387 | callback | function | Yes| Callback used to return the data structure of the task progress.| 2388 2389**Error codes** 2390 2391For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 2392 2393**Example** 2394 2395 ```ts 2396 let attachments: Array<request.agent.FormItem> = [{ 2397 name: "taskOnTest", 2398 value: { 2399 filename: "taskOnTest.avi", 2400 mimeType: "application/octet-stream", 2401 path: "./taskOnTest.avi", 2402 } 2403 }]; 2404 let config: request.agent.Config = { 2405 action: request.agent.Action.UPLOAD, 2406 url: 'http://127.0.0.1', 2407 title: 'taskOnTest', 2408 description: 'Sample code for event listening', 2409 mode: request.agent.Mode.FOREGROUND, 2410 overwrite: false, 2411 method: "PUT", 2412 data: attachments, 2413 saveas: "./", 2414 network: request.agent.Network.CELLULAR, 2415 metered: false, 2416 roaming: true, 2417 retry: true, 2418 redirect: true, 2419 index: 0, 2420 begins: 0, 2421 ends: -1, 2422 gauge: false, 2423 precise: false, 2424 token: "it is a secret" 2425 }; 2426 let createOnCallback = (progress: request.agent.Progress) => { 2427 console.info('upload task pause.'); 2428 }; 2429 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2430 task.on('pause', createOnCallback); 2431 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2432 }).catch((err: BusinessError) => { 2433 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2434 }); 2435 ``` 2436 2437> **NOTE** 2438> 2439> 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). 2440 2441### on('resume')<sup>11+</sup> 2442 2443on(event: 'resume', callback: (progress: Progress) => void): void 2444 2445Subscribes to task resume events. This API uses a callback to return the result asynchronously. 2446 2447**System capability**: SystemCapability.Request.FileTransferAgent 2448 2449**Parameters** 2450 2451 | Name| Type| Mandatory| Description| 2452 | -------- | -------- | -------- | -------- | 2453 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'resume'**, indicating task resume.| 2454 | callback | function | Yes| Callback used to return the data structure of the task progress.| 2455 2456**Error codes** 2457 2458For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 2459 2460**Example** 2461 2462 ```ts 2463 let attachments: Array<request.agent.FormItem> = [{ 2464 name: "taskOnTest", 2465 value: { 2466 filename: "taskOnTest.avi", 2467 mimeType: "application/octet-stream", 2468 path: "./taskOnTest.avi", 2469 } 2470 }]; 2471 let config: request.agent.Config = { 2472 action: request.agent.Action.UPLOAD, 2473 url: 'http://127.0.0.1', 2474 title: 'taskOnTest', 2475 description: 'Sample code for event listening', 2476 mode: request.agent.Mode.FOREGROUND, 2477 overwrite: false, 2478 method: "PUT", 2479 data: attachments, 2480 saveas: "./", 2481 network: request.agent.Network.CELLULAR, 2482 metered: false, 2483 roaming: true, 2484 retry: true, 2485 redirect: true, 2486 index: 0, 2487 begins: 0, 2488 ends: -1, 2489 gauge: false, 2490 precise: false, 2491 token: "it is a secret" 2492 }; 2493 let createOnCallback = (progress: request.agent.Progress) => { 2494 console.info('upload task resume.'); 2495 }; 2496 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2497 task.on('resume', createOnCallback); 2498 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2499 }).catch((err: BusinessError) => { 2500 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2501 }); 2502 ``` 2503 2504> **NOTE** 2505> 2506> 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). 2507 2508### on('remove')<sup>11+</sup> 2509 2510on(event: 'remove', callback: (progress: Progress) => void): void 2511 2512Subscribes to task removal events. This API uses a callback to return the result asynchronously. 2513 2514**System capability**: SystemCapability.Request.FileTransferAgent 2515 2516**Parameters** 2517 2518 | Name| Type| Mandatory| Description| 2519 | -------- | -------- | -------- | -------- | 2520 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'remove'**, indicating task removal.| 2521 | callback | function | Yes| Callback used to return the data structure of the task progress.| 2522 2523**Error codes** 2524 2525For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 2526 2527**Example** 2528 2529 ```ts 2530 let attachments: Array<request.agent.FormItem> = [{ 2531 name: "taskOnTest", 2532 value: { 2533 filename: "taskOnTest.avi", 2534 mimeType: "application/octet-stream", 2535 path: "./taskOnTest.avi", 2536 } 2537 }]; 2538 let config: request.agent.Config = { 2539 action: request.agent.Action.UPLOAD, 2540 url: 'http://127.0.0.1', 2541 title: 'taskOnTest', 2542 description: 'Sample code for event listening', 2543 mode: request.agent.Mode.FOREGROUND, 2544 overwrite: false, 2545 method: "PUT", 2546 data: attachments, 2547 saveas: "./", 2548 network: request.agent.Network.CELLULAR, 2549 metered: false, 2550 roaming: true, 2551 retry: true, 2552 redirect: true, 2553 index: 0, 2554 begins: 0, 2555 ends: -1, 2556 gauge: false, 2557 precise: false, 2558 token: "it is a secret" 2559 }; 2560 let createOnCallback = (progress: request.agent.Progress) => { 2561 console.info('upload task remove.'); 2562 }; 2563 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2564 task.on('remove', createOnCallback); 2565 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2566 }).catch((err: BusinessError) => { 2567 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2568 }); 2569 ``` 2570 2571> **NOTE** 2572> 2573> 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). 2574 2575### off('progress')<sup>10+</sup> 2576 2577off(event: 'progress', callback?: (progress: Progress) => void): void 2578 2579Unsubscribes from task progress events. 2580 2581**System capability**: SystemCapability.Request.FileTransferAgent 2582 2583**Parameters** 2584 2585 | Name| Type| Mandatory| Description| 2586 | -------- | -------- | -------- | -------- | 2587 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'progress'**, indicating the task progress.| 2588 | callback | function | No| Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered.| 2589 2590**Error codes** 2591 2592For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 2593 2594 | ID| Error Message| 2595 | -------- | -------- | 2596 | 21900005 | task mode error. | 2597 2598**Example** 2599 2600 ```ts 2601 let attachments: Array<request.agent.FormItem> = [{ 2602 name: "taskOffTest", 2603 value: { 2604 filename: "taskOffTest.avi", 2605 mimeType: "application/octet-stream", 2606 path: "./taskOffTest.avi", 2607 } 2608 }]; 2609 let config: request.agent.Config = { 2610 action: request.agent.Action.UPLOAD, 2611 url: 'http://127.0.0.1', 2612 title: 'taskOffTest', 2613 description: 'Sample code for event listening', 2614 mode: request.agent.Mode.FOREGROUND, 2615 overwrite: false, 2616 method: "PUT", 2617 data: attachments, 2618 saveas: "./", 2619 network: request.agent.Network.CELLULAR, 2620 metered: false, 2621 roaming: true, 2622 retry: true, 2623 redirect: true, 2624 index: 0, 2625 begins: 0, 2626 ends: -1, 2627 gauge: false, 2628 precise: false, 2629 token: "it is a secret" 2630 }; 2631 let createOffCallback1 = (progress: request.agent.Progress) => { 2632 console.info('upload task progress.'); 2633 }; 2634 let createOffCallback2 = (progress: request.agent.Progress) => { 2635 console.info('upload task progress.'); 2636 }; 2637 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2638 task.on('progress', createOffCallback1); 2639 task.on('progress', createOffCallback2); 2640 // Unsubscribe from createOffCallback1. 2641 task.off('progress', createOffCallback1); 2642 // Unsubscribe from all callbacks of task progress changes. 2643 task.off('progress'); 2644 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2645 }).catch((err: BusinessError) => { 2646 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2647 }); 2648 ``` 2649 2650> **NOTE** 2651> 2652> 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). 2653 2654### off('completed')<sup>10+</sup> 2655 2656off(event: 'completed', callback?: (progress: Progress) => void): void 2657 2658Unsubscribes from task completion events. 2659 2660**System capability**: SystemCapability.Request.FileTransferAgent 2661 2662**Parameters** 2663 2664 | Name| Type| Mandatory| Description| 2665 | -------- | -------- | -------- | -------- | 2666 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'completed'**, indicating task completion.| 2667 | callback | function | No| Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered.| 2668 2669**Error codes** 2670 2671For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 2672 2673 | ID| Error Message| 2674 | -------- | -------- | 2675 | 21900005 | task mode error. | 2676 2677**Example** 2678 2679 ```ts 2680 let attachments: Array<request.agent.FormItem> = [{ 2681 name: "taskOffTest", 2682 value: { 2683 filename: "taskOffTest.avi", 2684 mimeType: "application/octet-stream", 2685 path: "./taskOffTest.avi", 2686 } 2687 }]; 2688 let config: request.agent.Config = { 2689 action: request.agent.Action.UPLOAD, 2690 url: 'http://127.0.0.1', 2691 title: 'taskOffTest', 2692 description: 'Sample code for event listening', 2693 mode: request.agent.Mode.FOREGROUND, 2694 overwrite: false, 2695 method: "PUT", 2696 data: attachments, 2697 saveas: "./", 2698 network: request.agent.Network.CELLULAR, 2699 metered: false, 2700 roaming: true, 2701 retry: true, 2702 redirect: true, 2703 index: 0, 2704 begins: 0, 2705 ends: -1, 2706 gauge: false, 2707 precise: false, 2708 token: "it is a secret" 2709 }; 2710 let createOffCallback1 = (progress: request.agent.Progress) => { 2711 console.info('upload task completed.'); 2712 }; 2713 let createOffCallback2 = (progress: request.agent.Progress) => { 2714 console.info('upload task completed.'); 2715 }; 2716 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2717 task.on('completed', createOffCallback1); 2718 task.on('completed', createOffCallback2); 2719 // Unsubscribe from createOffCallback1. 2720 task.off('completed', createOffCallback1); 2721 // Unsubscribe from all callbacks of the task completion events. 2722 task.off('completed'); 2723 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2724 }).catch((err: BusinessError) => { 2725 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2726 }); 2727 ``` 2728 2729> **NOTE** 2730> 2731> 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). 2732 2733### off('failed')<sup>10+</sup> 2734 2735off(event: 'failed', callback?: (progress: Progress) => void): void 2736 2737Unsubscribes from task failure events. 2738 2739**System capability**: SystemCapability.Request.FileTransferAgent 2740 2741**Parameters** 2742 2743 | Name| Type| Mandatory| Description| 2744 | -------- | -------- | -------- | -------- | 2745 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'failed'**, indicating task failure.| 2746 | callback | function | No| Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered.| 2747 2748**Error codes** 2749 2750For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 2751 2752 | ID| Error Message| 2753 | -------- | -------- | 2754 | 21900005 | task mode error. | 2755 2756**Example** 2757 2758 ```ts 2759 let attachments: Array<request.agent.FormItem> = [{ 2760 name: "taskOffTest", 2761 value: { 2762 filename: "taskOffTest.avi", 2763 mimeType: "application/octet-stream", 2764 path: "./taskOffTest.avi", 2765 } 2766 }]; 2767 let config: request.agent.Config = { 2768 action: request.agent.Action.UPLOAD, 2769 url: 'http://127.0.0.1', 2770 title: 'taskOffTest', 2771 description: 'Sample code for event listening', 2772 mode: request.agent.Mode.FOREGROUND, 2773 overwrite: false, 2774 method: "PUT", 2775 data: attachments, 2776 saveas: "./", 2777 network: request.agent.Network.CELLULAR, 2778 metered: false, 2779 roaming: true, 2780 retry: true, 2781 redirect: true, 2782 index: 0, 2783 begins: 0, 2784 ends: -1, 2785 gauge: false, 2786 precise: false, 2787 token: "it is a secret" 2788 }; 2789 let createOffCallback1 = (progress: request.agent.Progress) => { 2790 console.info('upload task failed.'); 2791 }; 2792 let createOffCallback2 = (progress: request.agent.Progress) => { 2793 console.info('upload task failed.'); 2794 }; 2795 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2796 task.on('failed', createOffCallback1); 2797 task.on('failed', createOffCallback2); 2798 // Unsubscribe from createOffCallback1. 2799 task.off('failed', createOffCallback1); 2800 // Unsubscribe from all callbacks of the task failure events. 2801 task.off('failed'); 2802 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2803 }).catch((err: BusinessError) => { 2804 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2805 }); 2806 ``` 2807 2808> **NOTE** 2809> 2810> 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). 2811 2812### off('pause')<sup>11+</sup> 2813 2814off(event: 'pause', callback?: (progress: Progress) => void): void 2815 2816Unsubscribes from the foreground task pause event. 2817 2818**System capability**: SystemCapability.Request.FileTransferAgent 2819 2820**Parameters** 2821 2822 | Name| Type| Mandatory| Description| 2823 | -------- | -------- | -------- | -------- | 2824 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'pause'**, indicating task pause.| 2825 | callback | function | No| Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered.| 2826 2827**Error codes** 2828 2829For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 2830 2831**Example** 2832 2833 ```ts 2834 let attachments: Array<request.agent.FormItem> = [{ 2835 name: "taskOffTest", 2836 value: { 2837 filename: "taskOffTest.avi", 2838 mimeType: "application/octet-stream", 2839 path: "./taskOffTest.avi", 2840 } 2841 }]; 2842 let config: request.agent.Config = { 2843 action: request.agent.Action.UPLOAD, 2844 url: 'http://127.0.0.1', 2845 title: 'taskOffTest', 2846 description: 'Sample code for event listening', 2847 mode: request.agent.Mode.FOREGROUND, 2848 overwrite: false, 2849 method: "PUT", 2850 data: attachments, 2851 saveas: "./", 2852 network: request.agent.Network.CELLULAR, 2853 metered: false, 2854 roaming: true, 2855 retry: true, 2856 redirect: true, 2857 index: 0, 2858 begins: 0, 2859 ends: -1, 2860 gauge: false, 2861 precise: false, 2862 token: "it is a secret" 2863 }; 2864 let createOffCallback1 = (progress: request.agent.Progress) => { 2865 console.info('upload task pause.'); 2866 }; 2867 let createOffCallback2 = (progress: request.agent.Progress) => { 2868 console.info('upload task pause.'); 2869 }; 2870 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2871 task.on('pause', createOffCallback1); 2872 task.on('pause', createOffCallback2); 2873 // Unsubscribe from createOffCallback1. 2874 task.off('pause', createOffCallback1); 2875 // Unsubscribe from all callbacks of the foreground task pause event. 2876 task.off('pause'); 2877 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2878 }).catch((err: BusinessError) => { 2879 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2880 }); 2881 ``` 2882 2883> **NOTE** 2884> 2885> 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). 2886 2887### off('resume')<sup>11+</sup> 2888 2889off(event: 'resume', callback?: (progress: Progress) => void): void 2890 2891Unsubscribes from the foreground task resume event. 2892 2893**System capability**: SystemCapability.Request.FileTransferAgent 2894 2895**Parameters** 2896 2897 | Name| Type| Mandatory| Description| 2898 | -------- | -------- | -------- | -------- | 2899 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'resume'**, indicating task resume.| 2900 | callback | function | No| Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered.| 2901 2902**Error codes** 2903 2904For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 2905 2906**Example** 2907 2908 ```ts 2909 let attachments: Array<request.agent.FormItem> = [{ 2910 name: "taskOffTest", 2911 value: { 2912 filename: "taskOffTest.avi", 2913 mimeType: "application/octet-stream", 2914 path: "./taskOffTest.avi", 2915 } 2916 }]; 2917 let config: request.agent.Config = { 2918 action: request.agent.Action.UPLOAD, 2919 url: 'http://127.0.0.1', 2920 title: 'taskOffTest', 2921 description: 'Sample code for event listening', 2922 mode: request.agent.Mode.FOREGROUND, 2923 overwrite: false, 2924 method: "PUT", 2925 data: attachments, 2926 saveas: "./", 2927 network: request.agent.Network.CELLULAR, 2928 metered: false, 2929 roaming: true, 2930 retry: true, 2931 redirect: true, 2932 index: 0, 2933 begins: 0, 2934 ends: -1, 2935 gauge: false, 2936 precise: false, 2937 token: "it is a secret" 2938 }; 2939 let createOffCallback1 = (progress: request.agent.Progress) => { 2940 console.info('upload task resume.'); 2941 }; 2942 let createOffCallback2 = (progress: request.agent.Progress) => { 2943 console.info('upload task resume.'); 2944 }; 2945 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2946 task.on('resume', createOffCallback1); 2947 task.on('resume', createOffCallback2); 2948 // Unsubscribe from createOffCallback1. 2949 task.off('resume', createOffCallback1); 2950 // Unsubscribe from all callbacks of the foreground task resume event. 2951 task.off('resume'); 2952 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2953 }).catch((err: BusinessError) => { 2954 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2955 }); 2956 ``` 2957 2958> **NOTE** 2959> 2960> 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). 2961 2962### off('remove')<sup>11+</sup> 2963 2964off(event: 'remove', callback?: (progress: Progress) => void): void 2965 2966Unsubscribes from the task removal event. 2967 2968**System capability**: SystemCapability.Request.FileTransferAgent 2969 2970**Parameters** 2971 2972 | Name| Type| Mandatory| Description| 2973 | -------- | -------- | -------- | -------- | 2974 | event | string | Yes| Type of the event to subscribe to.<br>The value is **'remove'**, indicating task removal.| 2975 | callback | function | No| Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered.| 2976 2977**Error codes** 2978 2979For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 2980 2981**Example** 2982 2983 ```ts 2984 let attachments: Array<request.agent.FormItem> = [{ 2985 name: "taskOffTest", 2986 value: { 2987 filename: "taskOffTest.avi", 2988 mimeType: "application/octet-stream", 2989 path: "./taskOffTest.avi", 2990 } 2991 }]; 2992 let config: request.agent.Config = { 2993 action: request.agent.Action.UPLOAD, 2994 url: 'http://127.0.0.1', 2995 title: 'taskOffTest', 2996 description: 'Sample code for event listening', 2997 mode: request.agent.Mode.FOREGROUND, 2998 overwrite: false, 2999 method: "PUT", 3000 data: attachments, 3001 saveas: "./", 3002 network: request.agent.Network.CELLULAR, 3003 metered: false, 3004 roaming: true, 3005 retry: true, 3006 redirect: true, 3007 index: 0, 3008 begins: 0, 3009 ends: -1, 3010 gauge: false, 3011 precise: false, 3012 token: "it is a secret" 3013 }; 3014 let createOffCallback1 = (progress: request.agent.Progress) => { 3015 console.info('upload task remove.'); 3016 }; 3017 let createOffCallback2 = (progress: request.agent.Progress) => { 3018 console.info('upload task remove.'); 3019 }; 3020 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3021 task.on('remove', createOffCallback1); 3022 task.on('remove', createOffCallback2); 3023 // Unsubscribe from createOffCallback1. 3024 task.off('remove', createOffCallback1); 3025 // Unsubscribe from all callbacks of the task removal event. 3026 task.off('remove'); 3027 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 3028 }).catch((err: BusinessError) => { 3029 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 3030 }); 3031 ``` 3032 3033> **NOTE** 3034> 3035> 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). 3036 3037### start<sup>10+</sup> 3038 3039start(callback: AsyncCallback<void>): void 3040 3041Starts this task. This API cannot be used to start an initialized task. This API uses an asynchronous callback to return the result. 3042 3043**Required permissions**: ohos.permission.INTERNET 3044 3045**System capability**: SystemCapability.Request.FileTransferAgent 3046 3047**Parameters** 3048 3049 | Name| Type| Mandatory| Description| 3050 | -------- | -------- | -------- | -------- | 3051 | callback | function | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 3052 3053**Error codes** 3054 3055For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 3056 3057 | ID| Error Message| 3058 | -------- | -------- | 3059 | 13400003 | task service ability error. | 3060 | 21900007 | task state error. | 3061 3062**Example** 3063 3064 ```ts 3065 let config: request.agent.Config = { 3066 action: request.agent.Action.DOWNLOAD, 3067 url: 'http://127.0.0.1', 3068 title: 'taskStartTest', 3069 description: 'Sample code for start the download task', 3070 mode: request.agent.Mode.BACKGROUND, 3071 overwrite: false, 3072 method: "GET", 3073 data: "", 3074 saveas: "./", 3075 network: request.agent.Network.CELLULAR, 3076 metered: false, 3077 roaming: true, 3078 retry: true, 3079 redirect: true, 3080 index: 0, 3081 begins: 0, 3082 ends: -1, 3083 gauge: false, 3084 precise: false, 3085 token: "it is a secret" 3086 }; 3087 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3088 task.start((err: BusinessError) => { 3089 if (err) { 3090 console.error(`Failed to start the download task, Code: ${err.code}, message: ${err.message}`); 3091 return; 3092 } 3093 console.info(`Succeeded in starting a download task.`); 3094 }); 3095 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 3096 }).catch((err: BusinessError) => { 3097 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 3098 }); 3099 ``` 3100 3101> **NOTE** 3102> 3103> 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). 3104 3105### start<sup>10+</sup> 3106 3107start(): Promise<void> 3108 3109Starts this task. This API cannot be used to start an initialized task. This API uses a promise to return the result. 3110 3111**Required permissions**: ohos.permission.INTERNET 3112 3113**System capability**: SystemCapability.Request.FileTransferAgent 3114 3115**Return value** 3116 3117| Type | Description | 3118| ------------------- | ------------------------- | 3119| Promise<void> | Promise that returns no value.| 3120 3121**Error codes** 3122 3123For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 3124 3125 | ID| Error Message| 3126 | -------- | -------- | 3127 | 13400003 | task service ability error. | 3128 | 21900007 | task state error. | 3129 3130**Example** 3131 3132 ```ts 3133 let config: request.agent.Config = { 3134 action: request.agent.Action.DOWNLOAD, 3135 url: 'http://127.0.0.1', 3136 title: 'taskStartTest', 3137 description: 'Sample code for start the download task', 3138 mode: request.agent.Mode.BACKGROUND, 3139 overwrite: false, 3140 method: "GET", 3141 data: "", 3142 saveas: "./", 3143 network: request.agent.Network.CELLULAR, 3144 metered: false, 3145 roaming: true, 3146 retry: true, 3147 redirect: true, 3148 index: 0, 3149 begins: 0, 3150 ends: -1, 3151 gauge: false, 3152 precise: false, 3153 token: "it is a secret" 3154 }; 3155 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3156 task.start().then(() => { 3157 console.info(`Succeeded in starting a download task.`); 3158 }).catch((err: BusinessError) => { 3159 console.error(`Failed to start the download task, Code: ${err.code}, message: ${err.message}`); 3160 }); 3161 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 3162 }).catch((err: BusinessError) => { 3163 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 3164 }); 3165 ``` 3166 3167> **NOTE** 3168> 3169> 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). 3170 3171### pause<sup>10+</sup> 3172 3173pause(callback: AsyncCallback<void>): void 3174 3175Pauses 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. 3176 3177**System capability**: SystemCapability.Request.FileTransferAgent 3178 3179**Parameters** 3180 3181 | Name| Type| Mandatory| Description| 3182 | -------- | -------- | -------- | -------- | 3183 | callback | function | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 3184 3185**Error codes** 3186 3187For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 3188 3189 | ID| Error Message| 3190 | -------- | -------- | 3191 | 13400003 | task service ability error. | 3192 | 21900005 | task mode error. | 3193 | 21900007 | task state error. | 3194 3195**Example** 3196 3197 ```ts 3198 let config: request.agent.Config = { 3199 action: request.agent.Action.DOWNLOAD, 3200 url: 'http://127.0.0.1', 3201 title: 'taskPauseTest', 3202 description: 'Sample code for pause the download task', 3203 mode: request.agent.Mode.BACKGROUND, 3204 overwrite: false, 3205 method: "GET", 3206 data: "", 3207 saveas: "./", 3208 network: request.agent.Network.CELLULAR, 3209 metered: false, 3210 roaming: true, 3211 retry: true, 3212 redirect: true, 3213 index: 0, 3214 begins: 0, 3215 ends: -1, 3216 gauge: false, 3217 precise: false, 3218 token: "it is a secret" 3219 }; 3220 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3221 task.pause((err: BusinessError) => { 3222 if (err) { 3223 console.error(`Failed to pause the download task, Code: ${err.code}, message: ${err.message}`); 3224 return; 3225 } 3226 console.info(`Succeeded in pausing a download task. `); 3227 }); 3228 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 3229 }).catch((err: BusinessError) => { 3230 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 3231 }); 3232 ``` 3233 3234> **NOTE** 3235> 3236> The error code **21900005 task mode error** is removed from API version 11. 3237 3238### pause<sup>10+</sup> 3239 3240pause(): Promise<void> 3241 3242Pauses 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. 3243 3244**System capability**: SystemCapability.Request.FileTransferAgent 3245 3246**Return value** 3247 3248| Type | Description | 3249| ------------------- | ------------------------- | 3250| Promise<void> | Promise that returns no value.| 3251 3252**Error codes** 3253 3254For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 3255 3256 | ID| Error Message| 3257 | -------- | -------- | 3258 | 13400003 | task service ability error. | 3259 | 21900005 | task mode error. | 3260 | 21900007 | task state error. | 3261 3262**Example** 3263 3264 ```ts 3265 let config: request.agent.Config = { 3266 action: request.agent.Action.DOWNLOAD, 3267 url: 'http://127.0.0.1', 3268 title: 'taskPauseTest', 3269 description: 'Sample code for pause the download task', 3270 mode: request.agent.Mode.BACKGROUND, 3271 overwrite: false, 3272 method: "GET", 3273 data: "", 3274 saveas: "./", 3275 network: request.agent.Network.CELLULAR, 3276 metered: false, 3277 roaming: true, 3278 retry: true, 3279 redirect: true, 3280 index: 0, 3281 begins: 0, 3282 ends: -1, 3283 gauge: false, 3284 precise: false, 3285 token: "it is a secret" 3286 }; 3287 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3288 task.pause().then(() => { 3289 console.info(`Succeeded in pausing a download task. `); 3290 }).catch((err: BusinessError) => { 3291 console.error(`Failed to pause the upload task, Code: ${err.code}, message: ${err.message}`); 3292 }); 3293 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 3294 }).catch((err: BusinessError) => { 3295 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 3296 }); 3297 ``` 3298 3299> **NOTE** 3300> 3301> The error code **21900005 task mode error** is removed from API version 11. 3302 3303### resume<sup>10+</sup> 3304 3305resume(callback: AsyncCallback<void>): void 3306 3307Resumes this task. This API can be used to resume a paused background task. This API uses an asynchronous callback to return the result. 3308 3309**Required permissions**: ohos.permission.INTERNET 3310 3311**System capability**: SystemCapability.Request.FileTransferAgent 3312 3313**Parameters** 3314 3315 | Name| Type| Mandatory| Description| 3316 | -------- | -------- | -------- | -------- | 3317 | callback | function | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 3318 3319**Error codes** 3320 3321For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 3322 3323 | ID| Error Message| 3324 | -------- | -------- | 3325 | 13400003 | task service ability error. | 3326 | 21900005 | task mode error. | 3327 | 21900007 | task state error. | 3328 3329**Example** 3330 3331 ```ts 3332 let config: request.agent.Config = { 3333 action: request.agent.Action.DOWNLOAD, 3334 url: 'http://127.0.0.1', 3335 title: 'taskResumeTest', 3336 description: 'Sample code for resume the download task', 3337 mode: request.agent.Mode.BACKGROUND, 3338 overwrite: false, 3339 method: "GET", 3340 data: "", 3341 saveas: "./", 3342 network: request.agent.Network.CELLULAR, 3343 metered: false, 3344 roaming: true, 3345 retry: true, 3346 redirect: true, 3347 index: 0, 3348 begins: 0, 3349 ends: -1, 3350 gauge: false, 3351 precise: false, 3352 token: "it is a secret" 3353 }; 3354 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3355 task.resume((err: BusinessError) => { 3356 if (err) { 3357 console.error(`Failed to resume the download task, Code: ${err.code}, message: ${err.message}`); 3358 return; 3359 } 3360 console.info(`Succeeded in resuming a download task. `); 3361 }); 3362 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 3363 }).catch((err: BusinessError) => { 3364 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 3365 }); 3366 ``` 3367 3368> **NOTE** 3369> 3370> The error code **21900005 task mode error** is removed from API version 11. 3371 3372 3373### resume<sup>10+</sup> 3374 3375resume(): Promise<void> 3376 3377Resumes this task. This API can be used to resume a paused background task. This API uses a promise to return the result. 3378 3379**Required permissions**: ohos.permission.INTERNET 3380 3381**System capability**: SystemCapability.Request.FileTransferAgent 3382 3383**Return value** 3384 3385| Type | Description | 3386| ------------------- | ------------------------- | 3387| Promise<void> | Promise that returns no value.| 3388 3389**Error codes** 3390 3391For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 3392 3393 | ID| Error Message| 3394 | -------- | -------- | 3395 | 13400003 | task service ability error. | 3396 | 21900005 | task mode error. | 3397 | 21900007 | task state error. | 3398 3399**Example** 3400 3401 ```ts 3402 let config: request.agent.Config = { 3403 action: request.agent.Action.DOWNLOAD, 3404 url: 'http://127.0.0.1', 3405 title: 'taskResumeTest', 3406 description: 'Sample code for resume the download task', 3407 mode: request.agent.Mode.BACKGROUND, 3408 overwrite: false, 3409 method: "GET", 3410 data: "", 3411 saveas: "./", 3412 network: request.agent.Network.CELLULAR, 3413 metered: false, 3414 roaming: true, 3415 retry: true, 3416 redirect: true, 3417 index: 0, 3418 begins: 0, 3419 ends: -1, 3420 gauge: false, 3421 precise: false, 3422 token: "it is a secret" 3423 }; 3424 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3425 task.resume().then(() => { 3426 console.info(`Succeeded in resuming a download task. `); 3427 }).catch((err: BusinessError) => { 3428 console.error(`Failed to resume the download task, Code: ${err.code}, message: ${err.message}`); 3429 }); 3430 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 3431 }).catch((err: BusinessError) => { 3432 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 3433 }); 3434 ``` 3435 3436> **NOTE** 3437> 3438> The error code **21900005 task mode error** is removed from API version 11. 3439 3440 3441### stop<sup>10+</sup> 3442 3443stop(callback: AsyncCallback<void>): void 3444 3445Stops 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. 3446 3447**System capability**: SystemCapability.Request.FileTransferAgent 3448 3449**Parameters** 3450 3451 | Name| Type| Mandatory| Description| 3452 | -------- | -------- | -------- | -------- | 3453 | callback | function | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 3454 3455**Error codes** 3456 3457For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 3458 3459 | ID| Error Message| 3460 | -------- | -------- | 3461 | 13400003 | task service ability error. | 3462 | 21900007 | task state error. | 3463 3464**Example** 3465 3466 ```ts 3467 let config: request.agent.Config = { 3468 action: request.agent.Action.DOWNLOAD, 3469 url: 'http://127.0.0.1', 3470 title: 'taskStopTest', 3471 description: 'Sample code for stop the download task', 3472 mode: request.agent.Mode.BACKGROUND, 3473 overwrite: false, 3474 method: "GET", 3475 data: "", 3476 saveas: "./", 3477 network: request.agent.Network.CELLULAR, 3478 metered: false, 3479 roaming: true, 3480 retry: true, 3481 redirect: true, 3482 index: 0, 3483 begins: 0, 3484 ends: -1, 3485 gauge: false, 3486 precise: false, 3487 token: "it is a secret" 3488 }; 3489 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3490 task.stop((err: BusinessError) => { 3491 if (err) { 3492 console.error(`Failed to stop the download task, Code: ${err.code}, message: ${err.message}`); 3493 return; 3494 } 3495 console.info(`Succeeded in stopping a download task. `); 3496 }); 3497 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 3498 }).catch((err: BusinessError) => { 3499 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 3500 }); 3501 ``` 3502 3503 3504### stop<sup>10+</sup> 3505 3506stop(): Promise<void> 3507 3508Stops this task. This API can be used to stop a running, waiting, or retrying task. This API uses a promise to return the result. 3509 3510**System capability**: SystemCapability.Request.FileTransferAgent 3511 3512**Return value** 3513 3514| Type | Description | 3515| ------------------- | ------------------------- | 3516| Promise<void> | Promise that returns no value.| 3517 3518**Error codes** 3519 3520For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 3521 3522 | ID| Error Message| 3523 | -------- | -------- | 3524 | 13400003 | task service ability error. | 3525 | 21900007 | task state error. | 3526 3527**Example** 3528 3529 ```ts 3530 let config: request.agent.Config = { 3531 action: request.agent.Action.DOWNLOAD, 3532 url: 'http://127.0.0.1', 3533 title: 'taskStopTest', 3534 description: 'Sample code for stop the download task', 3535 mode: request.agent.Mode.BACKGROUND, 3536 overwrite: false, 3537 method: "GET", 3538 data: "", 3539 saveas: "./", 3540 network: request.agent.Network.CELLULAR, 3541 metered: false, 3542 roaming: true, 3543 retry: true, 3544 redirect: true, 3545 index: 0, 3546 begins: 0, 3547 ends: -1, 3548 gauge: false, 3549 precise: false, 3550 token: "it is a secret" 3551 }; 3552 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3553 task.stop().then(() => { 3554 console.info(`Succeeded in stopping a download task. `); 3555 }).catch((err: BusinessError) => { 3556 console.error(`Failed to stop the download task, Code: ${err.code}, message: ${err.message}`); 3557 }); 3558 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 3559 }).catch((err: BusinessError) => { 3560 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 3561 }); 3562 ``` 3563 3564## request.agent.create<sup>10+</sup> 3565 3566create(context: BaseContext, config: Config, callback: AsyncCallback<Task>): void 3567 3568Creates 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. 3569 3570 3571**Required permissions**: ohos.permission.INTERNET 3572 3573**System capability**: SystemCapability.Request.FileTransferAgent 3574 3575**Parameters** 3576 3577 | Name| Type| Mandatory| Description| 3578 | -------- | -------- | -------- | -------- | 3579 | config | [Config](#config10) | Yes| Task configuration.| 3580 | context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| 3581 | callback | AsyncCallback<[Task](#task10)> | Yes| Callback used to return the configuration about the created task.| 3582 3583**Error codes** 3584 3585For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 3586 3587 | ID| Error Message| 3588 | -------- | -------- | 3589 | 13400001 | file operation error. | 3590 | 13400003 | task service ability error. | 3591 | 21900004 | application task queue full error. | 3592 | 21900005 | task mode error. | 3593 3594**Example** 3595 3596 ```ts 3597 let attachments: Array<request.agent.FormItem> = [{ 3598 name: "createTest", 3599 value: { 3600 filename: "createTest.avi", 3601 mimeType: "application/octet-stream", 3602 path: "./createTest.avi", 3603 } 3604 }]; 3605 let config: request.agent.Config = { 3606 action: request.agent.Action.UPLOAD, 3607 url: 'http://127.0.0.1', 3608 title: 'createTest', 3609 description: 'Sample code for create task', 3610 mode: request.agent.Mode.BACKGROUND, 3611 overwrite: false, 3612 method: "PUT", 3613 data: attachments, 3614 saveas: "./", 3615 network: request.agent.Network.CELLULAR, 3616 metered: false, 3617 roaming: true, 3618 retry: true, 3619 redirect: true, 3620 index: 0, 3621 begins: 0, 3622 ends: -1, 3623 gauge: false, 3624 precise: false, 3625 token: "it is a secret" 3626 }; 3627 request.agent.create(getContext(), config, (err: BusinessError, task: request.agent.Task) => { 3628 if (err) { 3629 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 3630 return; 3631 } 3632 console.info(`Succeeded in creating a download task. result: ${task.config}`); 3633 }); 3634 ``` 3635 3636> **NOTE** 3637> 3638> 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). 3639 3640## request.agent.create<sup>10+</sup> 3641 3642create(context: BaseContext, config: Config): Promise<Task> 3643 3644Creates 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. 3645 3646 3647**Required permissions**: ohos.permission.INTERNET 3648 3649**System capability**: SystemCapability.Request.FileTransferAgent 3650 3651**Parameters** 3652 3653 | Name| Type| Mandatory| Description| 3654 | -------- | -------- | -------- | -------- | 3655 | context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| 3656 | config | [Config](#config10) | Yes| Task configuration.| 3657 3658**Return value** 3659 3660| Type | Description | 3661| ------------------- | ------------------------- | 3662| Promise<[Task](#task10)> | Promise used to return the configuration about the created task.| 3663 3664**Error codes** 3665 3666For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 3667 3668 | ID| Error Message| 3669 | -------- | -------- | 3670 | 13400001 | file operation error. | 3671 | 13400003 | task service ability error. | 3672 | 21900004 | application task queue full error. | 3673 | 21900005 | task mode error. | 3674 3675**Example** 3676 3677 ```ts 3678 let attachments: Array<request.agent.FormItem> = [{ 3679 name: "createTest", 3680 value: { 3681 filename: "createTest.avi", 3682 mimeType: "application/octet-stream", 3683 path: "./createTest.avi", 3684 } 3685 }]; 3686 let config: request.agent.Config = { 3687 action: request.agent.Action.UPLOAD, 3688 url: 'http://127.0.0.1', 3689 title: 'createTest', 3690 description: 'Sample code for create task', 3691 mode: request.agent.Mode.BACKGROUND, 3692 overwrite: false, 3693 method: "PUT", 3694 data: attachments, 3695 saveas: "./", 3696 network: request.agent.Network.CELLULAR, 3697 metered: false, 3698 roaming: true, 3699 retry: true, 3700 redirect: true, 3701 index: 0, 3702 begins: 0, 3703 ends: -1, 3704 gauge: false, 3705 precise: false, 3706 token: "it is a secret" 3707 }; 3708 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3709 console.info(`Succeeded in creating a download task. result: ${task.config}`); 3710 }).catch((err) => { 3711 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 3712 }); 3713 ``` 3714 3715> **NOTE** 3716> 3717> 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). 3718 3719## request.agent.getTask<sup>11+</sup> 3720 3721getTask(context: BaseContext, id: string, token?: string): Promise<Task> 3722 3723Obtains task information based on the task ID. This API uses a promise to return the result. 3724 3725**System capability**: SystemCapability.Request.FileTransferAgent 3726 3727**Parameters** 3728 3729 | Name| Type| Mandatory| Description| 3730 | -------- | -------- | -------- | -------- | 3731 | context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| 3732 | id | string | Yes| Task ID.| 3733 | token | string | No| Token for task query.| 3734 3735**Return value** 3736 3737| Type | Description | 3738| ------------------- | ------------------------- | 3739| Promise<[Task](#task10)> | Promise used to return the configuration about the created task.| 3740 3741**Error codes** 3742 3743For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 3744 3745 | ID| Error Message| 3746 | -------- | -------- | 3747 | 13400003 | task service ability error. | 3748 | 21900006 | task not found error. | 3749 3750**Example** 3751 3752 ```ts 3753 request.agent.getTask(context, "123456").then((task: request.agent.Task) => { 3754 console.info(`Succeeded in querying a upload task. result: ${task.uid}`); 3755 }).catch((err: BusinessError) => { 3756 console.error(`Failed to query a upload task, Code: ${err.code}, message: ${err.message}`); 3757 }); 3758 ``` 3759 3760## request.agent.remove<sup>10+</sup> 3761 3762remove(id: string, callback: AsyncCallback<void>): void 3763 3764Removes 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. 3765 3766**System capability**: SystemCapability.Request.FileTransferAgent 3767 3768**Parameters** 3769 3770 | Name| Type| Mandatory| Description| 3771 | -------- | -------- | -------- | -------- | 3772 | id | string | Yes| Task ID.| 3773 | callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 3774 3775**Error codes** 3776 3777For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 3778 3779 | ID| Error Message| 3780 | -------- | -------- | 3781 | 13400003 | task service ability error. | 3782 | 21900006 | task not found error. | 3783 3784**Example** 3785 3786 ```ts 3787 request.agent.remove("123456", (err: BusinessError) => { 3788 if (err) { 3789 console.error(`Failed to removing a download task, Code: ${err.code}, message: ${err.message}`); 3790 return; 3791 } 3792 console.info(`Succeeded in creating a download task.`); 3793 }); 3794 ``` 3795 3796 3797## request.agent.remove<sup>10+</sup> 3798 3799remove(id: string): Promise<void> 3800 3801Removes 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. 3802 3803**System capability**: SystemCapability.Request.FileTransferAgent 3804 3805**Parameters** 3806 3807 | Name| Type| Mandatory| Description| 3808 | -------- | -------- | -------- | -------- | 3809 | id | string | Yes| Task ID.| 3810 3811**Return value** 3812 3813| Type | Description | 3814| ------------------- | ------------------------- | 3815| Promise<void> | Promise that returns no value.| 3816 3817**Error codes** 3818 3819For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 3820 3821 | ID| Error Message| 3822 | -------- | -------- | 3823 | 13400003 | task service ability error. | 3824 | 21900006 | task not found error. | 3825 3826**Example** 3827 3828 ```ts 3829 request.agent.remove("123456").then(() => { 3830 console.info(`Succeeded in removing a download task. `); 3831 }).catch((err: BusinessError) => { 3832 console.error(`Failed to remove a download task, Code: ${err.code}, message: ${err.message}`); 3833 }); 3834 ``` 3835 3836 3837## request.agent.show<sup>10+</sup> 3838 3839show(id: string, callback: AsyncCallback<TaskInfo>): void 3840 3841Queries a task details based on the task ID. This API uses an asynchronous callback to return the result. 3842 3843**System capability**: SystemCapability.Request.FileTransferAgent 3844 3845**Parameters** 3846 3847 | Name| Type| Mandatory| Description| 3848 | -------- | -------- | -------- | -------- | 3849 | id | string | Yes| Task ID.| 3850 | callback | AsyncCallback<[TaskInfo](#taskinfo10)> | Yes| Callback used to return task details.| 3851 3852**Error codes** 3853For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 3854 3855 | ID| Error Message| 3856 | -------- | -------- | 3857 | 13400003 | task service ability error. | 3858 | 21900006 | task not found error. | 3859 3860**Example** 3861 3862 ```ts 3863 request.agent.show("123456", (err: BusinessError, taskInfo: request.agent.TaskInfo) => { 3864 if (err) { 3865 console.error(`Failed to show a upload task, Code: ${err.code}, message: ${err.message}`); 3866 return; 3867 } 3868 console.info(`Succeeded in showing a upload task.`); 3869 }); 3870 ``` 3871 3872 3873## request.agent.show<sup>10+</sup> 3874 3875show(id: string): Promise<TaskInfo> 3876 3877Queries a task details based on the task ID. This API uses a promise to return the result. 3878 3879**System capability**: SystemCapability.Request.FileTransferAgent 3880 3881**Parameters** 3882 3883 | Name| Type| Mandatory| Description| 3884 | -------- | -------- | -------- | -------- | 3885 | id | string | Yes| Task ID.| 3886 3887**Return value** 3888 3889| Type | Description | 3890| ------------------- | ------------------------- | 3891| Promise<[TaskInfo](#taskinfo10)> | Promise Promise used to return task details.| 3892 3893**Error codes** 3894For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 3895 3896 | ID| Error Message| 3897 | -------- | -------- | 3898 | 13400003 | task service ability error. | 3899 | 21900006 | task not found error. | 3900 3901**Example** 3902 3903 ```ts 3904 request.agent.show("123456").then((taskInfo: request.agent.TaskInfo) => { 3905 console.info(`Succeeded in showing a upload task.`); 3906 }).catch((err: BusinessError) => { 3907 console.error(`Failed to show a upload task, Code: ${err.code}, message: ${err.message}`); 3908 }); 3909 ``` 3910 3911 3912## request.agent.touch<sup>10+</sup> 3913 3914touch(id: string, token: string, callback: AsyncCallback<TaskInfo>): void 3915 3916Queries the task details based on the task ID and token. This API uses an asynchronous callback to return the result. 3917 3918**System capability**: SystemCapability.Request.FileTransferAgent 3919 3920**Parameters** 3921 3922 | Name| Type| Mandatory| Description| 3923 | -------- | -------- | -------- | -------- | 3924 | id | string | Yes| Task ID.| 3925 | token | string | Yes| Token for task query.| 3926 | callback | AsyncCallback<[TaskInfo](#taskinfo10)> | Yes| Callback used to return task details.| 3927 3928**Error codes** 3929For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 3930 3931 | ID| Error Message| 3932 | -------- | -------- | 3933 | 13400003 | task service ability error. | 3934 | 21900006 | task not found error. | 3935 3936**Example** 3937 3938 ```ts 3939 request.agent.touch("123456", "token", (err: BusinessError, taskInfo: request.agent.TaskInfo) => { 3940 if (err) { 3941 console.error(`Failed to touch a upload task, Code: ${err.code}, message: ${err.message}`); 3942 return; 3943 } 3944 console.info(`Succeeded in touching a upload task.`); 3945 }); 3946 ``` 3947 3948 3949## request.agent.touch<sup>10+</sup> 3950 3951touch(id: string, token: string): Promise<TaskInfo> 3952 3953Queries the task details based on the task ID and token. This API uses a promise to return the result. 3954 3955**System capability**: SystemCapability.Request.FileTransferAgent 3956 3957**Parameters** 3958 3959 | Name| Type| Mandatory| Description| 3960 | -------- | -------- | -------- | -------- | 3961 | id | string | Yes| Task ID.| 3962 | token | string | Yes| Token for task query.| 3963 3964**Return value** 3965 3966| Type | Description | 3967| ------------------- | ------------------------- | 3968| Promise<[TaskInfo](#taskinfo10)> | Promise Promise used to return task details.| 3969 3970**Error codes** 3971For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 3972 3973 | ID| Error Message| 3974 | -------- | -------- | 3975 | 13400003 | task service ability error. | 3976 | 21900006 | task not found error. | 3977 3978**Example** 3979 3980 ```ts 3981 request.agent.touch("123456", "token").then((taskInfo: request.agent.TaskInfo) => { 3982 console.info(`Succeeded in touching a upload task. `); 3983 }).catch((err: BusinessError) => { 3984 console.error(`Failed to touch a upload task, Code: ${err.code}, message: ${err.message}`); 3985 }); 3986 ``` 3987 3988## request.agent.search<sup>10+</sup> 3989 3990search(callback: AsyncCallback<Array<string>>): void 3991 3992Searches for task IDs based on [Filter](#filter10). This API uses an asynchronous callback to return the result. 3993 3994**System capability**: SystemCapability.Request.FileTransferAgent 3995 3996**Parameters** 3997 3998 | Name| Type| Mandatory| Description| 3999 | -------- | -------- | -------- | -------- | 4000 | callback | AsyncCallback<Array<string>> | Yes| Callback used to return task ID matches.| 4001 4002**Error codes** 4003For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 4004 4005 | ID| Error Message| 4006 | -------- | -------- | 4007 | 13400003 | task service ability error. | 4008 4009**Example** 4010 4011 ```ts 4012 request.agent.search((err: BusinessError, data: Array<string>) => { 4013 if (err) { 4014 console.error(`Upload task search failed. Code: ${err.code}, message: ${err.message}`); 4015 return; 4016 } 4017 console.info(`Upload task search succeeded. `); 4018 }); 4019 ``` 4020 4021## request.agent.search<sup>10+</sup> 4022 4023search(filter: Filter, callback: AsyncCallback<Array<string>>): void 4024 4025Searches for task IDs based on [Filter](#filter10). This API uses an asynchronous callback to return the result. 4026 4027**System capability**: SystemCapability.Request.FileTransferAgent 4028 4029**Parameters** 4030 4031 | Name| Type| Mandatory| Description| 4032 | -------- | -------- | -------- | -------- | 4033 | filter | [Filter](#filter10) | Yes| Filter criteria.| 4034 | callback | AsyncCallback<Array<string>> | Yes| Callback used to return task ID matches.| 4035 4036**Error codes** 4037For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 4038 4039 | ID| Error Message| 4040 | -------- | -------- | 4041 | 13400003 | task service ability error. | 4042 4043**Example** 4044 4045 ```ts 4046 let filter: request.agent.Filter = { 4047 bundle: "com.example.myapplication", 4048 action: request.agent.Action.UPLOAD, 4049 mode: request.agent.Mode.BACKGROUND 4050 } 4051 request.agent.search(filter, (err: BusinessError, data: Array<string>) => { 4052 if (err) { 4053 console.error(`Upload task search failed. Code: ${err.code}, message: ${err.message}`); 4054 return; 4055 } 4056 console.info(`Upload task search succeeded. `); 4057 }); 4058 ``` 4059 4060 4061## request.agent.search<sup>10+</sup> 4062 4063search(filter?: Filter): Promise<Array<string>> 4064 4065Searches for task IDs based on [Filter](#filter10). This API uses a promise to return the result. 4066 4067**System capability**: SystemCapability.Request.FileTransferAgent 4068 4069**Parameters** 4070 4071 | Name| Type| Mandatory| Description| 4072 | -------- | -------- | -------- | -------- | 4073 | filter | [Filter](#filter10) | No| Filter criteria.| 4074 4075**Return value** 4076 4077| Type | Description | 4078| ------------------- | ------------------------- | 4079| Promise<Array<string>> | Promise Promise used to return task ID matches.| 4080 4081**Error codes** 4082For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 4083 4084 | ID| Error Message| 4085 | -------- | -------- | 4086 | 13400003 | task service ability error. | 4087 4088**Example** 4089 4090 ```ts 4091 let filter: request.agent.Filter = { 4092 bundle: "com.example.myapplication", 4093 action: request.agent.Action.UPLOAD, 4094 mode: request.agent.Mode.BACKGROUND 4095 } 4096 request.agent.search(filter).then((data: Array<string>) => { 4097 console.info(`Upload task search succeeded. `); 4098 }).catch((err: BusinessError) => { 4099 console.error(`Upload task search failed. Code: ${err.code}, message: ${err.message}`); 4100 }); 4101 ``` 4102 4103 4104## request.agent.query<sup>10+</sup> 4105 4106query(id: string, callback: AsyncCallback<TaskInfo>): void 4107 4108Queries a task details based on the task ID. This API uses an asynchronous callback to return the result. 4109 4110**Required permissions**: ohos.permission.DOWNLOAD_SESSION_MANAGER or ohos.permission.UPLOAD_SESSION_MANAGER 4111 4112**System capability**: SystemCapability.Request.FileTransferAgent 4113 4114**System API**: This is a system API. 4115 4116**Parameters** 4117 4118 | Name| Type| Mandatory| Description| 4119 | -------- | -------- | -------- | -------- | 4120 | id | string | Yes| Task ID.| 4121 | callback | AsyncCallback<[TaskInfo](#taskinfo10)> | Yes| Callback used to return task details.| 4122 4123**Error codes** 4124For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 4125 4126 | ID| Error Message| 4127 | -------- | -------- | 4128 | 13400003 | task service ability error. | 4129 | 21900006 | task not found error. | 4130 4131**Example** 4132 4133 ```ts 4134 request.agent.query("123456", (err: BusinessError, taskInfo: request.agent.TaskInfo) => { 4135 if (err) { 4136 console.error(`Failed to query a upload task, Code: ${err.code}, message: ${err.message}`); 4137 return; 4138 } 4139 console.info(`Succeeded in querying the upload task. Result: ${taskInfo.uid}`); 4140 }); 4141 ``` 4142 4143 4144## request.agent.query<sup>10+</sup> 4145 4146query(id: string): Promise<TaskInfo> 4147 4148Queries a task details based on the task ID. This API uses a promise to return the result. 4149 4150**Required permissions**: ohos.permission.DOWNLOAD_SESSION_MANAGER or ohos.permission.UPLOAD_SESSION_MANAGER 4151 4152**System capability**: SystemCapability.Request.FileTransferAgent 4153 4154**System API**: This is a system API. 4155 4156**Parameters** 4157 4158 | Name| Type| Mandatory| Description| 4159 | -------- | -------- | -------- | -------- | 4160 | id | string | Yes| Task ID.| 4161 4162**Return value** 4163 4164| Type | Description | 4165| ------------------- | ------------------------- | 4166| Promise<[TaskInfo](#taskinfo10)> | Promise Promise used to return task details.| 4167 4168**Error codes** 4169For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 4170 4171 | ID| Error Message| 4172 | -------- | -------- | 4173 | 13400003 | task service ability error. | 4174 | 21900006 | task not found error. | 4175 4176**Example** 4177 4178 ```ts 4179 request.agent.query("123456").then((taskInfo: request.agent.TaskInfo) => { 4180 console.info(`Succeeded in querying the upload task. Result: ${taskInfo.uid}`); 4181 }).catch((err: BusinessError) => { 4182 console.error(`Failed to query a upload task, Code: ${err.code}, message: ${err.message}`); 4183 }); 4184 ``` 4185 4186<!--no_check--> 4187
