1# @ohos.file.cloudSync (端云同步能力) 2 3该模块向应用提供端云同步能力，包括启动/停止端云同步以及启动/停止原图下载功能。 4 5> **说明：** 6> 7> - 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> - 本模块接口为系统接口，三方应用不支持调用。 9 10## 导入模块 11 12```ts 13import cloudSync from '@ohos.file.cloudSync'; 14``` 15 16## SyncState 17 18端云同步状态，为枚举类型。 19 20> **说明：** 21> 22> 以下同步状态发生变更时，如果应用注册了同步过程事件监听，则通过回调通知应用。 23 24**系统能力**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 25 26| 名称 | 值| 说明 | 27| ----- | ---- | ---- | 28| UPLOADING | 0 | 上行同步中 | 29| UPLOAD_FAILED | 1 | 上行同步失败 | 30| DOWNLOADING | 2 | 下行同步中 | 31| DOWNLOAD_FAILED | 3 | 下行同步失败 | 32| COMPLETED | 4 | 同步成功 | 33| STOPPED | 5 | 同步已停止 | 34 35## ErrorType 36 37端云同步失败类型，为枚举类型。 38 39- 当前阶段，同步过程中，当移动数据网络和WIFI均不可用时，才会返回NETWORK_UNAVAILABLE；若有一种类型网络可用，则能正常同步。 40- 同步过程中，非充电场景下，电量低于15%，完成当前批上行同步后停止同步，返回低电量；电量低于10%，完成当前批上行同步后停止同步，返回告警电量。 41- 触发同步时，非充电场景下，若电量低于15%，则不允许同步，start接口返回对应错误。 42- 上行时，若云端空间不足，则文件上行失败，云端无该文件记录。 43- 下行时，若本地空间不足，则文件下行失败，本地空间释放后再次同步会重新下行。 44 45**系统能力**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 46 47| 名称 | 值| 说明 | 48| ----- | ---- | ---- | 49| NO_ERROR | 0 | 没有错误 | 50| NETWORK_UNAVAILABLE | 1 | 所有网络不可用 | 51| WIFI_UNAVAILABLE | 2 | WIFI不可用 | 52| BATTERY_LEVEL_LOW | 3 | 低电量（低于15%） | 53| BATTERY_LEVEL_WARNING | 4 | 告警电量（低于10%） | 54| CLOUD_STORAGE_FULL | 5 | 云端空间不足 | 55| LOCAL_STORAGE_FULL | 6 | 本地空间不足 | 56 57## SyncProgress 58 59端云同步过程。 60 61**系统能力**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 62 63| 名称 | 类型 | 必填 | 说明 | 64| ---------- | ------ | ---- | ---- | 65| state | [SyncState](#syncstate) | 是 | 枚举值，端云同步状态| 66| error | [ErrorType](#errortype) | 是 | 枚举值，同步失败错误类型| 67 68## GallerySync 69 70云图同步对象，用来支撑图库应用媒体资源端云同步流程。在使用前，需要先创建GallerySync实例。 71 72### constructor 73 74constructor() 75 76端云同步流程的构造函数，用于获取GallerySync类的实例。 77 78**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 79 80**示例：** 81 82 ```ts 83 let gallerySync = new cloudSync.GallerySync() 84 ``` 85 86### on 87 88on(evt: 'progress', callback: (pg: SyncProgress) => void): void 89 90添加同步过程事件监听。 91 92**需要权限**：ohos.permission.CLOUDFILE_SYNC 93 94**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 95 96**参数：** 97 98| 参数名 | 类型 | 必填 | 说明 | 99| ---------- | ------ | ---- | ---- | 100| evt | string | 是 | 订阅的事件类型，取值为'progress'（同步过程事件） | 101| callback | (pg: SyncProgress) => void | 是 | 同步过程事件回调，回调入参为[SyncProgress](#syncprogress), 返回值为void| 102 103**错误码：** 104 105以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 106 107| 错误码ID | 错误信息 | 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**示例：** 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 128移除同步过程事件监听。 129 130**需要权限**：ohos.permission.CLOUDFILE_SYNC 131 132**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 133 134**参数：** 135 136| 参数名 | 类型 | 必填 | 说明 | 137| ---------- | ------ | ---- | ---- | 138| evt | string | 是 | 取消订阅的事件类型，取值为'progress'（同步过程事件）| 139| callback | (pg: SyncProgress) => void | 是 | 同步过程事件回调，回调入参为[SyncProgress](#syncprogress), 返回值为void| 140 141**错误码：** 142 143以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 144 145| 错误码ID | 错误信息 | 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**示例：** 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 170移除同步过程事件监听。 171 172**需要权限**：ohos.permission.CLOUDFILE_SYNC 173 174**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 175 176**参数：** 177 178| 参数名 | 类型 | 必填 | 说明 | 179| ---------- | ------ | ---- | ---- | 180| evt | string | 是 | 取消订阅的事件类型，取值为'progress'（同步过程事件）| 181 182**错误码：** 183 184以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 185 186| 错误码ID | 错误信息 | 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**示例：** 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 209异步方法启动端云同步, 以Promise形式返回结果。 210 211**需要权限**：ohos.permission.CLOUDFILE_SYNC 212 213**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 214 215**返回值：** 216 217| 类型 | 说明 | 218| --------------------- | ---------------- | 219| Promise<void> | 使用Promise形式返回启动端云同步的结果 | 220 221**错误码：** 222 223以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 224 225| 错误码ID | 错误信息 | 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**示例：** 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 255异步方法启动端云同步, 以callback形式返回结果。 256 257**需要权限**：ohos.permission.CLOUDFILE_SYNC 258 259**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 260 261**参数：** 262 263| 参数名 | 类型 | 必填 | 说明 | 264| ---------- | ------ | ---- | ---- | 265| callback | AsyncCallback<void> | 是 | 异步启动端云同步的回调 | 266 267**错误码：** 268 269以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 270 271| 错误码ID | 错误信息 | 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**示例：** 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 299异步方法停止端云同步, 以Promise形式返回结果。 300 301> **说明：** 302> 303> 调用stop接口，同步流程会停止。再次调用[start](#start)接口会继续同步。 304 305**需要权限**：ohos.permission.CLOUDFILE_SYNC 306 307**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 308 309**返回值：** 310 311| 类型 | 说明 | 312| --------------------- | ---------------- | 313| Promise<void> | 使用Promise形式返回停止端云同步的结果 | 314 315**错误码：** 316 317以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 318 319| 错误码ID | 错误信息 | 320| ---------------------------- | ---------- | 321| 201 | Permission verification failed. | 322| 202 | The caller is not a system application. | 323| 401 | The input parameter is invalid. | 324 325**示例：** 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 342异步方法停止端云同步, 以callback形式返回结果。 343 344> **说明：** 345> 346> 调用stop接口，同步流程会停止。再次调用[start](#start)接口会继续同步。 347 348**需要权限**：ohos.permission.CLOUDFILE_SYNC 349 350**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 351 352**参数：** 353 354| 参数名 | 类型 | 必填 | 说明 | 355| ---------- | ------ | ---- | ---- | 356| callback | AsyncCallback<void> | 是 | 异步停止端云同步的回调 | 357 358**错误码：** 359 360以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 361 362| 错误码ID | 错误信息 | 363| ---------------------------- | ---------- | 364| 201 | Permission verification failed. | 365| 202 | The caller is not a system application. | 366| 401 | The input parameter is invalid. | 367 368**示例：** 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 385云文件下载状态，为枚举类型。 386 387**系统能力**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 388 389| 名称 | 值| 说明 | 390| ----- | ---- | ---- | 391| RUNNING | 0 | 云文件正在下载中 | 392| COMPLETED | 1 | 云文件下载完成 | 393| FAILED | 2 | 云文件下载失败 | 394| STOPPED | 3 | 云文件下载已停止 | 395 396## DownloadProgress 397 398云文件下载过程。 399 400**系统能力**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 401 402| 名称 | 类型 | 必填 | 说明 | 403| ---------- | ------ | ---- | ---- | 404| state | [State](#state) | 是 | 枚举值，云文件下载状态| 405| processed | number | 是 | 已下载数据大小| 406| size | number | 是 | 当前云文件大小| 407| uri | string | 是 | 当前云文件uri| 408 409## Download 410 411云文件下载对象，用来支撑图库应用原图文件下载流程。在使用前，需要先创建Download实例。 412 413### constructor 414 415constructor() 416 417云文件下载流程的构造函数，用于获取Download类的实例。 418 419**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 420 421**示例：** 422 423 ```ts 424 let download = new cloudSync.Download() 425 ``` 426 427### on 428 429on(evt: 'progress', callback: (pg: DownloadProgress) => void): void 430 431添加云文件下载过程事件监听。 432 433**需要权限**：ohos.permission.CLOUDFILE_SYNC 434 435**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 436 437**参数：** 438 439| 参数名 | 类型 | 必填 | 说明 | 440| ---------- | ------ | ---- | ---- | 441| evt | string | 是 | 订阅的事件类型，取值为'progress'（下载过程事件）| 442| callback | (pg: DownloadProgress) => void | 是 | 云文件下载过程事件回调，回调入参为[DownloadProgress](#downloadprogress), 返回值为void| 443 444**错误码：** 445 446以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 447 448| 错误码ID | 错误信息 | 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**示例：** 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 469移除云文件下载过程事件监听。 470 471**需要权限**：ohos.permission.CLOUDFILE_SYNC 472 473**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 474 475**参数：** 476 477| 参数名 | 类型 | 必填 | 说明 | 478| ---------- | ------ | ---- | ---- | 479| evt | string | 是 | 取消订阅的事件类型，取值为'progress'（同步过程事件）| 480| callback | (pg: DownloadProgress) => void | 是 | 云文件下载过程事件回调，回调入参为[DownloadProgress](#downloadprogress), 返回值为void| 481 482**错误码：** 483 484以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 485 486| 错误码ID | 错误信息 | 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**示例：** 494 495 ```ts 496 let download = new cloudSync.Download(); 497 498 let callback = (pg: cloudSync.DownloadProgress) => { 499 console.info("download state：" + pg.state); 500 } 501 502 download.on('progress', callback); 503 504 download.off('progress', callback); 505 ``` 506 507### off 508 509off(evt: 'progress'): void 510 511移除云文件下载过程事件监听。 512 513**需要权限**：ohos.permission.CLOUDFILE_SYNC 514 515**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 516 517**参数：** 518 519| 参数名 | 类型 | 必填 | 说明 | 520| ---------- | ------ | ---- | ---- | 521| evt | string | 是 | 取消订阅的事件类型，取值为'progress'（下载过程事件）| 522 523**错误码：** 524 525以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 526 527| 错误码ID | 错误信息 | 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**示例：** 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 550异步方法启动云文件下载, 以Promise形式返回结果。 551 552**需要权限**：ohos.permission.CLOUDFILE_SYNC 553 554**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 555 556**参数：** 557 558| 参数名 | 类型 | 必填 | 说明 | 559| ---------- | ------ | ---- | ---- | 560| uri | string | 是 | 待下载文件uri | 561 562**返回值：** 563 564| 类型 | 说明 | 565| --------------------- | ---------------- | 566| Promise<void> | 使用Promise形式返回启动云文件下载的结果 | 567 568**示例：** 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**错误码：** 587 588以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 589 590| 错误码ID | 错误信息 | 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 602异步方法启动云文件下载, 以callback形式返回结果。 603 604**需要权限**：ohos.permission.CLOUDFILE_SYNC 605 606**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 607 608**参数：** 609 610| 参数名 | 类型 | 必填 | 说明 | 611| ---------- | ------ | ---- | ---- | 612| uri | string | 是 | 待下载文件uri | 613| callback | AsyncCallback<void> | 是 | 异步启动云文件下载的回调 | 614 615**错误码：** 616 617以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 618 619| 错误码ID | 错误信息 | 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**示例：** 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 647异步方法停止云文件下载, 以Promise形式返回结果。 648 649> **说明：** 650> 651> 调用stop接口, 当前文件下载流程会终止, 缓存文件会被删除，再次调用start接口会重新开始下载 652 653**需要权限**：ohos.permission.CLOUDFILE_SYNC 654 655**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 656 657**参数：** 658 659| 参数名 | 类型 | 必填 | 说明 | 660| ---------- | ------ | ---- | ---- | 661| uri | string | 是 | 待下载文件uri | 662 663**返回值：** 664 665| 类型 | 说明 | 666| --------------------- | ---------------- | 667| Promise<void> | 使用Promise形式返回停止云文件下载的结果 | 668 669**错误码：** 670 671以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 672 673| 错误码ID | 错误信息 | 674| ---------------------------- | ---------- | 675| 201 | Permission verification failed. | 676| 202 | The caller is not a system application. | 677| 401 | The input parameter is invalid. | 678 679**示例：** 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 697异步方法停止云文件下载, 以callback形式返回结果。 698 699> **说明：** 700> 701> 调用stop接口, 当前文件下载流程会终止, 缓存文件会被删除, 再次调用start接口会重新开始下载 702 703**需要权限**：ohos.permission.CLOUDFILE_SYNC 704 705**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 706 707**参数：** 708 709| 参数名 | 类型 | 必填 | 说明 | 710| ---------- | ------ | ---- | ---- | 711| uri | string | 是 | 待下载文件uri | 712| callback | AsyncCallback<void> | 是 | 异步停止云文件下载的回调 | 713 714**错误码：** 715 716以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。 717 718| 错误码ID | 错误信息 | 719| ---------------------------- | ---------- | 720| 201 | Permission verification failed. | 721| 202 | The caller is not a system application. | 722| 401 | The input parameter is invalid. | 723 724**示例：** 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