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 '@kit.CoreFileKit'; 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. Possible causes:Incorrect parameter types. | 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 for the download progress event of a file from the Drive Kit.| 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. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 90| 13600001 | IPC error. | 91 92**Example** 93 94 ```ts 95 import { BusinessError } from '@kit.BasicServicesKit'; 96 let fileCache = new cloudSync.CloudFileCache(); 97 let callback = (pg: cloudSync.DownloadProgress) => { 98 console.info("download state: " + pg.state); 99 }; 100 101 try { 102 fileCache.on('progress', callback); 103 } catch (e) { 104 const error = e as BusinessError; 105 console.error(`Error code: ${error.code}, message: ${error.message}`); 106 } 107 ``` 108 109### off<sup>11+</sup> 110 111off(event: 'progress', callback?: Callback\<DownloadProgress>): void 112 113Unregisters a listener for the download progress of a file from the Drive Kit. 114 115**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 116 117**Parameters** 118 119| Name | Type | Mandatory| Description| 120| ---------- | ------ | ---- | ---- | 121| event | string | Yes | Event type. The value is **progress**, which indicates the download progress event of a file from the Drive Kit.| 122| callback | Callback\<[DownloadProgress](#downloadprogress11)> | No | Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the download progress event.| 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| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 131| 13600001 | IPC error. | 132 133**Example** 134 135 ```ts 136 import { BusinessError } from '@kit.BasicServicesKit'; 137 let fileCache = new cloudSync.CloudFileCache(); 138 139 let callback = (pg: cloudSync.DownloadProgress) => { 140 console.info("download state: " + pg.state); 141 } 142 143 try { 144 fileCache.on('progress', callback); 145 fileCache.off('progress', callback); 146 } catch (e) { 147 const error = e as BusinessError; 148 console.error(`Error code: ${error.code}, message: ${error.message}`); 149 } 150 ``` 151 152### start<sup>11+</sup> 153 154start(uri: string): Promise<void> 155 156Starts to download a file from the Drive Kit to the local device. This API uses a promise to return the result. 157 158**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 159 160**Parameters** 161 162| Name | Type | Mandatory| Description| 163| ---------- | ------ | ---- | ---- | 164| uri | string | Yes | URI of the file to download.| 165 166**Return value** 167 168| Type | Description | 169| --------------------- | ---------------- | 170| Promise<void> | Promise used to return the result.| 171 172**Example** 173 174 ```ts 175 import { BusinessError } from '@kit.BasicServicesKit'; 176 import { fileUri } from '@kit.CoreFileKit'; 177 let fileCache = new cloudSync.CloudFileCache(); 178 let path = "/data/storage/el2/cloud/1.txt"; 179 let uri = fileUri.getUriFromPath(path); 180 181 try { 182 fileCache.on('progress', (pg: cloudSync.DownloadProgress) => { 183 console.info("download state:" + pg.state); 184 }); 185 } catch (e) { 186 const error = e as BusinessError; 187 console.error(`Error code: ${error.code}, message: ${error.message}`); 188 } 189 190 fileCache.start(uri).then(() => { 191 console.info("start download successfully"); 192 }).catch((err: BusinessError) => { 193 console.error("start download failed with error message: " + err.message + ", error code: " + err.code); 194 }); 195 ``` 196 197**Error codes** 198 199For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 200 201| ID | Error Message | 202| ---------------------------- | ---------- | 203| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 204| 13600001 | IPC error. | 205| 13900002 | No such file or directory. | 206| 13900025 | No space left on device. | 207| 14000002 | Invalid uri. | 208 209### start<sup>11+</sup> 210 211start(uri: string, callback: AsyncCallback<void>): void 212 213Starts to download a file from the Drive Kit to the local device. This API uses an asynchronous callback to return the result. 214 215**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 216 217**Parameters** 218 219| Name | Type | Mandatory| Description| 220| ---------- | ------ | ---- | ---- | 221| uri | string | Yes | URI of the file to download.| 222| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 223 224**Error codes** 225 226For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 227 228| ID | Error Message | 229| ---------------------------- | ---------- | 230| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 231| 13600001 | IPC error. | 232| 13900002 | No such file or directory. | 233| 13900025 | No space left on device. | 234| 14000002 | Invalid uri. | 235 236**Example** 237 238 ```ts 239 import { BusinessError } from '@kit.BasicServicesKit'; 240 import { fileUri } from '@kit.CoreFileKit'; 241 let fileCache = new cloudSync.CloudFileCache(); 242 let path = "/data/storage/el2/cloud/1.txt"; 243 let uri = fileUri.getUriFromPath(path); 244 245 fileCache.start(uri, (err: BusinessError) => { 246 if (err) { 247 console.error("start download failed with error message: " + err.message + ", error code: " + err.code); 248 } else { 249 console.info("start download successfully"); 250 } 251 }); 252 ``` 253 254### stop<sup>11+</sup> 255 256stop(uri: string, needClean?: boolean): Promise<void> 257 258Stops downloading a file from the Drive Kit to the local device. This API uses a promise to return the result. 259 260Calling **stop** will terminate the download of the current file and clear the cache file. You can use **start** to start the download again. 261 262**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 263 264**Parameters** 265 266| Name | Type | Mandatory| Description| 267| ---------- | ------ | ---- | ---- | 268| uri | string | Yes | URI of the file to download.| 269| needClean<sup>12+</sup> | boolean | No | Whether to delete the downloaded files. By default, downloaded files are deleted.<br>This parameter is available since API version 12.| 270 271**Return value** 272 273| Type | Description | 274| --------------------- | ---------------- | 275| Promise<void> | Promise used to return the result.| 276 277**Error codes** 278 279For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 280 281| ID | Error Message | 282| ---------------------------- | ---------- | 283| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 284| 13600001 | IPC error. | 285| 13900002 | No such file or directory. | 286| 14000002 | Invalid URI. | 287 288**Example** 289 290 ```ts 291 import { BusinessError } from '@kit.BasicServicesKit'; 292 import { fileUri } from '@kit.CoreFileKit'; 293 let fileCache = new cloudSync.CloudFileCache(); 294 let path = "/data/storage/el2/cloud/1.txt"; 295 let uri = fileUri.getUriFromPath(path); 296 297 fileCache.stop(uri, true).then(() => { 298 console.info("stop download successfully"); 299 }).catch((err: BusinessError) => { 300 console.error("stop download failed with error message: " + err.message + ", error code: " + err.code); 301 }); 302 ``` 303 304### stop<sup>11+</sup> 305 306stop(uri: string, callback: AsyncCallback<void>): void 307 308Stops downloading a file from the Drive Kit to the local device. This API uses an asynchronous callback to return the result. 309 310Calling **stop** will terminate the download of the current file and clear the cache file. You can use **start** to start the download again. 311 312**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 313 314**Parameters** 315 316| Name | Type | Mandatory| Description| 317| ---------- | ------ | ---- | ---- | 318| uri | string | Yes | URI of the file to download.| 319| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 320 321**Error codes** 322 323For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 324 325| ID | Error Message | 326| ---------------------------- | ---------- | 327| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 328| 13600001 | IPC error. | 329| 13900002 | No such file or directory. | 330| 14000002 | Invalid URI. | 331 332**Example** 333 334 ```ts 335 import { BusinessError } from '@kit.BasicServicesKit'; 336 import { fileUri } from '@kit.CoreFileKit'; 337 let fileCache = new cloudSync.CloudFileCache(); 338 let path = "/data/storage/el2/cloud/1.txt"; 339 let uri = fileUri.getUriFromPath(path); 340 341 fileCache.stop(uri, (err: BusinessError) => { 342 if (err) { 343 console.error("stop download failed with error message: " + err.message + ", error code: " + err.code); 344 } else { 345 console.info("stop download successfully"); 346 } 347 }); 348 ``` 349 350## DownloadErrorType<sup>11+</sup> 351 352Enumerates the device-cloud download error types. 353 354**System capability**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 355 356| Name| Value| Description| 357| ----- | ---- | ---- | 358| NO_ERROR | 0 | No error.| 359| UNKNOWN_ERROR | 1 | Unknown error.| 360| NETWORK_UNAVAILABLE | 2 | The network is unavailable.| 361| LOCAL_STORAGE_FULL | 3 | The local space is insufficient.| 362| CONTENT_NOT_FOUND | 4 | The file is not found in the cloud space.| 363| FREQUENT_USER_REQUESTS | 5 | The user requests are too frequent to respond.| 364