1# @ohos.file.cloudSyncManager (Device-Cloud Sync Management) (System API) 2 3The **cloudSyncManager** module provides APIs for managing device-cloud synergy for applications. You can use the APIs to enable or disable device-cloud synergy, change the device-cloud sync switch for an application, notify cloud data changes, and clear or retain cloud files when a cloud account exits. 4 5> **NOTE** 6> 7> - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> - The APIs provided by this module are system APIs. 9 10## Modules to Import 11 12```ts 13import { cloudSyncManager } from '@kit.CoreFileKit'; 14``` 15 16## cloudSyncManager.changeAppCloudSwitch 17 18changeAppCloudSwitch(accountId: string, bundleName: string, status: boolean): Promise<void> 19 20Changes the device-cloud file sync switch for an application. This API uses a promise to return the result. 21 22**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSyncManager 23 24**Parameters** 25 26| Name | Type | Mandatory| Description| 27| ---------- | ------ | ---- | ---- | 28| accountId | string | Yes | Account ID.| 29| bundleName | string | Yes | Bundle name of the application.| 30| status | boolean | Yes | State of the cloud-device file sync switch to set. The value **true** means to enable this function; the value **false** means the opposite.| 31 32**Return value** 33 34| Type | Description | 35| --------------------- | ---------------- | 36| Promise<void> | Promise used to return the result.| 37 38**Error codes** 39 40For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 41 42| ID | Error Message | 43| ---------------------------- | ---------- | 44| 201 | Permission verification failed. | 45| 202 | The caller is not a system application. | 46| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 47 48**Example** 49 50 ```ts 51 import { BusinessError } from '@kit.BasicServicesKit'; 52 let accountId: string = "testAccount"; 53 let bundleName: string = "com.example.bundle"; 54 cloudSyncManager.changeAppCloudSwitch(accountId, bundleName, true).then(() => { 55 console.info("changeAppCloudSwitch successfully"); 56 }).catch((err: BusinessError) => { 57 console.error("changeAppCloudSwitch failed with error message: " + err.message + ", error code: " + err.code); 58 }); 59 ``` 60 61## cloudSyncManager.changeAppCloudSwitch 62 63changeAppCloudSwitch(accountId: string, bundleName: string, status: boolean, callback: AsyncCallback<void>): void 64 65Changes the device-cloud file sync switch for an application. This API uses an asynchronous callback to return the result. 66 67**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSyncManager 68 69**Parameters** 70 71| Name | Type | Mandatory| Description| 72| ---------- | ------ | ---- | ---- | 73| accountId | string | Yes | Account ID.| 74| bundleName | string | Yes | Bundle name of the application.| 75| status | boolean | Yes | State of the cloud-device file sync switch to set. The value **true** means to enable this function; the value **false** means the opposite.| 76| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 77 78**Error codes** 79 80For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 81 82| ID | Error Message | 83| ---------------------------- | ---------- | 84| 201 | Permission verification failed. | 85| 202 | The caller is not a system application. | 86| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 87 88**Example** 89 90 ```ts 91 import { BusinessError } from '@kit.BasicServicesKit'; 92 let accountId: string = "testAccount"; 93 let bundleName: string = "com.example.bundle"; 94 cloudSyncManager.changeAppCloudSwitch(accountId, bundleName, true, (err: BusinessError) => { 95 if (err) { 96 console.error("changeAppCloudSwitch failed with error message: " + err.message + ", error code: " + err.code); 97 } else { 98 console.info("changeAppCloudSwitch successfully"); 99 } 100 }); 101 ``` 102 103## cloudSyncManager.notifyDataChange 104 105notifyDataChange(accountId: string, bundleName: string): Promise<void> 106 107Notifies the cloud sync service of the application data change in the cloud. This API uses a promise to return the result. 108 109**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSyncManager 110 111**Parameters** 112 113| Name | Type | Mandatory| Description| 114| ---------- | ------ | ---- | ---- | 115| accountId | string | Yes | Account ID.| 116| bundleName | string | Yes | Bundle name of the application.| 117 118**Return value** 119 120| Type | Description | 121| --------------------- | ---------------- | 122| Promise<void> | Promise used to return the application data change in the cloud.| 123 124**Error codes** 125 126For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 127 128| ID | Error Message | 129| ---------------------------- | ---------- | 130| 201 | Permission verification failed. | 131| 202 | The caller is not a system application. | 132| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 133 134**Example** 135 136 ```ts 137 import { BusinessError } from '@kit.BasicServicesKit'; 138 let accountId: string = "testAccount"; 139 let bundleName: string = "com.example.bundle"; 140 cloudSyncManager.notifyDataChange(accountId, bundleName).then(() => { 141 console.info("notifyDataChange successfully"); 142 }).catch((err: BusinessError) => { 143 console.error("notifyDataChange failed with error message: " + err.message + ", error code: " + err.code); 144 }); 145 ``` 146 147## cloudSyncManager.notifyDataChange 148 149notifyDataChange(accountId: string, bundleName: string, callback: AsyncCallback<void>): void 150 151Notifies the cloud sync service of the application data change in the cloud. This API uses a promise to return the result. 152 153**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSyncManager 154 155**Parameters** 156 157| Name | Type | Mandatory| Description| 158| ---------- | ------ | ---- | ---- | 159| accountId | string | Yes | Account ID.| 160| bundleName | string | Yes | Bundle name of the application.| 161| callback | AsyncCallback<void> | Yes | Callback used to return the application data change in the cloud.| 162 163**Error codes** 164 165For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 166 167| ID | Error Message | 168| ---------------------------- | ---------- | 169| 201 | Permission verification failed. | 170| 202 | The caller is not a system application. | 171| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 172 173**Example** 174 175 ```ts 176 import { BusinessError } from '@kit.BasicServicesKit'; 177 let accountId: string = "testAccount"; 178 let bundleName: string = "com.example.bundle"; 179 cloudSyncManager.notifyDataChange(accountId, bundleName, (err: BusinessError) => { 180 if (err) { 181 console.error("notifyDataChange failed with error message: " + err.message + ", error code: " + err.code); 182 } else { 183 console.info("notifyDataChange successfully"); 184 } 185 }); 186 ``` 187 188## ExtraData<sup>11+</sup> 189 190Represents the cloud data change information. 191 192**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSyncManager 193 194| Name | Type | Mandatory| Description| 195| ---------- | ------ | ---- | ---- | 196| eventId | string | Yes | Change event ID.| 197| extraData | ExtraData | Yes | Change of the cloud data.| 198 199## cloudSyncManager.notifyDataChange<sup>11+</sup> 200 201notifyDataChange(userId: number, extraData: ExtraData): Promise<void> 202 203Notifies the cloud sync service of the application data change in the cloud. This API uses a promise to return the result. 204 205**Required permissions**: ohos.permission.CLOUDFILE_SYNC_MANAGER 206 207**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSyncManager 208 209**Parameters** 210 211| Name | Type | Mandatory| Description| 212| ---------- | ------ | ---- | ---- | 213| userId | number | Yes | User ID.| 214| extraData | ExtraData | Yes | Change of the cloud data.| 215 216**Return value** 217 218| Type | Description | 219| --------------------- | ---------------- | 220| Promise<void> | Promise used to return the application data change in the cloud.| 221 222**Error codes** 223 224For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 225 226| ID | Error Message | 227| ---------------------------- | ---------- | 228| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 229| 202 | Permission verification failed, application which is not a system application uses system API. | 230| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 231| 13600001 | IPC error. | 232 233**Example** 234 235 ```ts 236 import { BusinessError } from '@kit.BasicServicesKit'; 237 let userId: number = 100; 238 let extraData: cloudSyncManager.ExtraData = {eventId: "eventId", extraData: "data"}; 239 cloudSyncManager.notifyDataChange(userId, extraData).then(() => { 240 console.info("notifyDataChange successfully"); 241 }).catch((err: BusinessError) => { 242 console.error("notifyDataChange failed with error message: " + err.message + ", error code: " + err.code); 243 }); 244 ``` 245 246## cloudSyncManager.notifyDataChange<sup>11+</sup> 247 248notifyDataChange(userId: number, extraData: ExtraData, callback: AsyncCallback<void>): void 249 250Notifies the cloud sync service of the application data change in the cloud. This API uses an asynchronous callback to return the result. 251 252**Required permissions**: ohos.permission.CLOUDFILE_SYNC_MANAGER 253 254**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSyncManager 255 256**Parameters** 257 258| Name | Type | Mandatory| Description| 259| ---------- | ------ | ---- | ---- | 260| userId | number | Yes | User ID.| 261| extraData | ExtraData | Yes | Change of the cloud data.| 262| callback | AsyncCallback<void> | Yes | Callback used to return the application data change in the cloud.| 263 264**Error codes** 265 266For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 267 268| ID | Error Message | 269| ---------------------------- | ---------- | 270| 201 | Permission verification failed. | 271| 202 | The caller is not a system application. | 272| 401 | The input parameter is invalid. | 273| 13600001 | IPC error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 274 275**Example** 276 277 ```ts 278 import { BusinessError } from '@kit.BasicServicesKit'; 279 let userId: number = 100; 280 let extraData: cloudSyncManager.ExtraData = {eventId: "eventId", extraData: "data"}; 281 cloudSyncManager.notifyDataChange(userId, extraData, (err: BusinessError) => { 282 if (err) { 283 console.error("notifyDataChange failed with error message: " + err.message + ", error code: " + err.code); 284 } else { 285 console.info("notifyDataChange successfully"); 286 } 287 }); 288 ``` 289 290## cloudSyncManager.enableCloud 291 292enableCloud(accountId: string, switches: Record<string, boolean>): Promise<void> 293 294Enables device-cloud synergy. This API uses a promise to return the result. 295 296**Required permissions**: ohos.permission.CLOUDFILE_SYNC_MANAGER 297 298**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSyncManager 299 300**Parameters** 301 302| Name | Type | Mandatory| Description| 303| ---------- | ------ | ---- | ---- | 304| accountId | string | Yes | Account ID.| 305| switches | object | Yes | Whether to enable the device-cloud synergy feature. **bundleName** is a string indicating the application bundle name. The switch status is a Boolean value.| 306 307**Return value** 308 309| Type | Description | 310| --------------------- | ---------------- | 311| Promise<void> | Promise used to return the result.| 312 313**Error codes** 314 315For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 316 317| ID | Error Message | 318| ---------------------------- | ---------- | 319| 201 | Permission verification failed. | 320| 202 | The caller is not a system application. | 321| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 322 323**Example** 324 325 ```ts 326 import { BusinessError } from '@kit.BasicServicesKit'; 327 let accountId: string = "testAccount"; 328 let switches: Record<string, boolean> = { 329 'com.example.bundleName1': true, 330 'com.example.bundleName2': false 331 } 332 cloudSyncManager.enableCloud(accountId, switches).then(() => { 333 console.error("enableCloud successfully"); 334 }).catch((err: BusinessError) => { 335 console.info("enableCloud failed with error message: " + err.message + ", error code: " + err.code); 336 }); 337 ``` 338 339## cloudSyncManager.enableCloud 340 341enableCloud(accountId: string, switches: Record<string, boolean>, callback: AsyncCallback<void>): void 342 343Enables device-cloud synergy. This API uses an asynchronous callback to return the result. 344 345**Required permissions**: ohos.permission.CLOUDFILE_SYNC_MANAGER 346 347**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSyncManager 348 349**Parameters** 350 351| Name | Type | Mandatory| Description| 352| ---------- | ------ | ---- | ---- | 353| accountId | string | Yes | Account ID.| 354| switches | object | Yes | Whether to enable the device-cloud synergy feature. **bundleName** is a string indicating the application bundle name. The switch status is a Boolean value.| 355| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 356 357**Error codes** 358 359For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 360 361| ID | Error Message | 362| ---------------------------- | ---------- | 363| 201 | Permission verification failed. | 364| 202 | The caller is not a system application. | 365| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 366 367**Example** 368 369 ```ts 370 import { BusinessError } from '@kit.BasicServicesKit'; 371 let accountId: string = "testAccount"; 372 let switches: Record<string, boolean> = { 373 'com.example.bundleName1': true, 374 'com.example.bundleName2': false 375 } 376 cloudSyncManager.enableCloud(accountId, switches, (err: BusinessError) => { 377 if (err) { 378 console.error("enableCloud failed with error message: " + err.message + ", error code: " + err.code); 379 } else { 380 console.info("enableCloud successfully"); 381 } 382 }); 383 ``` 384 385## cloudSyncManager.disableCloud 386 387disableCloud(accountId: string): Promise<void> 388 389Disables device-cloud synergy. This API uses a promise to return the result. 390 391**Required permissions**: ohos.permission.CLOUDFILE_SYNC_MANAGER 392 393**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSyncManager 394 395**Parameters** 396 397| Name | Type | Mandatory| Description| 398| ---------- | ------ | ---- | ---- | 399| accountId | string | Yes | Account ID.| 400 401**Return value** 402 403| Type | Description | 404| --------------------- | ---------------- | 405| Promise<void> | Promise used to return the result.| 406 407**Error codes** 408 409For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 410 411| ID | Error Message | 412| ---------------------------- | ---------- | 413| 201 | Permission verification failed. | 414| 202 | The caller is not a system application. | 415| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 416 417**Example** 418 419 ```ts 420 import { BusinessError } from '@kit.BasicServicesKit'; 421 let accountId: string = "testAccount"; 422 cloudSyncManager.disableCloud(accountId).then(() => { 423 console.info("disableCloud successfully"); 424 }).catch((err: BusinessError) => { 425 console.error("disableCloud failed with error message: " + err.message + ", error code: " + err.code); 426 }); 427 ``` 428 429## cloudSyncManager.disableCloud 430 431disableCloud(accountId: string, callback: AsyncCallback<void>): void 432 433Disables device-cloud synergy. This API uses an asynchronous callback to return the result. 434 435**Required permissions**: ohos.permission.CLOUDFILE_SYNC_MANAGER 436 437**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSyncManager 438 439**Parameters** 440 441| Name | Type | Mandatory| Description| 442| ---------- | ------ | ---- | ---- | 443| accountId | string | Yes | Account ID.| 444| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 445 446**Error codes** 447 448For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 449 450| ID | Error Message | 451| ---------------------------- | ---------- | 452| 201 | Permission verification failed. | 453| 202 | The caller is not a system application. | 454| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 455 456**Example** 457 458 ```ts 459 import { BusinessError } from '@kit.BasicServicesKit'; 460 let accountId: string = "testAccount"; 461 cloudSyncManager.disableCloud(accountId, (err: BusinessError) => { 462 if (err) { 463 console.error("disableCloud failed with error message: " + err.message + ", error code: " + err.code); 464 } else { 465 console.info("disableCloud successfully"); 466 } 467 }); 468 ``` 469 470## Action 471 472Enumerates the actions that can be taken to clear local cloud data. 473 474**Required permissions**: ohos.permission.CLOUDFILE_SYNC_MANAGER 475 476**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSyncManager 477 478| Name| Value| Description| 479| ----- | ---- | ---- | 480| RETAIN_DATA | 0 | Clear the cloud identifier but retain the files cached locally.| 481| CLEAR_DATA | 1 | Clear the cloud identifier and the files cached locally.| 482 483## cloudSyncManager.clean 484 485clean(accountId: string, appActions: Record<string, Action>): Promise<void> 486 487Clears the cloud data locally. This API uses a promise to return the result. 488 489**Required permissions**: ohos.permission.CLOUDFILE_SYNC_MANAGER 490 491**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSyncManager 492 493**Parameters** 494 495| Name | Type | Mandatory| Description| 496| ---------- | ------ | ---- | ---- | 497| accountId | string | Yes | Account ID.| 498| appActions | object | Yes | Action to perform. **bundleName** is a string indicating the application whose data is to be cleared.[Action](#action) specifies the action to perform.| 499 500**Return value** 501 502| Type | Description | 503| --------------------- | ---------------- | 504| Promise<void> | Promise used to return the result.| 505 506**Error codes** 507 508For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 509 510| ID | Error Message | 511| ---------------------------- | ---------- | 512| 201 | Permission verification failed. | 513| 202 | The caller is not a system application. | 514| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 515 516**Example** 517 518 ```ts 519 import { BusinessError } from '@kit.BasicServicesKit'; 520 let accountId: string = "testAccount"; 521 let appActions: Record<string, cloudSyncManager.Action> = { 522 'com.example.bundleName1': cloudSyncManager.Action.RETAIN_DATA, 523 'com.example.bundleName2': cloudSyncManager.Action.CLEAR_DATA 524 }; 525 cloudSyncManager.clean(accountId, appActions).then(() => { 526 console.info("clean successfully"); 527 }).catch((err: BusinessError) => { 528 console.error("clean failed with error message: " + err.message + ", error code: " + err.code); 529 }); 530 ``` 531 532## cloudSyncManager.clean 533 534clean(accountId: string, appActions: Record<string, Action>, callback: AsyncCallback<void>): void 535 536Clears the cloud data locally. This API uses an asynchronous callback to return the result. 537 538**Required permissions**: ohos.permission.CLOUDFILE_SYNC_MANAGER 539 540**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSyncManager 541 542**Parameters** 543 544| Name | Type | Mandatory| Description| 545| ---------- | ------ | ---- | ---- | 546| accountId | string | Yes | Account ID.| 547| appActions | object | Yes | Action to perform. **bundleName** is a string indicating the application whose data is to be cleared.[Action](#action) specifies the action to perform.| 548| callback | AsyncCallback<void> | Yes | Callback used to clear the cloud data locally.| 549 550**Error codes** 551 552For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 553 554| ID | Error Message | 555| ---------------------------- | ---------- | 556| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 557| 202 | Permission verification failed, application which is not a system application uses system API. | 558| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 559| 13600001 | IPC error. | 560 561**Example** 562 563 ```ts 564 import { BusinessError } from '@kit.BasicServicesKit'; 565 let accountId: string = "testAccount"; 566 let appActions: Record<string, cloudSyncManager.Action> = { 567 'com.example.bundleName1': cloudSyncManager.Action.RETAIN_DATA, 568 'com.example.bundleName2': cloudSyncManager.Action.CLEAR_DATA 569 }; 570 cloudSyncManager.clean(accountId, appActions, (err: BusinessError) => { 571 if (err) { 572 console.error("clean failed with error message: " + err.message + ", error code: " + err.code); 573 } else { 574 console.info("clean successfully"); 575 } 576 }); 577 ``` 578