1/* 2 * Copyright (c) 2022 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15import { AsyncCallback } from './basic'; 16 17/** 18 * upload and download 19 * 20 * @import request from '@ohos.request'; 21 * @permission ohos.permission.INTERNET 22 */ 23declare namespace request { 24 25 /** 26 * Bit flag indicating download is allowed when using the cellular network. 27 * @syscap SystemCapability.MiscServices.Download 28 * @since 6 29 * @permission ohos.permission.INTERNET 30 */ 31 const NETWORK_MOBILE: number; 32 33 /** 34 * Bit flag indicating download is allowed when using the WLAN. 35 * @syscap SystemCapability.MiscServices.Download 36 * @since 6 37 * @permission ohos.permission.INTERNET 38 */ 39 const NETWORK_WIFI: number; 40 41 /** 42 * Indicates that the download cannot be resumed for some temporary errors. 43 * @syscap SystemCapability.MiscServices.Download 44 * @since 7 45 * @permission ohos.permission.INTERNET 46 */ 47 const ERROR_CANNOT_RESUME: number; 48 49 /** 50 * Indicates that no storage device, such as an SD card, is found. 51 * @syscap SystemCapability.MiscServices.Download 52 * @since 7 53 * @permission ohos.permission.INTERNET 54 */ 55 const ERROR_DEVICE_NOT_FOUND: number; 56 57 /** 58 * Indicates that files to be downloaded already exist, and that the download session cannot overwrite the existing files. 59 * @syscap SystemCapability.MiscServices.Download 60 * @since 7 61 * @permission ohos.permission.INTERNET 62 */ 63 const ERROR_FILE_ALREADY_EXISTS: number; 64 65 /** 66 * Indicates that a file operation fails. 67 * @syscap SystemCapability.MiscServices.Download 68 * @since 7 69 * @permission ohos.permission.INTERNET 70 */ 71 const ERROR_FILE_ERROR: number; 72 73 /** 74 * Indicates that the HTTP transmission fails. 75 * @syscap SystemCapability.MiscServices.Download 76 * @since 7 77 * @permission ohos.permission.INTERNET 78 */ 79 const ERROR_HTTP_DATA_ERROR: number; 80 81 /** 82 * Indicates insufficient storage space. 83 * @syscap SystemCapability.MiscServices.Download 84 * @since 7 85 * @permission ohos.permission.INTERNET 86 */ 87 const ERROR_INSUFFICIENT_SPACE: number; 88 89 /** 90 * Indicates an error caused by too many network redirections. 91 * @syscap SystemCapability.MiscServices.Download 92 * @since 7 93 * @permission ohos.permission.INTERNET 94 */ 95 const ERROR_TOO_MANY_REDIRECTS: number; 96 97 /** 98 * Indicates an HTTP code that cannot be identified. 99 * @syscap SystemCapability.MiscServices.Download 100 * @since 7 101 * @permission ohos.permission.INTERNET 102 */ 103 const ERROR_UNHANDLED_HTTP_CODE: number; 104 105 /** 106 * Indicates an undefined error. 107 * @syscap SystemCapability.MiscServices.Download 108 * @since 7 109 * @permission ohos.permission.INTERNET 110 */ 111 const ERROR_UNKNOWN: number; 112 113 /** 114 * Indicates that the download is paused and waiting for a WLAN connection, because the file size exceeds the maximum allowed for a session using the cellular network. 115 * @syscap SystemCapability.MiscServices.Download 116 * @since 7 117 * @permission ohos.permission.INTERNET 118 */ 119 const PAUSED_QUEUED_FOR_WIFI: number; 120 121 /** 122 * Indicates that the download is paused for some reasons. 123 * @syscap SystemCapability.MiscServices.Download 124 * @since 7 125 * @permission ohos.permission.INTERNET 126 */ 127 const PAUSED_UNKNOWN: number; 128 129 /** 130 * Indicates that the download is paused due to a network problem, for example, network disconnection. 131 * @syscap SystemCapability.MiscServices.Download 132 * @since 7 133 * @permission ohos.permission.INTERNET 134 */ 135 const PAUSED_WAITING_FOR_NETWORK: number; 136 137 /** 138 * Indicates that a network error occurs, and the download session will be retried. 139 * @syscap SystemCapability.MiscServices.Download 140 * @since 7 141 * @permission ohos.permission.INTERNET 142 */ 143 const PAUSED_WAITING_TO_RETRY: number; 144 145 /** 146 * Indicates that the download session has failed and will not be retried. 147 * @syscap SystemCapability.MiscServices.Download 148 * @since 7 149 * @permission ohos.permission.INTERNET 150 */ 151 const SESSION_FAILED: number; 152 153 /** 154 * Indicates that the download session has been paused. 155 * @syscap SystemCapability.MiscServices.Download 156 * @since 7 157 * @permission ohos.permission.INTERNET 158 */ 159 const SESSION_PAUSED: number; 160 161 /** 162 * Indicates that the download session is being scheduled. 163 * @syscap SystemCapability.MiscServices.Download 164 * @since 7 165 * @permission ohos.permission.INTERNET 166 */ 167 const SESSION_PENDING: number; 168 169 /** 170 * Indicates that the download session is in progress. 171 * @syscap SystemCapability.MiscServices.Download 172 * @since 7 173 * @permission ohos.permission.INTERNET 174 */ 175 const SESSION_RUNNING: number; 176 177 /** 178 * Indicates that the download session is completed. 179 * @syscap SystemCapability.MiscServices.Download 180 * @since 7 181 * @permission ohos.permission.INTERNET 182 */ 183 const SESSION_SUCCESSFUL: number; 184 185 /** 186 * Starts a download session. 187 * @syscap SystemCapability.MiscServices.Download 188 * @since 6 189 * @param config download config 190 * @param callback Indicate the callback function to receive DownloadTask. 191 * @permission ohos.permission.INTERNET 192 * @return - 193 */ 194 function download(config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void; 195 196 /** 197 * Starts a download session. 198 * @syscap SystemCapability.MiscServices.Download 199 * @since 6 200 * @param config download config 201 * @permission ohos.permission.INTERNET 202 * @return - 203 */ 204 function download(config: DownloadConfig): Promise<DownloadTask>; 205 206 /** 207 * Starts a upload session. 208 * @syscap SystemCapability.MiscServices.Upload 209 * @since 6 210 * @param config upload config 211 * @param callback Indicate the callback function to receive UploadTask. 212 * @permission ohos.permission.INTERNET 213 * @return - 214 */ 215 function upload(config: UploadConfig, callback: AsyncCallback<UploadTask>): void; 216 217 /** 218 * Starts a upload session. 219 * @syscap SystemCapability.MiscServices.Upload 220 * @since 6 221 * @param config upload config 222 * @permission ohos.permission.INTERNET 223 * @return - 224 */ 225 function upload(config: UploadConfig): Promise<UploadTask>; 226 227 /** 228 * DownloadConfig data Structure 229 * 230 * @name DownloadConfig 231 * @since 6 232 * @syscap SystemCapability.MiscServices.Download 233 * @permission ohos.permission.INTERNET 234 */ 235 interface DownloadConfig { 236 /** 237 * Resource address. 238 * 239 * @since 6 240 * @permission ohos.permission.INTERNET 241 */ 242 url: string; 243 /** 244 * Adds an HTTP or HTTPS header to be included with the download request. 245 * 246 * @since 6 247 * @permission ohos.permission.INTERNET 248 */ 249 header?: Object; 250 /** 251 * Allows download under a metered connection. 252 * 253 * @since 6 254 * @permission ohos.permission.INTERNET 255 */ 256 enableMetered?: boolean; 257 /** 258 * Allows download in a roaming network. 259 * 260 * @since 6 261 * @permission ohos.permission.INTERNET 262 */ 263 enableRoaming?: boolean; 264 /** 265 * Sets the description of a download session. 266 * 267 * @since 6 268 * @permission ohos.permission.INTERNET 269 */ 270 description?: string; 271 /** 272 * Sets the network type allowed for download. 273 * 274 * @since 6 275 * @permission ohos.permission.INTERNET 276 */ 277 networkType?: number; 278 /** 279 * Sets the path for downloads. 280 * 281 * @since 7 282 * @permission ohos.permission.INTERNET 283 */ 284 filePath?: string; 285 /** 286 * Sets a download session title. 287 * 288 * @since 6 289 * @permission ohos.permission.INTERNET 290 */ 291 title?: string; 292 } 293 294 /** 295 * DownloadInfo data Structure 296 * 297 * @name DownloadInfo 298 * @syscap SystemCapability.MiscServices.Download 299 * @since 7 300 * @permission ohos.permission.INTERNET 301 */ 302 interface DownloadInfo { 303 /** 304 * the description of a file to be downloaded. 305 * 306 * @since 7 307 * @permission ohos.permission.INTERNET 308 */ 309 description: string; 310 /** 311 * the real-time downloads size (in bytes). 312 * 313 * @since 7 314 * @permission ohos.permission.INTERNET 315 */ 316 downloadedBytes: number; 317 /** 318 * the ID of a file to be downloaded. 319 * 320 * @since 7 321 * @permission ohos.permission.INTERNET 322 */ 323 downloadId: number; 324 /** 325 * a download failure cause, which can be any DownloadSession.ERROR_* constant. 326 * 327 * @since 7 328 * @permission ohos.permission.INTERNET 329 */ 330 failedReason: number; 331 /** 332 * the name of a file to be downloaded. 333 * 334 * @since 7 335 * @permission ohos.permission.INTERNET 336 */ 337 fileName: string; 338 /** 339 * the URI of a stored file. 340 * 341 * @since 7 342 * @permission ohos.permission.INTERNET 343 */ 344 filePath: string; 345 /** 346 * the reason why a session is paused, which can be any DownloadSession.PAUSED_* constant. 347 * 348 * @since 7 349 * @permission ohos.permission.INTERNET 350 */ 351 pausedReason: number; 352 /** 353 * the download status code, which can be any DownloadSession.SESSION_* constant. 354 * 355 * @since 7 356 * @permission ohos.permission.INTERNET 357 */ 358 status: number; 359 /** 360 * the URI of files to be downloaded. 361 * 362 * @since 7 363 * @permission ohos.permission.INTERNET 364 */ 365 targetURI: string; 366 /** 367 * the title of a file to be downloaded. 368 * 369 * @since 7 370 * @permission ohos.permission.INTERNET 371 */ 372 downloadTitle: string; 373 /** 374 * the total size of files to be downloaded (in bytes). 375 * 376 * @since 7 377 * @permission ohos.permission.INTERNET 378 */ 379 downloadTotalBytes: number; 380 } 381 382 interface DownloadTask { 383 /** 384 * Called when the current download session is in process. 385 * @syscap SystemCapability.MiscServices.Download 386 * @since 6 387 * @param type progress Indicates the download task progress. 388 * @param callback The callback function for the download progress change event 389 * receivedSize the length of downloaded data, in bytes 390 * totalSize he length of data expected to be downloaded, in bytes. 391 * @permission ohos.permission.INTERNET 392 * @return - 393 */ 394 on(type: 'progress', callback: (receivedSize: number, totalSize: number) => void): void; 395 396 /** 397 * Called when the current download session is in process. 398 * @syscap SystemCapability.MiscServices.Download 399 * @since 6 400 * @param type progress Indicates the download task progress. 401 * @param callback The callback function for the download progress change event 402 * receivedSize the length of downloaded data, in bytes 403 * totalSize he length of data expected to be downloaded, in bytes. 404 * @permission ohos.permission.INTERNET 405 * @return - 406 */ 407 off(type: 'progress', callback?: (receivedSize: number, totalSize: number) => void): void; 408 409 /** 410 * Called when the current download session complete、pause or remove. 411 * @syscap SystemCapability.MiscServices.Download 412 * @since 7 413 * @param type Indicates the download session event type 414 * complete: download task completed, 415 * pause: download task stopped, 416 * remove: download task deleted. 417 * @param callback The callback function for the download complete、pause or remove change event. 418 * @permission ohos.permission.INTERNET 419 * @return - 420 */ 421 on(type: 'complete' | 'pause' | 'remove', callback: () => void): void; 422 423 /** 424 * Called when the current download session complete、pause or remove. 425 * @syscap SystemCapability.MiscServices.Download 426 * @since 7 427 * @param type Indicates the download session event type 428 * complete: download task completed, 429 * pause: download task stopped, 430 * remove: download task deleted. 431 * @param callback The callback function for the download complete、pause or remove change event. 432 * @permission ohos.permission.INTERNET 433 * @return - 434 */ 435 off(type: 'complete' | 'pause' | 'remove', callback?: () => void): void; 436 437 /** 438 * Called when the current download session fails. 439 * @syscap SystemCapability.MiscServices.Download 440 * @since 7 441 * @param type Indicates the download session type, fail: download task has failed. 442 * @param callback The callback function for the download fail change event 443 * err The error code for download task. 444 * @permission ohos.permission.INTERNET 445 * @return - 446 */ 447 on(type: 'fail', callback: (err: number) => void): void; 448 449 /** 450 * Called when the current download session fails. 451 * @syscap SystemCapability.MiscServices.Download 452 * @since 7 453 * @param type Indicates the download session type, fail: download task has failed. 454 * @param callback Indicate the callback function to receive err. 455 * err The error code for download task. 456 * @permission ohos.permission.INTERNET 457 * @return - 458 */ 459 off(type: 'fail', callback?: (err: number) => void): void; 460 461 /** 462 * Deletes a download session and the downloaded files. 463 * @syscap SystemCapability.MiscServices.Download 464 * @since 6 465 * @param callback Indicates asynchronous invoking Result. 466 * @permission ohos.permission.INTERNET 467 * @return - 468 */ 469 remove(callback: AsyncCallback<boolean>): void; 470 471 /** 472 * Deletes a download session and the downloaded files. 473 * @syscap SystemCapability.MiscServices.Download 474 * @since 6 475 * @permission ohos.permission.INTERNET 476 * @return - 477 */ 478 remove(): Promise<boolean>; 479 480 /** 481 * Pause a download session. 482 * @syscap SystemCapability.MiscServices.Download 483 * @since 7 484 * @param callback Indicates asynchronous invoking Result. 485 * @permission ohos.permission.INTERNET 486 * @return - 487 */ 488 pause(callback: AsyncCallback<void>): void; 489 490 /** 491 * Pause a download session. 492 * @syscap SystemCapability.MiscServices.Download 493 * @since 7 494 * @permission ohos.permission.INTERNET 495 * @return - 496 */ 497 pause(): Promise<void>; 498 499 /** 500 * Resume a paused download session. 501 * @syscap SystemCapability.MiscServices.Download 502 * @since 7 503 * @param callback Indicates asynchronous invoking Result. 504 * @permission ohos.permission.INTERNET 505 * @return - 506 */ 507 resume(callback: AsyncCallback<void>): void; 508 509 /** 510 * Resume a paused download session. 511 * @syscap SystemCapability.MiscServices.Download 512 * @since 7 513 * @permission ohos.permission.INTERNET 514 * @return - 515 */ 516 resume(): Promise<void>; 517 518 /** 519 * Queries download information of a session, which is defined in DownloadSession.DownloadInfo. 520 * @syscap SystemCapability.MiscServices.Download 521 * @since 7 522 * @param callback Indicate the callback function to receive download info. 523 * @permission ohos.permission.INTERNET 524 * @return - 525 */ 526 query(callback: AsyncCallback<DownloadInfo>): void; 527 528 /** 529 * Queries download information of a session, which is defined in DownloadSession.DownloadInfo. 530 * @syscap SystemCapability.MiscServices.Download 531 * @since 7 532 * @permission ohos.permission.INTERNET 533 * @return - 534 */ 535 query(): Promise<DownloadInfo>; 536 537 /** 538 * Queries the MIME type of the download file. 539 * @syscap SystemCapability.MiscServices.Download 540 * @since 7 541 * @param callback Indicate the callback function to receive download file MIME type. 542 * @permission ohos.permission.INTERNET 543 * @return - 544 */ 545 queryMimeType(callback: AsyncCallback<string>): void; 546 547 /** 548 * Queries the MIME type of the download file. 549 * @syscap SystemCapability.MiscServices.Download 550 * @since 7 551 * @permission ohos.permission.INTERNET 552 * @return - 553 */ 554 queryMimeType(): Promise<string>; 555 } 556 557 /** 558 * File data Structure 559 * 560 * @name File 561 * @since 6 562 * @syscap SystemCapability.MiscServices.Download 563 * @permission ohos.permission.INTERNET 564 */ 565 interface File { 566 /** 567 * When multipart is submitted, the file name in the request header. 568 * 569 * @since 6 570 * @permission ohos.permission.INTERNET 571 */ 572 filename: string; 573 /** 574 * When multipart is submitted, the name of the form item. The default is file. 575 * 576 * @since 6 577 * @permission ohos.permission.INTERNET 578 */ 579 name: string; 580 /** 581 * The local storage path of the file (please refer to the storage directory definition for path usage). 582 * 583 * @since 6 584 * @permission ohos.permission.INTERNET 585 */ 586 uri: string; 587 /** 588 * The content type of the file is obtained by default according to the suffix of the file name or path. 589 * 590 * @since 6 591 * @permission ohos.permission.INTERNET 592 */ 593 type: string; 594 } 595 596 /** 597 * RequestData data Structure 598 * 599 * @name RequestData 600 * @since 6 601 * @syscap SystemCapability.MiscServices.Download 602 * @permission ohos.permission.INTERNET 603 */ 604 interface RequestData { 605 /** 606 * Represents the name of the form element. 607 * 608 * @since 6 609 * @permission ohos.permission.INTERNET 610 */ 611 name: string; 612 /** 613 * Represents the value of the form element. 614 * 615 * @since 6 616 * @permission ohos.permission.INTERNET 617 */ 618 value: string; 619 } 620 621 /** 622 * UploadConfig data Structure 623 * 624 * @name UploadConfig 625 * @since 6 626 * @syscap SystemCapability.MiscServices.Upload 627 * @permission ohos.permission.INTERNET 628 */ 629 interface UploadConfig { 630 /** 631 * Resource address. 632 * 633 * @since 6 634 * @permission ohos.permission.INTERNET 635 */ 636 url: string; 637 /** 638 * Adds an HTTP or HTTPS header to be included with the upload request. 639 * 640 * @since 6 641 * @permission ohos.permission.INTERNET 642 */ 643 header: Object; 644 /** 645 * Request method: POST, PUT. The default POST. 646 * 647 * @since 6 648 * @permission ohos.permission.INTERNET 649 */ 650 method: string; 651 /** 652 * A list of files to be uploaded. Please use multipart/form-data to submit. 653 * 654 * @since 6 655 * @permission ohos.permission.INTERNET 656 */ 657 files: Array<File>; 658 /** 659 * The requested form data. 660 * 661 * @since 6 662 * @permission ohos.permission.INTERNET 663 */ 664 data: Array<RequestData>; 665 } 666 667 interface UploadTask { 668 /** 669 * Called when the current upload session is in process. 670 * @syscap SystemCapability.MiscServices.Upload 671 * @since 6 672 * @param type progress Indicates the upload task progress. 673 * @param callback The callback function for the upload progress change event 674 * uploadedSize The length of uploaded data, in bytes 675 * totalSize The length of data expected to be uploaded, in bytes. 676 * @permission ohos.permission.INTERNET 677 * @return - 678 */ 679 on(type: 'progress', callback: (uploadedSize: number, totalSize: number) => void): void; 680 681 /** 682 * Called when the current upload session is in process. 683 * @syscap SystemCapability.MiscServices.Upload 684 * @since 6 685 * @param type progress Indicates the upload task progress. 686 * @param callback The callback function for the upload progress change event 687 * uploadedSize The length of uploaded data, in bytes 688 * totalSize The length of data expected to be uploaded, in bytes. 689 * @permission ohos.permission.INTERNET 690 * @return - 691 */ 692 off(type: 'progress', callback?: (uploadedSize: number, totalSize: number) => void): void; 693 694 /** 695 * Called when the header of the current upload session has been received. 696 * @syscap SystemCapability.MiscServices.Upload 697 * @since 7 698 * @param type headerReceive Indicates the upload task headed receive. 699 * @param callback The callback function for the HTTP Response Header event 700 * header HTTP Response Header returned by the developer server. 701 * @permission ohos.permission.INTERNET 702 * @return - 703 */ 704 on(type: 'headerReceive', callback: (header: object) => void): void; 705 706 /** 707 * Called when the header of the current upload session has been received. 708 * @syscap SystemCapability.MiscServices.Upload 709 * @since 7 710 * @param type headerReceive Indicates the upload task headed receive. 711 * @param callback The callback function for the HTTP Response Header event 712 * header HTTP Response Header returned by the developer server. 713 * @permission ohos.permission.INTERNET 714 * @return - 715 */ 716 off(type: 'headerReceive', callback?: (header: object) => void): void; 717 718 /** 719 * Deletes a upload session. 720 * @syscap SystemCapability.MiscServices.Upload 721 * @since 6 722 * @param callback Indicates asynchronous invoking Result. 723 * @permission ohos.permission.INTERNET 724 * @return - 725 */ 726 remove(callback: AsyncCallback<boolean>): void; 727 728 /** 729 * Deletes a upload session. 730 * @syscap SystemCapability.MiscServices.Upload 731 * @since 6 732 * @permission ohos.permission.INTERNET 733 * @return - 734 */ 735 remove(): Promise<boolean>; 736 } 737} 738 739export default request; 740 741