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