@ohos.file.cloudSync (Device-Cloud Synchronization) (System API)

The 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.

NOTE

• 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.
• This topic describes only the system APIs provided by the module. For details about its public APIs, see @ohos.file.cloudSync (Device-Cloud Synchronization Capability).

Modules to Import

import cloudSync from '@ohos.file.cloudSync';

SyncState

Enumerates the device-cloud synchronization states.

NOTE

If a synchronization progress event listener is registered for an application, a callback will be invoked to notify the application when the device-cloud synchronization state is changed.

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

ErrorType

Enumerates the device-cloud synchronization errors.

• Currently, NETWORK_UNAVAILABLE is returned only when both the mobile network and Wi-Fi are unavailable during synchronization. If either network is available, synchronization can be performed normally.
• During the synchronization process, if the battery level is lower than 15% in non-charging scenarios, BATTERY_LEVEL_LOW will be return when the current upload is complete; if the battery level is lower than 10% in non-charging scenarios, BATTERY_LEVEL_WARNING will be returned when the current upload is complete.
• When synchronization is being triggered, if the battery level is lower than 15% in non-charging scenarios, synchronization is not allowed and an error code will be returned by start().
• If the cloud space is insufficient when a file is uploaded, the upload will fail and there is no such a file in the cloud.
• If the local space is insufficient when a file is downloaded, the download will fail. After the local space is released, the file will be downloaded again when synchronization starts.

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

SyncProgress

Represents information about the device-cloud synchronization progress.

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

GallerySync

Provides APIs to implement device-cloud synchronization of media assets in Gallery. Before using the APIs of GallerySync, you need to create a GallerySync instance.

constructor

constructor()

A constructor used to create a GallerySync instance.

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Example

let gallerySync = new cloudSync.GallerySync()

on

on(evt: 'progress', callback: (pg: SyncProgress) => void): void

Registers a listener for the device-cloud synchronization progress.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see File Management Error Codes.

Example

let gallerySync = new cloudSync.GallerySync();

gallerySync.on('progress', (pg: cloudSync.SyncProgress) => {
  console.info("syncState: " + pg.state);
});

off

off(evt: 'progress', callback: (pg: SyncProgress) => void): void

Unregisters a listener for the device-cloud synchronization progress.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see File Management Error Codes.

Example

let gallerySync = new cloudSync.GallerySync();

let callback = (pg: cloudSync.SyncProgress) => {
  console.info("gallery sync state: " + pg.state + "error type:" + pg.error);
}

gallerySync.on('progress', callback);

gallerySync.off('progress', callback);

off

off(evt: 'progress'): void

Unregisters all listeners for the device-cloud synchronization progress.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see File Management Error Codes.

Example

let gallerySync = new cloudSync.GallerySync();

gallerySync.on('progress', (pg: cloudSync.SyncProgress) => {
    console.info("syncState: " + pg.state);
});

gallerySync.off('progress');

start

start(): Promise<void>

Starts device-cloud synchronization. This API uses a promise to return the result.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Return value

Error codes

For details about the error codes, see File Management Error Codes.

Example

import { BusinessError } from '@ohos.base';
let gallerySync = new cloudSync.GallerySync();

gallerySync.on('progress', (pg: cloudSync.SyncProgress) => {
    console.info("syncState: " + pg.state);
});

gallerySync.start().then(() => {
    console.info("start sync successfully");
}).catch((err: BusinessError) => {
    console.info("start sync failed with error message: " + err.message + ", error code: " + err.code);
});

start

start(callback: AsyncCallback<void>): void

Starts device-cloud synchronization. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see File Management Error Codes.

Example

import { BusinessError } from '@ohos.base';
let gallerySync = new cloudSync.GallerySync();

gallerySync.start((err: BusinessError) => {
  if (err) {
    console.info("start sync failed with error message: " + err.message + ", error code: " + err.code);
  } else {
    console.info("start sync successfully");
  }
});

stop

stop(): Promise<void>

Stops device-cloud synchronization. This API uses a promise to return the result.

NOTE

Calling stop will stop the synchronization process. To resume the synchronization, call start.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Return value

Error codes

For details about the error codes, see File Management Error Codes.

Example

import { BusinessError } from '@ohos.base';
let gallerySync = new cloudSync.GallerySync();

gallerySync.stop().then(() => {
    console.info("stop sync successfully");
}).catch((err: BusinessError) => {
    console.info("stop sync failed with error message: " + err.message + ", error code: " + err.code);
});

stop

stop(callback: AsyncCallback<void>): void

Stops device-cloud synchronization. This API uses an asynchronous callback to return the result.

NOTE

Calling stop will stop the synchronization process. To resume the synchronization, call start.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see File Management Error Codes.

Example

import { BusinessError } from '@ohos.base';
let gallerySync = new cloudSync.GallerySync();

gallerySync.stop((err: BusinessError) => {
  if (err) {
    console.info("stop sync failed with error message: " + err.message + ", error code: " + err.code);
  } else {
    console.info("stop sync successfully");
  }
});

Download

Provides APIs for downloading image files to Gallery. Before using the APIs of Download, you need to create a Download instance.

constructor

constructor()

A constructor used to create a Download instance.

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Example

let download = new cloudSync.Download()

on

on(evt: 'progress', callback: (pg: DownloadProgress) => void): void

Registers a listener for the download progress of a cloud file.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see File Management Error Codes.

Example

let download = new cloudSync.Download();

download.on('progress', (pg: cloudSync.DownloadProgress) => {
  console.info("download state: " + pg.state);
});

off

off(evt: 'progress', callback: (pg: DownloadProgress) => void): void

Unregisters a listener for the download progress of a cloud file.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see File Management Error Codes.

Example

let download = new cloudSync.Download();

let callback = (pg: cloudSync.DownloadProgress) => {
  console.info("download state: " + pg.state);
}

download.on('progress', callback);

download.off('progress', callback);

off

off(evt: 'progress'): void

Unregisters all listeners for the download progress event of a cloud file.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see File Management Error Codes.

Example

let download = new cloudSync.Download();

download.on('progress', (pg: cloudSync.DownloadProgress) => {
    console.info("download state:" + pg.state);
});

download.off('progress');

start

start(uri: string): Promise<void>

Starts to download a cloud file. This API uses a promise to return the result.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Parameters

Return value

Example

import { BusinessError } from '@ohos.base';
let download = new cloudSync.Download();
let uri: string = "file:///media/Photo/1";

download.on('progress', (pg: cloudSync.DownloadProgress) => {
    console.info("download state:" + pg.state);
});

download.start(uri).then(() => {
    console.info("start download successfully");
}).catch((err: BusinessError) => {
    console.info("start download failed with error message: " + err.message + ", error code: " + err.code);
});

Error codes

For details about the error codes, see File Management Error Codes.

start

start(uri: string, callback: AsyncCallback<void>): void

Starts to download a cloud file. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see File Management Error Codes.

Example

import { BusinessError } from '@ohos.base';
let download = new cloudSync.Download();
let uri: string = "file:///media/Photo/1";

download.start(uri, (err: BusinessError) => {
  if (err) {
    console.info("start download failed with error message: " + err.message + ", error code: " + err.code);
  } else {
    console.info("start download successfully");
  }
});

stop

stop(uri: string): Promise<void>

Stops downloading a cloud file. This API uses a promise to return the result.

NOTE

Calling stop will terminate the download of the current file and clear the cache file. You can use start to start the download again.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Parameters

Return value

Error codes

For details about the error codes, see File Management Error Codes.

Example

import { BusinessError } from '@ohos.base';
let download = new cloudSync.Download();
let uri: string = "file:///media/Photo/1";

download.stop(uri).then(() => {
    console.info("stop download successfully");
}).catch((err: BusinessError) => {
    console.info("stop download failed with error message: " + err.message + ", error code: " + err.code);
});

stop

stop(uri: string, callback: AsyncCallback<void>): void

Stops downloading a cloud file. This API uses an asynchronous callback to return the result.

NOTE

Calling stop will terminate the download of the current file and clear the cache file. You can use start to start the download again.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see File Management Error Codes.

Example

import { BusinessError } from '@ohos.base';
let download = new cloudSync.Download();
let uri: string = "file:///media/Photo/1";

download.stop(uri, (err: BusinessError) => {
  if (err) {
    console.info("stop download failed with error message: " + err.message + ", error code: " + err.code);
  } else {
    console.info("stop download successfully");
  }
});

FileSync¹¹⁺

Provides APIs for the file manager application to perform device-cloud synchronization of the files stored in the Drive Kit. Before using the APIs of this class, you need to create a FileSync instance.

constructor¹¹⁺

constructor()

A constructor used to create a FileSync instance.

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Error codes

For details about the error codes, see File Management Error Codes.

Example

let fileSync = new cloudSync.FileSync()

on¹¹⁺

on(event: 'progress', callback: Callback<SyncProgress>): void

Registers a listener for the device-cloud synchronization progress.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see File Management Error Codes.

Example

let fileSync = new cloudSync.FileSync();
let callback = (pg: cloudSync.SyncProgress) => {
  console.info("file sync state: " + pg.state + "error type:" + pg.error);
}

fileSync.on('progress', callback);

off¹¹⁺

off(event: 'progress', callback?: Callback<SyncProgress>): void

Unregisters a listener for the device-cloud synchronization progress.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see File Management Error Codes.

Example

let fileSync = new cloudSync.FileSync();

let callback = (pg: cloudSync.SyncProgress) => {
  console.info("file sync state: " + pg.state + "error type:" + pg.error);
}

fileSync.on('progress', callback);

fileSync.off('progress', callback);

start¹¹⁺

start(): Promise<void>

Starts device-cloud synchronization of a file in the Drive Kit. This API uses a promise to return the result.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Return value

Error codes

For details about the error codes, see File Management Error Codes.

Example

import { BusinessError } from '@ohos.base';
let fileSync = new cloudSync.FileSync();

let callback = (pg: cloudSync.SyncProgress) => {
  console.info("file sync state: " + pg.state + "error type:" + pg.error);
}

fileSync.on('progress', callback);

fileSync.start().then(() => {
    console.info("start sync successfully");
}).catch((err: BusinessError) => {
    console.info("start sync failed with error message: " + err.message + ", error code: " + err.code);
});

start¹¹⁺

start(callback: AsyncCallback<void>): void

Starts device-cloud synchronization of a file in the Drive Kit. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see File Management Error Codes.

Example

import { BusinessError } from '@ohos.base';
let fileSync = new cloudSync.FileSync();

fileSync.start((err: BusinessError) => {
  if (err) {
    console.info("start sync failed with error message: " + err.message + ", error code: " + err.code);
  } else {
    console.info("start sync successfully");
  }
});

stop¹¹⁺

stop(): Promise<void>

Stops device-cloud synchronization of the file in the Drive Kit. This API uses a promise to return the result.

Calling stop will stop the synchronization process. To resume the synchronization, call start.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Return value

Error codes

For details about the error codes, see File Management Error Codes.

Example

import { BusinessError } from '@ohos.base';
let fileSync = new cloudSync.FileSync();

fileSync.stop().then(() => {
    console.info("stop sync successfully");
}).catch((err: BusinessError) => {
    console.info("stop sync failed with error message: " + err.message + ", error code: " + err.code);
});

stop¹¹⁺

stop(callback: AsyncCallback<void>): void

Stops device-cloud synchronization of the file in the Drive Kit. This API uses an asynchronous callback to return the result.

Calling stop will stop the synchronization process. To resume the synchronization, call start.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see File Management Error Codes.

Example

import { BusinessError } from '@ohos.base';
let fileSync = new cloudSync.FileSync();

fileSync.stop((err: BusinessError) => {
  if (err) {
    console.info("stop sync failed with error message: " + err.message + ", error code: " + err.code);
  } else {
    console.info("stop sync successfully");
  }
});

getLastSyncTime¹¹⁺

getLastSyncTime(): Promise<number>

Obtains the last synchronization time. This API uses a promise to return the result.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Return value

Error codes

For details about the error codes, see File Management Error Codes.

Example

import { BusinessError } from '@ohos.base';
let fileSync = new cloudSync.FileSync();

fileSync.getLastSyncTime().then((timeStamp: number) => {
  let date = new Date(timeStamp);
  console.info("get last sync time successfully:"+ date);
}).catch((err: BusinessError) => {
    console.info("get last sync time failed with error message: " + err.message + ", error code: " + err.code);
});

getLastSyncTime¹¹⁺

getLastSyncTime(callback: AsyncCallback<number>): void;

Obtains the last synchronization time. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see File Management Error Codes.

Example

import { BusinessError } from '@ohos.base';
let fileSync = new cloudSync.FileSync();

fileSync.getLastSyncTime((err: BusinessError, timeStamp: number) => {
  if (err) {
    console.info("get last sync time with error message: " + err.message + ", error code: " + err.code);
  } else {
    let date = new Date(timeStamp);
    console.info("get last sync time successfully:"+ date);
  }
});

CloudFileCache¹¹⁺

Provides APIs for the file manager application to download files from the Drive Kit to a local device.

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

cleanCache¹¹⁺

cleanCache(uri: string): void;

Deletes a cache file. This API returns the result synchronously.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see File Management Error Codes.

Example

import { BusinessError } from '@ohos.base';
import fileUri from '@ohos.file.fileuri';
let fileCache = new cloudSync.CloudFileCache();
let path = "/data/storage/el2/cloud/1.txt";
let uri = fileUri.getUriFromPath(path);

try {
  fileCache.cleanCache(uri);
} catch (err) {
  let error:BusinessError = err as BusinessError;
  console.info("clean cache failed with error message: " + err.message + ", error code: " + err.code);
} 

cloudSync.getFileSyncState¹¹⁺

getFileSyncState(uri: Array<string>): Promise<Array<FileSyncState>>

Obtains the file synchronization state. This API uses a promise to return the result.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Parameters

Return value

Error codes

For details about the error codes, see File Management Error Codes.

Example

import { BusinessError } from '@ohos.base';

let uris: Array<string> = ["file://uri"];
cloudSync.getFileSyncState(uris).then(function(syncStates: Array<cloudSync.FileSyncState>) {
  for(let i = 0, len = syncStates.length; i < len; i++){
      console.info("get file sync state successfully" + syncStates[i]);
  }
}).catch((err: BusinessError) => {
    console.info("get file sync state failed with error message: " + err.message + ", error code: " + err.code);
});

cloudSync.getFileSyncState¹¹⁺

getFileSyncState(uri: Array<string>, callback: AsyncCallback<Array<FileSyncState>>): void

Obtains the file synchronization state. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.CLOUDFILE_SYNC

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see File Management Error Codes.

Example

import { BusinessError } from '@ohos.base';

let uris: Array<string> = ["file://uri"];
cloudSync.getFileSyncState(uris, (err: BusinessError, syncStates: Array<cloudSync.FileSyncState>) => {
  if (err) {
    console.info("get file sync state with error message: " + err.message + ", error code: " + err.code);
  } else {
    for(let i = 0, len = syncStates.length; i < len; i++){
      console.info("get file sync state successfully" + syncStates[i]);
  }
  }
});

FileSyncState¹¹⁺

Enumerates the device-cloud file synchronization states.

System capability: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

System API: This is a system API.