1# @ohos.file.cloudSync (Device-Cloud Sync) (System API) 2<!--Kit: Core File Kit--> 3<!--Subsystem: FileManagement--> 4<!--Owner: @zsyztt; @Hermits; @reminder2352--> 5<!--Designer: @yunlanying--> 6<!--Tester: @liuhonggang123--> 7<!--Adviser: @foryourself--> 8 9The **cloudSync** module provides the device-cloud sync capabilities for applications. You can use the APIs to start or stop device-cloud sync and start or stop the download of images. 10 11> **NOTE** 12> 13> - 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. 14> - This topic describes only the system APIs provided by the module. For details about its public APIs, see [@ohos.file.cloudSync (Device-Cloud Sync Capability)](js-apis-file-cloudsync.md). 15 16## Modules to Import 17 18```ts 19import { cloudSync } from '@kit.CoreFileKit'; 20``` 21 22## GallerySync 23 24Provides APIs to implement device-cloud sync of media assets in **Gallery**. Before using the APIs of **GallerySync**, you need to create a **GallerySync** instance. 25 26### constructor 27 28constructor() 29 30A constructor used to create a **GallerySync** instance. 31 32**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 33 34**System API**: This is a system API. 35 36**Example** 37 38 ```ts 39 let gallerySync = new cloudSync.GallerySync() 40 ``` 41 42### on 43 44on(evt: 'progress', callback: (pg: SyncProgress) => void): void 45 46Registers a listener for the device-cloud sync progress. 47 48**Required permissions**: ohos.permission.CLOUDFILE_SYNC 49 50**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 51 52**System API**: This is a system API. 53 54**Parameters** 55 56| Name | Type | Mandatory| Description| 57| ---------- | ------ | ---- | ---- | 58| evt | string | Yes | Event type. The value is **progress**, which indicates the sync progress event.| 59| callback | (pg: SyncProgress) => void | Yes | Callback of the sync progress event. The input parameter is [SyncProgress](./js-apis-file-cloudsync.md#syncprogress12), and the return value is void.| 60 61**Error codes** 62 63For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 64 65| ID | Error Message | 66| ---------------------------- | ---------- | 67| 201 | Permission verification failed. | 68| 202 | The caller is not a system application. | 69| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 70| 13600001 | IPC error. | 71 72**Example** 73 74 ```ts 75 let gallerySync = new cloudSync.GallerySync(); 76 77 gallerySync.on('progress', (pg: cloudSync.SyncProgress) => { 78 console.info("syncState: " + pg.state); 79 }); 80 ``` 81 82### off 83 84off(evt: 'progress', callback: (pg: SyncProgress) => void): void 85 86Unregisters all listeners for the device-cloud sync progress. 87 88**Required permissions**: ohos.permission.CLOUDFILE_SYNC 89 90**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 91 92**System API**: This is a system API. 93 94**Parameters** 95 96| Name | Type | Mandatory| Description| 97| ---------- | ------ | ---- | ---- | 98| evt | string | Yes | Event type. The value is **progress**, which indicates the sync progress event.| 99| callback | (pg: SyncProgress) => void | Yes | Callback of the sync progress event. The input parameter is [SyncProgress](./js-apis-file-cloudsync.md#syncprogress12), and the return value is void.| 100 101**Error codes** 102 103For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 104 105| ID | Error Message | 106| ---------------------------- | ---------- | 107| 201 | Permission verification failed. | 108| 202 | The caller is not a system application. | 109| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 110| 13600001 | IPC error. | 111 112**Example** 113 114 ```ts 115 let gallerySync = new cloudSync.GallerySync(); 116 117 let callback = (pg: cloudSync.SyncProgress) => { 118 console.info("gallery sync state: " + pg.state + "error type:" + pg.error); 119 } 120 121 gallerySync.on('progress', callback); 122 123 gallerySync.off('progress', callback); 124 ``` 125 126### off 127 128off(evt: 'progress'): void 129 130Unregisters all listeners for the device-cloud sync progress. 131 132**Required permissions**: ohos.permission.CLOUDFILE_SYNC 133 134**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 135 136**System API**: This is a system API. 137 138**Parameters** 139 140| Name | Type | Mandatory| Description| 141| ---------- | ------ | ---- | ---- | 142| evt | string | Yes | Event type. The value is **progress**, which indicates the sync progress event.| 143 144**Error codes** 145 146For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 147 148| ID | Error Message | 149| ---------------------------- | ---------- | 150| 201 | Permission verification failed. | 151| 202 | The caller is not a system application. | 152| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 153| 13600001 | IPC error. | 154 155**Example** 156 157 ```ts 158 let gallerySync = new cloudSync.GallerySync(); 159 160 gallerySync.on('progress', (pg: cloudSync.SyncProgress) => { 161 console.info("syncState: " + pg.state); 162 }); 163 164 gallerySync.off('progress'); 165 ``` 166 167### start 168 169start(): Promise<void> 170 171Starts device-cloud sync. This API uses a promise to return the result. 172 173**Required permissions**: ohos.permission.CLOUDFILE_SYNC 174 175**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 176 177**System API**: This is a system API. 178 179**Return value** 180 181| Type | Description | 182| --------------------- | ---------------- | 183| Promise<void> | Promise used to return the result.| 184 185**Error codes** 186 187For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 188 189| ID | Error Message | 190| ---------------------------- | ---------- | 191| 201 | Permission verification failed. | 192| 202 | The caller is not a system application. | 193| 401 | The input parameter is invalid. Possible causes:Incorrect parameter types. | 194| 22400001 | Cloud status not ready. | 195| 22400002 | Network unavailable. | 196| 22400003 | Low battery level. | 197 198**Example** 199 200 ```ts 201 import { BusinessError } from '@kit.BasicServicesKit'; 202 let gallerySync = new cloudSync.GallerySync(); 203 204 gallerySync.on('progress', (pg: cloudSync.SyncProgress) => { 205 console.info("syncState: " + pg.state); 206 }); 207 208 gallerySync.start().then(() => { 209 console.info("start sync successfully"); 210 }).catch((err: BusinessError) => { 211 console.error("start sync failed with error message: " + err.message + ", error code: " + err.code); 212 }); 213 ``` 214 215### start 216 217start(callback: AsyncCallback<void>): void 218 219Starts device-cloud sync. This API uses an asynchronous callback to return the result. 220 221**Required permissions**: ohos.permission.CLOUDFILE_SYNC 222 223**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 224 225**System API**: This is a system API. 226 227**Parameters** 228 229| Name | Type | Mandatory| Description| 230| ---------- | ------ | ---- | ---- | 231| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 232 233**Error codes** 234 235For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 236 237| ID | Error Message | 238| ---------------------------- | ---------- | 239| 201 | Permission verification failed. | 240| 202 | The caller is not a system application. | 241| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 242| 22400001 | Cloud status not ready. | 243| 22400002 | Network unavailable. | 244| 22400003 | Low battery level. | 245 246**Example** 247 248 ```ts 249 import { BusinessError } from '@kit.BasicServicesKit'; 250 let gallerySync = new cloudSync.GallerySync(); 251 252 gallerySync.start((err: BusinessError) => { 253 if (err) { 254 console.error("start sync failed with error message: " + err.message + ", error code: " + err.code); 255 } else { 256 console.info("start sync successfully"); 257 } 258 }); 259 ``` 260 261### stop 262 263stop(): Promise<void> 264 265Stops device-cloud sync. This API uses a promise to return the result. 266 267> **NOTE** 268> 269> Calling **stop** will stop the sync process. To resume the sync, call [start](#start). 270 271**Required permissions**: ohos.permission.CLOUDFILE_SYNC 272 273**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 274 275**System API**: This is a system API. 276 277**Return value** 278 279| Type | Description | 280| --------------------- | ---------------- | 281| Promise<void> | Promise used to return the result.| 282 283**Error codes** 284 285For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 286 287| ID | Error Message | 288| ---------------------------- | ---------- | 289| 201 | Permission verification failed. | 290| 202 | The caller is not a system application. | 291| 401 | The input parameter is invalid. Possible causes:Incorrect parameter types. | 292 293**Example** 294 295 ```ts 296 import { BusinessError } from '@kit.BasicServicesKit'; 297 let gallerySync = new cloudSync.GallerySync(); 298 299 gallerySync.stop().then(() => { 300 console.info("stop sync successfully"); 301 }).catch((err: BusinessError) => { 302 console.error("stop sync failed with error message: " + err.message + ", error code: " + err.code); 303 }); 304 ``` 305 306### stop 307 308stop(callback: AsyncCallback<void>): void 309 310Stops device-cloud sync. This API uses an asynchronous callback to return the result. 311 312> **NOTE** 313> 314> Calling **stop** will stop the sync process. To resume the sync, call [start](#start). 315 316**Required permissions**: ohos.permission.CLOUDFILE_SYNC 317 318**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 319 320**System API**: This is a system API. 321 322**Parameters** 323 324| Name | Type | Mandatory| Description| 325| ---------- | ------ | ---- | ---- | 326| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 327 328**Error codes** 329 330For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 331 332| ID | Error Message | 333| ---------------------------- | ---------- | 334| 201 | Permission verification failed. | 335| 202 | The caller is not a system application. | 336| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 337 338**Example** 339 340 ```ts 341 import { BusinessError } from '@kit.BasicServicesKit'; 342 let gallerySync = new cloudSync.GallerySync(); 343 344 gallerySync.stop((err: BusinessError) => { 345 if (err) { 346 console.error("stop sync failed with error message: " + err.message + ", error code: " + err.code); 347 } else { 348 console.info("stop sync successfully"); 349 } 350 }); 351 ``` 352 353## Download 354 355Provides APIs for downloading image files to **Gallery**. Before using the APIs of **Download**, you need to create a **Download** instance. 356 357### constructor 358 359constructor() 360 361A constructor used to create a **Download** instance. 362 363**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 364 365**System API**: This is a system API. 366 367**Example** 368 369 ```ts 370 let download = new cloudSync.Download() 371 ``` 372 373### on 374 375on(evt: 'progress', callback: (pg: DownloadProgress) => void): void 376 377Registers a listener for the download progress of a cloud file. 378 379**Required permissions**: ohos.permission.CLOUDFILE_SYNC 380 381**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 382 383**System API**: This is a system API. 384 385**Parameters** 386 387| Name | Type | Mandatory| Description| 388| ---------- | ------ | ---- | ---- | 389| evt | string | Yes | Event. The value is **progress**, which indicates the download progress event of a cloud file.| 390| callback | (pg: DownloadProgress) => void | Yes | Callback used to return the file download progress. The input parameter is [DownloadProgress](js-apis-file-cloudsync.md#downloadprogress11), and the return value is **void**.| 391 392**Error codes** 393 394For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 395 396| ID | Error Message | 397| ---------------------------- | ---------- | 398| 201 | Permission verification failed. | 399| 202 | The caller is not a system application. | 400| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 401| 13600001 | IPC error. | 402 403**Example** 404 405 ```ts 406 let download = new cloudSync.Download(); 407 408 download.on('progress', (pg: cloudSync.DownloadProgress) => { 409 console.info("download state: " + pg.state); 410 }); 411 ``` 412 413### off 414 415off(evt: 'progress', callback: (pg: DownloadProgress) => void): void 416 417Unregisters all listeners for the download progress event of a cloud file. 418 419**Required permissions**: ohos.permission.CLOUDFILE_SYNC 420 421**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 422 423**System API**: This is a system API. 424 425**Parameters** 426 427| Name | Type | Mandatory| Description| 428| ---------- | ------ | ---- | ---- | 429| evt | string | Yes | Event type. The value is **progress**, which indicates the sync progress event.| 430| callback | (pg: DownloadProgress) => void | Yes | Callback used to return the file download progress. The input parameter is [DownloadProgress](js-apis-file-cloudsync.md#downloadprogress11), and the return value is **void**.| 431 432**Error codes** 433 434For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 435 436| ID | Error Message | 437| ---------------------------- | ---------- | 438| 201 | Permission verification failed. | 439| 202 | The caller is not a system application. | 440| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 441| 13600001 | IPC error. | 442 443**Example** 444 445 ```ts 446 let download = new cloudSync.Download(); 447 448 let callback = (pg: cloudSync.DownloadProgress) => { 449 console.info("download state: " + pg.state); 450 } 451 452 download.on('progress', callback); 453 454 download.off('progress', callback); 455 ``` 456 457### off 458 459off(evt: 'progress'): void 460 461Unregisters all listeners for the download progress event of a cloud file. 462 463**Required permissions**: ohos.permission.CLOUDFILE_SYNC 464 465**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 466 467**System API**: This is a system API. 468 469**Parameters** 470 471| Name | Type | Mandatory| Description| 472| ---------- | ------ | ---- | ---- | 473| evt | string | Yes | Event type. The value is **progress**, which indicates the download progress event of a cloud file.| 474 475**Error codes** 476 477For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 478 479| ID | Error Message | 480| ---------------------------- | ---------- | 481| 201 | Permission verification failed. | 482| 202 | The caller is not a system application. | 483| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 484| 13600001 | IPC error. | 485 486**Example** 487 488 ```ts 489 let download = new cloudSync.Download(); 490 491 download.on('progress', (pg: cloudSync.DownloadProgress) => { 492 console.info("download state:" + pg.state); 493 }); 494 495 download.off('progress'); 496 ``` 497 498### start 499 500start(uri: string): Promise<void> 501 502Starts to download a cloud file. This API uses a promise to return the result. 503 504**Required permissions**: ohos.permission.CLOUDFILE_SYNC 505 506**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 507 508**System API**: This is a system API. 509 510**Parameters** 511 512| Name | Type | Mandatory| Description| 513| ---------- | ------ | ---- | ---- | 514| uri | string | Yes | URI of the target file.| 515 516**Return value** 517 518| Type | Description | 519| --------------------- | ---------------- | 520| Promise<void> | Promise used to return the result.| 521 522**Example** 523 524 ```ts 525 import { BusinessError } from '@kit.BasicServicesKit'; 526 let download = new cloudSync.Download(); 527 let uri: string = "file:///media/Photo/1"; 528 529 download.on('progress', (pg: cloudSync.DownloadProgress) => { 530 console.info("download state:" + pg.state); 531 }); 532 533 download.start(uri).then(() => { 534 console.info("start download successfully"); 535 }).catch((err: BusinessError) => { 536 console.error("start download failed with error message: " + err.message + ", error code: " + err.code); 537 }); 538 ``` 539 540**Error codes** 541 542For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 543 544| ID | Error Message | 545| ---------------------------- | ---------- | 546| 201 | Permission verification failed. | 547| 202 | The caller is not a system application. | 548| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 549| 13900002 | No such file or directory. | 550| 13900025 | No space left on device. | 551 552### start 553 554start(uri: string, callback: AsyncCallback<void>): void 555 556Starts to download a cloud file. This API uses an asynchronous callback to return the result. 557 558**Required permissions**: ohos.permission.CLOUDFILE_SYNC 559 560**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 561 562**System API**: This is a system API. 563 564**Parameters** 565 566| Name | Type | Mandatory| Description| 567| ---------- | ------ | ---- | ---- | 568| uri | string | Yes | URI of the target file.| 569| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 570 571**Error codes** 572 573For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 574 575| ID | Error Message | 576| ---------------------------- | ---------- | 577| 201 | Permission verification failed. | 578| 202 | The caller is not a system application. | 579| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 580| 13900002 | No such file or directory. | 581| 13900025 | No space left on device. | 582 583**Example** 584 585 ```ts 586 import { BusinessError } from '@kit.BasicServicesKit'; 587 let download = new cloudSync.Download(); 588 let uri: string = "file:///media/Photo/1"; 589 590 download.start(uri, (err: BusinessError) => { 591 if (err) { 592 console.error("start download failed with error message: " + err.message + ", error code: " + err.code); 593 } else { 594 console.info("start download successfully"); 595 } 596 }); 597 ``` 598 599### stop 600 601stop(uri: string): Promise<void> 602 603Stops downloading a cloud file. This API uses a promise to return the result. 604 605> **NOTE** 606> 607> Calling **stop** will terminate the download of the current file and clear the cache file. You can use **start** to start the download again. 608 609**Required permissions**: ohos.permission.CLOUDFILE_SYNC 610 611**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 612 613**System API**: This is a system API. 614 615**Parameters** 616 617| Name | Type | Mandatory| Description| 618| ---------- | ------ | ---- | ---- | 619| uri | string | Yes | URI of the target file.| 620 621**Return value** 622 623| Type | Description | 624| --------------------- | ---------------- | 625| Promise<void> | Promise used to return the result.| 626 627**Error codes** 628 629For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 630 631| ID | Error Message | 632| ---------------------------- | ---------- | 633| 201 | Permission verification failed. | 634| 202 | The caller is not a system application. | 635| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 636 637**Example** 638 639 ```ts 640 import { BusinessError } from '@kit.BasicServicesKit'; 641 let download = new cloudSync.Download(); 642 let uri: string = "file:///media/Photo/1"; 643 644 download.stop(uri).then(() => { 645 console.info("stop download successfully"); 646 }).catch((err: BusinessError) => { 647 console.error("stop download failed with error message: " + err.message + ", error code: " + err.code); 648 }); 649 ``` 650 651### stop 652 653stop(uri: string, callback: AsyncCallback<void>): void 654 655Stops downloading a cloud file. This API uses an asynchronous callback 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 target file.| 672| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 673 674**Error codes** 675 676For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 677 678| ID | Error Message | 679| ---------------------------- | ---------- | 680| 201 | Permission verification failed. | 681| 202 | The caller is not a system application. | 682| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 683 684**Example** 685 686 ```ts 687 import { BusinessError } from '@kit.BasicServicesKit'; 688 let download = new cloudSync.Download(); 689 let uri: string = "file:///media/Photo/1"; 690 691 download.stop(uri, (err: BusinessError) => { 692 if (err) { 693 console.error("stop download failed with error message: " + err.message + ", error code: " + err.code); 694 } else { 695 console.info("stop download successfully"); 696 } 697 }); 698 ``` 699 700## FileSync<sup>12+</sup> 701 702Provides APIs for the file manager application to perform device-cloud sync of the files stored in the Drive Kit. Before using the APIs of this class, you need to create a **FileSync** instance. 703 704### constructor<sup>12+</sup> 705 706constructor(bundleName: string) 707 708A constructor used to create a **FileSync** instance. 709 710**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 711 712**System API**: This is a system API. 713 714**Parameters** 715 716| Name | Type | Mandatory| Description| 717| ---------- | ------ | ---- | ---- | 718| bundleName | string | Yes | Bundle name.| 719 720**Error codes** 721 722For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 723 724| ID | Error Message | 725| ---------------------------- | ---------- | 726| 202 | Permission verification failed, application which is not a system application uses system API. | 727| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 728 729**Example** 730 731 ```ts 732 let fileSync = new cloudSync.FileSync("com.ohos.demo") 733 ``` 734 735## CloudFileCache<sup>11+</sup> 736 737Provides APIs for the file manager application to download files from the Drive Kit to a local device. 738 739**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 740 741### cleanCache<sup>11+</sup> 742 743cleanCache(uri: string): void 744 745Deletes a cache file. This API returns the result synchronously. 746 747**Required permissions**: ohos.permission.CLOUDFILE_SYNC 748 749**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 750 751**System API**: This is a system API. 752 753**Parameters** 754 755| Name | Type | Mandatory| Description| 756| ---------- | ------ | ---- | ---- | 757| uri | string | Yes | URI of the cache file to delete.| 758 759**Error codes** 760 761For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 762 763| ID | Error Message | 764| ---------------------------- | ---------- | 765| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 766| 202 | Permission verification failed, application which is not a system application uses system API. | 767| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 768| 13600001 | IPC error. | 769| 13900002 | No such file or directory. | 770| 14000002 | Invalid URI. | 771 772**Example** 773 774 ```ts 775 import { BusinessError } from '@kit.BasicServicesKit'; 776 import { fileUri } from '@kit.CoreFileKit'; 777 let fileCache = new cloudSync.CloudFileCache(); 778 let path = "/data/storage/el2/cloud/1.txt"; 779 let uri = fileUri.getUriFromPath(path); 780 781 try { 782 fileCache.cleanCache(uri); 783 } catch (err) { 784 let error:BusinessError = err as BusinessError; 785 console.error("clean cache failed with error message: " + err.message + ", error code: " + err.code); 786 } 787 788 ``` 789 790## cloudSync.getFileSyncState<sup>11+</sup> 791 792getFileSyncState(uri: Array<string>): Promise<Array<FileSyncState>> 793 794Obtains the file sync state. This API uses a promise to return the result. 795 796**Required permissions**: ohos.permission.CLOUDFILE_SYNC 797 798**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 799 800**System API**: This is a system API. 801 802**Parameters** 803 804| Name | Type | Mandatory| Description| 805| ---------- | ------ | ---- | ---- | 806| uri | Array<string> | Yes | URI of the file whose sync state is to be obtained.| 807 808**Return value** 809 810| Type | Description | 811| --------------------- | ---------------- | 812| Promise<Array<FileSyncState>> | Promise used to return the sync state obtained.| 813 814**Error codes** 815 816For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 817 818| ID | Error Message | 819| ---------------------------- | ---------- | 820| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 821| 202 | Permission verification failed, application which is not a system application uses system API. | 822| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 823| 13600001 | IPC error. | 824| 13900002 | No such file or directory. | 825| 14000002 | Invalid URI. | 826 827**Example** 828 829 ```ts 830 import { BusinessError } from '@kit.BasicServicesKit'; 831 832 let uris: Array<string> = ["file://uri"]; 833 cloudSync.getFileSyncState(uris).then((syncStates: Array<cloudSync.FileSyncState>) => { 834 for(let i = 0, len = syncStates.length; i < len; i++){ 835 console.info("get file sync state successfully" + syncStates[i]); 836 } 837 }).catch((err: BusinessError) => { 838 console.error("get file sync state failed with error message: " + err.message + ", error code: " + err.code); 839 }); 840 841 ``` 842 843## cloudSync.getFileSyncState<sup>11+</sup> 844 845getFileSyncState(uri: Array<string>, callback: AsyncCallback<Array<FileSyncState>>): void 846 847Obtains the file sync state. This API uses an asynchronous callback to return the result. 848 849**Required permissions**: ohos.permission.CLOUDFILE_SYNC 850 851**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 852 853**System API**: This is a system API. 854 855**Parameters** 856 857| Name | Type | Mandatory| Description| 858| ---------- | ------ | ---- | ---- | 859| uri | Array<string> | Yes | URI of the file whose sync state is to be obtained.| 860| callback | AsyncCallback<Array<FileSyncState>> | Yes | Callback used to return the file sync state.| 861 862**Error codes** 863 864For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 865 866| ID | Error Message | 867| ---------------------------- | ---------- | 868| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 869| 202 | Permission verification failed, application which is not a system application uses system API. | 870| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 871| 13600001 | IPC error. | 872| 13900002 | No such file or directory. | 873| 14000002 | Invalid URI. | 874 875**Example** 876 877 ```ts 878 import { BusinessError } from '@kit.BasicServicesKit'; 879 880 let uris: Array<string> = ["file://uri"]; 881 cloudSync.getFileSyncState(uris, (err: BusinessError, syncStates: Array<cloudSync.FileSyncState>) => { 882 if (err) { 883 console.error("get file sync state with error message: " + err.message + ", error code: " + err.code); 884 } else { 885 for(let i = 0, len = syncStates.length; i < len; i++){ 886 console.info("get file sync state successfully" + syncStates[i]); 887 } 888 } 889 }); 890 ``` 891 892## cloudSync.getFileSyncState<sup>12+</sup> 893 894getFileSyncState(uri: string): FileSyncState 895 896Obtains the file sync state. 897 898**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 899 900**System API**: This is a system API. 901 902**Parameters** 903 904| Name | Type | Mandatory| Description| 905| ---------- | ------ | ---- | ---- | 906| uri | string | Yes | URI of the target file.| 907 908**Return value** 909 910| Type | Description | 911| --------------------- | ---------------- | 912| [FileSyncState](#filesyncstate11) | Sync state of the file.| 913 914**Error codes** 915 916For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 917 918| ID | Error Message | 919| ---------------------------- | ---------- | 920| 202 | Permission verification failed, application which is not a system application uses system API. | 921| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 922| 13900002 | No such file or directory. | 923| 13900004 | Interrupted system call. | 924| 13900010 | Try again. | 925| 13900012 | Permission denied by the file system. | 926| 13900031 | Function not implemented. | 927| 13900042 | Unknown error. | 928| 14000002 | Invalid URI. | 929 930**Example** 931 932 ```ts 933 import { BusinessError } from '@kit.BasicServicesKit'; 934 import { fileUri } from '@kit.CoreFileKit'; 935 let path = "/data/storage/el2/cloud/1.txt"; 936 let uri = fileUri.getUriFromPath(path); 937 try { 938 let state = cloudSync.getFileSyncState(uri); 939 } catch (err) { 940 let error:BusinessError = err as BusinessError; 941 console.error("getFileSyncStatefailed with error:" + JSON.stringify(error)); 942 } 943 ``` 944 945## FileSyncState<sup>11+</sup> 946 947Enumerates the device-cloud file sync states. 948 949**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 950 951**System API**: This is a system API. 952 953| Name| Value| Description| 954| ----- | ---- | ---- | 955| UPLOADING | 0 | The file is being uploaded.| 956| DOWNLOADING | 1 | The file is being downloaded.| 957| COMPLETED | 2 | Sync completed.| 958| STOPPED | 3 | Sync stopped.| 959| TO_BE_UPLOADED<sup>12+</sup> | 4 | The file is going to be uploaded.| 960| UPLOAD_SUCCESS<sup>12+</sup> | 5 | The file has been successfully uploaded.| 961| UPLOAD_FAILURE<sup>12+</sup> | 6 | The file fails to be uploaded.| 962 963## cloudSync.optimizeStorage<sup>17+</sup> 964 965optimizeStorage(): Promise<void> 966 967Optimizes the resources from the local Gallery that have been synced to the cloud and executes the automatic aging policy according to the remaining local space. This API uses a promise to return the result. 968 969**Required permissions**: ohos.permission.CLOUDFILE_SYNC 970 971**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 972 973**System API**: This is a system API. 974 975**Return value** 976 977 | Type | Description | 978 | ------------------- | ---------------------------- | 979 | Promise<void> | Promise that returns no value.| 980 981**Error codes** 982 983For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](errorcode-filemanagement.md). 984 985| ID | Error Message | 986| ---------------------------- | ---------- | 987| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 988| 202 | Permission verification failed, application which is not a system application uses system API. | 989| 13600001 | IPC error. | 990| 13900042 | Unknown error. | 991 992**Example** 993 994 ```ts 995 import { BusinessError } from '@kit.BasicServicesKit'; 996 997 cloudSync.optimizeStorage().then(() => { 998 console.info("optimize storage successfully"); // The foreground UX waits for blocking operations to complete. 999 }).catch((err: BusinessError) => { 1000 console.error("optimize storage failed with error message: " + err.message + ", error code: " + err.code); 1001 }); 1002 ``` 1003 1004## cloudSync.startOptimizeSpace<sup>17+</sup> 1005 1006startOptimizeSpace(optimizePara: OptimizeSpaceParam, callback?: Callback\<OptimizeSpaceProgress>): Promise<void> 1007 1008Optimizes local resources that have been synced to the cloud and optimizes local images and videos that have not been accessed before the aging period expires. This API uses a promise to return the result. 1009 1010**startOptimizeSpace** is used together with **stopOptimizeSpace**. If **startOptimizeSpace** is called repeatedly, the error code 22400006 will be returned, indicating that other tasks are being executed. 1011 1012**Required permissions**: ohos.permission.CLOUDFILE_SYNC 1013 1014**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1015 1016**System API**: This is a system API. 1017 1018**Parameters** 1019 1020| Name | Type | Mandatory| Description| 1021| ---------- | ------ | ---- | ---- | 1022| optimizePara | [OptimizeSpaceParam](#optimizespaceparam17) | Yes | Optimizes parameters.| 1023| callback | Callback<[OptimizeSpaceProgress](#optimizespaceprogress17)> | No | Callback used to return the optimization progress. By default, error 401 is returned and the clearing task is not executed.| 1024 1025**Return value** 1026 1027 | Type | Description | 1028 | ------------------- | ---------------------------- | 1029 | Promise<void> | Promise that returns no value.| 1030 1031**Error codes** 1032 1033For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](errorcode-filemanagement.md). 1034 1035| ID | Error Message | 1036| ---------------------------- | ---------- | 1037| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 1038| 202 | Permission verification failed, application which is not a system application uses system API. | 1039| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 1040| 13600001 | IPC error. | 1041| 22400005 | Inner error. | 1042| 22400006 | The same task is already in progress. | 1043 1044**Example** 1045 1046 ```ts 1047 import { BusinessError } from '@kit.BasicServicesKit'; 1048 let para:cloudSync.OptimizeSpaceParam = {totalSize: 1073741824, agingDays: 30}; 1049 let callback = (data:cloudSync.OptimizeSpaceProgress) => { 1050 if (data.state == cloudSync.OptimizeState.FAILED) { 1051 console.info("optimize space failed"); 1052 } else if (data.state == cloudSync.OptimizeState.COMPLETED && data.progress == 100) { 1053 console.info("optimize space successfully"); 1054 } else if (data.state == cloudSync.OptimizeState.RUNNING) { 1055 console.info("optimize space progress:" + data.progress); 1056 } 1057 } 1058 cloudSync.startOptimizeSpace(para, callback).then(() => { 1059 console.info("start optimize space"); 1060 }).catch((err: BusinessError) => { 1061 console.error("start optimize space failed with error message: " + err.message + ", error code: " + err.code); 1062 }); 1063 ``` 1064 1065## cloudSync.stopOptimizeSpace<sup>17+</sup> 1066 1067stopOptimizeSpace(): void 1068 1069Synchronously stops optimizing cloud resource space. This method is used with **startOptimizeSpace**. 1070 1071**Required permissions**: ohos.permission.CLOUDFILE_SYNC 1072 1073**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1074 1075**System API**: This is a system API. 1076 1077**Error codes** 1078 1079For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](errorcode-filemanagement.md). 1080 1081| ID | Error Message | 1082| ---------------------------- | ---------- | 1083| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 1084| 202 | Permission verification failed, application which is not a system application uses system API. | 1085| 13600001 | IPC error. | 1086| 22400005 | Inner error. | 1087 1088**Example** 1089 1090 ```ts 1091 import { BusinessError } from '@kit.BasicServicesKit'; 1092 let para:cloudSync.OptimizeSpaceParam = {totalSize: 1073741824, agingDays: 30}; 1093 let callback = (data:cloudSync.OptimizeSpaceProgress) => { 1094 if (data.state == cloudSync.OptimizeState.FAILED) { 1095 console.info("optimize space failed"); 1096 } else if (data.state == cloudSync.OptimizeState.RUNNING) { 1097 console.info("optimize space progress:" + data.progress); 1098 } 1099 } 1100 cloudSync.startOptimizeSpace(para, callback); 1101 cloudSync.stopOptimizeSpace(); // Stop space optimization. 1102 ``` 1103 1104## OptimizeState<sup>17+</sup> 1105 1106Enumerates the space optimization states. 1107 1108**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1109 1110**System API**: This is a system API. 1111 1112| Name| Value| Description| 1113| ----- | ---- | ---- | 1114| RUNNING | 0 | The space is being optimized.| 1115| COMPLETED | 1 | The space optimization is complete.| 1116| FAILED | 2 | Space optimization failed.| 1117| STOPPED | 3 | Space optimization stopped.| 1118 1119## OptimizeSpaceProgress<sup>17+</sup> 1120 1121Represents the space optimization states and optimization progress. 1122 1123**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1124 1125**System API**: This is a system API. 1126 1127| Name | Type | Mandatory| Description| 1128| ---------- | ------ | ---- | ---- | 1129| state | [OptimizeState](#optimizestate17) | Yes | Enumerates the space optimization states.| 1130| progress | number | Yes | Optimization progress percentage. The value ranges from 1 to 100.| 1131 1132## OptimizeSpaceParam<sup>17+</sup> 1133 1134Sets the total optimization space and aging days. 1135 1136**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1137 1138**System API**: This is a system API. 1139 1140| Name | Type | Mandatory| Description| 1141| ---------- | ------ | ---- | ---- | 1142| totalSize | number | Yes | Total size of the optimization space. You can obtain the total size of all files to be aged through the media library API. The size is transferred by the application and is in bytes.| 1143| agingDays | number | Yes | Aging days. The system will optimize the local images/videos that have not been accessed and have been synced to the cloud before the aging days.| 1144