1# @ohos.file.cloudSync (端云同步能力) 2<!--Kit: Core File Kit--> 3<!--Subsystem: FileManagement--> 4<!--Owner: @zsyztt; @Hermits; @reminder2352--> 5<!--Designer: @yunlanying--> 6<!--Tester: @liuhonggang123--> 7<!--Adviser: @foryourself--> 8 9该模块向应用提供端云同步能力，包括启动/停止端云同步以及启动/停止原图下载功能。 10 11> **说明：** 12> 13> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14 15## 导入模块 16 17```ts 18import { cloudSync } from '@kit.CoreFileKit'; 19``` 20## SyncState<sup>12+</sup> 21 22端云同步状态，为枚举类型。 23 24> **说明：** 25> 26> 以下同步状态发生变更时，如果应用注册了同步过程事件监听，则通过回调通知应用。 27 28**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 29 30| 名称 | 值| 说明 | 31| ----- | ---- | ---- | 32| UPLOADING | 0 | 上行同步中。 | 33| UPLOAD_FAILED | 1 | 上行同步失败。 | 34| DOWNLOADING | 2 | 下行同步中。 | 35| DOWNLOAD_FAILED | 3 | 下行同步失败。 | 36| COMPLETED | 4 | 同步成功。 | 37| STOPPED | 5 | 同步已停止。 | 38 39## ErrorType<sup>12+</sup> 40 41端云同步失败类型，为枚举类型。 42 43- 当前阶段，同步过程中，当开启无限量使用移动数据网络，移动数据网络和WIFI均不可用时，才会返回NETWORK_UNAVAILABLE；开启无限量使用移动数据网络，若有一种类型网络可用，则能正常同步。 44- 同步过程中，非充电场景下，电量低于10%，完成当前批上行同步后停止同步，返回低电量； 45- 触发同步时，非充电场景下，若电量低于10%，则不允许同步，start接口返回对应错误。 46- 上行时，若云端空间不足，则文件上行失败，云端无该文件记录。 47 48**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 49 50| 名称 | 值| 说明 | 51| ----- | ---- | ---- | 52| NO_ERROR | 0 | 没有错误。 | 53| NETWORK_UNAVAILABLE | 1 | 所有网络不可用。 | 54| WIFI_UNAVAILABLE | 2 | WIFI不可用。 | 55| BATTERY_LEVEL_LOW | 3 | 低电量（低于10%）。 | 56| BATTERY_LEVEL_WARNING | 4 | 告警电量（低于15%）。 | 57| CLOUD_STORAGE_FULL | 5 | 云端空间不足。 | 58| LOCAL_STORAGE_FULL | 6 | 本地空间不足。 | 59| DEVICE_TEMPERATURE_TOO_HIGH | 7 | 设备温度过高。 | 60| REMOTE_SERVER_ABNORMAL<sup>20+</sup> | 8 | 远端服务不可用。 | 61 62## SyncProgress<sup>12+</sup> 63 64端云同步过程。 65 66### 属性 67 68**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 69 70| 名称 | 类型 | 只读 | 可选 | 说明 | 71| ---------- | ------ | ---- | ---- | ---- | 72| state | [SyncState](#syncstate12) | 否 | 否 | 枚举值，端云同步状态。| 73| error | [ErrorType](#errortype12) | 否 | 否 | 枚举值，同步失败错误类型。| 74 75## State<sup>11+</sup> 76 77云文件下载状态，为枚举类型。 78 79**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 80 81| 名称 | 值| 说明 | 82| ----- | ---- | ---- | 83| RUNNING | 0 | 云文件正在下载中。 | 84| COMPLETED | 1 | 云文件下载完成。 | 85| FAILED | 2 | 云文件下载失败。 | 86| STOPPED | 3 | 云文件下载已停止。 | 87 88## DownloadProgress<sup>11+</sup> 89 90云文件下载过程。 91 92### 属性 93 94**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 95 96| 名称 | 类型 | 只读 | 可选 | 说明 | 97| ---------- | ------ | ---- | ---- | ---- | 98| state | [State](#state11) | 否 | 否 | 枚举值，云文件下载状态。| 99| processed | number | 否 | 否 | 已下载数据大小，取值范围[0，9223372036854775807]（单位：Byte）。| 100| size | number | 否 | 否 | 当前云文件大小，取值范围[0，9223372036854775807]（单位：Byte）。| 101| uri | string | 否 | 否 | 当前云文件URI。| 102| error | [DownloadErrorType](#downloaderrortype11) | 否 | 否 | 下载的错误类型。| 103 104## FileSync<sup>12+</sup> 105 106云盘同步对象，用于支撑文件管理器应用完成云盘文件的端云同步流程。在使用前，需要先创建FileSync实例。 107 108**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 109 110### constructor<sup>12+</sup> 111 112constructor() 113 114端云同步流程的构造函数，用于获取FileSync类的实例。 115 116**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 117 118**错误码：** 119 120以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 121 122| 错误码ID | 错误信息 | 123| ---------------------------- | ---------- | 124| 401 | The input parameter is invalid. Possible causes:Incorrect parameter types. | 125 126**示例：** 127 128 ```ts 129 let fileSync = new cloudSync.FileSync() 130 ``` 131 132### on<sup>12+</sup> 133 134on(event: 'progress', callback: Callback\<SyncProgress>): void 135 136添加同步过程事件监听。 137 138**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 139 140**参数：** 141 142| 参数名 | 类型 | 必填 | 说明 | 143| ---------- | ------ | ---- | ---- | 144| event | string | 是 | 订阅的事件类型，取值为'progress'（同步过程事件）。 | 145| callback | Callback\<[SyncProgress](#syncprogress12)> | 是 | 同步过程事件回调。| 146 147**错误码：** 148 149以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 150 151| 错误码ID | 错误信息 | 152| ---------------------------- | ---------- | 153| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 154| 13600001 | IPC error. | 155 156**示例：** 157 158 ```ts 159 let fileSync = new cloudSync.FileSync(); 160 let callback = (pg: cloudSync.SyncProgress) => { 161 console.info("file sync state：" + pg.state + "error type:" + pg.error); 162 } 163 164 fileSync.on('progress', callback); 165 ``` 166 167### off<sup>12+</sup> 168 169off(event: 'progress', callback?: Callback\<SyncProgress>): void 170 171移除同步过程事件监听。 172 173**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 174 175**参数：** 176 177| 参数名 | 类型 | 必填 | 说明 | 178| ---------- | ------ | ---- | ---- | 179| event | string | 是 | 取消订阅的事件类型，取值为'progress'（同步过程事件）。| 180| callback | Callback\<[SyncProgress](#syncprogress12)> | 否 | 同步过程事件回调， 默认值为null。 | 181 182**错误码：** 183 184以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 185 186| 错误码ID | 错误信息 | 187| ---------------------------- | ---------- | 188| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 189| 13600001 | IPC error. | 190 191**示例：** 192 193 ```ts 194 let fileSync = new cloudSync.FileSync(); 195 196 let callback = (pg: cloudSync.SyncProgress) => { 197 console.info("file sync state：" + pg.state + "error type:" + pg.error); 198 } 199 200 fileSync.on('progress', callback); 201 202 fileSync.off('progress', callback); 203 ``` 204 205### start<sup>12+</sup> 206 207start(): Promise<void> 208 209异步方法启动云盘端云同步，以Promise形式返回结果。 210 211**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 212 213**返回值：** 214 215| 类型 | 说明 | 216| --------------------- | ---------------- | 217| Promise<void> | Promise对象，无返回值。 | 218 219**错误码：** 220 221以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 222 223| 错误码ID | 错误信息 | 224| ---------------------------- | ---------- | 225| 401 | The input parameter is invalid. Possible causes:Incorrect parameter types. | 226| 13600001 | IPC error. | 227| 22400001 | Cloud status not ready. | 228| 22400002 | Network unavailable. | 229| 22400003 | Low battery level. | 230 231**示例：** 232 233 ```ts 234 import { BusinessError } from '@kit.BasicServicesKit'; 235 let fileSync = new cloudSync.FileSync(); 236 237 let callback = (pg: cloudSync.SyncProgress) => { 238 console.info("file sync state：" + pg.state + "error type:" + pg.error); 239 } 240 241 fileSync.on('progress', callback); 242 243 fileSync.start().then(() => { 244 console.info("start sync successfully"); 245 }).catch((err: BusinessError) => { 246 console.error("start sync failed with error message: " + err.message + ", error code: " + err.code); 247 }); 248 ``` 249 250### start<sup>12+</sup> 251 252start(callback: AsyncCallback<void>): void 253 254异步方法启动云盘端云同步，以callback形式返回结果。 255 256**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 257 258**参数：** 259 260| 参数名 | 类型 | 必填 | 说明 | 261| ---------- | ------ | ---- | ---- | 262| callback | AsyncCallback<void> | 是 | 异步启动端云同步的回调。 | 263 264**错误码：** 265 266以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 267 268| 错误码ID | 错误信息 | 269| ---------------------------- | ---------- | 270| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 271| 13600001 | IPC error. | 272| 22400001 | Cloud status not ready. | 273| 22400002 | Network unavailable. | 274| 22400003 | Low battery level. | 275 276**示例：** 277 278 ```ts 279 import { BusinessError } from '@kit.BasicServicesKit'; 280 let fileSync = new cloudSync.FileSync(); 281 282 fileSync.start((err: BusinessError) => { 283 if (err) { 284 console.error("start sync failed with error message: " + err.message + ", error code: " + err.code); 285 } else { 286 console.info("start sync successfully"); 287 } 288 }); 289 ``` 290 291### stop<sup>12+</sup> 292 293stop(): Promise<void> 294 295异步方法停止云盘端云同步，以Promise形式返回结果。 296 297调用stop接口，同步流程会停止。再次调用[start](#start12)接口会继续同步。 298 299**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 300 301**返回值：** 302 303| 类型 | 说明 | 304| --------------------- | ---------------- | 305| Promise<void> | 使用Promise形式返回停止端云同步的结果。 | 306 307**错误码：** 308 309以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 310 311| 错误码ID | 错误信息 | 312| ---------------------------- | ---------- | 313| 401 | The input parameter is invalid. Possible causes:Incorrect parameter types. | 314| 13600001 | IPC error. | 315 316**示例：** 317 318 ```ts 319 import { BusinessError } from '@kit.BasicServicesKit'; 320 let fileSync = new cloudSync.FileSync(); 321 322 fileSync.stop().then(() => { 323 console.info("stop sync successfully"); 324 }).catch((err: BusinessError) => { 325 console.error("stop sync failed with error message: " + err.message + ", error code: " + err.code); 326 }); 327 ``` 328 329### stop<sup>12+</sup> 330 331stop(callback: AsyncCallback<void>): void 332 333异步方法停止云盘端云同步，以callback形式返回结果。 334 335调用stop接口，同步流程会停止。再次调用[start](#start12)接口会继续同步。 336 337**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 338 339**参数：** 340 341| 参数名 | 类型 | 必填 | 说明 | 342| ---------- | ------ | ---- | ---- | 343| callback | AsyncCallback<void> | 是 | 异步停止端云同步的回调。 | 344 345**错误码：** 346 347以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 348 349| 错误码ID | 错误信息 | 350| ---------------------------- | ---------- | 351| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 352| 13600001 | IPC error. | 353 354**示例：** 355 356 ```ts 357 import { BusinessError } from '@kit.BasicServicesKit'; 358 let fileSync = new cloudSync.FileSync(); 359 360 fileSync.stop((err: BusinessError) => { 361 if (err) { 362 console.error("stop sync failed with error message: " + err.message + ", error code: " + err.code); 363 } else { 364 console.info("stop sync successfully"); 365 } 366 }); 367 ``` 368 369### getLastSyncTime<sup>12+</sup> 370 371getLastSyncTime(): Promise<number> 372 373异步方法获取上次同步时间，以promise形式返回结果。 374 375**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 376 377**返回值：** 378 379| 类型 | 说明 | 380| --------------------- | ---------------- | 381| Promise<number> | 使用Promise形式返回上次同步时间。 | 382 383**错误码：** 384 385以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 386 387| 错误码ID | 错误信息 | 388| ---------------------------- | ---------- | 389| 401 | The input parameter is invalid. Possible causes:Incorrect parameter types. | 390| 13600001 | IPC error. | 391 392**示例：** 393 394 ```ts 395 import { BusinessError } from '@kit.BasicServicesKit'; 396 let fileSync = new cloudSync.FileSync(); 397 398 fileSync.getLastSyncTime().then((timeStamp: number) => { 399 let date = new Date(timeStamp); 400 console.info("get last sync time successfully:"+ date); 401 }).catch((err: BusinessError) => { 402 console.error("get last sync time failed with error message: " + err.message + ", error code: " + err.code); 403 }); 404 405 ``` 406 407### getLastSyncTime<sup>12+</sup> 408 409getLastSyncTime(callback: AsyncCallback<number>): void 410 411异步方法获取上次同步时间，以callback形式返回结果。 412 413**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 414 415**参数：** 416 417| 参数名 | 类型 | 必填 | 说明 | 418| ---------- | ------ | ---- | ---- | 419| callback | AsyncCallback<number> | 是 | 异步获取上次同步时间的回调。| 420 421**错误码：** 422 423以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 424 425| 错误码ID | 错误信息 | 426| ---------------------------- | ---------- | 427| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 428| 13600001 | IPC error. | 429 430**示例：** 431 432 ```ts 433 import { BusinessError } from '@kit.BasicServicesKit'; 434 let fileSync = new cloudSync.FileSync(); 435 436 fileSync.getLastSyncTime((err: BusinessError, timeStamp: number) => { 437 if (err) { 438 console.error("get last sync time with error message: " + err.message + ", error code: " + err.code); 439 } else { 440 let date = new Date(timeStamp); 441 console.info("get last sync time successfully:"+ date); 442 } 443 }); 444 ``` 445 446## CloudFileCache<sup>11+</sup> 447 448云盘文件缓存对象，用来支撑文件管理应用原文件下载流程。 449 450**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 451 452### construct<sup>11+</sup> 453 454constructor() 455 456云盘文件缓存流程的构造函数，用于获取CloudFileCache类的实例。多个实例之间不互相共享数据。 457 458**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 459 460**错误码：** 461 462以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 463 464| 错误码ID | 错误信息 | 465| ---------------------------- | ---------- | 466| 401 | The input parameter is invalid. Possible causes:Incorrect parameter types. | 467 468**示例：** 469 470 ```ts 471 let fileCache = new cloudSync.CloudFileCache(); 472 ``` 473 474### on<sup>11+</sup> 475 476on(event: 'progress', callback: Callback\<DownloadProgress>): void 477 478添加云盘文件缓存过程事件监听。 479 480**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 481 482**参数：** 483 484| 参数名 | 类型 | 必填 | 说明 | 485| ---------- | ------ | ---- | ---- | 486| event | string | 是 | 订阅的事件类型，取值为'progress'（下载过程事件）。| 487| callback | Callback\<[DownloadProgress](#downloadprogress11)> | 是 | 云文件下载过程事件回调。 | 488 489**错误码：** 490 491以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 492 493| 错误码ID | 错误信息 | 494| ---------------------------- | ---------- | 495| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 496| 13600001 | IPC error. | 497 498**示例：** 499 500 ```ts 501 import { BusinessError } from '@kit.BasicServicesKit'; 502 let fileCache = new cloudSync.CloudFileCache(); 503 let callback = (pg: cloudSync.DownloadProgress) => { 504 console.info("download state：" + pg.state); 505 }; 506 507 try { 508 fileCache.on('progress', callback); 509 } catch (e) { 510 const error = e as BusinessError; 511 console.error(`Error code: ${error.code}, message: ${error.message}`); 512 } 513 ``` 514 515### on<sup>20+</sup> 516 517on(event: 'batchDownload', callback: Callback<MultiDownloadProgress>): void 518 519添加云文件批量缓存事件的监听。 520 521**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 522 523**参数：** 524 525| 参数名 | 类型 | 必填 | 说明 | 526| -------- | ----------------------------------------------------------------- | ---- | ------------------------------------------------------------- | 527| event | string | 是 | 订阅的事件类型，取值为'batchDownload'，表示批量缓存过程事件。 | 528| callback | Callback<[MultiDownloadProgress](#multidownloadprogress20)> | 是 | 云文件批量缓存过程的事件回调。 | 529 530**错误码：** 531 532以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 533 534| 错误码ID | 错误信息 | 535| -------- | -------- | 536| 13900020 | Invalid argument. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 537| 22400005 | Inner error. Possible causes: 1.Failed to access the database or execute the SQL statement. 2.System error, such as a null pointer, insufficient memory or a JS engine exception. | 538 539**示例：** 540 541 ```ts 542 import { BusinessError } from '@kit.BasicServicesKit'; 543 544 let fileCache = new cloudSync.CloudFileCache(); 545 let callback = (data: cloudSync.MultiDownloadProgress) => { 546 console.info(`Batch download progress: downloadedSize: ${data.downloadedSize}, totalSize: ${data.totalSize}`); 547 if (data.state == cloudSync.State.COMPLETED) { 548 console.info('Batch download finished.'); 549 } else if (data.state == cloudSync.State.FAILED) { 550 console.info(`Batch download stopped, error type: ${data.errType}.`); 551 } 552 }; 553 554 try { 555 fileCache.on('batchDownload', callback); 556 } catch (e) { 557 let error = e as BusinessError; 558 console.error(`Failed to register download callback, error code: ${error.code}, message: ${error.message}`); 559 } 560 ``` 561 562### off<sup>11+</sup> 563 564off(event: 'progress', callback?: Callback\<DownloadProgress>): void 565 566移除云盘文件缓存过程事件监听。 567 568**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 569 570**参数：** 571 572| 参数名 | 类型 | 必填 | 说明 | 573| ---------- | ------ | ---- | ---- | 574| event | string | 是 | 取消订阅的事件类型，取值为'progress'（同步过程事件）。| 575| callback | Callback\<[DownloadProgress](#downloadprogress11)> | 否 | 云文件下载过程事件回调。若填写，将视为取消指定的回调函数；否则为取消当前订阅的所有回调函数。 | 576 577**错误码：** 578 579以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 580 581| 错误码ID | 错误信息 | 582| ---------------------------- | ---------- | 583| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 584| 13600001 | IPC error. | 585 586**示例：** 587 588 ```ts 589 import { BusinessError } from '@kit.BasicServicesKit'; 590 let fileCache = new cloudSync.CloudFileCache(); 591 592 let callback = (pg: cloudSync.DownloadProgress) => { 593 console.info("download state：" + pg.state); 594 } 595 596 try { 597 fileCache.on('progress', callback); 598 fileCache.off('progress', callback); 599 } catch (e) { 600 const error = e as BusinessError; 601 console.error(`Error code: ${error.code}, message: ${error.message}`); 602 } 603 ``` 604 605### off<sup>20+</sup> 606 607off(event: 'batchDownload', callback?: Callback<MultiDownloadProgress>): void 608 609移除由[on](#on20)接口添加的云文件批量缓存过程事件的监听。 610 611**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 612 613**参数：** 614 615| 参数名 | 类型 | 必填 | 说明 | 616| -------- | ----------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------- | 617| event | string | 是 | 取消订阅的事件类型，取值为'batchDownload'，表示批量缓存过程事件。 | 618| callback | Callback<[MultiDownloadProgress](#multidownloadprogress20)> | 否 | 云文件批量缓存过程事件的回调。如果填写此参数，将取消指定的回调函数；否则，将取消当前订阅的相同事件类型的所有回调函数。 | 619 620**错误码：** 621 622以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 623 624| 错误码ID | 错误信息 | 625| -------- | -------- | 626| 13900020 | Invalid argument. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 627| 22400005 | Inner error. Possible causes: 1.Failed to access the database or execute the SQL statement. 2.System error, such as a null pointer, insufficient memory or a JS engine exception. | 628 629**示例：** 630 631 ```ts 632 import { BusinessError } from '@kit.BasicServicesKit'; 633 634 let fileCache = new cloudSync.CloudFileCache(); 635 let callback = (pg: cloudSync.MultiDownloadProgress) => { 636 console.info("download state：" + pg.state); 637 } 638 639 try { 640 fileCache.on('batchDownload', callback); 641 fileCache.off('batchDownload', callback); 642 } catch (e) { 643 let error = e as BusinessError; 644 console.error(`Failed to unregister download callback, error code: ${error.code}, message: ${error.message}`); 645 } 646 ``` 647 648### start<sup>11+</sup> 649 650start(uri: string): Promise<void> 651 652异步方法启动云盘文件缓存，以Promise形式返回结果。 653 654**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 655 656**参数：** 657 658| 参数名 | 类型 | 必填 | 说明 | 659| ---------- | ------ | ---- | ---- | 660| uri | string | 是 | 待下载文件uri。 | 661 662**返回值：** 663 664| 类型 | 说明 | 665| --------------------- | ---------------- | 666| Promise<void> | 使用Promise形式返回启动云文件下载的结果。 | 667 668**错误码：** 669 670以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 671 672| 错误码ID | 错误信息 | 673| ---------------------------- | ---------- | 674| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 675| 13600001 | IPC error. | 676| 13900002 | No such file or directory. | 677| 13900025 | No space left on device. | 678| 14000002 | Invalid URI. | 679 680**示例：** 681 682 ```ts 683 import { BusinessError } from '@kit.BasicServicesKit'; 684 import { fileUri } from '@kit.CoreFileKit'; 685 let fileCache = new cloudSync.CloudFileCache(); 686 let path = "/data/storage/el2/cloud/1.txt"; 687 let uri = fileUri.getUriFromPath(path); 688 689 try { 690 fileCache.on('progress', (pg: cloudSync.DownloadProgress) => { 691 console.info("download state:" + pg.state); 692 }); 693 } catch (e) { 694 const error = e as BusinessError; 695 console.error(`Error code: ${error.code}, message: ${error.message}`); 696 } 697 698 fileCache.start(uri).then(() => { 699 console.info("start download successfully"); 700 }).catch((err: BusinessError) => { 701 console.error("start download failed with error message: " + err.message + ", error code: " + err.code); 702 }); 703 ``` 704 705### start<sup>11+</sup> 706 707start(uri: string, callback: AsyncCallback<void>): void 708 709异步方法启动云盘文件缓存，以callback形式返回结果。 710 711**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 712 713**参数：** 714 715| 参数名 | 类型 | 必填 | 说明 | 716| ---------- | ------ | ---- | ---- | 717| uri | string | 是 | 待下载文件uri。 | 718| callback | AsyncCallback<void> | 是 | 异步启动云文件下载的回调。 | 719 720**错误码：** 721 722以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 723 724| 错误码ID | 错误信息 | 725| ---------------------------- | ---------- | 726| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 727| 13600001 | IPC error. | 728| 13900002 | No such file or directory. | 729| 13900025 | No space left on device. | 730| 14000002 | Invalid URI. | 731 732**示例：** 733 734 ```ts 735 import { BusinessError } from '@kit.BasicServicesKit'; 736 import { fileUri } from '@kit.CoreFileKit'; 737 let fileCache = new cloudSync.CloudFileCache(); 738 let path = "/data/storage/el2/cloud/1.txt"; 739 let uri = fileUri.getUriFromPath(path); 740 741 fileCache.start(uri, (err: BusinessError) => { 742 if (err) { 743 console.error("start download failed with error message: " + err.message + ", error code: " + err.code); 744 } else { 745 console.info("start download successfully"); 746 } 747 }); 748 ``` 749 750### startBatch<sup>20+</sup> 751 752startBatch(uris: Array<string>, fileType?: DownloadFileType): Promise<number> 753 754启动云文件批量缓存，以Promise形式返回结果。 755 756不同的批量缓存任务可以通过接口返回的任务ID区分。 757 758**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 759 760**参数：** 761 762| 参数名 | 类型 | 必填 | 说明 | 763| -------- | --------------------------------------- | ---- | ------------------------------------------------------------------- | 764| uris | Array<string> | 是 | URI列表，一次调用最多支持传入400个URI，超过报错22400004。 | 765| fileType | [DownloadFileType](#downloadfiletype20) | 否 | 文件类型，默认值为CONTENT类型。 | 766 767**返回值：** 768 769| 类型 | 说明 | 770| --------------------- | ------------------------------------------- | 771| Promise<number> | Promise对象，返回启动的云文件批量缓存任务的ID。 | 772 773**错误码：** 774 775以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 776 777| 错误码ID | 错误信息 | 778| -------- | -------- | 779| 13600001 | IPC error. Possible causes: 1.IPC failed or timed out. 2.Failed to load the service. | 780| 13900020 | Invalid argument. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 781| 22400004 | Exceed the maximum limit. | 782| 22400005 | Inner error. Possible causes: 1.Failed to access the database or execute the SQL statement. 2.System error, such as a null pointer, insufficient memory or a JS engine exception. | 783 784**示例：** 785 786 ```ts 787 import { BusinessError } from '@kit.BasicServicesKit'; 788 789 let fileCache = new cloudSync.CloudFileCache(); 790 try { 791 fileCache.on('batchDownload', (pg: cloudSync.MultiDownloadProgress) => { 792 console.info(`batch download state：${pg.state}`); 793 }); 794 } catch (e) { 795 let error = e as BusinessError; 796 console.error(`Failed to unregister download callback, error code: ${error.code}, message: ${error.message}`); 797 } 798 799 let uriList: Array<string> = []; 800 fileCache.startBatch(uriList, cloudSync.DownloadFileType.CONTENT).then((downloadId: number) => { 801 console.info(`start batch download successfully, taskId: ${downloadId}`); 802 }).catch((err: BusinessError) => { 803 console.error(`start download failed with error message: ${err.message}, error code: ${err.code}`); 804 }); 805 ``` 806 807### stop<sup>11+</sup> 808 809stop(uri: string, needClean?: boolean): Promise<void> 810 811异步方法停止云盘文件缓存，以Promise形式返回结果。 812 813调用stop接口，当前文件下载流程会终止，默认不删除缓存文件，再次调用start接口重新启动下载。 814 815**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 816 817**参数：** 818 819| 参数名 | 类型 | 必填 | 说明 | 820| ---------- | ------ | ---- | ---- | 821| uri | string | 是 | 待下载文件uri。 | 822| needClean<sup>12+</sup> | boolean | 否 | 是否删除已下载的文件。默认值为false表示不删除；true表示删除。<br>从API version12开始支持该参数。 | 823 824**返回值：** 825 826| 类型 | 说明 | 827| --------------------- | ---------------- | 828| Promise<void> | 使用Promise形式返回停止云文件下载的结果。 | 829 830**错误码：** 831 832以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 833 834| 错误码ID | 错误信息 | 835| ---------------------------- | ---------- | 836| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 837| 13600001 | IPC error. | 838| 13900002 | No such file or directory. | 839| 14000002 | Invalid URI. | 840 841**示例：** 842 843 ```ts 844 import { BusinessError } from '@kit.BasicServicesKit'; 845 import { fileUri } from '@kit.CoreFileKit'; 846 let fileCache = new cloudSync.CloudFileCache(); 847 let path = "/data/storage/el2/cloud/1.txt"; 848 let uri = fileUri.getUriFromPath(path); 849 850 fileCache.stop(uri, true).then(() => { 851 console.info("stop download successfully"); 852 }).catch((err: BusinessError) => { 853 console.error("stop download failed with error message: " + err.message + ", error code: " + err.code); 854 }); 855 ``` 856 857### stop<sup>11+</sup> 858 859stop(uri: string, callback: AsyncCallback<void>): void 860 861异步方法停止云盘文件缓存，以callback形式返回结果。 862 863调用stop接口，当前文件下载流程会终止，不删除缓存文件，再次调用start接口重新启动下载。 864 865**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 866 867**参数：** 868 869| 参数名 | 类型 | 必填 | 说明 | 870| ---------- | ------ | ---- | ---- | 871| uri | string | 是 | 待下载文件uri。 | 872| callback | AsyncCallback<void> | 是 | 异步停止云文件下载的回调。 | 873 874**错误码：** 875 876以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 877 878| 错误码ID | 错误信息 | 879| ---------------------------- | ---------- | 880| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 881| 13600001 | IPC error. | 882| 13900002 | No such file or directory. | 883| 14000002 | Invalid URI. | 884 885**示例：** 886 887 ```ts 888 import { BusinessError } from '@kit.BasicServicesKit'; 889 import { fileUri } from '@kit.CoreFileKit'; 890 let fileCache = new cloudSync.CloudFileCache(); 891 let path = "/data/storage/el2/cloud/1.txt"; 892 let uri = fileUri.getUriFromPath(path); 893 894 fileCache.stop(uri, (err: BusinessError) => { 895 if (err) { 896 console.error("stop download failed with error message: " + err.message + ", error code: " + err.code); 897 } else { 898 console.info("stop download successfully"); 899 } 900 }); 901 ``` 902 903### stopBatch<sup>20+</sup> 904 905stopBatch(downloadId: number, needClean?: boolean): Promise<void> 906 907停止由[startBatch](#startbatch20)启动的云文件批量缓存任务，以Promise形式返回结果。 908 909调用stopBatch接口会终止当前文件批量缓存流程，未下载完成的缓存文件是否删除由needClean参数决定。 910 911**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 912 913**参数：** 914 915| 参数名 | 类型 | 必填 | 说明 | 916| ---------- | ------- | ---- | ----------------------------------------------------------------- | 917| downloadId | number | 是 | 需要停止缓存的任务ID。 | 918| needClean | boolean | 否 | 是否删除未完成缓存的文件。默认值为false表示不删除；true表示删除。 | 919 920**返回值：** 921 922| 类型 | 说明 | 923| ------------------- | ------------------------- | 924| Promise<void> | 使用Promise形式返回，无返回结果。 | 925 926**错误码：** 927 928以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 929 930| 错误码ID | 错误信息 | 931| -------- | -------- | 932| 13600001 | IPC error. Possible causes: 1.IPC failed or timed out. 2.Failed to load the service. | 933| 13900020 | Invalid argument. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 934| 22400005 | Inner error. Possible causes: 1.Failed to access the database or execute the SQL statement. 2.System error, such as a null pointer, insufficient memory or a JS engine exception. | 935 936**示例：** 937 938 ```ts 939 import { BusinessError } from '@kit.BasicServicesKit'; 940 941 let taskId = -1; 942 let uriList: Array<string> = []; 943 let fileCache = new cloudSync.CloudFileCache(); 944 fileCache.startBatch(uriList, cloudSync.DownloadFileType.CONTENT).then((downloadId: number) => { 945 taskId = downloadId; 946 console.info("start batch download successfully"); 947 }).catch((err: BusinessError) => { 948 console.error(`start batch download failed with error message: ${err.message}, error code: ${err.code}`); 949 }); 950 951 let needStop = true; 952 if (needStop && taskId > 0) { 953 fileCache.stopBatch(taskId, true).then(() => { 954 console.info("stop batch download successfully"); 955 }).catch((err: BusinessError) => { 956 console.error(`stop batch download failed with error message: ${err.message}, error code: ${err.code}`); 957 }); 958 } 959 ``` 960 961### cleanFileCache<sup>20+</sup> 962 963cleanFileCache(uri: string): void 964 965同步方法删除文件缓存。 966 967**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 968 969**参数：** 970 971| 参数名 | 类型 | 必填 | 说明 | 972| ---------- | ------ | ---- | ---- | 973| uri | string | 是 | 待删除缓存文件的URI。| 974 975**错误码：** 976 977以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 978 979| 错误码ID | 错误信息 | 980| ---------------------------- | ---------- | 981| 13600001 | IPC error. Possible causes:1.IPC failed or timed out. 2.Failed to load the service. | 982| 13900002 | No such file or directory. | 983| 13900010 | Try again. | 984| 13900012 | Permission denied by the file system. | 985| 13900020 | Parameter error. Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 986| 14000002 | Invalid URI. | 987| 22400005 | Inner error. Possible causes:1.Failed to access the database or execute the SQL statement. 2.System error, such as a null pointer, insufficient memory or a JS engine exception. | 988 989**示例：** 990 991 ```ts 992 import { BusinessError } from '@kit.BasicServicesKit'; 993 import { fileUri } from '@kit.CoreFileKit'; 994 995 let fileCache = new cloudSync.CloudFileCache(); 996 let path = "/data/storage/el2/cloud/1.txt"; 997 let uri = fileUri.getUriFromPath(path); 998 999 try { 1000 fileCache.cleanFileCache(uri); 1001 } catch (err) { 1002 let error:BusinessError = err as BusinessError; 1003 console.error("clean file cache failed with error message: " + err.message + ", error code: " + err.code); 1004 } 1005 1006 ``` 1007 1008## DownloadErrorType<sup>11+</sup> 1009 1010端云下载错误类型，为枚举类型。 1011 1012**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1013 1014| 名称 | 值| 说明 | 1015| ----- | ---- | ---- | 1016| NO_ERROR | 0 | 没有错误。 | 1017| UNKNOWN_ERROR | 1 | 未知错误。 | 1018| NETWORK_UNAVAILABLE | 2 | 网络不可用。 | 1019| LOCAL_STORAGE_FULL | 3 | 本地空间不足。 | 1020| CONTENT_NOT_FOUND | 4 | 云端空间未找到对应文件。 | 1021| FREQUENT_USER_REQUESTS | 5 | 用户请求过于频繁。 | 1022 1023## DownloadFileType<sup>20+</sup> 1024 1025云盘缓存文件类型的枚举。 1026 1027**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1028 1029| 名称 | 值 | 说明 | 1030| --------- | --- | ------------------- | 1031| CONTENT | 0 | content类型文件。 | 1032| THUMBNAIL | 1 | thumbnail类型文件。 | 1033| LCD | 2 | lcd类型文件。 | 1034 1035## FailedFileInfo<sup>20+</sup> 1036 1037云文件批量缓存失败列表及失败原因。 1038 1039**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1040 1041| 名称 | 类型 | 必填 | 说明 | 1042| ----- | ----------------------------------------- | ---- | ---------------------- | 1043| uri | string | 是 | 下载失败文件URI。 | 1044| error | [DownloadErrorType](#downloaderrortype11) | 是 | 文件下载失败错误类型。 | 1045 1046 1047## MultiDownloadProgress<sup>20+</sup> 1048 1049云文件批量缓存的进度信息。 1050 1051### 属性 1052 1053**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1054 1055| 名称 | 类型 | 只读 | 可选 | 说明 | 1056| --------------- | ----------------------------------------- | ---- | ---- | -------------------------------------------------------------------------------------------------- | 1057| state | [State](#state11) | 否 | 否 | 批量缓存任务的执行状态。 | 1058| taskId | number | 否 | 否 | 批量缓存任务的ID，取值范围为0到INT64_MAX。如果进度异常，返回值为-1。 | 1059| successfulCount | number | 否 | 否 | 缓存成功的文件数量，取值范围为0至400，单位：个。如果进度异常，返回值为-1。 | 1060| failedCount | number | 否 | 否 | 缓存失败的文件数，取值范围为0至400，单位：个。如果进度异常，返回值为-1。 | 1061| totalCount | number | 否 | 否 | 文件总数，取值范围为0至400，单位：个。如果进度异常，返回值为-1。 | 1062| downloadedSize | number | 否 | 否 | 已缓存的文件大小，取值范围为 [0, INT64_MAX)，单位：Byte。如果进度异常，返回值为 INT64_MAX。 | 1063| totalSize | number | 否 | 否 | 待缓存的文件总大小，取值范围为 [0, INT64_MAX)，单位为 Byte。如果进度异常，返回值为 INT64_MAX。 | 1064| errType | [DownloadErrorType](#downloaderrortype11) | 否 | 否 | 返回批量缓存任务执行失败时的错误类型。 | 1065 1066### getFailedFiles<sup>20+</sup> 1067 1068getFailedFiles(): Array<FailedFileInfo> 1069 1070获取批量缓存失败的文件列表。 1071 1072**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1073 1074**返回值：** 1075 1076| 类型 | 说明 | 1077| ------------------------------------------------ | --------------------------------------------------- | 1078| Array<[FailedFileInfo](#failedfileinfo20)> | 返回缓存失败的文件URI列表及其对应的错误类型。 | 1079 1080**错误码：** 1081 1082以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1083 1084| 错误码ID | 错误信息 | 1085| -------- | -------- | 1086| 22400005 | Inner error. Possible causes: 1.Failed to access the database or execute the SQL statement. 2.System error, such as a null pointer, insufficient memory or a JS engine exception. | 1087 1088**示例：** 1089 1090 ```ts 1091 import { BusinessError } from '@kit.BasicServicesKit'; 1092 1093 let taskId = -1; 1094 let failedList: Array<cloudSync.FailedFileInfo> = []; 1095 let fileCache = new cloudSync.CloudFileCache(); 1096 let callback = (data: cloudSync.MultiDownloadProgress) => { 1097 console.info(`Batch download progress: downloadedSize: ${data.downloadedSize}, totalSize: ${data.totalSize}`); 1098 if (data.state == cloudSync.State.FAILED) { 1099 console.info(`Batch download stopped, error type: ${data.errType}.`); 1100 failedList = data.getFailedFiles(); 1101 } 1102 }; 1103 1104 try { 1105 fileCache.on('batchDownload', callback); 1106 } catch (e) { 1107 let error = e as BusinessError; 1108 console.error(`Failed to register download callback, error code: ${error.code}, message: ${error.message}`); 1109 } 1110 1111 let uriList: Array<string> = []; 1112 fileCache.startBatch(uriList, cloudSync.DownloadFileType.CONTENT).then((downloadId: number) => { 1113 taskId = downloadId; 1114 console.info("start batch download successfully"); 1115 }).catch((err: BusinessError) => { 1116 console.error(`start batch download failed with error message: ${err.message}, error code: ${err.code}`); 1117 }); 1118 ``` 1119 1120### getSuccessfulFiles<sup>20+</sup> 1121 1122getSuccessfulFiles(): Array<string> 1123 1124获取批量缓存成功的文件列表。 1125 1126**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1127 1128**返回值：** 1129 1130| 类型 | 说明 | 1131| ------------------- | ------------------------------------- | 1132| Array<string> | 数组类型，返回缓存成功的文件URI列表。 | 1133 1134**错误码：** 1135 1136以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1137 1138| 错误码ID | 错误信息 | 1139| -------- | -------- | 1140| 22400005 | Inner error. Possible causes: 1.Failed to access the database or execute the SQL statement. 2.System error, such as a null pointer, insufficient memory or a JS engine exception. | 1141 1142**示例：** 1143 1144 ```ts 1145 import { BusinessError } from '@kit.BasicServicesKit'; 1146 1147 let finishedList: Array<string> = []; 1148 let fileCache = new cloudSync.CloudFileCache(); 1149 let callback = (data: cloudSync.MultiDownloadProgress) => { 1150 console.info(`Batch download progress: downloadedSize: ${data.downloadedSize}, totalSize: ${data.totalSize}`); 1151 if (data.state == cloudSync.State.COMPLETED) { 1152 console.info(`Batch download stopped, error type: ${data.errType}.`); 1153 finishedList = data.getSuccessfulFiles(); 1154 } 1155 }; 1156 1157 try { 1158 fileCache.on('batchDownload', callback); 1159 } catch (e) { 1160 const error = e as BusinessError; 1161 console.error(`Failed to register download callback, error code: ${error.code}, message: ${error.message}`); 1162 } 1163 1164 let uriList: Array<string> = []; 1165 fileCache.startBatch(uriList, cloudSync.DownloadFileType.CONTENT).then((downloadId: number) => { 1166 console.info(`start batch download successfully, taskId: ${downloadId}`); 1167 }).catch((err: BusinessError) => { 1168 console.error(`start batch download failed with error message: ${err.message}, error code: ${err.code}`); 1169 }); 1170 ``` 1171 1172## cloudSync.registerChange<sup>12+</sup> 1173 1174registerChange(uri: string, recursion: boolean, callback: Callback<ChangeData>): void 1175 1176订阅监听指定文件的变化通知。 1177 1178**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1179 1180**参数：** 1181 1182| 参数名 | 类型 | 必填 | 说明 | 1183| ---------- | ------ | ---- | ---- | 1184| uri | string | 是 | 待下载文件uri。 | 1185| recursion | boolean | 是 | true为监听该URI以及子文件和子目录，false为仅监听该URI文件。| 1186| callback | Callback<[ChangeData](#changedata12)> | 是 | 返回更改的数据。 | 1187 1188**错误码：** 1189 1190以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 1191 1192| 错误码ID | 错误信息 | 1193| ---------------------------- | ---------- | 1194| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 1195| 13900001 | Operation not permitted. | 1196| 13900002 | No such file or directory. | 1197| 13900012 | Permission denied. | 1198| 14000002 | Invalid URI. | 1199 1200**示例：** 1201 1202 ```ts 1203 import { fileUri } from '@kit.CoreFileKit'; 1204 let path = "/data/storage/el2/cloud/1.txt"; 1205 let uri = fileUri.getUriFromPath(path); 1206 let onCallback1 = (changeData: cloudSync.ChangeData) => { 1207 if (changeData.type == cloudSync.NotifyType.NOTIFY_ADDED) { 1208 //file had added, do something 1209 } else if (changeData.type== cloudSync.NotifyType.NOTIFY_DELETED) { 1210 //file had removed, do something 1211 } 1212 } 1213 cloudSync.registerChange(uri, false, onCallback1); 1214 // 取消注册监听 1215 cloudSync.unregisterChange(uri); 1216 ``` 1217 1218## cloudSync.unregisterChange<sup>12+</sup> 1219 1220unregisterChange(uri: string): void 1221 1222取消订阅监听指定文件的变化通知。 1223 1224**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1225 1226**参数：** 1227 1228| 参数名 | 类型 | 必填 | 说明 | 1229| ---------- | ------ | ---- | ---- | 1230| uri | string | 是 | 待下载文件uri。 | 1231 1232**错误码：** 1233 1234以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 1235 1236| 错误码ID | 错误信息 | 1237| ---------------------------- | ---------- | 1238| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 1239| 13900001 | Operation not permitted. | 1240| 13900002 | No such file or directory. | 1241| 13900012 | Permission denied. | 1242| 14000002 | Invalid URI. | 1243 1244**示例：** 1245 1246 ```ts 1247 import { fileUri } from '@kit.CoreFileKit'; 1248 let path = "/data/storage/el2/cloud/1.txt"; 1249 let uri = fileUri.getUriFromPath(path); 1250 let onCallback1 = (changeData: cloudSync.ChangeData) => { 1251 if (changeData.type == cloudSync.NotifyType.NOTIFY_ADDED) { 1252 //file had added, do something 1253 } else if (changeData.type== cloudSync.NotifyType.NOTIFY_DELETED) { 1254 //file had removed, do something 1255 } 1256 } 1257 cloudSync.registerChange(uri, false, onCallback1); 1258 // 取消注册监听 1259 cloudSync.unregisterChange(uri); 1260 ``` 1261 1262## NotifyType<sup>12+</sup> 1263 1264数据变更通知类型。 1265 1266**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1267 1268| 名称 | 值| 说明 | 1269| ----- | ---- | ---- | 1270| NOTIFY_ADDED | 0 | 文件已新建。 | 1271| NOTIFY_MODIFIED | 1 | 文件已修改。 | 1272| NOTIFY_DELETED | 2 | 文件已被删除。 | 1273| NOTIFY_RENAMED | 3 | 文件被重命名或者移动。 | 1274 1275## ChangeData<sup>12+</sup> 1276 1277定义变更数据。 1278 1279**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1280 1281| 名称 | 类型 | 必填 | 说明 | 1282| ---------- | ------ | ---- | ---- | 1283| type | [NotifyType](#notifytype12) | 是 | 更改的通知类型。| 1284| isDirectory | Array<boolean> | 是 | 指示更改的URI是否为目录。true：是目录。false：非目录。| 1285| uris | Array<string> | 是 | 需要更改的URI列表。| 1286 1287 1288## HistoryVersion<sup>20+</sup> 1289 1290端云文件历史版本信息，调用端云文件版本管理类[FileVersion](#fileversion20)的[gethistoryversionlist](#gethistoryversionlist20)方法时，历史版本列表中的属性。 1291 1292### 属性 1293 1294**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1295 1296| 名称 | 类型 | 只读 | 可选 | 说明 | 1297| ---------- | ------ | ---- | ---- | ---- | 1298| editedTime | number | 否 | 否 | 文件内容修改时间。 | 1299| fileSize | number | 否 | 否 | 文件大小，单位：Byte。 | 1300| versionId | string | 否 | 否 | 文件版本号。 | 1301| originalFileName | string | 否 | 否 | 当前版本对应的文件名。 | 1302| sha256 | string | 否 | 否 | 当前版本对应文件内容的哈希值。 | 1303| autoResolved | boolean | 否 | 否 | 当前版本是否为自动解决冲突的版本。<br>应用设置手动解冲突时，默认返回false，无意义。<br>应用设置自动解冲突时，端侧会自动解冲突，true表示当前版本存在冲突，端云服务已自动解决冲突，false表示无冲突，未自动解冲突。 | 1304 1305**补充说明**：当本地和他端同时修改文件产生冲突时，当前端云同步有自动解冲突机制，但有些应用希望由用户手动解决冲突，此时应用可以通过在项目工程的/entry/src/main/resources/base/profile目录下增加cloudkit_config.json文件，并配置manualConflictResolutionEnable为true，表示手动解决冲突使能；若应用不需要手动解决冲突，可以不配置该文件或者配置manualConflictResolutionEnable为false，表示采用已有的自动解冲突策略。 1306 1307配置文件cloudkit_config.json样例： 1308 1309 ```json 1310 { 1311 "cloudKitConfig": { 1312 "cloudFileSyncConfig": { 1313 "manualConflictResolutionEnable": "true" 1314 } 1315 } 1316 } 1317 ``` 1318 1319## VersionDownloadProgress<sup>20+</sup> 1320 1321历史版本文件下载状态和进度信息，调用端云文件版本管理类[FileVersion](#fileversion20)的[downloadHistoryVersion](#downloadhistoryversion20)方法时，回调函数的入参类型。 1322 1323### 属性 1324 1325**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1326 1327| 名称 | 类型 | 只读 | 可选 | 说明 | 1328| ---------- | ------ | ---- | ---- | ---- | 1329| state | [State](#state11) | 否 | 否 | 所选版本云文件的下载状态。 | 1330| progress | number | 否 | 否 | 下载进度。 | 1331| errType | [DownloadErrorType](#downloaderrortype11) | 否 | 否 | 若出现下载失败，失败的错误类型。 | 1332 1333## FileVersion<sup>20+</sup> 1334 1335端云文件版本管理类。支持对端云文件的历史版本进行管理，提供获取文件历史版本信息列表的能力，通过历史版本信息，可将历史版本下载到本地；并提供历史版本文件替换当前本地文件的能力，针对版本冲突，提供查询冲突标志，解除冲突标志的能力。 1336 1337### construct<sup>20+</sup> 1338 1339constructor() 1340 1341端云文件版本管理的构造函数，用于获取FileVersion类的实例。 1342 1343**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1344 1345**错误码：** 1346 1347以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1348 1349| 错误码ID | 错误信息 | 1350| ---------------------------- | ---------- | 1351| 22400005 | Inner error. Possible causes: 1.Failed to access the database or execute the SQL statement. 2.System error, such as a null pointer, insufficient memory or a JS engine exception. | 1352 1353**示例：** 1354 1355 ```ts 1356 let fileVersion = new cloudSync.FileVersion(); 1357 ``` 1358 1359### getHistoryVersionList<sup>20+</sup> 1360 1361getHistoryVersionList(uri: string, versionNumLimit: number): Promise<Array<HistoryVersion>> 1362 1363获取历史版本列表，返回内容按修改时间排序，修改时间越早，位置越靠后。使用Promise异步回调。 1364 1365当云上版本数量小于传入的长度限制时，按照实际版本数量返回历史版本列表。 1366 1367当云上版本数量大于等于传入的长度限制时，则返回最新的versionNumLimit个版本。 1368 1369**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1370 1371**参数：** 1372 1373| 参数名 | 类型 | 必填 | 说明 | 1374| ---------- | ------ | ---- | ---- | 1375| uri | string | 是 | 文件的URI。 | 1376| versionNumLimit | number | 是 | 历史版本列表长度限制，取值范围[0, 100000]（单位：个）。当输入值大于100000时，按照最大值返回列表。 | 1377 1378**返回值：** 1379 1380| 类型 | 说明 | 1381| ------ | ---- | 1382| Promise<Array<[HistoryVersion](#historyversion20)>> | Promise对象，返回历史版本列表。 | 1383 1384**错误码：** 1385 1386以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1387 1388| 错误码ID | 错误信息 | 1389| ---------------------------- | ---------- | 1390| 13600001 | IPC error. Possible causes: 1.IPC failed or timed out. 2.Failed to load the service. | 1391| 13900002 | No such file or directory. | 1392| 13900010 | Try again. | 1393| 13900012 | Permission denied by the file system. | 1394| 13900020 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1395| 14000002 | Invalid URI. | 1396| 22400002 | Network unavailable. | 1397| 22400005 | Inner error. Possible causes: 1.Failed to access the database or execute the SQL statement. 2.System error, such as a null pointer, insufficient memory or a JS engine exception. | 1398 1399**示例：** 1400 1401 ```ts 1402 import { fileUri } from '@kit.CoreFileKit'; 1403 import { BusinessError } from '@kit.BasicServicesKit'; 1404 1405 let fileVersion = new cloudSync.FileVersion(); 1406 1407 let path = "/data/storage/el2/cloud/1.txt"; 1408 let uri = fileUri.getUriFromPath(path); 1409 let limit = 10; 1410 1411 fileVersion.getHistoryVersionList(uri, limit).then((versionList: Array<cloudSync.HistoryVersion>) => { 1412 for(let i = 0, len = versionList.length; i < len; i++) { 1413 console.info("get history versionId: " + versionList[i].versionId); 1414 } 1415 }).catch((err: BusinessError) => { 1416 console.error("get history version failed with error message: " + err.message + ", error code: " + err.code); 1417 }); 1418 ``` 1419 1420### downloadHistoryVersion<sup>20+</sup> 1421 1422downloadHistoryVersion(uri: string, versionId: string, callback: Callback<[VersionDownloadProgress](#versiondownloadprogress20)>): Promise<string> 1423 1424根据版本号获取指定文件的某一版本的文件内容。用户通过版本号指定云上某一版本，将其下载到本地临时存储路径，临时文件由应用自行决定是否替换原始文件，也可以选择保留或直接删除。使用Promise异步回调。 1425 1426**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1427 1428**参数：** 1429 1430| 参数名 | 类型 | 必填 | 说明 | 1431| ---------- | ------ | ---- | ---- | 1432| uri | string | 是 | 文件的URI。 | 1433| versionId | string | 是 | 文件某一版本的版本号，格式以接口[gethistoryversionlist](#gethistoryversionlist20)返回为准。 | 1434| callback | Callback<[VersionDownloadProgress](#versiondownloadprogress20)> | 是 | 下载进度的回调。 | 1435 1436**返回值：** 1437 1438| 类型 | 说明 | 1439| ------ | ---- | 1440| Promise<string> | Promise对象，返回历史版本临时存储文件的URI。 | 1441 1442**错误码：** 1443 1444以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1445 1446| 错误码ID | 错误信息 | 1447| ---------------------------- | ---------- | 1448| 13600001 | IPC error. Possible causes: 1.IPC failed or timed out. 2.Failed to load the service. | 1449| 13900002 | No such file or directory. | 1450| 13900010 | Try again. | 1451| 13900012 | Permission denied by the file system. | 1452| 13900020 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1453| 14000002 | Invalid URI. | 1454| 22400002 | Network unavailable. | 1455| 22400005 | Inner error. Possible causes: 1.Failed to access the database or execute the SQL statement. 2.System error, such as a null pointer, insufficient memory or a JS engine exception. | 1456 1457**示例：** 1458 1459 ```ts 1460 import { fileUri } from '@kit.CoreFileKit'; 1461 import { BusinessError } from '@kit.BasicServicesKit'; 1462 1463 let fileVersion = new cloudSync.FileVersion(); 1464 1465 let path = "/data/storage/el2/cloud/1.txt"; 1466 let uri = fileUri.getUriFromPath(path); 1467 let versionId = '123456'; // 以 getHistoryVersionList 方法返回的格式为准，此处仅作为 demo 示例。 1468 1469 let callback = (data: cloudSync.VersionDownloadProgress) => { 1470 if (data.state == cloudSync.State.RUNNING) { 1471 console.info("download progress: " + data.progress); 1472 } else if (data.state == cloudSync.State.FAILED) { 1473 console.info("download failed errType: " + data.errType); 1474 } else if (data.state == cloudSync.State.COMPLETED) { 1475 console.info("download version file success"); 1476 } 1477 }; 1478 1479 fileVersion.downloadHistoryVersion(uri, versionId, callback).then((fileUri: string) => { 1480 console.info("success to begin download, downloadFileUri: " + fileUri); 1481 }).catch((err: BusinessError) => { 1482 console.error("download history version file failed with error message: " + err.message + ", error code: " + err.code); 1483 }); 1484 ``` 1485 1486### replaceFileWithHistoryVersion<sup>20+</sup> 1487 1488replaceFileWithHistoryVersion(originalUri: string, versionUri: string): Promise<void> 1489 1490提供使用历史版本文件替换本地文件的能力。在替换前，需要调用[downloadHistoryVersion](#downloadhistoryversion20)方法对选择的历史版本进行下载并拿到versionUri；直接调用此接口或者versionUri非法会产生异常；替换完成后会删除临时存储文件。使用Promise异步回调。 1491 1492**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1493 1494**参数：** 1495 1496| 参数名 | 类型 | 必填 | 说明 | 1497| ---------- | ------ | ---- | ---- | 1498| originalUri | string | 是 | 本地文件的URI。 | 1499| versionUri | string | 是 | 历史版本文件的URI。 | 1500 1501**返回值：** 1502 1503| 类型 | 说明 | 1504| ------ | ---- | 1505| Promise<void> | Promise对象，无返回结果。 | 1506 1507**错误码：** 1508 1509以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1510 1511| 错误码ID | 错误信息 | 1512| ---------------------------- | ---------- | 1513| 13600001 | IPC error. Possible causes: 1.IPC failed or timed out. 2.Failed to load the service. | 1514| 13900002 | No such file or directory. | 1515| 13900005 | I/O error. | 1516| 13900008 | Bad file descriptor. | 1517| 13900010 | Try again. | 1518| 13900012 | Permission denied by the file system. | 1519| 13900020 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1520| 14000002 | Invalid URI. | 1521| 22400005 | Inner error. Possible causes: 1.Failed to access the database or execute the SQL statement. 2.System error, such as a null pointer, insufficient memory or a JS engine exception. | 1522| 22400007 | Version file not exist. | 1523 1524**示例：** 1525 1526 ```ts 1527 import { fileUri } from '@kit.CoreFileKit'; 1528 import { BusinessError } from '@kit.BasicServicesKit'; 1529 1530 let fileVersion = new cloudSync.FileVersion(); 1531 1532 let path = "/data/storage/el2/cloud/1.txt"; 1533 let uri = fileUri.getUriFromPath(path); 1534 let versionId = '123456'; // 以 getHistoryVersionList 方法返回的格式为准，此处仅作为 demo 示例。 1535 1536 let callback = (data: cloudSync.VersionDownloadProgress) => { 1537 if (data.state == cloudSync.State.RUNNING) { 1538 console.info("download progress: " + data.progress); 1539 } else if (data.state == cloudSync.State.FAILED) { 1540 console.info("download failed errType: " + data.errType); 1541 } else if (data.state == cloudSync.State.COMPLETED) { 1542 console.info("download version file success"); 1543 } 1544 }; 1545 1546 let versionUri = ""; 1547 fileVersion.downloadHistoryVersion(uri, versionId, callback).then((fileUri: string) => { 1548 versionUri = fileUri; 1549 console.info("success to begin download, downloadFileUri: " + fileUri); 1550 }).catch((err: BusinessError) => { 1551 console.error(`download history version file failed with error message: ${err.message}, error code: ${err.code}`); 1552 }); 1553 fileVersion.replaceFileWithHistoryVersion(uri, versionUri).then(() => { 1554 console.info("replace file with history version success."); 1555 }).catch((err: BusinessError) => { 1556 console.error("replace file with history version filed with error message: " + err.message + ", error code: " + err.code); 1557 }); 1558 ``` 1559 1560### isFileConflict<sup>20+</sup> 1561 1562isFileConflict(uri: string): Promise<boolean> 1563 1564获取本地文件版本冲突标志。使用Promise异步回调。此方法只有应用在配置手动解冲突后才会生效，否则默认自动解冲突，返回值为false，由同步流程自动完成解冲突； 1565 1566当应用配置手动解冲突后，调用此方法会返回当前文件是否与云侧文件产生冲突，并且由应用提示用户对冲突进行处理，在冲突解决前不会再自动同步上云。当处理完冲突后，需要调用[clearfileconflict](#clearfileconflict20)方法来清除冲突标志，后续才会继续触发同步，与云端保持一致。 1567 1568**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1569 1570**参数：** 1571 1572| 参数名 | 类型 | 必填 | 说明 | 1573| ---------- | ------ | ---- | ---- | 1574| uri | string | 是 | 文件的URI。 | 1575 1576**返回值：** 1577 1578| 类型 | 说明 | 1579| ------ | ---- | 1580| Promise<boolean> | Promise对象，返回本地文件和云端文件的冲突标志，true表示冲突，false表示不冲突。 | 1581 1582**错误码：** 1583 1584以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1585 1586| 错误码ID | 错误信息 | 1587| ---------------------------- | ---------- | 1588| 13600001 | IPC error. Possible causes: 1.IPC failed or timed out. 2.Failed to load the service. | 1589| 13900002 | No such file or directory. | 1590| 13900010 | Try again. | 1591| 13900012 | Permission denied by the file system. | 1592| 13900020 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1593| 14000002 | Invalid URI. | 1594| 22400005 | Inner error. Possible causes: 1.Failed to access the database or execute the SQL statement. 2.System error, such as a null pointer, insufficient memory or a JS engine exception. | 1595 1596**示例：** 1597 1598 ```ts 1599 import { fileUri } from '@kit.CoreFileKit'; 1600 import { BusinessError } from '@kit.BasicServicesKit'; 1601 1602 let fileVersion = new cloudSync.FileVersion(); 1603 1604 let path = "/data/storage/el2/cloud/1.txt"; 1605 let uri = fileUri.getUriFromPath(path); 1606 1607 fileVersion.isFileConflict(uri).then((isConflict: boolean) => { 1608 console.info("current file is conflict: " + isConflict); 1609 }).catch((err: BusinessError) => { 1610 console.error("get current file conflict flag failed with error message: " + err.message + ", error code: " + err.code); 1611 }); 1612 ``` 1613 1614### clearFileConflict<sup>20+</sup> 1615 1616clearFileConflict(uri: string): Promise<void> 1617 1618清除本地文件版本冲突标志。如果产生冲突，本地解决冲突后需要调用此方法来清除冲突标记，后续才可以触发自动同步机制，和云上保持一致。使用Promise异步回调。 1619 1620**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1621 1622**参数：** 1623 1624| 参数名 | 类型 | 必填 | 说明 | 1625| ---------- | ------ | ---- | ---- | 1626| uri | string | 是 | 待清除冲突标志的文件URI。 | 1627 1628**返回值：** 1629 1630| 类型 | 说明 | 1631| ------ | ---- | 1632| Promise<void> | Promise对象，无返回结果。 | 1633 1634**错误码：** 1635 1636以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1637 1638| 错误码ID | 错误信息 | 1639| ---------------------------- | ---------- | 1640| 13600001 | IPC error. Possible causes: 1.IPC failed or timed out. 2.Failed to load the service. | 1641| 13900002 | No such file or directory. | 1642| 13900010 | Try again. | 1643| 13900012 | Permission denied by the file system. | 1644| 13900020 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1645| 14000002 | Invalid URI. | 1646| 22400005 | Inner error. Possible causes: 1.Failed to access the database or execute the SQL statement. 2.System error, such as a null pointer, insufficient memory or a JS engine exception. | 1647 1648**示例：** 1649 1650 ```ts 1651 import { fileUri } from '@kit.CoreFileKit'; 1652 import { BusinessError } from '@kit.BasicServicesKit'; 1653 1654 let fileVersion = new cloudSync.FileVersion(); 1655 1656 let path = "/data/storage/el2/cloud/1.txt"; 1657 let uri = fileUri.getUriFromPath(path); 1658 1659 let isConflict = false; 1660 fileVersion.isFileConflict(uri).then((isConflictRet: boolean) => { 1661 isConflict = isConflictRet; 1662 console.info("current file is conflict: " + isConflictRet); 1663 }).catch((err: BusinessError) => { 1664 console.error(`get current file conflict flag failed with error message: ${err.message}, error code: ${err.code}`); 1665 }); 1666 fileVersion.clearFileConflict(uri).then(() => { 1667 console.info("clean file conflict flag success"); 1668 }).catch((err: BusinessError) => { 1669 console.error("clean file conflict flag failed with error message: " + err.message + ", error code: " + err.code); 1670 }); 1671 ``` 1672 1673## cloudSync.getCoreFileSyncState<sup>20+</sup> 1674 1675getCoreFileSyncState(uri: string): FileState 1676 1677同步方法获取云盘文件同步上行状态。 1678 1679**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1680 1681**参数：** 1682 1683| 参数名 | 类型 | 必填 | 说明 | 1684| ---------- | ------ | ---- | ---- | 1685| uri | string | 是 | 待获取云盘文件同步上行状态的文件URI。 | 1686 1687**返回值：** 1688 1689| 类型 | 说明 | 1690| --------------------- | ---------------- | 1691| [FileState](#filestate20) | 返回给定云盘文件的同步上行状态。 | 1692 1693**错误码：** 1694 1695以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 1696 1697| 错误码ID | 错误信息 | 1698| ---------------------------- | ---------- | 1699| 13600001 | IPC error. Possible causes:1.IPC failed or timed out. 2.Failed to load the service. | 1700| 13900002 | No such file or directory. | 1701| 13900004 | Interrupted system call. | 1702| 13900010 | Try again. | 1703| 13900012 | Permission denied by the file system. | 1704| 13900020 | Parameter error. Possible causes:1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1705| 13900031 | Function not implemented. | 1706| 14000002 | Invalid URI. | 1707| 22400005 | Inner error. Possible causes:1.Failed to access the database or execute the SQL statement. | 1708 1709**示例：** 1710 1711 ```ts 1712 import { BusinessError } from '@kit.BasicServicesKit'; 1713 import { fileUri } from '@kit.CoreFileKit'; 1714 1715 let path = "/data/storage/el2/cloud/1.txt"; 1716 let uri = fileUri.getUriFromPath(path); 1717 try { 1718 let state = cloudSync.getCoreFileSyncState(uri); 1719 } catch (err) { 1720 let error:BusinessError = err as BusinessError; 1721 console.error(`getCoreFileSyncState failed with error ${error.code}, message is ${error.message}`); 1722 } 1723 ``` 1724 1725## FileState<sup>20+</sup> 1726 1727端云文件同步状态，为枚举类型。 1728 1729**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1730 1731| 名称 | 值| 说明 | 1732| ----- | ---- | ---- | 1733| INITIAL_AFTER_DOWNLOAD | 0 | 首次下行后的初始状态。 | 1734| UPLOADING | 1 | 上行同步中。 | 1735| STOPPED | 2 | 上行已停止。 | 1736| TO_BE_UPLOADED | 3 | 正在等待上行。 | 1737| UPLOAD_SUCCESS | 4 | 文件已成功上行。 | 1738| UPLOAD_FAILURE | 5 | 文件上行失败。 |