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 18## Constraints 19 20Only HTTP requests are supported. HTTPS requests are not supported. 21 22The download server must support the HTTP HEAD method so that the size of the data to download can be obtained through **Content-length**. Otherwise, the download task fails. If this is the case, you can check the failure cause through [on('fail')<sup>7+</sup>](#onfail7). 23 24## Constants 25 26**Required permissions**: ohos.permission.INTERNET 27 28**System capability**: SystemCapability.MiscServices.Download 29 30### Network Types 31You can set **networkType** in [DownloadConfig](#downloadconfig) to specify the network type for the download service. 32 33| Name| Type| Value| Description| 34| -------- | -------- | -------- | -------- | 35| NETWORK_MOBILE | number | 0x00000001 | Whether download is allowed on a mobile network.| 36| NETWORK_WIFI | number | 0x00010000 | Whether download is allowed on a WLAN.| 37 38### Download Error Codes 39The table below lists the error codes that may be returned by [on('fail')<sup>7+</sup>](#onfail7)/[off('fail')<sup>7+</sup>](#offfail7)/[getTaskInfo<sup>9+</sup>](#gettaskinfo9). 40 41| Name| Type| Value| Description| 42| -------- | -------- | -------- | -------- | 43| ERROR_CANNOT_RESUME<sup>7+</sup> | number | 0 | Failure to resume the download due to network errors.| 44| ERROR_DEVICE_NOT_FOUND<sup>7+</sup> | number | 1 | Failure to find a storage device such as a memory card.| 45| ERROR_FILE_ALREADY_EXISTS<sup>7+</sup> | number | 2 | Failure to download the file because it already exists.| 46| ERROR_FILE_ERROR<sup>7+</sup> | number | 3 | File operation failure.| 47| ERROR_HTTP_DATA_ERROR<sup>7+</sup> | number | 4 | HTTP transmission failure.| 48| ERROR_INSUFFICIENT_SPACE<sup>7+</sup> | number | 5 | Insufficient storage space.| 49| ERROR_TOO_MANY_REDIRECTS<sup>7+</sup> | number | 6 | Error caused by too many network redirections.| 50| ERROR_UNHANDLED_HTTP_CODE<sup>7+</sup> | number | 7 | Unidentified HTTP code.| 51| ERROR_UNKNOWN<sup>7+</sup> | number | 8 | Unknown error.| 52| ERROR_OFFLINE<sup>9+</sup> | number | 9 | No network connection.| 53| ERROR_UNSUPPORTED_NETWORK_TYPE<sup>9+</sup> | number | 10 | Network type mismatch.| 54 55 56### Causes of Download Pause 57The table below lists the causes of download pause that may be returned by [getTaskInfo<sup>9+</sup>](#gettaskinfo9). 58 59| Name| Type| Value| Description| 60| -------- | -------- | -------- | -------- | 61| 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.| 62| PAUSED_WAITING_FOR_NETWORK<sup>7+</sup> | number | 1 | Download paused due to a network connection problem, for example, network disconnection.| 63| PAUSED_WAITING_TO_RETRY<sup>7+</sup> | number | 2 | Download paused and then retried.| 64| PAUSED_BY_USER<sup>9+</sup> | number | 3 | The user paused the session.| 65| PAUSED_UNKNOWN<sup>7+</sup> | number | 4 | Download paused due to unknown reasons.| 66 67### Download Task Status Codes 68The table below lists the download task status codes that may be returned by [getTaskInfo<sup>9+</sup>](#gettaskinfo9). 69 70| Name| Type| Value| Description| 71| -------- | -------- | -------- | -------- | 72| SESSION_SUCCESSFUL<sup>7+</sup> | number | 0 | Successful download.| 73| SESSION_RUNNING<sup>7+</sup> | number | 1 | Download in progress.| 74| SESSION_PENDING<sup>7+</sup> | number | 2 | Download pending.| 75| SESSION_PAUSED<sup>7+</sup> | number | 3 | Download paused.| 76| SESSION_FAILED<sup>7+</sup> | number | 4 | Download failure without retry.| 77 78 79## request.uploadFile<sup>9+</sup> 80 81uploadFile(context: BaseContext, config: UploadConfig): Promise<UploadTask> 82 83Uploads 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. 84 85**Required permissions**: ohos.permission.INTERNET 86 87**System capability**: SystemCapability.MiscServices.Upload 88 89**Parameters** 90 91| Name| Type| Mandatory| Description| 92| -------- | -------- | -------- | -------- | 93| context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| 94| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| 95 96 97**Return value** 98 99| Type| Description| 100| -------- | -------- | 101| Promise<[UploadTask](#uploadtask)> | Promise used to return the **UploadTask** object.| 102 103**Error codes** 104For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 105 106| ID| Error Message| 107| -------- | -------- | 108| 13400002 | Bad file path. | 109 110**Example** 111 112 ```js 113 let uploadTask; 114 let uploadConfig = { 115 url: 'https://patch', 116 header: { key1: "value1", key2: "value2" }, 117 method: "POST", 118 files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], 119 data: [{ name: "name123", value: "123" }], 120 }; 121 try { 122 request.uploadFile(globalThis.abilityContext, uploadConfig).then((data) => { 123 uploadTask = data; 124 }).catch((err) => { 125 console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); 126 }); 127 } catch (err) { 128 console.error('err.code : ' + err.code + ', err.message : ' + err.message); 129 } 130 ``` 131 132 133## request.uploadFile<sup>9+</sup> 134 135uploadFile(context: BaseContext, config: UploadConfig, callback: AsyncCallback<UploadTask>): void 136 137Uploads 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. 138 139**Required permissions**: ohos.permission.INTERNET 140 141**System capability**: SystemCapability.MiscServices.Upload 142 143**Parameters** 144 145| Name| Type| Mandatory| Description| 146| -------- | -------- | -------- | -------- | 147| context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| 148| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| 149| callback | AsyncCallback<[UploadTask](#uploadtask)> | Yes| Callback used to return the **UploadTask** object.| 150 151**Error codes** 152For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 153 154| ID| Error Message| 155| -------- | -------- | 156| 13400002 | Bad file path. | 157 158**Example** 159 160 ```js 161 let uploadTask; 162 let uploadConfig = { 163 url: 'https://patch', 164 header: { key1: "value1", key2: "value2" }, 165 method: "POST", 166 files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], 167 data: [{ name: "name123", value: "123" }], 168 }; 169 try { 170 request.uploadFile(globalThis.abilityContext, uploadConfig, (err, data) => { 171 if (err) { 172 console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); 173 return; 174 } 175 uploadTask = data; 176 }); 177 } catch (err) { 178 console.error('err.code : ' + err.code + ', err.message : ' + err.message); 179 } 180 ``` 181 182## request.upload<sup>(deprecated)</sup> 183 184upload(config: UploadConfig): Promise<UploadTask> 185 186Uploads files. This API uses a promise to return the result. 187 188**Model restriction**: This API can be used only in the FA model. 189 190> **NOTE** 191> 192> This API is deprecated since API version 9. You are advised to use [request.uploadFile<sup>9+</sup>](#requestuploadfile9). 193 194**Required permissions**: ohos.permission.INTERNET 195 196**System capability**: SystemCapability.MiscServices.Upload 197 198**Parameters** 199 200| Name| Type| Mandatory| Description| 201| -------- | -------- | -------- | -------- | 202| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| 203 204**Return value** 205 206| Type| Description| 207| -------- | -------- | 208| Promise<[UploadTask](#uploadtask)> | Promise used to return the **UploadTask** object.| 209 210**Example** 211 212 ```js 213 let uploadTask; 214 let uploadConfig = { 215 url: 'https://patch', 216 header: { key1: "value1", key2: "value2" }, 217 method: "POST", 218 files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], 219 data: [{ name: "name123", value: "123" }], 220 }; 221 request.upload(uploadConfig).then((data) => { 222 uploadTask = data; 223 }).catch((err) => { 224 console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); 225 }) 226 ``` 227 228 229## request.upload<sup>(deprecated)</sup> 230 231upload(config: UploadConfig, callback: AsyncCallback<UploadTask>): void 232 233Uploads files. This API uses an asynchronous callback to return the result. 234 235**Model restriction**: This API can be used only in the FA model. 236 237> **NOTE** 238> 239> This API is deprecated since API version 9. You are advised to use [request.uploadFile<sup>9+</sup>](#requestuploadfile9-1). 240 241**Required permissions**: ohos.permission.INTERNET 242 243**System capability**: SystemCapability.MiscServices.Upload 244 245**Parameters** 246 247| Name| Type| Mandatory| Description| 248| -------- | -------- | -------- | -------- | 249| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| 250| callback | AsyncCallback<[UploadTask](#uploadtask)> | Yes| Callback used to return the **UploadTask** object.| 251 252**Example** 253 254 ```js 255 let uploadTask; 256 let uploadConfig = { 257 url: 'https://patch', 258 header: { key1: "value1", key2: "value2" }, 259 method: "POST", 260 files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], 261 data: [{ name: "name123", value: "123" }], 262 }; 263 request.upload(uploadConfig, (err, data) => { 264 if (err) { 265 console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); 266 return; 267 } 268 uploadTask = data; 269 }); 270 ``` 271 272## UploadTask 273 274Implements file uploads. Before using any APIs of this class, you must obtain an **UploadTask** object. 275 276 277 278### on('progress') 279 280on(type: 'progress', callback:(uploadedSize: number, totalSize: number) => void): void 281 282Subscribes to an upload event. This API uses an asynchronous callback to return the result. 283 284**Required permissions**: ohos.permission.INTERNET 285 286**System capability**: SystemCapability.MiscServices.Upload 287 288**Parameters** 289 290| Name| Type| Mandatory| Description| 291| -------- | -------- | -------- | -------- | 292| type | string | Yes| Type of the event to subscribe to. The value is **'progress'** (upload progress).| 293| callback | function | Yes| Callback for the upload progress event.| 294 295 Parameters of the callback function 296 297| Name| Type| Mandatory| Description| 298| -------- | -------- | -------- | -------- | 299| uploadedSize | number | Yes| Size of the uploaded files, in bits. | 300| totalSize | number | Yes| Total size of the files to upload, in bits. | 301 302**Example** 303 304 ```js 305 uploadTask.on('progress', function callback(uploadedSize, totalSize) { 306 console.info("upload totalSize:" + totalSize + " uploadedSize:" + uploadedSize); 307 } 308 ); 309 ``` 310 311 312### on('headerReceive')<sup>7+</sup> 313 314on(type: 'headerReceive', callback: (header: object) => void): void 315 316Subscribes to an upload event. This API uses an asynchronous callback to return the result. 317 318**Required permissions**: ohos.permission.INTERNET 319 320**System capability**: SystemCapability.MiscServices.Upload 321 322**Parameters** 323 324| Name| Type| Mandatory| Description| 325| -------- | -------- | -------- | -------- | 326| type | string | Yes| Type of the event to subscribe to. The value is **'headerReceive'** (response header).| 327| callback | function | Yes| Callback for the HTTP Response Header event.| 328 329 Parameters of the callback function 330 331| Name| Type| Mandatory| Description| 332| -------- | -------- | -------- | -------- | 333| header | object | Yes| HTTP Response Header.| 334 335**Example** 336 337 ```js 338 uploadTask.on('headerReceive', function callback(headers){ 339 console.info("upOnHeader headers:" + JSON.stringify(headers)); 340 } 341 ); 342 ``` 343 344 345### on('complete' | 'fail')<sup>9+</sup> 346 347 on(type:'complete' | 'fail', callback: Callback<Array<TaskState>>): void; 348 349Subscribes to an upload event. This API uses an asynchronous callback to return the result. 350 351**Required permissions**: ohos.permission.INTERNET 352 353**System capability**: SystemCapability.MiscServices.Upload 354 355**Parameters** 356 357| Name| Type| Mandatory| Description| 358| -------- | -------- | -------- | -------- | 359| 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.| 360| callback | Callback<Array<TaskState>> | Yes| Callback used to return the result.| 361 362 Parameters of the callback function 363 364| Name| Type| Mandatory| Description| 365| -------- | -------- | -------- | -------- | 366| taskstates | Array<[TaskState](#taskstate9)> | Yes| Upload result.| 367 368**Example** 369 370 ```js 371 uploadTask.on('complete', function callback(taskStates) { 372 for (let i = 0; i < taskStates.length; i++ ) { 373 console.info("upOnComplete taskState:" + JSON.stringify(taskStates[i])); 374 } 375 } 376 ); 377 378 uploadTask.on('fail', function callback(taskStates) { 379 for (let i = 0; i < taskStates.length; i++ ) { 380 console.info("upOnFail taskState:" + JSON.stringify(taskStates[i])); 381 } 382 } 383 ); 384 ``` 385 386 387### off('progress') 388 389off(type: 'progress', callback?: (uploadedSize: number, totalSize: number) => void): void 390 391Unsubscribes from an upload event. This API uses an asynchronous callback to return the result. 392 393**Required permissions**: ohos.permission.INTERNET 394 395**System capability**: SystemCapability.MiscServices.Upload 396 397**Parameters** 398 399| Name| Type| Mandatory| Description| 400| -------- | -------- | -------- | -------- | 401| type | string | Yes| Type of the event to unsubscribe from. The value is **'progress'** (upload progress).| 402| callback | function | No| Callback for the upload progress event.| 403 404 Parameters of the callback function 405 406| Name| Type| Mandatory| Description| 407| -------- | -------- | -------- | -------- | 408| uploadedSize | number | Yes| Size of the uploaded files, in bits. | 409| totalSize | number | Yes| Total size of the files to upload, in bits. | 410 411**Example** 412 413 ```js 414 uploadTask.off('progress', function callback(uploadedSize, totalSize) { 415 console.info('uploadedSize: ' + uploadedSize, 'totalSize: ' + totalSize); 416 } 417 ); 418 ``` 419 420 421### off('headerReceive')<sup>7+</sup> 422 423off(type: 'headerReceive', callback?: (header: object) => void): void 424 425Unsubscribes from an upload event. This API uses an asynchronous callback to return the result. 426 427**Required permissions**: ohos.permission.INTERNET 428 429**System capability**: SystemCapability.MiscServices.Upload 430 431**Parameters** 432 433| Name| Type| Mandatory| Description| 434| -------- | -------- | -------- | -------- | 435| type | string | Yes| Type of the event to unsubscribe from. The value is **'headerReceive'** (response header).| 436| callback | function | No| Callback for the HTTP Response Header event.| 437 438 Parameters of the callback function 439 440| Name| Type| Mandatory| Description| 441| -------- | -------- | -------- | -------- | 442| header | object | Yes| HTTP Response Header.| 443 444**Example** 445 446 ```js 447 uploadTask.off('headerReceive', function callback(headers) { 448 console.info("upOnHeader headers:" + JSON.stringify(headers)); 449 } 450 ); 451 ``` 452 453### off('complete' | 'fail')<sup>9+</sup> 454 455 off(type:'complete' | 'fail', callback?: Callback<Array<TaskState>>): void; 456 457Unsubscribes from an upload event. This API uses an asynchronous callback to return the result. 458 459**Required permissions**: ohos.permission.INTERNET 460 461**System capability**: SystemCapability.MiscServices.Upload 462 463**Parameters** 464 465| Name| Type| Mandatory| Description| 466| -------- | -------- | -------- | -------- | 467| 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.| 468| callback | Callback<Array<TaskState>> | No| Callback used to return the result.| 469 470 Parameters of the callback function 471 472| Name| Type| Mandatory| Description| 473| -------- | -------- | -------- | -------- | 474| taskstates | Array<[TaskState](#taskstate9)> | Yes| Upload result.| 475 476**Example** 477 478 ```js 479 uploadTask.off('complete', function callback(taskStates) { 480 for (let i = 0; i < taskStates.length; i++ ) { 481 console.info("upOnComplete taskState:" + JSON.stringify(taskStates[i])); 482 } 483 } 484 ); 485 486 uploadTask.off('fail', function callback(taskStates) { 487 for (let i = 0; i < taskStates.length; i++ ) { 488 console.info("upOnFail taskState:" + JSON.stringify(taskStates[i])); 489 } 490 } 491 ); 492 ``` 493 494### delete<sup>9+</sup> 495delete(): Promise<boolean> 496 497Deletes this upload task. This API uses a promise to return the result. 498 499**Required permissions**: ohos.permission.INTERNET 500 501**System capability**: SystemCapability.MiscServices.Upload 502 503**Return value** 504 505| Type| Description| 506| -------- | -------- | 507| Promise<boolean> | Promise used to return the task removal result. It returns **true** if the operation is successful and returns **false** otherwise.| 508 509**Example** 510 511 ```js 512 uploadTask.delete().then((result) => { 513 if (result) { 514 console.info('Upload task removed successfully. '); 515 } else { 516 console.error('Failed to remove the upload task. '); 517 } 518 }).catch((err) => { 519 console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err)); 520 }); 521 ``` 522 523 524### delete<sup>9+</sup> 525 526delete(callback: AsyncCallback<boolean>): void 527 528Deletes this upload task. This API uses an asynchronous callback to return the result. 529 530**Required permissions**: ohos.permission.INTERNET 531 532**System capability**: SystemCapability.MiscServices.Upload 533 534**Parameters** 535 536| Name| Type| Mandatory| Description| 537| -------- | -------- | -------- | -------- | 538| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| 539 540**Example** 541 542 ```js 543 uploadTask.delete((err, result) => { 544 if (err) { 545 console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err)); 546 return; 547 } 548 if (result) { 549 console.info('Upload task removed successfully.'); 550 } else { 551 console.error('Failed to remove the upload task.'); 552 } 553 }); 554 ``` 555 556 557### remove<sup>(deprecated)</sup> 558 559remove(): Promise<boolean> 560 561Removes this upload task. This API uses a promise to return the result. 562 563> **NOTE** 564> 565> This API is deprecated since API version 9. You are advised to use [delete<sup>9+</sup>](#delete9). 566 567**Required permissions**: ohos.permission.INTERNET 568 569**System capability**: SystemCapability.MiscServices.Upload 570 571**Return value** 572 573| Type| Description| 574| -------- | -------- | 575| Promise<boolean> | Promise used to return the task removal result. It returns **true** if the operation is successful and returns **false** otherwise.| 576 577**Example** 578 579 ```js 580 uploadTask.remove().then((result) => { 581 if (result) { 582 console.info('Upload task removed successfully. '); 583 } else { 584 console.error('Failed to remove the upload task. '); 585 } 586 }).catch((err) => { 587 console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err)); 588 }); 589 ``` 590 591 592### remove<sup>(deprecated)</sup> 593 594remove(callback: AsyncCallback<boolean>): void 595 596Removes this upload task. This API uses an asynchronous callback to return the result. 597 598> **NOTE** 599> 600> This API is deprecated since API version 9. You are advised to use [delete<sup>9+</sup>](#delete9-1). 601 602**Required permissions**: ohos.permission.INTERNET 603 604**System capability**: SystemCapability.MiscServices.Upload 605 606**Parameters** 607 608| Name| Type| Mandatory| Description| 609| -------- | -------- | -------- | -------- | 610| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| 611 612**Example** 613 614 ```js 615 uploadTask.remove((err, result) => { 616 if (err) { 617 console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err)); 618 return; 619 } 620 if (result) { 621 console.info('Upload task removed successfully.'); 622 } else { 623 console.error('Failed to remove the upload task.'); 624 } 625 }); 626 ``` 627 628## UploadConfig 629Describes the configuration for an upload task. 630 631**Required permissions**: ohos.permission.INTERNET 632 633**System capability**: SystemCapability.MiscServices.Upload 634 635| Name| Type| Mandatory| Description| 636| -------- | -------- | -------- | -------- | 637| url | string | Yes| Resource URL.| 638| header | Object | Yes| HTTP or HTTPS header added to an upload request.| 639| method | string | Yes| Request method, which can be **'POST'** or **'PUT'**. The default value is **'POST'**.| 640| files | Array<[File](#file)> | Yes| List of files to upload, which is submitted through **multipart/form-data**.| 641| data | Array<[RequestData](#requestdata)> | Yes| Form data in the request body.| 642 643## TaskState<sup>9+</sup> 644Implements 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. 645 646**Required permissions**: ohos.permission.INTERNET 647 648**System capability**: SystemCapability.MiscServices.Upload 649 650| Name| Type| Mandatory| Description| 651| -------- | -------- | -------- | -------- | 652| path | string | Yes| File path.| 653| responseCode | number | Yes| Return value of an upload task.| 654| message | string | Yes| Description of the upload task result.| 655 656## File 657Describes the list of files in [UploadConfig](#uploadconfig). 658 659**Required permissions**: ohos.permission.INTERNET 660 661**System capability**: SystemCapability.MiscServices.Download 662 663| Name| Type| Mandatory| Description| 664| -------- | -------- | -------- | -------- | 665| filename | string | Yes| File name in the header when **multipart** is used.| 666| name | string | Yes| Name of a form item when **multipart** is used. The default value is **file**.| 667| uri | string | Yes| Local path for storing files.<br>Only the **internal** protocol type is supported. In the value, **internal://cache/** is mandatory. Example:<br>internal://cache/path/to/file.txt | 668| type | string | Yes| Type of the file content. By default, the type is obtained based on the extension of the file name or URI.| 669 670 671## RequestData 672Describes the form data in [UploadConfig](#uploadconfig). 673 674**Required permissions**: ohos.permission.INTERNET 675 676**System capability**: SystemCapability.MiscServices.Download 677 678| Name| Type| Mandatory| Description| 679| -------- | -------- | -------- | -------- | 680| name | string | Yes| Name of a form element.| 681| value | string | Yes| Value of a form element.| 682 683## request.downloadFile<sup>9+</sup> 684 685downloadFile(context: BaseContext, config: DownloadConfig): Promise<DownloadTask> 686 687Downloads 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. 688 689 690**Required permissions**: ohos.permission.INTERNET 691 692**System capability**: SystemCapability.MiscServices.Download 693 694**Parameters** 695 696| Name| Type| Mandatory| Description| 697| -------- | -------- | -------- | -------- | 698| context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| 699| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| 700 701**Return value** 702 703| Type| Description| 704| -------- | -------- | 705| Promise<[DownloadTask](#downloadtask)> | Promise used to return the result.| 706 707**Error codes** 708For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 709 710| ID| Error Message| 711| -------- | -------- | 712| 13400001 | File operation error. | 713| 13400002 | Bad file path. | 714| 13400003 | Task manager service error. | 715 716**Example** 717 718 ```js 719 let downloadTask; 720 try { 721 request.downloadFile(globalThis.abilityContext, { url: 'https://xxxx/xxxx.hap' }).then((data) => { 722 downloadTask = data; 723 }).catch((err) => { 724 console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); 725 }) 726 } catch (err) { 727 console.error('err.code : ' + err.code + ', err.message : ' + err.message); 728 } 729 ``` 730 731 732## request.downloadFile<sup>9+</sup> 733 734downloadFile(context: BaseContext, config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void; 735 736Downloads 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. 737 738 739**Required permissions**: ohos.permission.INTERNET 740 741**System capability**: SystemCapability.MiscServices.Download 742 743**Parameters** 744 745| Name| Type| Mandatory| Description| 746| -------- | -------- | -------- | -------- | 747| context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| 748| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| 749| callback | AsyncCallback<[DownloadTask](#downloadtask)> | Yes| Callback used to return the result.| 750 751**Error codes** 752For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). 753 754| ID| Error Message| 755| -------- | -------- | 756| 13400001 | File operation error. | 757| 13400002 | Bad file path. | 758| 13400003 | Task manager service error. | 759 760**Example** 761 762 ```js 763 let downloadTask; 764 try { 765 request.downloadFile(globalThis.abilityContext, { url: 'https://xxxx/xxxxx.hap', 766 filePath: 'xxx/xxxxx.hap'}, (err, data) => { 767 if (err) { 768 console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); 769 return; 770 } 771 downloadTask = data; 772 }); 773 } catch (err) { 774 console.error('err.code : ' + err.code + ', err.message : ' + err.message); 775 } 776 ``` 777 778## request.download<sup>(deprecated)</sup> 779 780download(config: DownloadConfig): Promise<DownloadTask> 781 782Downloads files. This API uses a promise to return the result. 783 784> **NOTE** 785> 786> This API is deprecated since API version 9. You are advised to use [request.downloadFile<sup>9+</sup>](#requestdownloadfile9). 787 788**Model restriction**: This API can be used only in the FA model. 789 790**Required permissions**: ohos.permission.INTERNET 791 792**System capability**: SystemCapability.MiscServices.Download 793 794**Parameters** 795 796| Name| Type| Mandatory| Description| 797| -------- | -------- | -------- | -------- | 798| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| 799 800**Return value** 801 802| Type| Description| 803| -------- | -------- | 804| Promise<[DownloadTask](#downloadtask)> | Promise used to return the result.| 805 806**Example** 807 808 ```js 809 let downloadTask; 810 request.download({ url: 'https://xxxx/xxxx.hap' }).then((data) => { 811 downloadTask = data; 812 }).catch((err) => { 813 console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); 814 }) 815 ``` 816 817 818## request.download<sup>(deprecated)</sup> 819 820download(config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void 821 822Downloads files. This API uses an asynchronous callback to return the result. 823 824> **NOTE** 825> 826> This API is deprecated since API version 9. You are advised to use [request.downloadFile<sup>9+</sup>](#requestdownloadfile9-1). 827 828**Model restriction**: This API can be used only in the FA model. 829 830**Required permissions**: ohos.permission.INTERNET 831 832**System capability**: SystemCapability.MiscServices.Download 833 834**Parameters** 835 836| Name| Type| Mandatory| Description| 837| -------- | -------- | -------- | -------- | 838| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| 839| callback | AsyncCallback<[DownloadTask](#downloadtask)> | Yes| Callback used to return the result.| 840 841**Example** 842 843 ```js 844 let downloadTask; 845 request.download({ url: 'https://xxxx/xxxxx.hap', 846 filePath: 'xxx/xxxxx.hap'}, (err, data) => { 847 if (err) { 848 console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); 849 return; 850 } 851 downloadTask = data; 852 }); 853 ``` 854 855## DownloadTask 856 857Implements file downloads. 858 859 860### on('progress') 861 862on(type: 'progress', callback:(receivedSize: number, totalSize: number) => void): void 863 864Subscribes to a download event. This API uses an asynchronous callback to return the result. 865 866**Required permissions**: ohos.permission.INTERNET 867 868**System capability**: SystemCapability.MiscServices.Download 869 870**Parameters** 871 872| Name| Type| Mandatory| Description| 873| -------- | -------- | -------- | -------- | 874| type | string | Yes| Type of the event to subscribe to. The value is **'progress'** (download progress).| 875| callback | function | Yes| Callback for the download progress event.| 876 877 Parameters of the callback function 878 879| Name| Type| Mandatory| Description| 880| -------- | -------- | -------- | -------- | 881| receivedSize | number | Yes| Size of the downloaded files, in bits.| 882| totalSize | number | Yes| Total size of the files to download, in bits.| 883 884**Example** 885 886 ```js 887 downloadTask.on('progress', function download_callback(receivedSize, totalSize) { 888 console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize); 889 } 890 ); 891 ``` 892 893 894### off('progress') 895 896off(type: 'progress', callback?: (receivedSize: number, totalSize: number) => void): void 897 898Unsubscribes from a download event. This API uses an asynchronous callback to return the result. 899 900**Required permissions**: ohos.permission.INTERNET 901 902**System capability**: SystemCapability.MiscServices.Download 903 904**Parameters** 905 906| Name| Type| Mandatory| Description| 907| -------- | -------- | -------- | -------- | 908| type | string | Yes| Type of the event to unsubscribe from. The value is **'progress'** (download progress).| 909| callback | function | No| Callback for the download progress event.| 910 911 Parameters of the callback function 912 913| Name| Type| Mandatory| Description| 914| -------- | -------- | -------- | -------- | 915| receivedSize | number | Yes| Size of the downloaded files, in bits.| 916| totalSize | number | Yes| Total size of the files to download, in bits.| 917 918**Example** 919 920 ```js 921 downloadTask .off('progress', function download_callback(receivedSize, totalSize) { 922 console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize); 923 } 924 ); 925 ``` 926 927 928### on('complete'|'pause'|'remove')<sup>7+</sup> 929 930on(type: 'complete'|'pause'|'remove', callback:() => void): void 931 932Subscribes to a download event. This API uses an asynchronous callback to return the result. 933 934**Required permissions**: ohos.permission.INTERNET 935 936**System capability**: SystemCapability.MiscServices.Download 937 938**Parameters** 939 940| Name| Type| Mandatory| Description| 941| -------- | -------- | -------- | -------- | 942| 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.| 943| callback | function | Yes| Callback used to return the result.| 944 945**Example** 946 947 ```js 948 downloadTask.on('complete', function callback() { 949 console.info('Download task completed.'); 950 } 951 ); 952 ``` 953 954 955### off('complete'|'pause'|'remove')<sup>7+</sup> 956 957off(type: 'complete'|'pause'|'remove', callback?:() => void): void 958 959Unsubscribes from a download event. This API uses an asynchronous callback to return the result. 960 961**Required permissions**: ohos.permission.INTERNET 962 963**System capability**: SystemCapability.MiscServices.Download 964 965**Parameters** 966 967| Name| Type| Mandatory| Description| 968| -------- | -------- | -------- | -------- | 969| 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.| 970| callback | function | No| Callback used to return the result.| 971 972**Example** 973 974 ```js 975 downloadTask.off('complete', function callback() { 976 console.info('Download task completed.'); 977 } 978 ); 979 ``` 980 981 982### on('fail')<sup>7+</sup> 983 984on(type: 'fail', callback: (err: number) => void): void 985 986Subscribes to the download task failure event. This API uses an asynchronous callback to return the result. 987 988**Required permissions**: ohos.permission.INTERNET 989 990**System capability**: SystemCapability.MiscServices.Download 991 992**Parameters** 993 994| Name| Type| Mandatory| Description| 995| -------- | -------- | -------- | -------- | 996| type | string | Yes| Type of the event to subscribe to. The value is **'fail'** (download failure).| 997| callback | function | Yes| Callback for the download task failure event.| 998 999 Parameters of the callback function 1000 1001| Name| Type| Mandatory| Description| 1002| -------- | -------- | -------- | -------- | 1003| err | number | Yes| Error code of the download failure. For details about the error codes, see [Download Error Codes](#download-error-codes).| 1004 1005**Example** 1006 1007 ```js 1008 downloadTask.on('fail', function callBack(err) { 1009 console.info('Download task failed. Cause:' + err); 1010 } 1011 ); 1012 ``` 1013 1014 1015### off('fail')<sup>7+</sup> 1016 1017off(type: 'fail', callback?: (err: number) => void): void 1018 1019Unsubscribes from the download task failure event. This API uses an asynchronous callback to return the result. 1020 1021**Required permissions**: ohos.permission.INTERNET 1022 1023**System capability**: SystemCapability.MiscServices.Download 1024 1025**Parameters** 1026 1027| Name| Type| Mandatory| Description| 1028| -------- | -------- | -------- | -------- | 1029| type | string | Yes| Type of the event to unsubscribe from. The value is **'fail'** (download failure).| 1030| callback | function | No| Callback for the download task failure event.| 1031 1032 Parameters of the callback function 1033 1034| Name| Type| Mandatory| Description| 1035| -------- | -------- | -------- | -------- | 1036| err | number | Yes| Error code of the download failure. For details about the error codes, see [Download Error Codes](#download-error-codes).| 1037 1038**Example** 1039 1040 ```js 1041 downloadTask.off('fail', function callBack(err) { 1042 console.info('Download task failed. Cause:' + err); 1043 } 1044 ); 1045 ``` 1046 1047### delete<sup>9+</sup> 1048 1049delete(): Promise<boolean> 1050 1051Removes this download task. This API uses a promise to return the result. 1052 1053**Required permissions**: ohos.permission.INTERNET 1054 1055**System capability**: SystemCapability.MiscServices.Download 1056 1057**Return value** 1058 1059| Type| Description| 1060| -------- | -------- | 1061| Promise<boolean> | Promise used to return the task removal result.| 1062 1063**Example** 1064 1065 ```js 1066 downloadTask.delete().then((result) => { 1067 if (result) { 1068 console.info('Download task removed.'); 1069 } else { 1070 console.error('Failed to remove the download task.'); 1071 } 1072 }).catch ((err) => { 1073 console.error('Failed to remove the download task.'); 1074 }); 1075 ``` 1076 1077 1078### delete<sup>9+</sup> 1079 1080delete(callback: AsyncCallback<boolean>): void 1081 1082Deletes this download task. This API uses an asynchronous callback to return the result. 1083 1084**Required permissions**: ohos.permission.INTERNET 1085 1086**System capability**: SystemCapability.MiscServices.Download 1087 1088**Parameters** 1089 1090| Name| Type| Mandatory| Description| 1091| -------- | -------- | -------- | -------- | 1092| callback | AsyncCallback<boolean> | Yes| Callback used to return the task deletion result.| 1093 1094**Example** 1095 1096 ```js 1097 downloadTask.delete((err, result)=>{ 1098 if(err) { 1099 console.error('Failed to remove the download task.'); 1100 return; 1101 } 1102 if (result) { 1103 console.info('Download task removed.'); 1104 } else { 1105 console.error('Failed to remove the download task.'); 1106 } 1107 }); 1108 ``` 1109 1110 1111### getTaskInfo<sup>9+</sup> 1112 1113getTaskInfo(): Promise<DownloadInfo> 1114 1115Obtains the information about this download task. This API uses a promise to return the result. 1116 1117**Required permissions**: ohos.permission.INTERNET 1118 1119**System capability**: SystemCapability.MiscServices.Download 1120 1121**Return value** 1122 1123| Type| Description| 1124| -------- | -------- | 1125| Promise<[DownloadInfo](#downloadinfo7)> | Promise used to return the download task information.| 1126 1127**Example** 1128 1129 ```js 1130 downloadTask.getTaskInfo().then((downloadInfo) => { 1131 console.info('Download task queried. Data:' + JSON.stringify(downloadInfo)) 1132 }) .catch((err) => { 1133 console.error('Failed to query the download task. Cause:' + err) 1134 }); 1135 ``` 1136 1137 1138### getTaskInfo<sup>9+</sup> 1139 1140getTaskInfo(callback: AsyncCallback<DownloadInfo>): void 1141 1142Obtains the information about this download task. This API uses an asynchronous callback to return the result. 1143 1144**Required permissions**: ohos.permission.INTERNET 1145 1146**System capability**: SystemCapability.MiscServices.Download 1147 1148**Parameters** 1149 1150| Name| Type| Mandatory| Description| 1151| -------- | -------- | -------- | -------- | 1152| callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | Yes| Callback used to return the download task information.| 1153 1154**Example** 1155 1156 ```js 1157 downloadTask.getTaskInfo((err, downloadInfo)=>{ 1158 if(err) { 1159 console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); 1160 } else { 1161 console.info('download query success. data:'+ JSON.stringify(downloadInfo)); 1162 } 1163 }); 1164 ``` 1165 1166 1167### getTaskMimeType<sup>9+</sup> 1168 1169getTaskMimeType(): Promise<string> 1170 1171Obtains the **MimeType** of this download task. This API uses a promise to return the result. 1172 1173**Required permissions**: ohos.permission.INTERNET 1174 1175**System capability**: SystemCapability.MiscServices.Download 1176 1177**Return value** 1178 1179| Type| Description| 1180| -------- | -------- | 1181| Promise<string> | Promise used to return the **MimeType** of the download task.| 1182 1183**Example** 1184 1185 ```js 1186 downloadTask.getTaskMimeType().then((data) => { 1187 console.info('Download task queried. Data:' + JSON.stringify(data)); 1188 }).catch((err) => { 1189 console.error('Failed to query the download MimeType. Cause:' + JSON.stringify(err)) 1190 }); 1191 ``` 1192 1193 1194### getTaskMimeType<sup>9+</sup> 1195 1196getTaskMimeType(callback: AsyncCallback<string>): void; 1197 1198Obtains the **MimeType** of this download task. This API uses an asynchronous callback to return the result. 1199 1200**Required permissions**: ohos.permission.INTERNET 1201 1202**System capability**: SystemCapability.MiscServices.Download 1203 1204**Parameters** 1205 1206| Name| Type| Mandatory| Description| 1207| -------- | -------- | -------- | -------- | 1208| callback | AsyncCallback<string> | Yes| Callback used to return the **MimeType** of the download task.| 1209 1210**Example** 1211 1212 ```js 1213 downloadTask.getTaskMimeType((err, data)=>{ 1214 if(err) { 1215 console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); 1216 } else { 1217 console.info('Download task queried. data:' + JSON.stringify(data)); 1218 } 1219 }); 1220 ``` 1221 1222 1223### suspend<sup>9+</sup> 1224 1225suspend(): Promise<boolean> 1226 1227Pauses this download task. This API uses a promise to return the result. 1228 1229**Required permissions**: ohos.permission.INTERNET 1230 1231**System capability**: SystemCapability.MiscServices.Download 1232 1233**Return value** 1234 1235| Type| Description| 1236| -------- | -------- | 1237| Promise<boolean> | Promise used to return the download task pause result.| 1238 1239**Example** 1240 1241 ```js 1242 downloadTask.suspend().then((result) => { 1243 if (result) { 1244 console.info('Download task paused. '); 1245 } else { 1246 console.error('Failed to pause the download task. Cause:' + JSON.stringify(result)); 1247 } 1248 }).catch((err) => { 1249 console.error('Failed to pause the download task. Cause:' + JSON.stringify(err)); 1250 }); 1251 ``` 1252 1253 1254### suspend<sup>9+</sup> 1255 1256suspend(callback: AsyncCallback<boolean>): void 1257 1258Pauses this download task. This API uses an asynchronous callback to return the result. 1259 1260**Required permissions**: ohos.permission.INTERNET 1261 1262**System capability**: SystemCapability.MiscServices.Download 1263 1264**Parameters** 1265 1266| Name| Type| Mandatory| Description| 1267| -------- | -------- | -------- | -------- | 1268| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| 1269 1270**Example** 1271 1272 ```js 1273 downloadTask.suspend((err, result)=>{ 1274 if(err) { 1275 console.error('Failed to pause the download task. Cause:' + JSON.stringify(err)); 1276 return; 1277 } 1278 if (result) { 1279 console.info('Download task paused. '); 1280 } else { 1281 console.error('Failed to pause the download task. Cause:' + JSON.stringify(result)); 1282 } 1283 }); 1284 ``` 1285 1286 1287### restore<sup>9+</sup> 1288 1289restore(): Promise<boolean> 1290 1291Resumes this download task. This API uses a promise to return the result. 1292 1293**Required permissions**: ohos.permission.INTERNET 1294 1295**System capability**: SystemCapability.MiscServices.Download 1296 1297**Return value** 1298 1299| Type| Description| 1300| -------- | -------- | 1301| Promise<boolean> | Promise used to return the result.| 1302 1303**Example** 1304 1305 ```js 1306 downloadTask.restore().then((result) => { 1307 if (result) { 1308 console.info('Download task resumed.') 1309 } else { 1310 console.error('Failed to resume the download task. '); 1311 } 1312 console.info('Download task resumed.') 1313 }).catch((err) => { 1314 console.error('Failed to resume the download task. Cause:' + err); 1315 }); 1316 ``` 1317 1318 1319### restore<sup>9+</sup> 1320 1321restore(callback: AsyncCallback<boolean>): void 1322 1323Resumes this download task. This API uses an asynchronous callback to return the result. 1324 1325**Required permissions**: ohos.permission.INTERNET 1326 1327**System capability**: SystemCapability.MiscServices.Download 1328 1329**Parameters** 1330 1331| Name| Type| Mandatory| Description| 1332| -------- | -------- | -------- | -------- | 1333| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| 1334 1335**Example** 1336 1337 ```js 1338 downloadTask.restore((err, result)=>{ 1339 if (err) { 1340 console.error('Failed to resume the download task. Cause:' + err); 1341 return; 1342 } 1343 if (result) { 1344 console.info('Download task resumed.'); 1345 } else { 1346 console.error('Failed to resume the download task.'); 1347 } 1348 }); 1349 ``` 1350 1351 1352 1353### remove<sup>(deprecated)</sup> 1354 1355remove(): Promise<boolean> 1356 1357Removes this download task. This API uses a promise to return the result. 1358 1359> **NOTE** 1360> 1361> This API is deprecated since API version 9. You are advised to use [delete<sup>9+</sup>](#delete9-2). 1362 1363**Required permissions**: ohos.permission.INTERNET 1364 1365**System capability**: SystemCapability.MiscServices.Download 1366 1367**Return value** 1368 1369| Type| Description| 1370| -------- | -------- | 1371| Promise<boolean> | Promise used to return the task removal result.| 1372 1373**Example** 1374 1375 ```js 1376 downloadTask.remove().then((result) => { 1377 if (result) { 1378 console.info('Download task removed.'); 1379 } else { 1380 console.error('Failed to remove the download task.'); 1381 } 1382 }).catch ((err) => { 1383 console.error('Failed to remove the download task.'); 1384 }); 1385 ``` 1386 1387 1388### remove<sup>(deprecated)</sup> 1389 1390remove(callback: AsyncCallback<boolean>): void 1391 1392Removes this download task. This API uses an asynchronous callback to return the result. 1393 1394> **NOTE** 1395> 1396> This API is deprecated since API version 9. You are advised to use [delete<sup>9+</sup>](#delete9-3). 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<boolean> | Yes| Callback used to return the task removal result.| 1407 1408**Example** 1409 1410 ```js 1411 downloadTask.remove((err, result)=>{ 1412 if(err) { 1413 console.error('Failed to remove the download task.'); 1414 return; 1415 } 1416 if (result) { 1417 console.info('Download task removed.'); 1418 } else { 1419 console.error('Failed to remove the download task.'); 1420 } 1421 }); 1422 ``` 1423 1424 1425### query<sup>(deprecated)</sup> 1426 1427query(): Promise<DownloadInfo> 1428 1429Queries this download task. This API uses a promise to return the result. 1430 1431> **NOTE** 1432> 1433> 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). 1434 1435**Required permissions**: ohos.permission.INTERNET 1436 1437**System capability**: SystemCapability.MiscServices.Download 1438 1439**Return value** 1440 1441| Type| Description| 1442| -------- | -------- | 1443| Promise<[DownloadInfo](#downloadinfo7)> | Promise used to return the download task information.| 1444 1445**Example** 1446 1447 ```js 1448 downloadTask.query().then((downloadInfo) => { 1449 console.info('Download task queried. Data:' + JSON.stringify(downloadInfo)) 1450 }) .catch((err) => { 1451 console.error('Failed to query the download task. Cause:' + err) 1452 }); 1453 ``` 1454 1455 1456### query<sup>(deprecated)</sup> 1457 1458query(callback: AsyncCallback<DownloadInfo>): void 1459 1460Queries this download task. This API uses an asynchronous callback to return the result. 1461 1462> **NOTE** 1463> 1464> 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). 1465 1466**Required permissions**: ohos.permission.INTERNET 1467 1468**System capability**: SystemCapability.MiscServices.Download 1469 1470**Parameters** 1471 1472| Name| Type| Mandatory| Description| 1473| -------- | -------- | -------- | -------- | 1474| callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | Yes| Callback used to return the download task information.| 1475 1476**Example** 1477 1478 ```js 1479 downloadTask.query((err, downloadInfo)=>{ 1480 if(err) { 1481 console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); 1482 } else { 1483 console.info('download query success. data:'+ JSON.stringify(downloadInfo)); 1484 } 1485 }); 1486 ``` 1487 1488 1489### queryMimeType<sup>(deprecated)</sup> 1490 1491queryMimeType(): Promise<string> 1492 1493Queries the **MimeType** of this download task. This API uses a promise to return the result. 1494 1495> **NOTE** 1496> 1497> 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). 1498 1499**Required permissions**: ohos.permission.INTERNET 1500 1501**System capability**: SystemCapability.MiscServices.Download 1502 1503**Return value** 1504 1505| Type| Description| 1506| -------- | -------- | 1507| Promise<string> | Promise used to return the **MimeType** of the download task.| 1508 1509**Example** 1510 1511 ```js 1512 downloadTask.queryMimeType().then((data) => { 1513 console.info('Download task queried. Data:' + JSON.stringify(data)); 1514 }).catch((err) => { 1515 console.error('Failed to query the download MimeType. Cause:' + JSON.stringify(err)) 1516 }); 1517 ``` 1518 1519 1520### queryMimeType<sup>(deprecated)</sup> 1521 1522queryMimeType(callback: AsyncCallback<string>): void; 1523 1524Queries the **MimeType** of this download task. This API uses an asynchronous callback to return the result. 1525 1526> **NOTE** 1527> 1528> 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). 1529 1530**Required permissions**: ohos.permission.INTERNET 1531 1532**System capability**: SystemCapability.MiscServices.Download 1533 1534**Parameters** 1535 1536| Name| Type| Mandatory| Description| 1537| -------- | -------- | -------- | -------- | 1538| callback | AsyncCallback<string> | Yes| Callback used to return the **MimeType** of the download task.| 1539 1540**Example** 1541 1542 ```js 1543 downloadTask.queryMimeType((err, data)=>{ 1544 if(err) { 1545 console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); 1546 } else { 1547 console.info('Download task queried. data:' + JSON.stringify(data)); 1548 } 1549 }); 1550 ``` 1551 1552 1553### pause<sup>(deprecated)</sup> 1554 1555pause(): Promise<void> 1556 1557Pauses this download task. This API uses a promise to return the result. 1558 1559> **NOTE** 1560> 1561> 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). 1562 1563**Required permissions**: ohos.permission.INTERNET 1564 1565**System capability**: SystemCapability.MiscServices.Download 1566 1567**Return value** 1568 1569| Type| Description| 1570| -------- | -------- | 1571| Promise<void> | Promise used to return the download task pause result.| 1572 1573**Example** 1574 1575 ```js 1576 downloadTask.pause().then((result) => { 1577 if (result) { 1578 console.info('Download task paused. '); 1579 } else { 1580 console.error('Failed to pause the download task. Cause:' + JSON.stringify(result)); 1581 } 1582 }).catch((err) => { 1583 console.error('Failed to pause the download task. Cause:' + JSON.stringify(err)); 1584 }); 1585 ``` 1586 1587 1588### pause<sup>(deprecated)</sup> 1589 1590pause(callback: AsyncCallback<void>): void 1591 1592> **NOTE** 1593> 1594> 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). 1595 1596Pauses this download task. This API uses an asynchronous callback to return the result. 1597 1598**Required permissions**: ohos.permission.INTERNET 1599 1600**System capability**: SystemCapability.MiscServices.Download 1601 1602**Parameters** 1603 1604| Name| Type| Mandatory| Description| 1605| -------- | -------- | -------- | -------- | 1606| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 1607 1608**Example** 1609 1610 ```js 1611 downloadTask.pause((err, result)=>{ 1612 if(err) { 1613 console.error('Failed to pause the download task. Cause:' + JSON.stringify(err)); 1614 return; 1615 } 1616 if (result) { 1617 console.info('Download task paused. '); 1618 } else { 1619 console.error('Failed to pause the download task. Cause:' + JSON.stringify(result)); 1620 } 1621 }); 1622 ``` 1623 1624 1625### resume<sup>(deprecated)</sup> 1626 1627resume(): Promise<void> 1628 1629Resumes this download task. This API uses a promise to return the result. 1630 1631> **NOTE** 1632> 1633> 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). 1634 1635**Required permissions**: ohos.permission.INTERNET 1636 1637**System capability**: SystemCapability.MiscServices.Download 1638 1639**Return value** 1640 1641| Type| Description| 1642| -------- | -------- | 1643| Promise<void> | Promise used to return the result.| 1644 1645**Example** 1646 1647 ```js 1648 downloadTask.resume().then((result) => { 1649 if (result) { 1650 console.info('Download task resumed.') 1651 } else { 1652 console.error('Failed to resume the download task. '); 1653 } 1654 console.info('Download task resumed.') 1655 }).catch((err) => { 1656 console.error('Failed to resume the download task. Cause:' + err); 1657 }); 1658 ``` 1659 1660 1661### resume<sup>(deprecated)</sup> 1662 1663resume(callback: AsyncCallback<void>): void 1664 1665> **NOTE** 1666> 1667> 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). 1668 1669Resumes this download task. This API uses an asynchronous callback to return the result. 1670 1671**Required permissions**: ohos.permission.INTERNET 1672 1673**System capability**: SystemCapability.MiscServices.Download 1674 1675**Parameters** 1676 1677| Name| Type| Mandatory| Description| 1678| -------- | -------- | -------- | -------- | 1679| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 1680 1681**Example** 1682 1683 ```js 1684 downloadTask.resume((err, result)=>{ 1685 if (err) { 1686 console.error('Failed to resume the download task. Cause:' + err); 1687 return; 1688 } 1689 if (result) { 1690 console.info('Download task resumed.'); 1691 } else { 1692 console.error('Failed to resume the download task.'); 1693 } 1694 }); 1695 ``` 1696 1697 1698## DownloadConfig 1699Defines the download task configuration. 1700 1701**Required permissions**: ohos.permission.INTERNET 1702 1703**System capability**: SystemCapability.MiscServices.Download 1704 1705| Name| Type| Mandatory| Description| 1706| -------- | -------- | -------- | -------- | 1707| url | string | Yes| Resource URL.| 1708| 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 | 1709| enableMetered | boolean | No| Whether download is allowed on a metered connection.<br>- **true**: allowed<br>- **false**: not allowed| 1710| enableRoaming | boolean | No| Whether download is allowed on a roaming network.<br>- **true**: allowed<br>- **false**: not allowed| 1711| description | string | No| Description of the download session.| 1712| filePath<sup>7+</sup> | string | No| Path where the downloaded file is stored.<br>- filePath:'/data/storage/el2/base/haps/entry/files/test.txt': Save the file to an absolute path.<br>- In the FA model, use [context](js-apis-inner-app-context.md#contextgetcachedir) to obtain the cache directory of the application, for example, **\${featureAbility.getContext().getFilesDir()}/test.txt\**, and store the file in this directory.<br>- In the stage model, use [AbilityContext](js-apis-inner-application-context.md) to obtain the file path, for example, **\${globalThis.abilityContext.tempDir}/test.txt\**, and store the file in this path.| 1713| networkType | number | No| Network type allowed for download.<br>- NETWORK_MOBILE: 0x00000001<br>- NETWORK_WIFI: 0x00010000| 1714| title | string | No| Download task name.| 1715| background<sup>9+</sup> | boolean | No| Whether to enable the background task notification. When this parameter is enabled, the download status is displayed in the notification panel.| 1716 1717 1718## DownloadInfo<sup>7+</sup> 1719Defines the download task information, which is the callback parameter of the [query<sup>(deprecated)</sup>](#querydeprecated-1) API. 1720 1721**Required permissions**: ohos.permission.INTERNET 1722 1723**System capability**: SystemCapability.MiscServices.Download 1724 1725| Name| Type| Mandatory| Description| 1726| -------- | -------- | -------- | -------- | 1727| downloadId | number | Yes| ID of the downloaded file.| 1728| failedReason | number | No| Cause of the download failure. The value can be any constant in [Download Error Codes](#download-error-codes).| 1729| fileName | string | Yes| Name of the downloaded file.| 1730| filePath | string | Yes| URI of the saved file.| 1731| pausedReason | number | No| Cause of download pause. The value can be any constant in [Causes of Download Pause](#causes-of-download-pause).| 1732| status | number | Yes| Download task status code. The value can be any constant in [Download Task Status Codes](#download-task-status-codes).| 1733| targetURI | string | Yes| URI of the downloaded file.| 1734| downloadTitle | string | Yes| Download task name.| 1735| downloadTotalBytes | number | Yes| Total size of the files to download, in bytes.| 1736| description | string | Yes| Description of the file to download.| 1737| downloadedBytes | number | Yes| Size of the files downloaded, in bytes.| 1738
