1# @ohos.file.cloudSync (Device-Cloud Synchronization) (System API) 2 3The **cloudSync** module provides the device-cloud synchronization capabilities for applications. You can use the APIs to start or stop device-cloud synchronization and start or stop the download of images. 4 5> **NOTE** 6> 7> - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> - This topic describes only the system APIs provided by the module. For details about its public APIs, see [@ohos.file.cloudSync (Device-Cloud Synchronization Capability)](js-apis-file-cloudsync.md). 9 10## Modules to Import 11 12```ts 13import cloudSync from '@ohos.file.cloudSync'; 14``` 15 16## SyncState 17 18Enumerates the device-cloud synchronization states. 19 20> **NOTE** 21> 22> If a synchronization progress event listener is registered for an application, a callback will be invoked to notify the application when the device-cloud synchronization state is changed. 23 24**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 25 26**System API**: This is a system API. 27 28| Name| Value| Description| 29| ----- | ---- | ---- | 30| UPLOADING | 0 | Uploading.| 31| UPLOAD_FAILED | 1 | Upload failed.| 32| DOWNLOADING | 2 | Downloading.| 33| DOWNLOAD_FAILED | 3 | Download failed.| 34| COMPLETED | 4 | Synchronization completed.| 35| STOPPED | 5 | Synchronization stopped.| 36 37## ErrorType 38 39Enumerates the device-cloud synchronization errors. 40 41- Currently, **NETWORK_UNAVAILABLE** is returned only when both the mobile network and Wi-Fi are unavailable during synchronization. If either network is available, synchronization can be performed normally. 42- During the synchronization process, if the battery level is lower than 15% in non-charging scenarios, **BATTERY_LEVEL_LOW** will be return when the current upload is complete; if the battery level is lower than 10% in non-charging scenarios, **BATTERY_LEVEL_WARNING** will be returned when the current upload is complete. 43- When synchronization is being triggered, if the battery level is lower than 15% in non-charging scenarios, synchronization is not allowed and an error code will be returned by **start()**. 44- If the cloud space is insufficient when a file is uploaded, the upload will fail and there is no such a file in the cloud. 45- If the local space is insufficient when a file is downloaded, the download will fail. After the local space is released, the file will be downloaded again when synchronization starts. 46 47**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 48 49**System API**: This is a system API. 50 51| Name| Value| Description| 52| ----- | ---- | ---- | 53| NO_ERROR | 0 | No error.| 54| NETWORK_UNAVAILABLE | 1 | No network is available.| 55| WIFI_UNAVAILABLE | 2 | Wi-Fi is unavailable.| 56| BATTERY_LEVEL_LOW | 3 | The battery level is lower than 15%.| 57| BATTERY_LEVEL_WARNING | 4 | The battery level is lower than 10%.| 58| CLOUD_STORAGE_FULL | 5 | The cloud space is insufficient.| 59| LOCAL_STORAGE_FULL | 6 | The local space is insufficient.| 60 61## SyncProgress 62 63Represents information about the device-cloud synchronization progress. 64 65**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 66 67**System API**: This is a system API. 68 69| Name | Type | Mandatory| Description| 70| ---------- | ------ | ---- | ---- | 71| state | [SyncState](#syncstate) | Yes | Device-cloud synchronization state.| 72| error | [ErrorType](#errortype) | Yes | Synchronization error.| 73 74## GallerySync 75 76Provides APIs to implement device-cloud synchronization of media assets in **Gallery**. Before using the APIs of **GallerySync**, you need to create a **GallerySync** instance. 77 78### constructor 79 80constructor() 81 82A constructor used to create a **GallerySync** instance. 83 84**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 85 86**System API**: This is a system API. 87 88**Example** 89 90 ```ts 91 let gallerySync = new cloudSync.GallerySync() 92 ``` 93 94### on 95 96on(evt: 'progress', callback: (pg: SyncProgress) => void): void 97 98Registers a listener for the device-cloud synchronization progress. 99 100**Required permissions**: ohos.permission.CLOUDFILE_SYNC 101 102**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 103 104**System API**: This is a system API. 105 106**Parameters** 107 108| Name | Type | Mandatory| Description| 109| ---------- | ------ | ---- | ---- | 110| evt | string | Yes | Event type. The value is **progress**, which indicates the synchronization progress event.| 111| callback | (pg: SyncProgress) => void | Yes | Callback invoked to return the synchronization progress event. The input parameter is [SyncProgress](#syncprogress), and the return value is **void**.| 112 113**Error codes** 114 115For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 116 117| ID | Error Message | 118| ---------------------------- | ---------- | 119| 201 | Permission verification failed. | 120| 202 | The caller is not a system application. | 121| 401 | The input parameter is invalid. | 122| 13600001 | IPC error. | 123 124**Example** 125 126 ```ts 127 let gallerySync = new cloudSync.GallerySync(); 128 129 gallerySync.on('progress', (pg: cloudSync.SyncProgress) => { 130 console.info("syncState: " + pg.state); 131 }); 132 ``` 133 134### off 135 136off(evt: 'progress', callback: (pg: SyncProgress) => void): void 137 138Unregisters a listener for the device-cloud synchronization progress. 139 140**Required permissions**: ohos.permission.CLOUDFILE_SYNC 141 142**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 143 144**System API**: This is a system API. 145 146**Parameters** 147 148| Name | Type | Mandatory| Description| 149| ---------- | ------ | ---- | ---- | 150| evt | string | Yes | Event type. The value is **progress**, which indicates the synchronization progress event.| 151| callback | (pg: SyncProgress) => void | Yes | Callback for the synchronization progress event. The input parameter is [SyncProgress](#syncprogress), and the return value is **void**.| 152 153**Error codes** 154 155For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 156 157| ID | Error Message | 158| ---------------------------- | ---------- | 159| 201 | Permission verification failed. | 160| 202 | The caller is not a system application. | 161| 401 | The input parameter is invalid. | 162| 13600001 | IPC error. | 163 164**Example** 165 166 ```ts 167 let gallerySync = new cloudSync.GallerySync(); 168 169 let callback = (pg: cloudSync.SyncProgress) => { 170 console.info("gallery sync state: " + pg.state + "error type:" + pg.error); 171 } 172 173 gallerySync.on('progress', callback); 174 175 gallerySync.off('progress', callback); 176 ``` 177 178### off 179 180off(evt: 'progress'): void 181 182Unregisters all listeners for the device-cloud synchronization progress. 183 184**Required permissions**: ohos.permission.CLOUDFILE_SYNC 185 186**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 187 188**System API**: This is a system API. 189 190**Parameters** 191 192| Name | Type | Mandatory| Description| 193| ---------- | ------ | ---- | ---- | 194| evt | string | Yes | Event type. The value is **progress**, which indicates the synchronization progress event.| 195 196**Error codes** 197 198For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 199 200| ID | Error Message | 201| ---------------------------- | ---------- | 202| 201 | Permission verification failed. | 203| 202 | The caller is not a system application. | 204| 401 | The input parameter is invalid. | 205| 13600001 | IPC error. | 206 207**Example** 208 209 ```ts 210 let gallerySync = new cloudSync.GallerySync(); 211 212 gallerySync.on('progress', (pg: cloudSync.SyncProgress) => { 213 console.info("syncState: " + pg.state); 214 }); 215 216 gallerySync.off('progress'); 217 ``` 218 219### start 220 221start(): Promise<void> 222 223Starts device-cloud synchronization. This API uses a promise to return the result. 224 225**Required permissions**: ohos.permission.CLOUDFILE_SYNC 226 227**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 228 229**System API**: This is a system API. 230 231**Return value** 232 233| Type | Description | 234| --------------------- | ---------------- | 235| Promise<void> | Promise used to return the result.| 236 237**Error codes** 238 239For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 240 241| ID | Error Message | 242| ---------------------------- | ---------- | 243| 201 | Permission verification failed. | 244| 202 | The caller is not a system application. | 245| 401 | The input parameter is invalid. | 246| 22400001 | Cloud status not ready. | 247| 22400002 | Network unavailable. | 248| 22400003 | Battery level warning. | 249 250**Example** 251 252 ```ts 253 import { BusinessError } from '@ohos.base'; 254 let gallerySync = new cloudSync.GallerySync(); 255 256 gallerySync.on('progress', (pg: cloudSync.SyncProgress) => { 257 console.info("syncState: " + pg.state); 258 }); 259 260 gallerySync.start().then(() => { 261 console.info("start sync successfully"); 262 }).catch((err: BusinessError) => { 263 console.info("start sync failed with error message: " + err.message + ", error code: " + err.code); 264 }); 265 ``` 266 267### start 268 269start(callback: AsyncCallback<void>): void 270 271Starts device-cloud synchronization. This API uses an asynchronous callback to return the result. 272 273**Required permissions**: ohos.permission.CLOUDFILE_SYNC 274 275**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 276 277**System API**: This is a system API. 278 279**Parameters** 280 281| Name | Type | Mandatory| Description| 282| ---------- | ------ | ---- | ---- | 283| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.| 284 285**Error codes** 286 287For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 288 289| ID | Error Message | 290| ---------------------------- | ---------- | 291| 201 | Permission verification failed. | 292| 202 | The caller is not a system application. | 293| 401 | The input parameter is invalid. | 294| 22400001 | Cloud status not ready. | 295| 22400002 | Network unavailable. | 296| 22400003 | Battery level warning. | 297 298**Example** 299 300 ```ts 301 import { BusinessError } from '@ohos.base'; 302 let gallerySync = new cloudSync.GallerySync(); 303 304 gallerySync.start((err: BusinessError) => { 305 if (err) { 306 console.info("start sync failed with error message: " + err.message + ", error code: " + err.code); 307 } else { 308 console.info("start sync successfully"); 309 } 310 }); 311 ``` 312 313### stop 314 315stop(): Promise<void> 316 317Stops device-cloud synchronization. This API uses a promise to return the result. 318 319> **NOTE** 320> 321> Calling **stop** will stop the synchronization process. To resume the synchronization, call [start](#start). 322 323**Required permissions**: ohos.permission.CLOUDFILE_SYNC 324 325**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 326 327**System API**: This is a system API. 328 329**Return value** 330 331| Type | Description | 332| --------------------- | ---------------- | 333| Promise<void> | Promise used to return the result.| 334 335**Error codes** 336 337For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 338 339| ID | Error Message | 340| ---------------------------- | ---------- | 341| 201 | Permission verification failed. | 342| 202 | The caller is not a system application. | 343| 401 | The input parameter is invalid. | 344 345**Example** 346 347 ```ts 348 import { BusinessError } from '@ohos.base'; 349 let gallerySync = new cloudSync.GallerySync(); 350 351 gallerySync.stop().then(() => { 352 console.info("stop sync successfully"); 353 }).catch((err: BusinessError) => { 354 console.info("stop sync failed with error message: " + err.message + ", error code: " + err.code); 355 }); 356 ``` 357 358### stop 359 360stop(callback: AsyncCallback<void>): void 361 362Stops device-cloud synchronization. This API uses an asynchronous callback to return the result. 363 364> **NOTE** 365> 366> Calling **stop** will stop the synchronization process. To resume the synchronization, call [start](#start-1). 367 368**Required permissions**: ohos.permission.CLOUDFILE_SYNC 369 370**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 371 372**System API**: This is a system API. 373 374**Parameters** 375 376| Name | Type | Mandatory| Description| 377| ---------- | ------ | ---- | ---- | 378| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.| 379 380**Error codes** 381 382For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 383 384| ID | Error Message | 385| ---------------------------- | ---------- | 386| 201 | Permission verification failed. | 387| 202 | The caller is not a system application. | 388| 401 | The input parameter is invalid. | 389 390**Example** 391 392 ```ts 393 import { BusinessError } from '@ohos.base'; 394 let gallerySync = new cloudSync.GallerySync(); 395 396 gallerySync.stop((err: BusinessError) => { 397 if (err) { 398 console.info("stop sync failed with error message: " + err.message + ", error code: " + err.code); 399 } else { 400 console.info("stop sync successfully"); 401 } 402 }); 403 ``` 404 405## Download 406 407Provides APIs for downloading image files to **Gallery**. Before using the APIs of **Download**, you need to create a **Download** instance. 408 409### constructor 410 411constructor() 412 413A constructor used to create a **Download** instance. 414 415**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 416 417**System API**: This is a system API. 418 419**Example** 420 421 ```ts 422 let download = new cloudSync.Download() 423 ``` 424 425### on 426 427on(evt: 'progress', callback: (pg: DownloadProgress) => void): void 428 429Registers a listener for the download progress of a cloud file. 430 431**Required permissions**: ohos.permission.CLOUDFILE_SYNC 432 433**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 434 435**System API**: This is a system API. 436 437**Parameters** 438 439| Name | Type | Mandatory| Description| 440| ---------- | ------ | ---- | ---- | 441| evt | string | Yes | Event. The value is **progress**, which indicates the download progress event of a cloud file.| 442| callback | (pg: DownloadProgress) => void | Yes | Callback invoked to return the registered event. The input parameter is [DownloadProgress](js-apis-file-cloudsync.md#downloadprogress11), and the return value is **void**.| 443 444**Error codes** 445 446For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 447 448| ID | Error Message | 449| ---------------------------- | ---------- | 450| 201 | Permission verification failed. | 451| 202 | The caller is not a system application. | 452| 401 | The input parameter is invalid. | 453| 13600001 | IPC error. | 454 455**Example** 456 457 ```ts 458 let download = new cloudSync.Download(); 459 460 download.on('progress', (pg: cloudSync.DownloadProgress) => { 461 console.info("download state: " + pg.state); 462 }); 463 ``` 464 465### off 466 467off(evt: 'progress', callback: (pg: DownloadProgress) => void): void 468 469Unregisters a listener for the download progress of a cloud file. 470 471**Required permissions**: ohos.permission.CLOUDFILE_SYNC 472 473**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 474 475**System API**: This is a system API. 476 477**Parameters** 478 479| Name | Type | Mandatory| Description| 480| ---------- | ------ | ---- | ---- | 481| evt | string | Yes | Event type. The value is **progress**, which indicates the download progress event of a cloud file.| 482| callback | (pg: DownloadProgress) => void | Yes | Callback for the download progress event of a cloud file. The input parameter is [DownloadProgress](js-apis-file-cloudsync.md#downloadprogress11), and the return value is **void**.| 483 484**Error codes** 485 486For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 487 488| ID | Error Message | 489| ---------------------------- | ---------- | 490| 201 | Permission verification failed. | 491| 202 | The caller is not a system application. | 492| 401 | The input parameter is invalid. | 493| 13600001 | IPC error. | 494 495**Example** 496 497 ```ts 498 let download = new cloudSync.Download(); 499 500 let callback = (pg: cloudSync.DownloadProgress) => { 501 console.info("download state: " + pg.state); 502 } 503 504 download.on('progress', callback); 505 506 download.off('progress', callback); 507 ``` 508 509### off 510 511off(evt: 'progress'): void 512 513Unregisters all listeners for the download progress event of a cloud file. 514 515**Required permissions**: ohos.permission.CLOUDFILE_SYNC 516 517**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 518 519**System API**: This is a system API. 520 521**Parameters** 522 523| Name | Type | Mandatory| Description| 524| ---------- | ------ | ---- | ---- | 525| evt | string | Yes | Event type. The value is **progress**, which indicates the download progress event of a cloud file.| 526 527**Error codes** 528 529For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 530 531| ID | Error Message | 532| ---------------------------- | ---------- | 533| 201 | Permission verification failed. | 534| 202 | The caller is not a system application. | 535| 401 | The input parameter is invalid. | 536| 13600001 | IPC error. | 537 538**Example** 539 540 ```ts 541 let download = new cloudSync.Download(); 542 543 download.on('progress', (pg: cloudSync.DownloadProgress) => { 544 console.info("download state:" + pg.state); 545 }); 546 547 download.off('progress'); 548 ``` 549 550### start 551 552start(uri: string): Promise<void> 553 554Starts to download a cloud file. This API uses a promise to return the result. 555 556**Required permissions**: ohos.permission.CLOUDFILE_SYNC 557 558**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 559 560**System API**: This is a system API. 561 562**Parameters** 563 564| Name | Type | Mandatory| Description| 565| ---------- | ------ | ---- | ---- | 566| uri | string | Yes | URI of the file to download.| 567 568**Return value** 569 570| Type | Description | 571| --------------------- | ---------------- | 572| Promise<void> | Promise used to return the result.| 573 574**Example** 575 576 ```ts 577 import { BusinessError } from '@ohos.base'; 578 let download = new cloudSync.Download(); 579 let uri: string = "file:///media/Photo/1"; 580 581 download.on('progress', (pg: cloudSync.DownloadProgress) => { 582 console.info("download state:" + pg.state); 583 }); 584 585 download.start(uri).then(() => { 586 console.info("start download successfully"); 587 }).catch((err: BusinessError) => { 588 console.info("start download failed with error message: " + err.message + ", error code: " + err.code); 589 }); 590 ``` 591 592**Error codes** 593 594For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 595 596| ID | Error Message | 597| ---------------------------- | ---------- | 598| 201 | Permission verification failed. | 599| 202 | The caller is not a system application. | 600| 401 | The input parameter is invalid. | 601| 13900002 | No such file or directory. | 602| 13900025 | No space left on device. | 603 604### start 605 606start(uri: string, callback: AsyncCallback<void>): void 607 608Starts to download a cloud file. This API uses an asynchronous callback to return the result. 609 610**Required permissions**: ohos.permission.CLOUDFILE_SYNC 611 612**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 613 614**System API**: This is a system API. 615 616**Parameters** 617 618| Name | Type | Mandatory| Description| 619| ---------- | ------ | ---- | ---- | 620| uri | string | Yes | URI of the file to download.| 621| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.| 622 623**Error codes** 624 625For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 626 627| ID | Error Message | 628| ---------------------------- | ---------- | 629| 201 | Permission verification failed. | 630| 202 | The caller is not a system application. | 631| 401 | The input parameter is invalid. | 632| 13900002 | No such file or directory. | 633| 13900025 | No space left on device. | 634 635**Example** 636 637 ```ts 638 import { BusinessError } from '@ohos.base'; 639 let download = new cloudSync.Download(); 640 let uri: string = "file:///media/Photo/1"; 641 642 download.start(uri, (err: BusinessError) => { 643 if (err) { 644 console.info("start download failed with error message: " + err.message + ", error code: " + err.code); 645 } else { 646 console.info("start download successfully"); 647 } 648 }); 649 ``` 650 651### stop 652 653stop(uri: string): Promise<void> 654 655Stops downloading a cloud file. This API uses a promise to return the result. 656 657> **NOTE** 658> 659> Calling **stop** will terminate the download of the current file and clear the cache file. You can use **start** to start the download again. 660 661**Required permissions**: ohos.permission.CLOUDFILE_SYNC 662 663**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 664 665**System API**: This is a system API. 666 667**Parameters** 668 669| Name | Type | Mandatory| Description| 670| ---------- | ------ | ---- | ---- | 671| uri | string | Yes | URI of the file to download.| 672 673**Return value** 674 675| Type | Description | 676| --------------------- | ---------------- | 677| Promise<void> | Promise used to return the result.| 678 679**Error codes** 680 681For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 682 683| ID | Error Message | 684| ---------------------------- | ---------- | 685| 201 | Permission verification failed. | 686| 202 | The caller is not a system application. | 687| 401 | The input parameter is invalid. | 688 689**Example** 690 691 ```ts 692 import { BusinessError } from '@ohos.base'; 693 let download = new cloudSync.Download(); 694 let uri: string = "file:///media/Photo/1"; 695 696 download.stop(uri).then(() => { 697 console.info("stop download successfully"); 698 }).catch((err: BusinessError) => { 699 console.info("stop download failed with error message: " + err.message + ", error code: " + err.code); 700 }); 701 ``` 702 703### stop 704 705stop(uri: string, callback: AsyncCallback<void>): void 706 707Stops downloading a cloud file. This API uses an asynchronous callback to return the result. 708 709> **NOTE** 710> 711> Calling **stop** will terminate the download of the current file and clear the cache file. You can use **start** to start the download again. 712 713**Required permissions**: ohos.permission.CLOUDFILE_SYNC 714 715**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 716 717**System API**: This is a system API. 718 719**Parameters** 720 721| Name | Type | Mandatory| Description| 722| ---------- | ------ | ---- | ---- | 723| uri | string | Yes | URI of the file to download.| 724| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.| 725 726**Error codes** 727 728For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 729 730| ID | Error Message | 731| ---------------------------- | ---------- | 732| 201 | Permission verification failed. | 733| 202 | The caller is not a system application. | 734| 401 | The input parameter is invalid. | 735 736**Example** 737 738 ```ts 739 import { BusinessError } from '@ohos.base'; 740 let download = new cloudSync.Download(); 741 let uri: string = "file:///media/Photo/1"; 742 743 download.stop(uri, (err: BusinessError) => { 744 if (err) { 745 console.info("stop download failed with error message: " + err.message + ", error code: " + err.code); 746 } else { 747 console.info("stop download successfully"); 748 } 749 }); 750 ``` 751 752## FileSync<sup>11+</sup> 753 754Provides APIs for the file manager application to perform device-cloud synchronization of the files stored in the Drive Kit. Before using the APIs of this class, you need to create a **FileSync** instance. 755 756### constructor<sup>11+</sup> 757 758constructor() 759 760A constructor used to create a **FileSync** instance. 761 762**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 763 764**System API**: This is a system API. 765 766**Error codes** 767 768For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 769 770| ID | Error Message | 771| ---------------------------- | ---------- | 772| 202 | Permission verification failed, application which is not a system application uses system API. | 773| 401 | The input parameter is invalid. | 774 775**Example** 776 777 ```ts 778 let fileSync = new cloudSync.FileSync() 779 ``` 780 781### on<sup>11+</sup> 782 783on(event: 'progress', callback: Callback\<SyncProgress>): void 784 785Registers a listener for the device-cloud synchronization progress. 786 787**Required permissions**: ohos.permission.CLOUDFILE_SYNC 788 789**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 790 791**System API**: This is a system API. 792 793**Parameters** 794 795| Name | Type | Mandatory| Description| 796| ---------- | ------ | ---- | ---- | 797| event | string | Yes | Event type. The value is **progress**, which indicates the synchronization progress event.| 798| callback | Callback\<[SyncProgress](#syncprogress)> | Yes | Callback invoked to return the synchronization progress information.| 799 800**Error codes** 801 802For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 803 804| ID | Error Message | 805| ---------------------------- | ---------- | 806| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 807| 202 | Permission verification failed, application which is not a system application uses system API. | 808| 401 | The input parameter is invalid. | 809| 13600001 | IPC error. | 810 811**Example** 812 813 ```ts 814 let fileSync = new cloudSync.FileSync(); 815 let callback = (pg: cloudSync.SyncProgress) => { 816 console.info("file sync state: " + pg.state + "error type:" + pg.error); 817 } 818 819 fileSync.on('progress', callback); 820 ``` 821 822### off<sup>11+</sup> 823 824off(event: 'progress', callback?: Callback\<SyncProgress>): void 825 826Unregisters a listener for the device-cloud synchronization progress. 827 828**Required permissions**: ohos.permission.CLOUDFILE_SYNC 829 830**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 831 832**System API**: This is a system API. 833 834**Parameters** 835 836| Name | Type | Mandatory| Description| 837| ---------- | ------ | ---- | ---- | 838| event | string | Yes | Event type. The value is **progress**, which indicates the synchronization progress event.| 839| callback | Callback\<[SyncProgress](#syncprogress)> | No | Callback for the synchronization progress event.| 840 841**Error codes** 842 843For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 844 845| ID | Error Message | 846| ---------------------------- | ---------- | 847| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 848| 202 | Permission verification failed, application which is not a system application uses system API. | 849| 401 | The input parameter is invalid. | 850| 13600001 | IPC error. | 851 852**Example** 853 854 ```ts 855 let fileSync = new cloudSync.FileSync(); 856 857 let callback = (pg: cloudSync.SyncProgress) => { 858 console.info("file sync state: " + pg.state + "error type:" + pg.error); 859 } 860 861 fileSync.on('progress', callback); 862 863 fileSync.off('progress', callback); 864 ``` 865 866### start<sup>11+</sup> 867 868start(): Promise<void> 869 870Starts device-cloud synchronization of a file in the Drive Kit. This API uses a promise to return the result. 871 872**Required permissions**: ohos.permission.CLOUDFILE_SYNC 873 874**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 875 876**System API**: This is a system API. 877 878**Return value** 879 880| Type | Description | 881| --------------------- | ---------------- | 882| Promise<void> | Promise that returns no value.| 883 884**Error codes** 885 886For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 887 888| ID | Error Message | 889| ---------------------------- | ---------- | 890| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 891| 202 | Permission verification failed, application which is not a system application uses system API. | 892| 401 | The input parameter is invalid. | 893| 13600001 | IPC error. | 894| 22400001 | Cloud status not ready. | 895| 22400002 | Network unavailable. | 896| 22400003 | Battery level warning. | 897 898**Example** 899 900 ```ts 901 import { BusinessError } from '@ohos.base'; 902 let fileSync = new cloudSync.FileSync(); 903 904 let callback = (pg: cloudSync.SyncProgress) => { 905 console.info("file sync state: " + pg.state + "error type:" + pg.error); 906 } 907 908 fileSync.on('progress', callback); 909 910 fileSync.start().then(() => { 911 console.info("start sync successfully"); 912 }).catch((err: BusinessError) => { 913 console.info("start sync failed with error message: " + err.message + ", error code: " + err.code); 914 }); 915 ``` 916 917### start<sup>11+</sup> 918 919start(callback: AsyncCallback<void>): void 920 921Starts device-cloud synchronization of a file in the Drive Kit. This API uses an asynchronous callback to return the result. 922 923**Required permissions**: ohos.permission.CLOUDFILE_SYNC 924 925**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 926 927**System API**: This is a system API. 928 929**Parameters** 930 931| Name | Type | Mandatory| Description| 932| ---------- | ------ | ---- | ---- | 933| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.| 934 935**Error codes** 936 937For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 938 939| ID | Error Message | 940| ---------------------------- | ---------- | 941| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 942| 202 | Permission verification failed, application which is not a system application uses system API. | 943| 401 | The input parameter is invalid. | 944| 13600001 | IPC error. | 945| 22400001 | Cloud status not ready. | 946| 22400002 | Network unavailable. | 947| 22400003 | Battery level warning. | 948 949**Example** 950 951 ```ts 952 import { BusinessError } from '@ohos.base'; 953 let fileSync = new cloudSync.FileSync(); 954 955 fileSync.start((err: BusinessError) => { 956 if (err) { 957 console.info("start sync failed with error message: " + err.message + ", error code: " + err.code); 958 } else { 959 console.info("start sync successfully"); 960 } 961 }); 962 ``` 963 964### stop<sup>11+</sup> 965 966stop(): Promise<void> 967 968Stops device-cloud synchronization of the file in the Drive Kit. This API uses a promise to return the result. 969 970Calling **stop** will stop the synchronization process. To resume the synchronization, call [start](#start11). 971 972**Required permissions**: ohos.permission.CLOUDFILE_SYNC 973 974**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 975 976**System API**: This is a system API. 977 978**Return value** 979 980| Type | Description | 981| --------------------- | ---------------- | 982| Promise<void> | Promise used to return the result.| 983 984**Error codes** 985 986For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 987 988| ID | Error Message | 989| ---------------------------- | ---------- | 990| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 991| 202 | Permission verification failed, application which is not a system application uses system API. | 992| 401 | The input parameter is invalid. | 993| 13600001 | IPC error. | 994 995**Example** 996 997 ```ts 998 import { BusinessError } from '@ohos.base'; 999 let fileSync = new cloudSync.FileSync(); 1000 1001 fileSync.stop().then(() => { 1002 console.info("stop sync successfully"); 1003 }).catch((err: BusinessError) => { 1004 console.info("stop sync failed with error message: " + err.message + ", error code: " + err.code); 1005 }); 1006 ``` 1007 1008### stop<sup>11+</sup> 1009 1010stop(callback: AsyncCallback<void>): void 1011 1012Stops device-cloud synchronization of the file in the Drive Kit. This API uses an asynchronous callback to return the result. 1013 1014Calling **stop** will stop the synchronization process. To resume the synchronization, call [start](#start11-1). 1015 1016**Required permissions**: ohos.permission.CLOUDFILE_SYNC 1017 1018**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1019 1020**System API**: This is a system API. 1021 1022**Parameters** 1023 1024| Name | Type | Mandatory| Description| 1025| ---------- | ------ | ---- | ---- | 1026| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.| 1027 1028**Error codes** 1029 1030For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 1031 1032| ID | Error Message | 1033| ---------------------------- | ---------- | 1034| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 1035| 202 | Permission verification failed, application which is not a system application uses system API. | 1036| 401 | The input parameter is invalid. | 1037| 13600001 | IPC error. | 1038 1039**Example** 1040 1041 ```ts 1042 import { BusinessError } from '@ohos.base'; 1043 let fileSync = new cloudSync.FileSync(); 1044 1045 fileSync.stop((err: BusinessError) => { 1046 if (err) { 1047 console.info("stop sync failed with error message: " + err.message + ", error code: " + err.code); 1048 } else { 1049 console.info("stop sync successfully"); 1050 } 1051 }); 1052 ``` 1053 1054### getLastSyncTime<sup>11+</sup> 1055 1056getLastSyncTime(): Promise<number> 1057 1058Obtains the last synchronization time. This API uses a promise to return the result. 1059 1060**Required permissions**: ohos.permission.CLOUDFILE_SYNC 1061 1062**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1063 1064**System API**: This is a system API. 1065 1066**Return value** 1067 1068| Type | Description | 1069| --------------------- | ---------------- | 1070| Promise<number> | Promise used to return the last synchronization time obtained.| 1071 1072**Error codes** 1073 1074For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 1075 1076| ID | Error Message | 1077| ---------------------------- | ---------- | 1078| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 1079| 202 | Permission verification failed, application which is not a system application uses system API. | 1080| 401 | The input parameter is invalid. | 1081| 13600001 | IPC error. | 1082 1083**Example** 1084 1085 ```ts 1086 import { BusinessError } from '@ohos.base'; 1087 let fileSync = new cloudSync.FileSync(); 1088 1089 fileSync.getLastSyncTime().then((timeStamp: number) => { 1090 let date = new Date(timeStamp); 1091 console.info("get last sync time successfully:"+ date); 1092 }).catch((err: BusinessError) => { 1093 console.info("get last sync time failed with error message: " + err.message + ", error code: " + err.code); 1094 }); 1095 1096 ``` 1097 1098### getLastSyncTime<sup>11+</sup> 1099 1100getLastSyncTime(callback: AsyncCallback<number>): void; 1101 1102Obtains the last synchronization time. This API uses an asynchronous callback to return the result. 1103 1104**Required permissions**: ohos.permission.CLOUDFILE_SYNC 1105 1106**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1107 1108**System API**: This is a system API. 1109 1110**Parameters** 1111 1112| Name | Type | Mandatory| Description| 1113| ---------- | ------ | ---- | ---- | 1114| callback | AsyncCallback<number> | Yes | Callback invoked to return the last synchronization time obtained.| 1115 1116**Error codes** 1117 1118For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 1119 1120| ID | Error Message | 1121| ---------------------------- | ---------- | 1122| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 1123| 202 | Permission verification failed, application which is not a system application uses system API. | 1124| 401 | The input parameter is invalid. | 1125| 13600001 | IPC error. | 1126 1127**Example** 1128 1129 ```ts 1130 import { BusinessError } from '@ohos.base'; 1131 let fileSync = new cloudSync.FileSync(); 1132 1133 fileSync.getLastSyncTime((err: BusinessError, timeStamp: number) => { 1134 if (err) { 1135 console.info("get last sync time with error message: " + err.message + ", error code: " + err.code); 1136 } else { 1137 let date = new Date(timeStamp); 1138 console.info("get last sync time successfully:"+ date); 1139 } 1140 }); 1141 ``` 1142 1143## CloudFileCache<sup>11+</sup> 1144 1145Provides APIs for the file manager application to download files from the Drive Kit to a local device. 1146 1147**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1148 1149### cleanCache<sup>11+</sup> 1150 1151cleanCache(uri: string): void; 1152 1153Deletes a cache file. This API returns the result synchronously. 1154 1155**Required permissions**: ohos.permission.CLOUDFILE_SYNC 1156 1157**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1158 1159**System API**: This is a system API. 1160 1161**Parameters** 1162 1163| Name | Type | Mandatory| Description| 1164| ---------- | ------ | ---- | ---- | 1165| uri | string | Yes | URI of the cache file to delete.| 1166 1167**Error codes** 1168 1169For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 1170 1171| ID | Error Message | 1172| ---------------------------- | ---------- | 1173| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 1174| 202 | Permission verification failed, application which is not a system application uses system API. | 1175| 401 | The input parameter is invalid. | 1176| 13600001 | IPC error. | 1177| 13900002 | No such file or directory. | 1178| 14000002 | Invalid uri. | 1179 1180**Example** 1181 1182 ```ts 1183 import { BusinessError } from '@ohos.base'; 1184 import fileUri from '@ohos.file.fileuri'; 1185 let fileCache = new cloudSync.CloudFileCache(); 1186 let path = "/data/storage/el2/cloud/1.txt"; 1187 let uri = fileUri.getUriFromPath(path); 1188 1189 try { 1190 fileCache.cleanCache(uri); 1191 } catch (err) { 1192 let error:BusinessError = err as BusinessError; 1193 console.info("clean cache failed with error message: " + err.message + ", error code: " + err.code); 1194 } 1195 1196 ``` 1197 1198## cloudSync.getFileSyncState<sup>11+</sup> 1199 1200getFileSyncState(uri: Array<string>): Promise<Array<FileSyncState>> 1201 1202Obtains the file synchronization state. This API uses a promise to return the result. 1203 1204**Required permissions**: ohos.permission.CLOUDFILE_SYNC 1205 1206**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1207 1208**System API**: This is a system API. 1209 1210**Parameters** 1211 1212| Name | Type | Mandatory| Description| 1213| ---------- | ------ | ---- | ---- | 1214| uri | Array<string> | Yes | URI of the file whose synchronization state is to be obtained.| 1215 1216**Return value** 1217 1218| Type | Description | 1219| --------------------- | ---------------- | 1220| Promise<Array<FileSyncState>> | Promise used to return the synchronization state obtained.| 1221 1222**Error codes** 1223 1224For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 1225 1226| ID | Error Message | 1227| ---------------------------- | ---------- | 1228| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 1229| 202 | Permission verification failed, application which is not a system application uses system API. | 1230| 401 | The input parameter is invalid. | 1231| 13600001 | IPC error. | 1232| 13900002 | No such file or directory. | 1233| 14000002 | Invalid uri. | 1234 1235**Example** 1236 1237 ```ts 1238 import { BusinessError } from '@ohos.base'; 1239 1240 let uris: Array<string> = ["file://uri"]; 1241 cloudSync.getFileSyncState(uris).then(function(syncStates: Array<cloudSync.FileSyncState>) { 1242 for(let i = 0, len = syncStates.length; i < len; i++){ 1243 console.info("get file sync state successfully" + syncStates[i]); 1244 } 1245 }).catch((err: BusinessError) => { 1246 console.info("get file sync state failed with error message: " + err.message + ", error code: " + err.code); 1247 }); 1248 1249 ``` 1250 1251## cloudSync.getFileSyncState<sup>11+</sup> 1252 1253getFileSyncState(uri: Array<string>, callback: AsyncCallback<Array<FileSyncState>>): void 1254 1255Obtains the file synchronization state. This API uses an asynchronous callback to return the result. 1256 1257**Required permissions**: ohos.permission.CLOUDFILE_SYNC 1258 1259**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1260 1261**System API**: This is a system API. 1262 1263**Parameters** 1264 1265| Name | Type | Mandatory| Description| 1266| ---------- | ------ | ---- | ---- | 1267| uri | Array<string> | Yes | URI of the file whose synchronization state is to be obtained.| 1268| callback | AsyncCallback<Array<FileSyncState>> | Yes | Callback invoked to return the file synchronization state.| 1269 1270**Error codes** 1271 1272For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 1273 1274| ID | Error Message | 1275| ---------------------------- | ---------- | 1276| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 1277| 202 | Permission verification failed, application which is not a system application uses system API. | 1278| 401 | The input parameter is invalid. | 1279| 13600001 | IPC error. | 1280| 13900002 | No such file or directory. | 1281| 14000002 | Invalid uri. | 1282 1283**Example** 1284 1285 ```ts 1286 import { BusinessError } from '@ohos.base'; 1287 1288 let uris: Array<string> = ["file://uri"]; 1289 cloudSync.getFileSyncState(uris, (err: BusinessError, syncStates: Array<cloudSync.FileSyncState>) => { 1290 if (err) { 1291 console.info("get file sync state with error message: " + err.message + ", error code: " + err.code); 1292 } else { 1293 for(let i = 0, len = syncStates.length; i < len; i++){ 1294 console.info("get file sync state successfully" + syncStates[i]); 1295 } 1296 } 1297 }); 1298 ``` 1299 1300## FileSyncState<sup>11+</sup> 1301 1302Enumerates the device-cloud file synchronization states. 1303 1304**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1305 1306**System API**: This is a system API. 1307 1308| Name| Value| Description| 1309| ----- | ---- | ---- | 1310| UPLOADING | 0 | Uploading.| 1311| DOWNLOADING | 1 | Downloading.| 1312| COMPLETED | 2 | Synchronization completed.| 1313| STOPPED | 3 | Synchronization stopped.| 1314