1# @ohos.file.cloudSync (Device-Cloud Synchronization) 2 3The **cloudSync** module provides the device-cloud synchronization capabilities for applications. You can use the APIs to start or stop device-cloud synchronization and start or stop the download of images. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9## Modules to Import 10 11```ts 12import cloudSync from '@ohos.file.cloudSync'; 13``` 14 15## State<sup>11+</sup> 16 17Enumerates the download states of a cloud file. 18 19**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 20 21| Name| Value| Description| 22| ----- | ---- | ---- | 23| RUNNING | 0 | The cloud file is being downloaded.| 24| COMPLETED | 1 | The cloud file download is complete.| 25| FAILED | 2 | The cloud file download failed.| 26| STOPPED | 3 | The cloud file download is stopped.| 27 28## DownloadProgress<sup>11+</sup> 29 30Represents information about the download progress of a cloud file. 31 32**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 33 34| Name | Type | Mandatory| Description| 35| ---------- | ------ | ---- | ---- | 36| state | [State](#state11) | Yes | File download state.| 37| processed | number | Yes | Size of the data downloaded.| 38| size | number | Yes | Size of the cloud file.| 39| uri | string | Yes | URI of the cloud file.| 40| error | [DownloadErrorType](#downloaderrortype11) | Yes | Download error type.| 41 42## CloudFileCache<sup>11+</sup> 43 44Provides APIs for the file manager application to download files from the Drive Kit to a local device. 45 46**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 47 48### construct<sup>11+</sup> 49 50constructor() 51 52A constructor used to create a **CloudFileCache** instance. 53 54**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 55 56**Error codes** 57 58| ID | Error Message | 59| ---------------------------- | ---------- | 60| 401 | The input parameter is invalid. | 61 62**Example** 63 64 ```ts 65 let fileCache = new cloudSync.CloudFileCache(); 66 ``` 67 68### on<sup>11+</sup> 69 70on(event: 'progress', callback: Callback\<DownloadProgress>): void 71 72Registers a listener for the download progress of a file from the Drive Kit. 73 74**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 75 76**Parameters** 77 78| Name | Type | Mandatory| Description| 79| ---------- | ------ | ---- | ---- | 80| event | string | Yes | Event type. The value is **progress**, which indicates the download progress event of a file from the Drive Kit.| 81| callback | Callback\<[DownloadProgress](#downloadprogress11)> | Yes | Callback invoked to return the download progress information.| 82 83**Error codes** 84 85For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 86 87| ID | Error Message | 88| ---------------------------- | ---------- | 89| 401 | The input parameter is invalid. | 90| 13600001 | IPC error. | 91 92**Example** 93 94 ```ts 95 let fileCache = new cloudSync.CloudFileCache(); 96 let callback = (pg: cloudSync.DownloadProgress) => { 97 console.info("download state: " + pg.state); 98 }; 99 100 fileCache.on('progress', callback); 101 ``` 102 103### off<sup>11+</sup> 104 105off(event: 'progress', callback?: Callback\<DownloadProgress>): void 106 107Unregisters a listener for the download progress of a file from the Drive Kit. 108 109**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 110 111**Parameters** 112 113| Name | Type | Mandatory| Description| 114| ---------- | ------ | ---- | ---- | 115| event | string | Yes | Event type. The value is **progress**, which indicates the download progress event of a file from the Drive Kit.| 116| callback | Callback\<[DownloadProgress](#downloadprogress11)> | No | Callback for the download progress event of a file from the Drive Kit.| 117 118**Error codes** 119 120For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 121 122| ID | Error Message | 123| ---------------------------- | ---------- | 124| 401 | The input parameter is invalid. | 125| 13600001 | IPC error. | 126| 13900002 | No such file or directory. | 127| 13900025 | No space left on device. | 128| 14000002 | Invalid uri. | 129 130**Example** 131 132 ```ts 133 let fileCache = new cloudSync.CloudFileCache(); 134 135 let callback = (pg: cloudSync.DownloadProgress) => { 136 console.info("download state: " + pg.state); 137 } 138 139 fileCache.on('progress', callback); 140 141 fileCache.off('progress', callback); 142 ``` 143 144### start<sup>11+</sup> 145 146start(uri: string): Promise<void> 147 148Starts to download a file from the Drive Kit to the local device. This API uses a promise to return the result. 149 150**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 151 152**Parameters** 153 154| Name | Type | Mandatory| Description| 155| ---------- | ------ | ---- | ---- | 156| uri | string | Yes | URI of the file to download.| 157 158**Return value** 159 160| Type | Description | 161| --------------------- | ---------------- | 162| Promise<void> | Promise used to return the result.| 163 164**Example** 165 166 ```ts 167 import { BusinessError } from '@ohos.base'; 168 import fileUri from '@ohos.file.fileuri'; 169 let fileCache = new cloudSync.CloudFileCache(); 170 let path = "/data/storage/el2/cloud/1.txt"; 171 let uri = fileUri.getUriFromPath(path); 172 173 fileCache.on('progress', (pg: cloudSync.DownloadProgress) => { 174 console.info("download state:" + pg.state); 175 }); 176 177 fileCache.start(uri).then(() => { 178 console.info("start download successfully"); 179 }).catch((err: BusinessError) => { 180 console.info("start download failed with error message: " + err.message + ", error code: " + err.code); 181 }); 182 ``` 183 184**Error codes** 185 186For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 187 188| ID | Error Message | 189| ---------------------------- | ---------- | 190| 401 | The input parameter is invalid. | 191| 13600001 | IPC error. | 192| 13900002 | No such file or directory. | 193| 13900025 | No space left on device. | 194| 14000002 | Invalid uri. | 195 196### start<sup>11+</sup> 197 198start(uri: string, callback: AsyncCallback<void>): void 199 200Starts to download a file from the Drive Kit to the local device. This API uses an asynchronous callback to return the result. 201 202**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 203 204**Parameters** 205 206| Name | Type | Mandatory| Description| 207| ---------- | ------ | ---- | ---- | 208| uri | string | Yes | URI of the file to download.| 209| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.| 210 211**Error codes** 212 213For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 214 215| ID | Error Message | 216| ---------------------------- | ---------- | 217| 401 | The input parameter is invalid. | 218| 13600001 | IPC error. | 219| 13900002 | No such file or directory. | 220| 13900025 | No space left on device. | 221| 14000002 | Invalid uri. | 222 223**Example** 224 225 ```ts 226 import { BusinessError } from '@ohos.base'; 227 import fileUri from '@ohos.file.fileuri'; 228 let fileCache = new cloudSync.CloudFileCache(); 229 let path = "/data/storage/el2/cloud/1.txt"; 230 let uri = fileUri.getUriFromPath(path); 231 232 fileCache.start(uri, (err: BusinessError) => { 233 if (err) { 234 console.info("start download failed with error message: " + err.message + ", error code: " + err.code); 235 } else { 236 console.info("start download successfully"); 237 } 238 }); 239 ``` 240 241### stop<sup>11+</sup> 242 243stop(uri: string): Promise<void> 244 245Stops downloading a file from the Drive Kit to the local device. This API uses a promise to return the result. 246 247Calling **stop** will terminate the download of the current file and clear the cache file. You can use **start** to start the download again. 248 249**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 250 251**Parameters** 252 253| Name | Type | Mandatory| Description| 254| ---------- | ------ | ---- | ---- | 255| uri | string | Yes | URI of the file to download.| 256 257**Return value** 258 259| Type | Description | 260| --------------------- | ---------------- | 261| Promise<void> | Promise used to return the result.| 262 263**Error codes** 264 265For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 266 267| ID | Error Message | 268| ---------------------------- | ---------- | 269| 401 | The input parameter is invalid. | 270| 13600001 | IPC error. | 271| 13900002 | No such file or directory. | 272| 14000002 | Invalid uri. | 273 274**Example** 275 276 ```ts 277 import { BusinessError } from '@ohos.base'; 278 import fileUri from '@ohos.file.fileuri'; 279 let fileCache = new cloudSync.CloudFileCache(); 280 let path = "/data/storage/el2/cloud/1.txt"; 281 let uri = fileUri.getUriFromPath(path); 282 283 fileCache.stop(uri).then(() => { 284 console.info("stop download successfully"); 285 }).catch((err: BusinessError) => { 286 console.info("stop download failed with error message: " + err.message + ", error code: " + err.code); 287 }); 288 ``` 289 290### stop<sup>11+</sup> 291 292stop(uri: string, callback: AsyncCallback<void>): void 293 294Stops downloading a file from the Drive Kit to the local device. This API uses an asynchronous callback to return the result. 295 296Calling **stop** will terminate the download of the current file and clear the cache file. You can use **start** to start the download again. 297 298**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 299 300**Parameters** 301 302| Name | Type | Mandatory| Description| 303| ---------- | ------ | ---- | ---- | 304| uri | string | Yes | URI of the file to download.| 305| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.| 306 307**Error codes** 308 309For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 310 311| ID | Error Message | 312| ---------------------------- | ---------- | 313| 401 | The input parameter is invalid. | 314| 13600001 | IPC error. | 315| 13900002 | No such file or directory. | 316| 14000002 | Invalid uri. | 317 318**Example** 319 320 ```ts 321 import { BusinessError } from '@ohos.base'; 322 import fileUri from '@ohos.file.fileuri'; 323 let fileCache = new cloudSync.CloudFileCache(); 324 let path = "/data/storage/el2/cloud/1.txt"; 325 let uri = fileUri.getUriFromPath(path); 326 327 fileCache.stop(uri, (err: BusinessError) => { 328 if (err) { 329 console.info("stop download failed with error message: " + err.message + ", error code: " + err.code); 330 } else { 331 console.info("stop download successfully"); 332 } 333 }); 334 ``` 335 336## DownloadErrorType<sup>11+</sup> 337 338Enumerates the device-cloud download error types. 339 340**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 341 342| Name| Value| Description| 343| ----- | ---- | ---- | 344| NO_ERROR | 0 | No error.| 345| UNKNOWN_ERROR | 1 | Unknown error.| 346| NETWORK_UNAVAILABLE | 2 | The network is unavailable.| 347| LOCAL_STORAGE_FULL | 3 | The local space is insufficient.| 348| CONTENT_NOT_FOUND | 4 | The file is not found in the cloud space.| 349| FREQUENT_USER_REQUESTS | 5 | The user requests are too frequent to respond.| 350