1# @ohos.file.cloudSync (Device-Cloud Synchronization) 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> - The APIs of this module are system APIs and cannot be called by third-party applications. 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 process event listener is registered for an application, a callback will be invoked to notify the application when any of the following states is changed. 23 24**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 25 26| Name| Value| Description| 27| ----- | ---- | ---- | 28| UPLOADING | 0 | Uploading.| 29| UPLOAD_FAILED | 1 | Upload failed.| 30| DOWNLOADING | 2 | Downloading.| 31| DOWNLOAD_FAILED | 3 | Download failed.| 32| COMPLETED | 4 | Synchronization completed.| 33| STOPPED | 5 | Synchronization stopped.| 34 35## ErrorType 36 37Enumerates the device-cloud synchronization error types. 38 39- 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. 40- 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. 41- When synchronization is 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()**. 42- If the cloud space is insufficient when a file is uploaded, the upload will fail. 43- 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. 44 45**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 46 47| Name| Value| Description| 48| ----- | ---- | ---- | 49| NO_ERROR | 0 | No error.| 50| NETWORK_UNAVAILABLE | 1 | No network is available.| 51| WIFI_UNAVAILABLE | 2 | Wi-Fi is unavailable.| 52| BATTERY_LEVEL_LOW | 3 | The battery level is lower than 15%.| 53| BATTERY_LEVEL_WARNING | 4 | The battery level is lower than 10%.| 54| CLOUD_STORAGE_FULL | 5 | The cloud space is insufficient.| 55| LOCAL_STORAGE_FULL | 6 | The local space is insufficient.| 56 57## SyncProgress 58 59Defines the device-cloud synchronization process. 60 61**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 62 63| Name | Type | Mandatory| Description| 64| ---------- | ------ | ---- | ---- | 65| state | [SyncState](#syncstate) | Yes | Device-cloud synchronization state.| 66| error | [ErrorType](#errortype) | Yes | Synchronization error type.| 67 68## GallerySync 69 70Provides APIs to implement device-cloud synchronization of media resources of the Gallery. Before using the APIs of **GallerySync**, you need to create a **GallerySync** instance. 71 72### constructor 73 74constructor() 75 76A constructor used to create a **GallerySync** instance. 77 78**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 79 80**Example** 81 82 ```ts 83 let gallerySync = new cloudSync.GallerySync() 84 ``` 85 86### on 87 88on(evt: 'progress', callback: (pg: SyncProgress) => void): void 89 90Subscribes to the synchronization process event. 91 92**Required permissions**: ohos.permission.CLOUDFILE_SYNC 93 94**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 95 96**Parameters** 97 98| Name | Type | Mandatory| Description| 99| ---------- | ------ | ---- | ---- | 100| evt | string | Yes | Type of the event to subscribe to. The value is **progress**, which indicates the synchronization process event.| 101| callback | (pg: SyncProgress) => void | Yes | Callback invoked to return the result. The input parameter is [SyncProgress](#syncprogress), and the return value is **void**.| 102 103**Error codes** 104 105For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 106 107| ID | Error Message | 108| ---------------------------- | ---------- | 109| 201 | Permission verification failed. | 110| 202 | The caller is not a system application. | 111| 401 | The input parameter is invalid. | 112| 13600001 | IPC error. | 113 114**Example** 115 116 ```ts 117 let gallerySync = new cloudSync.GallerySync(); 118 119 gallerySync.on('progress', (pg: cloudSync.SyncProgress) => { 120 console.info("syncState: " + pg.state); 121 }); 122 ``` 123 124### off 125 126off(evt: 'progress', callback: (pg: SyncProgress) => void): void 127 128Unsubscribes from the synchronization process event. 129 130**Required permissions**: ohos.permission.CLOUDFILE_SYNC 131 132**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 133 134**Parameters** 135 136| Name | Type | Mandatory| Description| 137| ---------- | ------ | ---- | ---- | 138| evt | string | Yes | Type of the event to unsubscribe from. The value is **progress**, which indicates the synchronization process event.| 139| callback | (pg: SyncProgress) => void | Yes | Callback for the synchronization process event. The input parameter is [SyncProgress](#syncprogress), and the return value is **void**.| 140 141**Error codes** 142 143For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 144 145| ID | Error Message | 146| ---------------------------- | ---------- | 147| 201 | Permission verification failed. | 148| 202 | The caller is not a system application. | 149| 401 | The input parameter is invalid. | 150| 13600001 | IPC error. | 151 152**Example** 153 154 ```ts 155 let gallerySync = new cloudSync.GallerySync(); 156 157 let callback = (pg: cloudSync.SyncProgress) => { 158 console.info("gallery sync state: " + pg.state + "error type:" + pg.error); 159 } 160 161 gallerySync.on('progress', callback); 162 163 gallerySync.off('progress', callback); 164 ``` 165 166### off 167 168off(evt: 'progress'): void 169 170Unsubscribes from the synchronization process event. 171 172**Required permissions**: ohos.permission.CLOUDFILE_SYNC 173 174**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 175 176**Parameters** 177 178| Name | Type | Mandatory| Description| 179| ---------- | ------ | ---- | ---- | 180| evt | string | Yes | Type of the event to unsubscribe from. The value is **progress**, which indicates the synchronization process event.| 181 182**Error codes** 183 184For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 185 186| ID | Error Message | 187| ---------------------------- | ---------- | 188| 201 | Permission verification failed. | 189| 202 | The caller is not a system application. | 190| 401 | The input parameter is invalid. | 191| 13600001 | IPC error. | 192 193**Example** 194 195 ```ts 196 let gallerySync = new cloudSync.GallerySync(); 197 198 gallerySync.on('progress', (pg: cloudSync.SyncProgress) => { 199 console.info("syncState: " + pg.state); 200 }); 201 202 gallerySync.off('progress'); 203 ``` 204 205### start 206 207start(): Promise<void> 208 209Starts device-cloud synchronization. This API uses a promise to return the result. 210 211**Required permissions**: ohos.permission.CLOUDFILE_SYNC 212 213**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 214 215**Return value** 216 217| Type | Description | 218| --------------------- | ---------------- | 219| Promise<void> | Promise used to return the result.| 220 221**Error codes** 222 223For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 224 225| ID | Error Message | 226| ---------------------------- | ---------- | 227| 201 | Permission verification failed. | 228| 202 | The caller is not a system application. | 229| 401 | The input parameter is invalid. | 230| 22400001 | Cloud status not ready. | 231| 22400002 | Network unavailable. | 232| 22400003 | Battery level warning. | 233 234**Example** 235 236 ```ts 237 import { BusinessError } from '@ohos.base'; 238 let gallerySync = new cloudSync.GallerySync(); 239 240 gallerySync.on('progress', (pg: cloudSync.SyncProgress) => { 241 console.info("syncState: " + pg.state); 242 }); 243 244 gallerySync.start().then(() => { 245 console.info("start sync successfully"); 246 }).catch((err: BusinessError) => { 247 console.info("start sync failed with error message: " + err.message + ", error code: " + err.code); 248 }); 249 ``` 250 251### start 252 253start(callback: AsyncCallback<void>): void 254 255Starts device-cloud synchronization. This API uses an asynchronous callback to return the result. 256 257**Required permissions**: ohos.permission.CLOUDFILE_SYNC 258 259**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 260 261**Parameters** 262 263| Name | Type | Mandatory| Description| 264| ---------- | ------ | ---- | ---- | 265| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.| 266 267**Error codes** 268 269For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 270 271| ID | Error Message | 272| ---------------------------- | ---------- | 273| 201 | Permission verification failed. | 274| 202 | The caller is not a system application. | 275| 401 | The input parameter is invalid. | 276| 22400001 | Cloud status not ready. | 277| 22400002 | Network unavailable. | 278| 22400003 | Battery level warning. | 279 280**Example** 281 282 ```ts 283 import { BusinessError } from '@ohos.base'; 284 let gallerySync = new cloudSync.GallerySync(); 285 286 gallerySync.start((err: BusinessError) => { 287 if (err) { 288 console.info("start sync failed with error message: " + err.message + ", error code: " + err.code); 289 } else { 290 console.info("start sync successfully"); 291 } 292 }); 293 ``` 294 295### stop 296 297stop(): Promise<void> 298 299Stops device-cloud synchronization. This API uses a promise to return the result. 300 301> **NOTE** 302> 303> Calling **stop** will stop the synchronization process. To resume the synchronization, call [start](#start). 304 305**Required permissions**: ohos.permission.CLOUDFILE_SYNC 306 307**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 308 309**Return value** 310 311| Type | Description | 312| --------------------- | ---------------- | 313| Promise<void> | Promise used to return the result.| 314 315**Error codes** 316 317For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 318 319| ID | Error Message | 320| ---------------------------- | ---------- | 321| 201 | Permission verification failed. | 322| 202 | The caller is not a system application. | 323| 401 | The input parameter is invalid. | 324 325**Example** 326 327 ```ts 328 import { BusinessError } from '@ohos.base'; 329 let gallerySync = new cloudSync.GallerySync(); 330 331 gallerySync.stop().then(() => { 332 console.info("stop sync successfully"); 333 }).catch((err: BusinessError) => { 334 console.info("stop sync failed with error message: " + err.message + ", error code: " + err.code); 335 }); 336 ``` 337 338### stop 339 340stop(callback: AsyncCallback<void>): void 341 342Stops device-cloud synchronization. This API uses an asynchronous callback to return the result. 343 344> **NOTE** 345> 346> Calling **stop** will stop the synchronization process. To resume the synchronization, call [start](#start-1). 347 348**Required permissions**: ohos.permission.CLOUDFILE_SYNC 349 350**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 351 352**Parameters** 353 354| Name | Type | Mandatory| Description| 355| ---------- | ------ | ---- | ---- | 356| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.| 357 358**Error codes** 359 360For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 361 362| ID | Error Message | 363| ---------------------------- | ---------- | 364| 201 | Permission verification failed. | 365| 202 | The caller is not a system application. | 366| 401 | The input parameter is invalid. | 367 368**Example** 369 370 ```ts 371 import { BusinessError } from '@ohos.base'; 372 let gallerySync = new cloudSync.GallerySync(); 373 374 gallerySync.stop((err: BusinessError) => { 375 if (err) { 376 console.info("stop sync failed with error message: " + err.message + ", error code: " + err.code); 377 } else { 378 console.info("stop sync successfully"); 379 } 380 }); 381 ``` 382 383## State 384 385Enumerates the download states of a cloud file. 386 387**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 388 389| Name| Value| Description| 390| ----- | ---- | ---- | 391| RUNNING | 0 | The cloud file is being downloaded.| 392| COMPLETED | 1 | The cloud file download is complete.| 393| FAILED | 2 | The cloud file download failed.| 394| STOPPED | 3 | The cloud file download is stopped.| 395 396## DownloadProgress 397 398Defines the download process of a cloud file. 399 400**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 401 402| Name | Type | Mandatory| Description| 403| ---------- | ------ | ---- | ---- | 404| state | [State](#state) | Yes | File download state.| 405| processed | number | Yes | Size of data downloaded.| 406| size | number | Yes | Current size of the file.| 407| uri | string | Yes | URI of the file.| 408 409## Download 410 411Provides APIs for downloading the image files in Gallery. Before using the APIs of **Download**, you need to create a **Download** instance. 412 413### constructor 414 415constructor() 416 417A constructor used to create a **Download** instance. 418 419**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 420 421**Example** 422 423 ```ts 424 let download = new cloudSync.Download() 425 ``` 426 427### on 428 429on(evt: 'progress', callback: (pg: DownloadProgress) => void): void 430 431Subscribes to the cloud file download event. 432 433**Required permissions**: ohos.permission.CLOUDFILE_SYNC 434 435**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 436 437**Parameters** 438 439| Name | Type | Mandatory| Description| 440| ---------- | ------ | ---- | ---- | 441| evt | string | Yes | Type of the event to subscribe to. The value is **progress**, which indicates the download process event.| 442| callback | (pg: DownloadProgress) => void | Yes | Callback invoked to return the result. The input parameter is [DownloadProgress](#downloadprogress), and the return value is **void**.| 443 444**Error codes** 445 446For details about the error codes, see [File Management Error Codes](../errorcodes/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 469Unsubscribes from the cloud file download event. 470 471**Required permissions**: ohos.permission.CLOUDFILE_SYNC 472 473**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 474 475**Parameters** 476 477| Name | Type | Mandatory| Description| 478| ---------- | ------ | ---- | ---- | 479| evt | string | Yes | Type of the event to unsubscribe from. The value is **progress**, which indicates the synchronization process event.| 480| callback | (pg: DownloadProgress) => void | Yes | Callback for the cloud file download event. The input parameter is [DownloadProgress](#downloadprogress), and the return value is **void**.| 481 482**Error codes** 483 484For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 485 486| ID | Error Message | 487| ---------------------------- | ---------- | 488| 201 | Permission verification failed. | 489| 202 | The caller is not a system application. | 490| 401 | The input parameter is invalid. | 491| 13600001 | IPC error. | 492 493**Example** 494 495 ```ts 496 let download = new cloudSync.Download(); 497 498 let callback = (pg: cloudSync.DownloadProgress) => { 499 console.info("download state: " + pg.state + "error type:" + pg.error); 500 } 501 502 download.on('progress', callback); 503 504 download.off('progress', callback); 505 ``` 506 507### off 508 509off(evt: 'progress'): void 510 511Unsubscribes from the cloud file download event. 512 513**Required permissions**: ohos.permission.CLOUDFILE_SYNC 514 515**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 516 517**Parameters** 518 519| Name | Type | Mandatory| Description| 520| ---------- | ------ | ---- | ---- | 521| evt | string | Yes | Type of the event to unsubscribe from. The value is **progress**, which indicates the download process event.| 522 523**Error codes** 524 525For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 526 527| ID | Error Message | 528| ---------------------------- | ---------- | 529| 201 | Permission verification failed. | 530| 202 | The caller is not a system application. | 531| 401 | The input parameter is invalid. | 532| 13600001 | IPC error. | 533 534**Example** 535 536 ```ts 537 let download = new cloudSync.Download(); 538 539 download.on('progress', (pg: cloudSync.DownloadProgress) => { 540 console.info("download state:" + pg.state); 541 }); 542 543 download.off('progress'); 544 ``` 545 546### start 547 548start(uri: string): Promise<void> 549 550Starts to download a cloud file. This API uses a promise to return the result. 551 552**Required permissions**: ohos.permission.CLOUDFILE_SYNC 553 554**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 555 556**Parameters** 557 558| Name | Type | Mandatory| Description| 559| ---------- | ------ | ---- | ---- | 560| uri | string | Yes | URI of the file to download.| 561 562**Return value** 563 564| Type | Description | 565| --------------------- | ---------------- | 566| Promise<void> | Promise used to return the result.| 567 568**Example** 569 570 ```ts 571 import { BusinessError } from '@ohos.base'; 572 let download = new cloudSync.Download(); 573 let uri: string = "file:///media/Photo/1"; 574 575 download.on('progress', (pg: cloudSync.DownloadProgress) => { 576 console.info("download state:" + pg.state); 577 }); 578 579 download.start(uri).then(() => { 580 console.info("start download successfully"); 581 }).catch((err: BusinessError) => { 582 console.info("start download failed with error message: " + err.message + ", error code: " + err.code); 583 }); 584 ``` 585 586**Error codes** 587 588For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 589 590| ID | Error Message | 591| ---------------------------- | ---------- | 592| 201 | Permission verification failed. | 593| 202 | The caller is not a system application. | 594| 401 | The input parameter is invalid. | 595| 13900002 | No such file or directory. | 596| 13900025 | No space left on device. | 597 598### start 599 600start(uri: string, callback: AsyncCallback<void>): void 601 602Starts to download a cloud file. This API uses an asynchronous callback to return the result. 603 604**Required permissions**: ohos.permission.CLOUDFILE_SYNC 605 606**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 607 608**Parameters** 609 610| Name | Type | Mandatory| Description| 611| ---------- | ------ | ---- | ---- | 612| uri | string | Yes | URI of the file to download.| 613| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.| 614 615**Error codes** 616 617For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 618 619| ID | Error Message | 620| ---------------------------- | ---------- | 621| 201 | Permission verification failed. | 622| 202 | The caller is not a system application. | 623| 401 | The input parameter is invalid. | 624| 13900002 | No such file or directory. | 625| 13900025 | No space left on device. | 626 627**Example** 628 629 ```ts 630 import { BusinessError } from '@ohos.base'; 631 let download = new cloudSync.Download(); 632 let uri: string = "file:///media/Photo/1"; 633 634 download.start(uri, (err: BusinessError) => { 635 if (err) { 636 console.info("start download failed with error message: " + err.message + ", error code: " + err.code); 637 } else { 638 console.info("start download successfully"); 639 } 640 }); 641 ``` 642 643### stop 644 645stop(uri: string): Promise<void> 646 647Stops downloading a cloud file. This API uses a promise to return the result. 648 649> **NOTE** 650> 651> Calling **stop** will terminate the download of the current file and clear the cached file. You can use **start** to start the download again. 652 653**Required permissions**: ohos.permission.CLOUDFILE_SYNC 654 655**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 656 657**Parameters** 658 659| Name | Type | Mandatory| Description| 660| ---------- | ------ | ---- | ---- | 661| uri | string | Yes | URI of the file to download.| 662 663**Return value** 664 665| Type | Description | 666| --------------------- | ---------------- | 667| Promise<void> | Promise used to return the result.| 668 669**Error codes** 670 671For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 672 673| ID | Error Message | 674| ---------------------------- | ---------- | 675| 201 | Permission verification failed. | 676| 202 | The caller is not a system application. | 677| 401 | The input parameter is invalid. | 678 679**Example** 680 681 ```ts 682 import { BusinessError } from '@ohos.base'; 683 let download = new cloudSync.Download(); 684 let uri: string = "file:///media/Photo/1"; 685 686 download.stop(uri).then(() => { 687 console.info("stop download successfully"); 688 }).catch((err: BusinessError) => { 689 console.info("stop download failed with error message: " + err.message + ", error code: " + err.code); 690 }); 691 ``` 692 693### stop 694 695stop(uri: string, callback: AsyncCallback<void>): void 696 697Stops downloading a cloud file. This API uses an asynchronous callback to return the result. 698 699> **NOTE** 700> 701> Calling **stop** will terminate the download of the current file and clear the cached file. You can use **start** to start the download again. 702 703**Required permissions**: ohos.permission.CLOUDFILE_SYNC 704 705**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 706 707**Parameters** 708 709| Name | Type | Mandatory| Description| 710| ---------- | ------ | ---- | ---- | 711| uri | string | Yes | URI of the file to download.| 712| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.| 713 714**Error codes** 715 716For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 717 718| ID | Error Message | 719| ---------------------------- | ---------- | 720| 201 | Permission verification failed. | 721| 202 | The caller is not a system application. | 722| 401 | The input parameter is invalid. | 723 724**Example** 725 726 ```ts 727 import { BusinessError } from '@ohos.base'; 728 let download = new cloudSync.Download(); 729 let uri: string = "file:///media/Photo/1"; 730 731 download.stop(uri, (err: BusinessError) => { 732 if (err) { 733 console.info("stop download failed with error message: " + err.message + ", error code: " + err.code); 734 } else { 735 console.info("stop download successfully"); 736 } 737 }); 738 ``` 739