harmony 鸿蒙@ohos.file.backup (Backup and Restore) (System API)

  • 2025-06-12
  • 浏览 (5)

@ohos.file.backup (Backup and Restore) (System API)

The file.backup module provides APIs for backing up and restoring data for applications.

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.
  • The APIs provided by this module are system APIs.

Modules to Import

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

FileMeta

Defines a file metadata object, which includes the application name and file URI. FileMeta is an indispensable object for data backup and restore.

System capability: SystemCapability.FileManagement.StorageService.Backup

Name Type Mandatory Description
bundleName string Yes Application name, which can be obtained from bundleManager.BundleInfo.
uri string Yes URI of the file in the application sandbox.
Currently, the URI is not in the uniform data format. It can consist of digits (0–9), letters (a–z and A–Z), underscores (_), and period (.) only.

FileData

Defines a file data object, which includes the file descriptor (FD) of the file opened. FileData is an indispensable object for data backup and restore.

NOTE

The FileData must be closed after being used. Otherwise, memory leakage may occur. For details about how to close a FileData object, see fs.closeSync provided by @ohos.file.fs.

System capability: SystemCapability.FileManagement.StorageService.Backup

Name Type Mandatory Description
fd number Yes FD, which can be obtained through the backup service.

FileManifestData12+

Defines a file data object, which includes the file descriptor (FD) of the file opened. The file opened by FileManifestData provides basic information about the files involved in incremental backup or restore. FileManifestData is an indispensable object for incremental backup or restore.

NOTE

For details about how to close FileManifestData, see fs.closeSync.

System capability: SystemCapability.FileManagement.StorageService.Backup

Name Type Mandatory Description
manifestFd number Yes FD, which can be obtained through the backup service.

IncrementalBackupTime12+

Represents the time of the last incremental backup.

System capability: SystemCapability.FileManagement.StorageService.Backup

Name Type Mandatory Description
bundleName string Yes Application name, which can be obtained from bundleManager.BundleInfo.
lastIncrementalTime number Yes Time when the last incremental backup was performed.

BackupParams12+

Represents optional parameters in JSON strings for backup and restore.

System capability: SystemCapability.FileManagement.StorageService.Backup

Name Type Mandatory Description
parameters string No Optional parameters for backup or restore, in JSON strings. It is empty by default.

BackupPriority12+

Represents the backup priority.

System capability: SystemCapability.FileManagement.StorageService.Backup

Name Type Mandatory Description
priority number No Backup priority. A larger value indicates a higher priority. If the priorities are the same, the API called first is executed first. The default value is 0.

IncrementalBackupData12+

Represents an incremental backup object, which inherits from IncrementalBackupTime, FileManifestData, BackupParams, and BackupPriority.

NOTE

This object provides information about the last incremental backup time and the FD of the file that contains a list of the files involved in the incremental backup. Optional parameters include backup and restore configuration and backup priority.

System capability: SystemCapability.FileManagement.StorageService.Backup

File

Defines a file object, which inherits FileMeta and FileData.

NOTE

file.backup.File is different from File provided in @ohos.file.fs. The former is an object that inherits from FileMeta and FileData, while the latter has only one FD object. Pay attention to the difference between them.

System capability: SystemCapability.FileManagement.StorageService.Backup

File12+

Defines a file object, which inherits from FileMeta, FileData, and FileManifestData.

NOTE

file.backup.File is different from File provided in @ohos.file.fs. The former is an object that inherits from FileMeta and FileData, while the latter has only one FD object. Pay attention to the difference between them.

System capability: SystemCapability.FileManagement.StorageService.Backup

GeneralCallbacks

Provides callbacks to be used in the backup or restore process. The backup service uses these callbacks to notify the client of the backup/restore progress of the application.

System capability: SystemCapability.FileManagement.StorageService.Backup

Attributes

System capability: SystemCapability.FileManagement.StorageService.Backup

Name Type Read-Only Optional Description
onBackupSizeReport18+ OnBackupSizeReport No Yes Size of the data to be backed up.

onFileReady

onFileReady : AsyncCallback<File>

Called when the file is ready for sending to the client. If the callback is invoked successfully, File is returned. Otherwise, an err object is returned.

NOTE

The File returned by AsyncCallback is the file.backup.File. The returned file belongs to the backup service. Once the file is closed, the backup service shall clear the resources used by the file. However, the client must close the file handle first.

System capability: SystemCapability.FileManagement.StorageService.Backup

Return value

Name Type Mandatory Description
File File Yes File content.

Error codes

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

ID Error Message
13600001 IPC error.
13900005 I/O error.
13900011 Out of memory.
13900020 Invalid argument.
13900025 No space left on device.
13900042 Unknown error.

Example

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

  onFileReady: (err: BusinessError, file: backup.File) => {
    if (err) {
      console.error('onFileReady failed with err: ' + JSON.stringify(err));
      return;
    }
    console.info('onFileReady success with file: ' + file.bundleName + ' ' + file.uri);
    fs.closeSync(file.fd);
  }

onBundleBegin

onBundleBegin: AsyncCallback<string, void|string>

Called when the application backup or restore starts. If the callback is successfully invoked, bundleName is returned. Otherwise, an err object is returned. Since API version 12, err and bundleName are returned.

System capability: SystemCapability.FileManagement.StorageService.Backup

Return value

Name Type Mandatory Description
bundleName string Yes Application name.
err BusinessError No Error returned if the operation fails. If the operation is successful, err is undefined, and data is the bundle name.

Error codes

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

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.
13500001 The application is not added to the backup or restore.
13500002 Failed to start application extension Procedure.
13600001 IPC error.
13900005 I/O error.
13900011 Out of memory.
13900025 No space left on device.
13900042 Unknown error.

Example

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

  onBundleBegin: (err: BusinessError, bundleName: string) => {
    if (err) {
      console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code));
      return;
    }
    console.info('onBundleBegin success');
  }

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

  onBundleBegin: (err: BusinessError<string>, bundleName: string) => {
    if (err) {
      console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
      return;
    }
    console.info('onBundleBegin success');
  }

onBundleEnd

onBundleEnd: AsyncCallback&lt;string, void|string&gt;

Called when the application backup or restore ends. If the callback is successfully invoked, bundleName is returned. Otherwise, an err object is returned. Since API version 12, err and bundleName are returned.

System capability: SystemCapability.FileManagement.StorageService.Backup

Return value

Name Type Mandatory Description
bundleName string Yes Application name.
err BusinessError No Error returned if the operation fails. If the operation is successful, err is undefined, and data is the bundle name.

Error codes

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

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.
13500003 Backup or restore timed out.
13500004 Application extension death.
13600001 IPC error.
13900005 I/O error.
13900011 Out of memory.
13900020 Invalid argument.
13900025 No space left on device.
13900042 Unknown error.

Example

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

  onBundleEnd: (err: BusinessError, bundleName: string) => {
    if (err) {
      console.error('onBundleEnd failed with err: ' + JSON.stringify(err));
      return;
    }
    console.info('onBundleEnd success with bundleName: ' + bundleName);
  }

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

  onBundleEnd: (err: BusinessError<string>, bundleName: string) => {
    if (err) {
      console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
      return;
    }
    console.info('onBundleEnd success');
  }

onAllBundlesEnd

onAllBundlesEnd: AsyncCallback&lt;undefined&gt;

Called when the backup or restore of all applications ends. If the callback fails to be invoked, an err object is returned.

System capability: SystemCapability.FileManagement.StorageService.Backup

Error codes

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

ID Error Message
13600001 IPC error.
13900005 I/O error.
13900011 Out of memory.
13900020 Invalid argument.
13900025 No space left on device.
13900042 Unknown error.

Example

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

  onAllBundlesEnd: (err: BusinessError) => {
    if (err) {
      console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
      return;
    }
    console.info('onAllBundlesEnd success');
  }

onBackupServiceDied

onBackupServiceDied: Callback&lt;undefined&gt;

Called when the backup service is suspended. If this callback fails to be invoked, an err object is returned.

System capability: SystemCapability.FileManagement.StorageService.Backup

Example

  onBackupServiceDied: () => {
    console.info('onBackupServiceDied success');
  }

onResultReport12+

onResultReport (bundleName: string, result: string)

Called when the backup or restore is complete. If the callback is invoked successfully, the application bundle name and backup or restore information (such as the number of backed up or restored records or exception information) are returned.

System capability: SystemCapability.FileManagement.StorageService.Backup

Return value

Name Type Mandatory Description
bundleName string Yes Bundle name of the application.
result string Yes Application backup/restore information returned in JSON format.

Example

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

  onResultReport: (bundleName: string, result: string) => {
    console.info('onResultReport bundleName : ' + bundleName);
    console.info('onResultReport result : ' + result);
  }

onProcess12+

onProcess (bundleName: string, process: string)

Called to report the backup or restore progress information. If the callback is invoked successfully, the progress information or exception information are returned.

System capability: SystemCapability.FileManagement.StorageService.Backup

Return value

Name Type Mandatory Description
bundleName string Yes Bundle name of the application.
process string Yes Backup/restore progress information in JSON format.

Example

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

  onProcess: (bundleName: string, process: string) => {
    console.info('onProcess bundleName : ' + bundleName);
    console.info('onProcess processInfo : ' + process);
  }

backup.getBackupVersion18+

getBackupVersion(): string

Obtains the backup or restore version information.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Return value

Type Description
string Returns the backup or restore version information.
The version number is in the API version format. For example, the version number is 16.0 if the internal version is API16.

Error codes

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

ID Error Message
201 Permission verification failed, usually the result returned by VerifyAccessToken.
202 Permission verification failed, application which is not a system application uses system API.

Example

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

  function getBackupVersion() {
    try {
      let result = backup.getBackupVersion();
      console.info('getBackupVersion success, result: ' + result);
    } catch (error) {
      let err: BusinessError = error as BusinessError;
      console.error('getBackupVersion failed with err: ' + JSON.stringify(err));
    }
  }

Content example:

  { "backupVersion" : "16.0" }

backup.getLocalCapabilities

getLocalCapabilities(callback: AsyncCallback&lt;FileData&gt;): void

Obtains a JSON file that describes local capabilities. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
callback AsyncCallback&lt;FileData&gt; Yes Callback used to return the FileData object obtained.

Error codes

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

ID Error Message
13600001 IPC error.
13900005 I/O error.
13900011 Out of memory.
13900025 No space left on device.
13900042 Unknown error.

Example

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

  try {
    backup.getLocalCapabilities((err: BusinessError, fileData: backup.FileData) => {
      if (err) {
        console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('getLocalCapabilities success');
      console.info('fileData info:' + fileData.fd);
      fs.closeSync(fileData.fd);
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err));
  }

The capability file can be obtained by using fs.stat of the @ohos.file.fs module. The following is an example of the capability file.

 {
  "backupVersion" : "16.0",
  "bundleInfos" :[{
    "allToBackup" : true,
    "extensionName" : "BackupExtensionAbility",
    "name" : "com.example.hiworld",
    "needToInstall" : false,
    "spaceOccupied" : 0,
    "versionCode" : 1000000,
    "versionName" : "1.0.0"
    }],
  "deviceType" : "default",
  "systemFullName" : "OpenHarmony-4.0.0.0"
 }

backup.getLocalCapabilities

getLocalCapabilities(): Promise&lt;FileData&gt;

Obtains a JSON file that describes local capabilities. This API uses a promise to return the result.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Return value

Type Description
Promise&lt;FileData&gt; Promise FileData object obtained.

Error codes

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

ID Error Message
13600001 IPC error.
13900005 I/O error.
13900011 Out of memory.
13900025 No space left on device.
13900042 Unknown error.

Example

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

  async function getLocalCapabilities() {
    try {
      let fileData = await backup.getLocalCapabilities();
      console.info('getLocalCapabilities success');
      console.info('fileData info:' + fileData.fd);
      fs.closeSync(fileData.fd);
    } catch (error) {
      let err: BusinessError = error as BusinessError;
      console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err));
    }
  }

The capability file can be obtained by using fs.stat of the @ohos.file.fs module. The following is an example of the capability file.

 {
  "backupVersion" : "16.0",
  "bundleInfos" :[{
    "allToBackup" : true,
    "extensionName" : "BackupExtensionAbility",
    "name" : "com.example.hiworld",
    "needToInstall" : false,
    "spaceOccupied" : 0,
    "versionCode" : 1000000,
    "versionName" : "1.0.0"
    }],
  "deviceType" : "default",
  "systemFullName" : "OpenHarmony-4.0.0.0"
 }

backup.getLocalCapabilities12+

getLocalCapabilities(dataList:Array&lt;IncrementalBackupTime&gt;): Promise&lt;FileData&gt;

Obtains local capabilities. The local capabilities of an application are queried based on the dataList parameter passed in. This API uses a promise to return the result.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
dataList Array&lt;IncrementalBackupTime&gt; Yes List of the files involved in the incremental backup.

Return value

Type Description
Promise&lt;FileData&gt; Promise FileData object obtained.

Error codes

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

ID Error Message
201 Permission verification failed, usually the result returned by VerifyAccessToken.
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.
13600001 IPC error.
13900005 I/O error.
13900011 Out of memory.
13900020 Invalid argument.
13900025 No space left on device.
13900042 Unknown error.

Example

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

  async function getLocalCapabilities() {
    try {
      let backupApps: backup.IncrementalBackupTime[] = [{
        bundleName: "com.example.hiworld",
        lastIncrementalTime: 1700107870 // Time of the last incremental backup.
      }];
      let fileData = await backup.getLocalCapabilities(backupApps);
      console.info('getLocalCapabilities success');
      console.info('fileData info:' + fileData.fd);
      fs.closeSync(fileData.fd);
    } catch (error) {
      let err: BusinessError = error as BusinessError;
      console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err));
    }
  }

backup.getBackupInfo12+

getBackupInfo(bundleToBackup: string): string

Obtains information about the application to back up.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
bundleToBackup string Yes Name of the application to back up.

Return value

Type Description
string Application information obtained.

Error codes

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

ID Error Message
201 Permission verification failed, usually the result returned by VerifyAccessToken.
202 Permission verification failed, application which is not a system application uses system API.
401 The input parameter is invalid.

Example

  import fs from '@ohos.file.fs';
  import { BusinessError } from '@ohos.base';
  import backup from '@ohos.file.backup';

  function getBackupInfo() {
    try {
      let backupApp = "com.example.hiworld";
      let result = backup.getBackupInfo(backupApp);
      console.info('getBackupInfo success, result: ' + result);
    } catch (error) {
      let err: BusinessError = error as BusinessError;
      console.error('getBackupInfo failed with err: ' + JSON.stringify(err));
    }
  }

backup.updateTimer12+

updateTimer(bundleName: string, timeout: number): boolean

Called after onBundleBegin and before onBundleEnd to set the backup or restore timer.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
bundleName string Yes Name of the application, for which you want to set the backup or restore duration.
timeout number Yes Maximum backup or restore duration, in ms.
Value range: [0, 14400000]

Return value

Type Description
boolean A Boolean value indicating whether the backup or restore timeout is set successfully. The value true indicates that the setting is successful, and the value false indicates that the setting fails.

Error codes

ID Error Message
201 Permission verification failed, usually the result returned by VerifyAccessToken.
202 Permission verification failed, application which is not a system application uses system API.
401 The input parameter is invalid.

Example

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

  function updateTimer() {
    try {
      let timeout = 30000;
      let bundleName = "com.example.hiworld";
      let result = backup.updateTimer(bundleName, timeout);
      if (result) {
        console.info('updateTimer success');
      } else {
        console.info('updateTimer fail');
      }
    } catch (error) {
      let err: BusinessError = error as BusinessError;
      console.error('updateTimer failed with err: ' + JSON.stringify(err));
    }
  }

backup.updateSendRate12+

updateSendRate(bundleName: string, sendRate: number): boolean

Called after onBundleBegin and before onBundleEnd to set the backup or restore timer.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
bundleName string Yes Name of the target application.
sendRate number Yes Send rate to set, in file descriptors (FDs) per second.
Value range: 0 to 800
Default value: 60 FDs/second
The value 0 means to stop transmission. If the value is greater than 800, the send rate is 800 FDs/second.

Return value

Type Description
boolean A Boolean value indicating whether the send rate is set successfully. The value true indicates that the setting is successful, and the value false indicates that the setting fails.

Error codes

ID Error Message
201 Permission verification failed, usually the result returned by VerifyAccessToken.
202 Permission verification failed, application which is not a system application uses system API.
401 The input parameter is invalid.

Example

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

  function updateSendRate() {
    try {
      let bundleName = "com.example.myApp";
      let sendRate = 300;
      let result = backup.updateSendRate(bundleName, sendRate);
      if (result) {
        console.info('updateSendRate success');
      } else {
        console.info('updateSendRate fail');
      }
    } catch (error) {
      let err: BusinessError = error as BusinessError;
      console.error('updateSendRate failed with err: ' + JSON.stringify(err));
    }
  }

OnBackupSizeReport18+

type OnBackupSizeReport = (reportInfo: string) => void

Reports the size of the application data to be backed up.

System capability: SystemCapability.FileManagement.StorageService.Backup

Name Type Mandatory Description
reportInfo string Yes Size of the application data to be backed up.

Example

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

  onBackupSizeReport: (OnBackupSizeReport) => {
    console.info('dataSizeCallback success');
    console.info('dataSizeCallback report : ' + OnBackupSizeReport);
  }

SessionBackup

Provides a backup process object to support the application backup process. Before using the APIs of this class, you need to create a SessionBackup instance.

constructor

constructor(callbacks: GeneralCallbacks)

A constructor used to create a SessionBackup instance.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
callback GeneralCallbacks Yes Callbacks to be invoked during the backup process.

Example

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

  let generalCallbacks: backup.GeneralCallbacks = {
    onFileReady: (err: BusinessError, file: backup.File) => {
      if (err) {
        console.error('onFileReady failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
        return;
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
        return;
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onAllBundlesEnd success');
    },
    onBackupServiceDied: () => {
      console.info('service died');
    },
    onResultReport: (bundleName: string, result: string) => {
      console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
    },
    onProcess: (bundleName: string, process: string) => {
      console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
    }
  };
  let sessionBackup = new backup.SessionBackup(generalCallbacks); // Create a backup process.

getLocalCapabilities18+

getLocalCapabilities(): Promise&lt;FileData&gt;

Obtains a JSON file that describes local capabilities in the backup service. This API uses a promise to return the result.

Required permissions: ohos.permission.BACKUP

System API: This is a system API.

System capability: SystemCapability.FileManagement.StorageService.Backup

Return value

Type Description
Promise&lt;FileData&gt; Promise FileData object obtained.

Error codes

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

ID Error Message
201 Permission verification failed, usually the result returned by VerifyAccessToken.
202 Permission verification failed, application which is not a system application uses system API.
13600001 IPC error.
13900001 Operation not permitted.
13900020 Invalid argument.
13900042 Internal error.

Example

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

  interface test { // Parse the capability file.
    bundleInfos: [];
    deviceType: string;
    systemFullName: string;
  }

  interface BundleInfo { // Obtain the local capability information of an application.
    name: string;
    appIndex: number;
    versionCode: number;
    versionName: string;
    spaceOccupied: number;
    allToBackup: boolean;
    increSpaceOccupied?: number;
    fullBackupOnly: boolean;
    extensionName: string;
    restoreDeps: string;
    supportScene: string;
    extraInfo: object;
  }

  let generalCallbacks: backup.GeneralCallbacks = { // Define general callbacks to be used in the backup or restore process.
    onFileReady: (err: BusinessError, file: backup.File) => {
      if (err) {
        console.error('onFileReady failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
        return;
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
        return;
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onAllBundlesEnd success');
    },
    onBackupServiceDied: () => {
      console.info('service died');
    },
    onResultReport: (bundleName: string, result: string) => {
      console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
    },
    onProcess: (bundleName: string, process: string) => {
      console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
    }
  };
  let sessionBackup = new backup.SessionBackup(generalCallbacks); // Create a backup process.
  let basePath = '/data/storage/el2/base/backup'; 
  let path = basePath + '/localCapabilities.json'; // Local path for storing capability files.
  try {
    let fileData = await sessionBackup.getLocalCapabilities(); // Obtain the local capability file.
    if (fileData) {
      console.info('getLocalCapabilities success');
      console.info('fileData info:' + fileData.fd);
      if (!fs.accessSync(basePath)) {
        fs.mkdirSync(basePath);
        console.info('creat success' + basePath);
      }
      fs.copyFileSync(fileData.fd, path); // Save the obtained local capability file to the local host.
      fs.closeSync(fileData.fd);
    }
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err));
  }
  let data = await fs.readTextSync(path, 'utf8'); // Obtain information from the local capability file.
  try {
    const jsonsObj: test|null = JSON.parse(data); // Parse the local capability file and print some information.
    if (jsonsObj) {
      const infos:BundleInfo [] = jsonsObj.bundleInfos;
      for (let i = 0; i < infos.length; i++) {
        console.info('name: ' + infos[i].name);
        console.info('appIndex: ' + infos[i].appIndex);
        console.info('allToBackup: ' + infos[i].allToBackup);
      }
      const systemFullName: string = jsonsObj.systemFullName;
      console.info('systemFullName: ' + systemFullName);
      const deviceType: string = jsonsObj.deviceType;
      console.info('deviceType: ' + deviceType);
    }
  } catch (error) {
    console.error('parse failed with err: ' + JSON.stringify(error));
  }

The capability file can be obtained by using fs.stat of the @ohos.file.fs module. The following is an example of the capability file.

 {
  "backupVersion" : "16.0",
  "bundleInfos" :[{
    "allToBackup" : true,
    "extensionName" : "BackupExtensionAbility",
    "name" : "com.example.hiworld",
    "needToInstall" : false,
    "spaceOccupied" : 0,
    "versionCode" : 1000000,
    "versionName" : "1.0.0"
    }],
  "deviceType" : "default",
  "systemFullName" : "OpenHarmony-4.0.0.0"
 }

getBackupDataSize18+

getBackupDataSize(isPreciseScan: boolean, dataList: Array<IncrementalBackupTime>): Promise&lt;void&gt;

Obtains the amount of data to be backed up. This method is called before appendBundles. The scanning result is returned at a fixed interval of 5 seconds by calling the general callback onBackupSizeReport asynchronously until all application data in the datalist is returned.

Required permissions: ohos.permission.BACKUP

System API: This is a system API.

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
isPreciseScan boolean Yes Whether to perform accurate scanning. The value true means to perform accurate scanning; the value false means to perform inaccurate scanning. Inaccurate scanning is fast and is used to estimate the data size. Accurate scanning is slow and returns more accurate result. However, the data to be backed up may change. Therefore, the precise scanning result may not match the actual backup data size.
dataList Array<IncrementalBackupTime> Yes Backup application list, which describes the application whose data size is to be obtained and the last backup time. For a full backup, set this parameter to 0.

Return value

Type Description
Promise&lt;void&gt; Promise that returns no value.

Error codes

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

ID Error Message
201 Permission verification failed, usually the result returned by VerifyAccessToken.
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.
13600001 IPC error.
13900001 Operation not permitted.
13900020 Invalid argument.
13900042 Internal error.

Example

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

  interface scanedInfos { // Parse the scanning result.
    scaned: [];
    scanning: string;
  }

  interface ScanedInfo { // Parse the scanning result of an application.
    bundleName: string;
    dataSize: number;
    incDataSize: number;
  }

  let generalCallbacks: backup.GeneralCallbacks = { // Define general callbacks to be used in the backup or restore process.
    onFileReady: (err: BusinessError, file: backup.File) => {
      if (err) {
        console.error('onFileReady failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
        return;
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
        return;
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onAllBundlesEnd success');
    },
    onBackupServiceDied: () => {
      console.info('service died');
    },
    onResultReport: (bundleName: string, result: string) => {
      console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
    },
    onProcess: (bundleName: string, process: string) => {
      console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
    },
    onBackupSizeReport: (OnBackupSizeReport) => { // The callback function is used together with getBackupDataSize to return the obtained application data size and the bundle name of the application that is obtaining the data size.
      console.info('dataSizeCallback success');
      const jsonObj: scanedInfos|null = JSON.parse(OnBackupSizeReport); // Parse and print the returned information.
      if (jsonObj) {
        const infos: ScanedInfo [] = jsonObj.scaned;
        for (let i = 0; i < infos.length; i++) {
          console.info('name: ' + infos[i].bundleName);
          console.info('dataSize: ' + infos[i].dataSize);
          console.info('incDataSize: ' + infos[i].incDataSize);
        }
        const scanning: string = jsonObj.scanning;
        console.info('scanning: ' + scanning);
      }
    }
  };

  let sessionBackup = new backup.SessionBackup(generalCallbacks); // Create a backup process.
  let backupApps: backup.IncrementalBackupTime[] = [{
    bundleName: "com.example.hiworld",
    lastIncrementalTime: 0 // The caller performs incremental backup based on the last recorded time. The value is 0 for full backup.
  }];
  try {
    sessionBackup.getBackupDataSize(false, backupApps); // Obtain the data to be backed up of a specified application in backupApps. The value false indicates that inaccurate scanning is used.
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('getBackupDataSize failed with err: ' + JSON.stringify(err));
  }

Example of a JSON string returned asynchronously:

{
 "scaned" :[ // Scanned application. The result will not be returned in the next callback.
     {
         "name": "com.example.hiworld", // Application name.
         "dataSize": 1006060, // Data size.
         "incDataSize":-1 // Incremental data size. The value is -1 for full scan and inaccurate scan, and is the actual incremental data size for incremental accurate scan.
     },
     {
         "name": "com.example.myAPP",
         "dataSize": 5000027,
         "incDataSize": -1
     }
 ],
 "scanning" :"com.example.smartAPP" // Application that is being scanned. This field is empty when the last result is returned.
}

appendBundles

appendBundles(bundlesToBackup: string[], callback: AsyncCallback&lt;void&gt;): void

Appends the applications whose data needs to be backed up. Currently, the obtained SessionBackup instance can be called only once in the entire backup process. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
bundlesToBackup string[] Yes Array of the application names to append.
callback AsyncCallback&lt;void&gt; Yes Callback used to return the result.

Error codes

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

ID Error Message
13600001 IPC error
13900001 Operation not permitted
13900005 I/O error
13900011 Out of memory
13900020 Invalid argument
13900025 No space left on device
13900042 Unknown error

Example

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

  let generalCallbacks: backup.GeneralCallbacks = {
    onFileReady: (err: BusinessError, file: backup.File) => {
      if (err) {
        console.error('onFileReady failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
        return;
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
        return;
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onAllBundlesEnd success');
    },
    onBackupServiceDied: () => {
      console.info('service died');
    },
    onResultReport: (bundleName: string, result: string) => {
      console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
    },
    onProcess: (bundleName: string, process: string) => {
      console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
    }
  };
  let sessionBackup = new backup.SessionBackup(generalCallbacks); // Create a backup process.
  try {
    let backupApps: Array<string> = [
      "com.example.hiworld",
    ];
    sessionBackup.appendBundles(backupApps, (err: BusinessError) => {
      if (err) {
        console.error('appendBundles failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('appendBundles success');
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('appendBundles failed with err: ' + JSON.stringify(err));
  }

appendBundles

appendBundles(bundlesToBackup: string[], infos?: string[]): Promise&lt;void&gt;

Appends the applications whose data needs to be backed up. Currently, the obtained SessionBackup instance can be called only once in the entire backup process. This API uses a promise to return the result.

From API version 12, the optional parameter infos is added to carry information about each application to be backed up. The mappings between infos and bundlesToBackup are identified by index.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
bundlesToBackup string[] Yes Array of the application names to append.
infos string[] No Array of the information about each application to be backed up. The mappings between infos and bundlesToBackup are identified by index. It is left blank by default. This parameter is supported since API version 12.

Return value

Type Description
Promise&lt;void&gt; Promise that returns no value.

Error codes

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

ID Error Message
13600001 IPC error
13900001 Operation not permitted
13900005 I/O error
13900011 Out of memory
13900020 Invalid argument
13900025 No space left on device
13900042 Unknown error

Example

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

  let generalCallbacks: backup.GeneralCallbacks = {
    onFileReady: (err: BusinessError, file: backup.File) => {
      if (err) {
        console.error('onFileReady failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onAllBundlesEnd success');
    },
    onBackupServiceDied: () => {
      console.info('service died');
    },
    onResultReport: (bundleName: string, result: string) => {
      console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
    },
    onProcess: (bundleName: string, process: string) => {
      console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
    }
  };
  let sessionBackup = new backup.SessionBackup(generalCallbacks); // Create a backup process.
  async function appendBundles() {
    try {
      let backupApps: Array<string> = [
        "com.example.hiworld",
        "com.example.myApp"
      ];
      await sessionBackup.appendBundles(backupApps);
      console.info('appendBundles success');
      // Application information is carried. In the following, infos, details, and type are fixed parameters.
      let infos: Array<string> = [
        `
        {
        "infos": [
            {
                "details": [
                    {
                        "detail": [
                            {
                                "key1": "value1",
                                "key2": "value2"
                            }
                        ]
                    }
                ],
                "type": "unicast",
                "bundleName": "com.example.hiworld"
            }
        ]
    },
    {
        "infos": [
            {
                "details": [
                    {
                        "detail": [
                            {
                                "key1": "value1",
                                "key2": "value2"
                            }
                        ]
                    }
                ],
                "type": "unicast",
                "bundleName": "com.example.myApp"
            }
        ]
    }
      `
    ]
      await sessionBackup.appendBundles(backupApps, infos);
      console.info('appendBundles success');
    } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('appendBundles failed with err: ' + JSON.stringify(err));
    }
  }

release12+

release(): Promise&lt;void&gt;

Releases the backup session when the backup process is complete. This API disconnects the application from the backup and restore service and exits the service. This API uses a promise to return the result.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Return value

Type Description
Promise&lt;void&gt; Promise that returns no value.

Error codes

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

ID Error Message
201 Permission verification failed, usually the result returned by VerifyAccessToken.
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.
13600001 IPC error.
13900001 Operation not permitted.
13900005 I/O error.
13900042 Unknown error.

Example

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

  let generalCallbacks: backup.GeneralCallbacks = {
    onFileReady: (err: BusinessError, file: backup.File) => {
      if (err) {
        console.error('onFileReady failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onAllBundlesEnd success');
    },
    onBackupServiceDied: () => {
      console.info('service died');
    },
    onResultReport: (bundleName: string, result: string) => {
      console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
    },
    onProcess: (bundleName: string, process: string) => {
      console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
    }
  };
  let sessionBackup = new backup.SessionBackup(generalCallbacks); // Create a backup process.
  sessionBackup.release(); // Release the backup session when the backup process is complete.
  console.info('release success');

cancel18+

cancel(bundleName: string): number

Cancels the backup of an application when data exceptions occur.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
bundleName string Yes Application name.

Return value

Type Description
number Cancelled.
0: The task is successfully cancelled.
13500011: The task to be cancelled is not started.
13500012: The task to be cancelled does not exist.

Error codes

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

ID Error Message
201 Permission verification failed, usually the result returned by VerifyAccessToken.
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.

Example

  import fs from '@ohos.file.fs';
  import { BusinessError } from '@ohos.base';
  import backup from '@ohos.file.backup';

  let generalCallbacks: backup.GeneralCallbacks = {
    onFileReady: (err: BusinessError, file: backup.File) => {
      if (err) {
        // If the FD fails to be passed, call the cancel API to cancel the backup task of the application.
        let result = sessionBackup.cancel(err.name);
        console.info('cancel result:' + result);
        console.error('onFileReady failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onAllBundlesEnd success');
    },
    onBackupServiceDied: () => {
      console.info('service died');
    },
    onResultReport: (bundleName: string, result: string) => {
      console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
    },
    onProcess: (bundleName: string, process: string) => {
      console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
    }
  };
  let sessionBackup = new backup.SessionBackup(generalCallbacks); // Create a backup process.
  let backupBundles: Array<string> = ["com.example.helloWorld"];
  sessionBackup.appendBundles(backupBundles);

SessionRestore

Provides an object to support the application restore process. Before using the APIs of this class, you need to create a SessionRestore instance.

constructor

constructor(callbacks: GeneralCallbacks)

A constructor used to create a SessionRestore instance.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
callback GeneralCallbacks Yes Callbacks to be invoked during the data restore process.

Example

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

  let generalCallbacks: backup.GeneralCallbacks = {
    onFileReady: (err: BusinessError, file: backup.File) => {
      if (err) {
        console.error('onFileReady failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onAllBundlesEnd success');
    },
    onBackupServiceDied: () => {
      console.info('service died');
    },
    onResultReport: (bundleName: string, result: string) => {
      console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
    },
    onProcess: (bundleName: string, process: string) => {
      console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
    }
  };
  let sessionRestore = new backup.SessionRestore(generalCallbacks); // Create a restore process.

getLocalCapabilities18+

getLocalCapabilities(): Promise&lt;FileData&gt;

Obtains a JSON file that describes local capabilities in the restore service. This API uses a promise to return the result.

Required permissions: ohos.permission.BACKUP

System API: This is a system API.

System capability: SystemCapability.FileManagement.StorageService.Backup

Return value

Type Description
Promise&lt;FileData&gt; Promise FileData object obtained.

Error codes

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

ID Error Message
201 Permission verification failed, usually the result returned by VerifyAccessToken.
202 Permission verification failed, application which is not a system application uses system API.
13600001 IPC error.
13900001 Operation not permitted.
13900020 Invalid argument.
13900042 Internal error.

Example

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

  interface test { // Parse the capability file.
    bundleInfos: [];
    deviceType: string;
    systemFullName: string;
  }

  interface BundleInfo { // Obtain the local capability information of an application.
    name: string;
    appIndex: number;
    versionCode: number;
    versionName: string;
    spaceOccupied: number;
    allToBackup: boolean;
    increSpaceOccupied?: number;
    fullBackupOnly: boolean;
    extensionName: string;
    restoreDeps: string;
    supportScene: string;
    extraInfo: object;
  }

  let generalCallbacks: backup.GeneralCallbacks = { // Define general callbacks to be used in the backup or restore process.
    onFileReady: (err: BusinessError, file: backup.File) => {
      if (err) {
        console.error('onFileReady failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
        return;
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
        return;
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onAllBundlesEnd success');
    },
    onBackupServiceDied: () => {
      console.info('service died');
    },
    onResultReport: (bundleName: string, result: string) => {
      console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
    },
    onProcess: (bundleName: string, process: string) => {
      console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
    }
  };
  let sessionRestore = new backup.SessionRestore(generalCallbacks); // Create a restore process.
  let basePath = '/data/storage/el2/base/backup';
  let path = basePath + '/localCapabilities.json'; // Local path for storing capability files.
  try {
    let fileData = await sessionRestore.getLocalCapabilities(); // Obtain the local capability file.
    if (fileData) {
      console.info('getLocalCapabilities success');
      console.info('fileData info:' + fileData.fd);
      if (!fs.accessSync(basePath)) {
        fs.mkdirSync(basePath);
        console.info('creat success' + basePath);
      }
      fs.copyFileSync(fileData.fd, path); // Save the obtained local capability file to the local host.
      fs.closeSync(fileData.fd);
    }
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err));
  }
  let data = await fs.readTextSync(path, 'utf8'); // Obtain information from the local capability file.
  try {
    const jsonsObj: test|null = JSON.parse(data); // Parse the local capability file and print some information.
    if (jsonsObj) {
      const infos:BundleInfo [] = jsonsObj.bundleInfos;
      for (let i = 0; i < infos.length; i++) {
        console.info('name: ' + infos[i].name);
        console.info('appIndex: ' + infos[i].appIndex);
        console.info('allToBackup: ' + infos[i].allToBackup);
      }
      const systemFullName: string = jsonsObj.systemFullName;
      console.info('systemFullName: ' + systemFullName);
      const deviceType: string = jsonsObj.deviceType;
      console.info('deviceType: ' + deviceType);
    }
  } catch (error) {
    console.error('parse failed with err: ' + JSON.stringify(error));
  }

The capability file can be obtained by using fs.stat of the @ohos.file.fs module. The following is an example of the capability file.

 {
  "backupVersion" : "16.0",
  "bundleInfos" :[{
    "allToBackup" : true,
    "extensionName" : "BackupExtensionAbility",
    "name" : "com.example.hiworld",
    "needToInstall" : false,
    "spaceOccupied" : 0,
    "versionCode" : 1000000,
    "versionName" : "1.0.0"
    }],
  "deviceType" : "default",
  "systemFullName" : "OpenHarmony-4.0.0.0"
 }

appendBundles

appendBundles(remoteCapabilitiesFd: number, bundlesToBackup: string[], callback: AsyncCallback&lt;void&gt;): void

Appends the applications whose data needs to be restored. Currently, the obtained SessionRestore instance can be called only once in the entire restore process. This API uses an asynchronous callback to return the result.

NOTE

  • During the data restore, the capability file needs to be verified.
  • Therefore, remoteCapabilitiesFd can be obtained by using the getLocalCapabilities API provided by the backup service. You can modify the parameters based on the actual situation of your application. You can also use the JSON file example provided by getLocalCapabilities to generate a capability file.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
remoteCapabilitiesFd number Yes FD of the file containing the capabilities to be restored.
bundlesToBackup string[] Yes Array of the application names to append.
callback AsyncCallback&lt;void&gt; Yes Callback used to return the result.

Error codes

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

ID Error Message
13600001 IPC error.
13900001 Operation not permitted.
13900005 I/O error.
13900011 Out of memory.
13900020 Invalid argument.
13900025 No space left on device.
13900042 Unknown error.

Example

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

  let generalCallbacks: backup.GeneralCallbacks = {
    onFileReady: (err: BusinessError, file: backup.File) => {
      if (err) {
        console.error('onFileReady failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onAllBundlesEnd success');
    },
    onBackupServiceDied: () => {
      console.info('service died');
    },
    onResultReport: (bundleName: string, result: string) => {
      console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
    },
    onProcess: (bundleName: string, process: string) => {
      console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
    }
  };
  let sessionRestore = new backup.SessionRestore(generalCallbacks); // Create a restore process.
  async function appendBundles() {
    let fileData : backup.FileData = {
      fd : -1
    }
    try {
      fileData = await backup.getLocalCapabilities();
      console.info('getLocalCapabilities success');
      let restoreApps: Array<string> = [
        "com.example.hiworld",
      ];
      sessionRestore.appendBundles(fileData.fd, restoreApps, (err: BusinessError) => {
        if (err) {
          console.error('appendBundles failed with err: ' + JSON.stringify(err));
          return;
        }
        console.info('appendBundles success');
      });
    } catch (error) {
      let err: BusinessError = error as BusinessError;
      console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err));
    } finally {
      fs.closeSync(fileData.fd);
    }
  }

appendBundles

appendBundles(remoteCapabilitiesFd: number, bundlesToBackup: string[], infos?: string[]): Promise&lt;void&gt;

Appends the applications whose data needs to be restored. From API version 12, the optional parameter infos is added to carry information about each application to be restored. The mappings between infos and bundlesToBackup are identified by index. Currently, the obtained SessionRestore instance can be called only once in the entire restore process. This API uses a promise to return the result.

NOTE

  • During the data restore, the capability file needs to be verified.
  • You can use getLocalCapabilities to obtain remoteCapabilitiesFd, and modify the parameters based on the application to be restored. You can also use the JSON file example provided by getLocalCapabilities to generate a capability file.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
remoteCapabilitiesFd number Yes FD of the file containing the capabilities to be restored.
bundlesToBackup string[] Yes Array of the application names to append.
infos12+ string[] No Array of the information about each application to be restored. The mappings between infos and bundlesToBackup are identified by index. It is left blank by default. This parameter is supported since API version 12.

Return value

Type Description
Promise&lt;void&gt; Promise that returns no value.

Error codes

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

ID Error Message
13600001 IPC error.
13900001 Operation not permitted.
13900005 I/O error.
13900011 Out of memory.
13900020 Invalid argument.
13900025 No space left on device.
13900042 Unknown error.

Example

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

  let generalCallbacks: backup.GeneralCallbacks = {
    onFileReady: (err: BusinessError, file: backup.File) => {
      if (err) {
        console.error('onFileReady failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onAllBundlesEnd success');
    },
    onBackupServiceDied: () => {
      console.info('service died');
    },
    onResultReport: (bundleName: string, result: string) => {
      console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
    },
    onProcess: (bundleName: string, process: string) => {
      console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
    }
  };
  let sessionRestore = new backup.SessionRestore(generalCallbacks); // Create a restore process.
  async function appendBundles() {
    let fileData : backup.FileData = {
      fd : -1
    }
    try {
      fileData = await backup.getLocalCapabilities();
      console.info('getLocalCapabilities success');
      let restoreApps: Array<string> = [
        "com.example.hiworld",
      ];
      await sessionRestore.appendBundles(fileData.fd, restoreApps);
      console.info('appendBundles success');
      // Information of the applications to restore.
      let infos: Array<string> = [
        `
         {
          "infos":[
            {
              "details": [
                {
                  "detail": [
                    {
                      "source": "com.example.hiworld", // Old bundle name of the application.
                      "target": "com.example.helloworld" // New bundle name of the application.
                    }
                  ],
                  "type": "app_mapping_relation"
                }
              ],
              "type":"broadcast"
            }
          ]
         }
        `
      ]
      await sessionRestore.appendBundles(fileData.fd, restoreApps, infos);
      console.info('appendBundles success');
    } catch (error) {
      let err: BusinessError = error as BusinessError;
      console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err));
    } finally {
      fs.closeSync(fileData.fd);
    }
  }

getFileHandle

getFileHandle(fileMeta: FileMeta, callback: AsyncCallback&lt;void&gt;): void

Obtains the handle to the shared file from the service. This API uses an asynchronous callback to return the result.

NOTE

  • This interface is part of the zero-copy feature, which reduces unnecessary memory copies and increases transmission efficiency. For details about the zero-copy methods, see the zero-copy APIs such as fs.copyFile provided by @ohos.file.fs.
  • Before using getFileHandle, you need to obtain a SessionRestore instance and add the applications with data to be restored by using appendBundles.
  • You can use onFileReady to obtain the file handle. When file operations are completed at the client, you need to use publishFile to publish the file.
  • getFileHandle can be called multiple times based on the number of files to be restored.
  • File to be restored cannot be a relative path (../) or soft link.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
fileMeta FileMeta Yes Metadata of the file to restore.
callback AsyncCallback&lt;void&gt; Yes Callback used to return the result.

Error codes

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

ID Error Message
13600001 IPC error.
13900001 Operation not permitted.
13900020 Invalid argument.
13900042 Unknown error.

Example

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

  let generalCallbacks: backup.GeneralCallbacks = {
    onFileReady: (err: BusinessError, file: backup.File) => {
      if (err) {
        console.error('onFileReady failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onAllBundlesEnd success');
    },
    onBackupServiceDied: () => {
      console.info('service died');
    },
    onResultReport: (bundleName: string, result: string) => {
      console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
    },
    onProcess: (bundleName: string, process: string) => {
      console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
    }
  };
  let sessionRestore = new backup.SessionRestore(generalCallbacks); // Create a restore process.
  let fileMeta: backup.FileMeta = {
    bundleName: "com.example.hiworld",
    uri: "test.txt"
  }
  sessionRestore.getFileHandle(fileMeta, (err: BusinessError) => {
    if (err) {
      console.error('getFileHandle failed with err: ' + JSON.stringify(err));
    }
    console.info('getFileHandle success');
  });

getFileHandle

getFileHandle(fileMeta: FileMeta): Promise&lt;void&gt;

Obtains the handle to the shared file from the service. This API uses a promise to return the result.

NOTE

  • This interface is part of the zero-copy feature, which reduces unnecessary memory copies and increases transmission efficiency. For details about the zero-copy methods, see the zero-copy APIs such as fs.copyFile provided by @ohos.file.fs.
  • Before using getFileHandle, you need to obtain a SessionRestore instance and add the applications with data to be restored by using appendBundles.
  • You can use onFileReady to obtain the file handle. When file operations are completed at the client, you need to use publishFile to publish the file.
  • getFileHandle can be called multiple times based on the number of files to be restored.
  • File to be restored cannot be a relative path (../) or soft link.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
fileMeta FileMeta Yes Metadata of the file to restore.

Return value

Type Description
Promise&lt;void&gt; Promise that returns no value.

Error codes

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

ID Error Message
13600001 IPC error.
13900001 Operation not permitted.
13900020 Invalid argument.
13900042 Unknown error.

Example

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

  let generalCallbacks: backup.GeneralCallbacks = {
    onFileReady: (err: BusinessError, file: backup.File) => {
      if (err) {
        console.error('onFileReady failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onAllBundlesEnd success');
    },
    onBackupServiceDied: () => {
      console.info('service died');
    },
    onResultReport: (bundleName: string, result: string) => {
      console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
    },
    onProcess: (bundleName: string, process: string) => {
      console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
    }
  };
  let sessionRestore = new backup.SessionRestore(generalCallbacks); // Create a restore process.
  async function getFileHandle() {
    try {
      let fileMeta: backup.FileMeta = {
        bundleName: "com.example.hiworld",
        uri: "test.txt"
      }
      await sessionRestore.getFileHandle(fileMeta);
      console.info('getFileHandle success');
    } catch (error) {
      let err: BusinessError = error as BusinessError;
      console.error('getFileHandle failed with err: ' + JSON.stringify(err));
    }
  }

publishFile

publishFile(fileMeta: FileMeta, callback: AsyncCallback&lt;void&gt;): void

Publishes FileMeta to the backup service to indicate that the file content is ready. This API uses an asynchronous callback to return the result.

NOTE

  • This interface is part of the zero-copy feature, which reduces unnecessary memory copies and increases transmission efficiency. For details about the zero-copy methods, see the zero-copy APIs such as fs.copyFile provided by @ohos.file.fs.
  • After the server returns a file handle through onFileReady, the client can copy data to the file corresponding to the file handle provided by the server through zero-copy operations.
  • This API can be called only after the caller has written all the data to be restored. The caller must ensure the consistency and integrity of the data to be written.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
fileMeta FileMeta Yes Metadata of the file to restore.
callback AsyncCallback&lt;void&gt; Yes Callback used to return the result.

Error codes

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

ID Error Message
13600001 IPC error.
13900001 Operation not permitted.
13900020 Invalid argument.
13900042 Unknown error.

Example

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

  let g_session: backup.SessionRestore;
  let initMap = new Map<string, number>();
  let testFileNum = 123; // Number of files required for the restore.
  let testBundleName = 'com.example.myapplication'; // Test bundle name.
  initMap.set(testBundleName, testFileNum);
  let countMap = new Map<string, number>();
  countMap.set(testBundleName, 0); // Initialize the number of files written.
  function createSessionRestore() {
    let generalCallbacks: backup.GeneralCallbacks = {
      onFileReady: (err: BusinessError, file: backup.File) => {
        if (err) {
          console.error('onFileReady failed with err: ' + JSON.stringify(err));
          return;
        }
        console.info('onFileReady success');
        fs.closeSync(file.fd);
        countMap[file.bundleName]++; // Update the number of files written.
        // Called only when the number of files to be restored is the same as the number of files actually written. This ensures data consistency and integrity.
        if (countMap[file.bundleName] == initMap[file.bundleName]) { // Trigger publishFile when all the files of each package are received.
          let fileMeta: backup.FileMeta = {
            bundleName: file.bundleName,
            uri: ''
          }
          g_session.publishFile(fileMeta, (err: BusinessError) => {
            if (err) {
              console.error('publishFile failed with err: ' + JSON.stringify(err));
              return;
            }
            console.info('publishFile success');
          });
        }
      },
      onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
        if (err) {
          console.error('onBundleBegin failed with err: ' + JSON.stringify(err));
          return;
        }
        console.info('onBundleBegin success');
      },
      onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
        if (err) {
          console.error('onBundleEnd failed with err: ' + JSON.stringify(err));
          return;
        }
        console.info('onBundleEnd success');
      },
      onAllBundlesEnd: (err: BusinessError) => {
        if (err) {
          console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
          return;
        }
        console.info('onAllBundlesEnd success');
      },
      onBackupServiceDied: () => {
        console.info('service died');
      },
      onResultReport: (bundleName: string, result: string) => {
        console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
      },
      onProcess: (bundleName: string, process: string) => {
       console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
      }
    };
    let sessionRestore = new backup.SessionRestore(generalCallbacks); // Create a restore process.
    return sessionRestore;
  }
  g_session = createSessionRestore();

publishFile

publishFile(fileMeta: FileMeta): Promise&lt;void&gt;

Publishes FileMeta to the backup service to indicate that the file content is ready. This API uses a promise to return the result.

NOTE

  • This interface is part of the zero-copy feature, which reduces unnecessary memory copies and increases transmission efficiency. For details about the zero-copy methods, see the zero-copy APIs such as fs.copyFile provided by @ohos.file.fs.
  • After the server returns a file handle through onFileReady, the client can copy data to the file corresponding to the file handle provided by the server through zero-copy operations.
  • This API can be called only after the caller has written all the data to be restored. The caller must ensure the consistency and integrity of the data to be written.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
fileMeta FileMeta Yes Metadata of the file to restore.

Return value

Type Description
Promise&lt;void&gt; Promise that returns no value.

Error codes

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

ID Error Message
13600001 IPC error.
13900001 Operation not permitted.
13900020 Invalid argument.
13900042 Unknown error.

Example

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

  let g_session: backup.SessionRestore;
  let initMap = new Map<string, number>();
  let testFileNum = 123; // Number of files required for the restore.
  let testBundleName = 'com.example.myapplication'; // Test bundle name.
  initMap.set(testBundleName, testFileNum);
  let countMap = new Map<string, number>();
  countMap.set(testBundleName, 0); // Initialize the number of files written.
  async function publishFile(file: backup.FileMeta) {
    let fileMeta: backup.FileMeta = {
      bundleName: file.bundleName,
      uri: ''
    }
    await g_session.publishFile(fileMeta);
  }
  function createSessionRestore() {
    let generalCallbacks: backup.GeneralCallbacks = {
      onFileReady: (err: BusinessError, file: backup.File) => {
        if (err) {
          console.error('onFileReady failed with err: ' + JSON.stringify(err));
          return;
        }
        console.info('onFileReady success');
        fs.closeSync(file.fd);
        countMap[file.bundleName]++; // Update the number of files written.
        // Called only when the number of files to be restored is the same as the number of files actually written. This ensures data consistency and integrity.
        if (countMap[file.bundleName] == initMap[file.bundleName]) { // Trigger publishFile when all the files of each package are received.
          publishFile(file);
        }
        console.info('publishFile success');
      },
      onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
        if (err) {
          console.error('onBundleBegin failed with err: ' + JSON.stringify(err));
          return;
        }
        console.info('onBundleBegin success');
      },
      onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
        if (err) {
          console.error('onBundleEnd failed with err: ' + JSON.stringify(err));
          return;
        }
        console.info('onBundleEnd success');
      },
      onAllBundlesEnd: (err: BusinessError) => {
        if (err) {
          console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
          return;
        }
        console.info('onAllBundlesEnd success');
      },
      onBackupServiceDied: () => {
        console.info('service died');
      },
      onResultReport: (bundleName: string, result: string) => {
        console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
      },
      onProcess: (bundleName: string, process: string) => {
        console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
      }
    };
    let sessionRestore = new backup.SessionRestore(generalCallbacks); // Create a restore process.
    return sessionRestore;
  }
  g_session = createSessionRestore();

release12+

release(): Promise&lt;void&gt;

Releases the restore session when the restore process is complete. This API disconnects the application from the backup and restore service and exits the service. This API uses a promise to return the result.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Return value

Type Description
Promise&lt;void&gt; Promise that returns no value.

Error codes

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

ID Error Message
201 Permission verification failed, usually the result returned by VerifyAccessToken.
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.
13600001 IPC error.
13900001 Operation not permitted.
13900005 I/O error.
13900042 Unknown error.

Example

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

  let g_session: backup.SessionRestore;
  let initMap = new Map<string, number>();
  let testFileNum = 123; // Number of files required for the restore.
  let testBundleName = 'com.example.myapplication'; // Test bundle name.
  initMap.set(testBundleName, testFileNum);
  let countMap = new Map<string, number>();
  countMap.set(testBundleName, 0); // Initialize the number of files written.
  function createSessionRestore() {
    let generalCallbacks: backup.GeneralCallbacks = {
      onFileReady: (err: BusinessError, file: backup.File) => {
        if (err) {
          console.error('onFileReady failed with err: ' + JSON.stringify(err));
          return;
        }
        console.info('onFileReady success');
        fs.closeSync(file.fd);
        countMap[file.bundleName]++; // Update the number of files written.
        // Called only when the number of files to be restored is the same as the number of files actually written. This ensures data consistency and integrity.
        if (countMap[file.bundleName] == initMap[file.bundleName]) { // Trigger publishFile when all the files of each package are received.
          let fileMeta: backup.FileMeta = {
            bundleName: file.bundleName,
            uri: ''
          }
          g_session.publishFile(fileMeta, (err: BusinessError) => {
            if (err) {
              console.error('publishFile failed with err: ' + JSON.stringify(err));
              return;
            }
            console.info('publishFile success');
          });
        }
      },
      onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
        if (err) {
          console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
          return;
        }
        console.info('onBundleBegin success');
      },
      onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
        if (err) {
          console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
          return;
        }
        console.info('onBundleEnd success');
      },
      onAllBundlesEnd: (err: BusinessError) => {
        if (err) {
          console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
          return;
        }
        console.info('onAllBundlesEnd success');
      },
      onBackupServiceDied: () => {
        console.info('service died');
      },
      onResultReport: (bundleName: string, result: string) => {
        console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
      },
      onProcess: (bundleName: string, process: string) => {
        console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
      }
    };
    let sessionRestore = new backup.SessionRestore(generalCallbacks); // Create a restore process.
    return sessionRestore;
  }
  g_session = createSessionRestore();
  g_session.release();
  console.info('release success');

cancel18+

cancel(bundleName: string): number

Cancels the restoration of an application when data exceptions occur.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
bundleName string Yes Application name.

Return value

Type Description
number Cancelled.
0: The task is successfully cancelled.
13500011: The task to be cancelled is not started.
13500012: The task to be cancelled does not exist.

Error codes

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

ID Error Message
201 Permission verification failed, usually the result returned by VerifyAccessToken.
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.

Example

  import fs from '@ohos.file.fs';
  import { BusinessError } from '@ohos.base';
  import backup from '@ohos.file.backup';

  let generalCallbacks: backup.GeneralCallbacks = {
    onFileReady: (err: BusinessError, file: backup.File) => {
      if (err) {
        // If the FD fails to be passed, call the cancel API to cancel the restoration task of the application.
        let result = sessionRestore.cancel(err.name);
        console.info('cancel result:' + result);
        console.error('onFileReady failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onAllBundlesEnd success');
    },
    onBackupServiceDied: () => {
      console.info('service died');
    },
    onResultReport: (bundleName: string, result: string) => {
      console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
    },
    onProcess: (bundleName: string, process: string) => {
      console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
    }
  };
  let sessionRestore = new backup.SessionRestore(generalCallbacks); // Create a restore process.
  let fileData: backup.FileData = {
    fd: -1
  }
  fileData = await backup.getLocalCapabilities(); // Call getLocalCapabilities provided by the backup and restore framework to obtain the capability set file.
  let backupBundles: Array<string> = ["com.example.helloWorld"];
  sessionRestore.appendBundles(fileData.fd, backupBundles);

IncrementalBackupSession12+

An object used to implement the incremental backup of applications. Before using the APIs of this class, you need to create an IncrementalBackupSession instance.

constructor12+

constructor(callbacks: GeneralCallbacks)

A constructor used to create an IncrementalBackupSession instance.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
callback GeneralCallbacks Yes Callbacks to be invoked during the incremental backup process.

Error codes

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

ID Error Message
201 Permission verification failed, usually the result returned by VerifyAccessToken.
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.

Example

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

  let generalCallbacks: backup.GeneralCallbacks = {
    onFileReady: (err: BusinessError, file: backup.File) => {
      if (err) {
        console.error('onFileReady failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
        return;
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
        return;
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onAllBundlesEnd success');
    },
    onBackupServiceDied: () => {
      console.info('service died');
    },
    onResultReport: (bundleName: string, result: string) => {
      console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
    },
    onProcess: (bundleName: string, process: string) => {
      console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
    }
  };
  let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // Create a session for an incremental backup.

getLocalCapabilities18+

getLocalCapabilities(): Promise&lt;FileData&gt;

Obtains a JSON file that describes local capabilities in the incremental backup service. This API uses a promise to return the result.

Required permissions: ohos.permission.BACKUP

System API: This is a system API.

System capability: SystemCapability.FileManagement.StorageService.Backup

Return value

Type Description
Promise&lt;FileData&gt; Promise FileData object obtained.

Error codes

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

ID Error Message
201 Permission verification failed, usually the result returned by VerifyAccessToken.
202 Permission verification failed, application which is not a system application uses system API.
13600001 IPC error.
13900001 Operation not permitted.
13900020 Invalid argument.
13900042 Internal error.

Example

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

  interface test { // Parse the capability file.
    bundleInfos: [];
    deviceType: string;
    systemFullName: string;
  }

  interface BundleInfo { // Obtain the local capability information of an application.
    name: string;
    appIndex: number;
    versionCode: number;
    versionName: string;
    spaceOccupied: number;
    allToBackup: boolean;
    increSpaceOccupied?: number;
    fullBackupOnly: boolean;
    extensionName: string;
    restoreDeps: string;
    supportScene: string;
    extraInfo: object;
  }

  let generalCallbacks: backup.GeneralCallbacks = { // Define general callbacks to be used in the backup or restore process.
    onFileReady: (err: BusinessError, file: backup.File) => {
      if (err) {
        console.error('onFileReady failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
        return;
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
        return;
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onAllBundlesEnd success');
    },
    onBackupServiceDied: () => {
      console.info('service died');
    },
    onResultReport: (bundleName: string, result: string) => {
      console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
    },
    onProcess: (bundleName: string, process: string) => {
      console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
    }
  };
  let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // Create a session for an incremental backup.
  let basePath = '/data/storage/el2/base/backup';
  let path = basePath + '/localCapabilities.json'; // Local path for storing capability files.
  try {
    let fileData = await incrementalBackupSession.getLocalCapabilities(); // Obtain the local capability file.
    if (fileData) {
      console.info('getLocalCapabilities success');
      console.info('fileData info:' + fileData.fd);
      if (!fs.accessSync(basePath)) {
        fs.mkdirSync(basePath);
        console.info('creat success' + basePath);
      }
      fs.copyFileSync(fileData.fd, path); // Save the obtained local capability file to the local host.
      fs.closeSync(fileData.fd);
    }
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('getLocalCapabilities failed with err: ' + JSON.stringify(err));
  }
  let data = await fs.readTextSync(path, 'utf8'); // Obtain information from the local capability file.
  try {
    const jsonsObj: test|null = JSON.parse(data); // Parse the local capability file and print some information.
    if (jsonsObj) {
      const infos:BundleInfo [] = jsonsObj.bundleInfos;
      for (let i = 0; i < infos.length; i++) {
        console.info('name: ' + infos[i].name);
        console.info('appIndex: ' + infos[i].appIndex);
        console.info('allToBackup: ' + infos[i].allToBackup);
      }
      const systemFullName: string = jsonsObj.systemFullName;
      console.info('systemFullName: ' + systemFullName);
      const deviceType: string = jsonsObj.deviceType;
      console.info('deviceType: ' + deviceType);
    }
  } catch (error) {
    console.error('parse failed with err: ' + JSON.stringify(error));
  }

The capability file can be obtained by using fs.stat of the @ohos.file.fs module. The following is an example of the capability file.

 {
  "backupVersion" : "16.0",
  "bundleInfos" :[{
    "allToBackup" : true,
    "extensionName" : "BackupExtensionAbility",
    "name" : "com.example.hiworld",
    "needToInstall" : false,
    "spaceOccupied" : 0,
    "versionCode" : 1000000,
    "versionName" : "1.0.0"
    }],
  "deviceType" : "default",
  "systemFullName" : "OpenHarmony-4.0.0.0"
 }

getBackupDataSize18+

getBackupDataSize(isPreciseScan: boolean, dataList: Array<IncrementalBackupTime>): Promise&lt;void&gt;

Obtains the amount of data to be backed up. This method is called before appendBundles. The scanning result is returned at a fixed interval of 5 seconds by calling the general callback onBackupSizeReport asynchronously until all application data in the datalist is returned.

Required permissions: ohos.permission.BACKUP

System API: This is a system API.

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
isPreciseScan boolean Yes Whether to perform accurate scanning. The value true means to perform accurate scanning; the value false means to perform inaccurate scanning. Inaccurate scanning is fast and is used to estimate the data size. Accurate scanning is slow and returns more accurate result. However, the data to be backed up may change. Therefore, the precise scanning result may not match the actual backup data size.
dataList Array<IncrementalBackupTime> Yes Backup application list, which describes the application whose data size is to be obtained and the last backup time. For a full backup, set this parameter to 0.

Return value

Type Description
Promise&lt;void&gt; Promise that returns no value.

Error codes

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

ID Error Message
201 Permission verification failed, usually the result returned by VerifyAccessToken.
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.
13600001 IPC error.
13900001 Operation not permitted.
13900020 Invalid argument.
13900042 Internal error.

Example

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

  interface scanedInfos { // Parse the scanning result.
    scaned: [];
    scanning: string;
  }

  interface ScanedInfo { // Parse the scanning result of an application.
    bundleName: string;
    dataSize: number;
    incDataSize: number;
  }

  let generalCallbacks: backup.GeneralCallbacks = {
    onFileReady: (err: BusinessError, file: backup.File) => { // Define the universal callbacks to be used in the backup or restore process.
      if (err) {
        console.error('onFileReady failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
        return;
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
        return;
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onAllBundlesEnd success');
    },
    onBackupServiceDied: () => {
      console.info('service died');
    },
    onResultReport: (bundleName: string, result: string) => {
      console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
    },
    onProcess: (bundleName: string, process: string) => {
      console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
    },
    onBackupSizeReport: (OnBackupSizeReport) => { // The callback function is used together with getBackupDataSize to return the obtained application data size and the bundle name of the application that is obtaining the data size.
      console.info('dataSizeCallback success');
      const jsonObj: scanedInfos|null = JSON.parse(OnBackupSizeReport); // Parse and print the returned information.
      if (jsonObj) {
        const infos: ScanedInfo [] = jsonObj.scaned;
        for (let i = 0; i < infos.length; i++) {
          console.info('name: ' + infos[i].bundleName);
          console.info('dataSize: ' + infos[i].dataSize);
          console.info('incDataSize: ' + infos[i].incDataSize);
        }
        const scanning: string = jsonObj.scanning;
        console.info('scanning: ' + scanning);
      }
    }
  };

  let incrementalBackupSession = new backup.incrementalBackupSession(generalCallbacks); // Create a session for an incremental backup.

  let backupApps: backup.IncrementalBackupTime[] = [{
    bundleName: "com.example.hiworld",
    lastIncrementalTime: 1700107870 // Time of the last incremental backup.
  }];
  try {
    incrementalBackupSession.getBackupDataSize(true, backupApps); // Obtain the amount of specified application data to be backed up in backupApps. The value true indicates that accurate scanning is used.
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('getBackupDataSize failed with err: ' + JSON.stringify(err));
  }

Example of a JSON string returned asynchronously:

{
 "scaned" :[ // Scanned application. The result will not be returned in the next callback.
     {
         "name": "com.example.hiworld", // Application name.
         "dataSize": 1006060, // Data size.
         "incDataSize": 50800 // Incremental data size.
     },
     {
         "name": "com.example.myAPP",
         "dataSize": 5000027,
         "incDataSize": 232344
     }
 ],
 "scanning" :"com.example.smartAPP" // Application that is being scanned. This field is empty when the last result is returned.
}

appendBundles12+

appendBundles(bundlesToBackup: Array&lt;IncrementalBackupData&gt;): Promise&lt;void&gt;

Appends applications that require incremental backup. In the current process, appendBundles can be called before Release() is called. This API uses a promise to return the result.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
bundlesToBackup Array&lt;IncrementalBackupData&gt; Yes Array of applications that require incremental backup.

Return value

Type Description
Promise&lt;void&gt; Promise that returns no value.

Error codes

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

ID Error Message
201 Permission verification failed, usually the result returned by VerifyAccessToken.
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.
13600001 IPC error.
13900001 Operation not permitted.
13900005 I/O error.
13900011 Out of memory.
13900020 Invalid argument.
13900025 No space left on device.
13900042 Unknown error.

Example

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

  let generalCallbacks: backup.GeneralCallbacks = {
    onFileReady: (err: BusinessError, file: backup.File) => {
      if (err) {
        console.error('onFileReady failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
        return;
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
        return;
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onAllBundlesEnd success');
    },
    onBackupServiceDied: () => {
      console.info('service died');
    },
    onResultReport: (bundleName: string, result: string) => {
      console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
    },
    onProcess: (bundleName: string, process: string) => {
      console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
    }
  };
  let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // Create a session for an incremental backup.
  let incrementalBackupData: backup.IncrementalBackupData = {
    bundleName: "com.example.hiworld",
    lastIncrementalTime: 1700107870, // Timestamp of the last backup.
    manifestFd:1 // FD of the manifest file of the last backed.
  }
  let incrementalBackupDataArray: backup.IncrementalBackupData[] = [incrementalBackupData];
  incrementalBackupSession.appendBundles(incrementalBackupDataArray).then(() => {
    console.info('appendBundles success');
  }).catch((err: BusinessError) => {
    console.error('appendBundles failed with err: ' + JSON.stringify(err));
  }); // Appends the applications that require incremental backup.

appendBundles12+

appendBundles(bundlesToBackup: Array&lt;IncrementalBackupData&gt;, infos: string[]): Promise&lt;void&gt;

Appends applications that require incremental backup. In the current process, appendBundles can be called before Release() is called. This API uses a promise to return the result.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
bundlesToBackup Array&lt;IncrementalBackupData&gt; Yes Array of applications that require incremental backup.
infos string[] Yes Array of the information about each application to be backed up. The mappings between infos and bundlesToBackup are identified by index. This parameter is supported since API version 12.

Return value

Type Description
Promise&lt;void&gt; Promise that returns no value.

Error codes

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

ID Error Message
201 Permission verification failed, usually the result returned by VerifyAccessToken.
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.
13600001 IPC error.
13900001 Operation not permitted.
13900005 I/O error.
13900011 Out of memory.
13900020 Invalid argument.
13900025 No space left on device.
13900042 Unknown error.

Example

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

  let generalCallbacks: backup.GeneralCallbacks = {
    onFileReady: (err: BusinessError, file: backup.File) => {
      if (err) {
        console.error('onFileReady failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
        return;
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
        return;
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onAllBundlesEnd success');
    },
    onBackupServiceDied: () => {
      console.info('service died');
    },
    onResultReport: (bundleName: string, result: string) => {
      console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
    },
    onProcess: (bundleName: string, process: string) => {
      console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
    }
  };
  let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // Create a session for an incremental backup.
  let incrementalBackupData: backup.IncrementalBackupData = {
    bundleName: "com.example.hiworld",
    lastIncrementalTime: 1700107870, // Timestamp of the last backup.
    manifestFd:1 // FD of the manifest file of the last backed.
  }
      let infos: Array<string> = [
        `
        {
        "infos": [
            {
                "details": [
                    {
                        "detail": [
                            {
                                "key1": "value1",
                                "key2": "value2"
                            }
                        ]
                    }
                ],
                "type": "unicast",
                "bundleName": "com.example.hiworld"
            }
        ]
    },
    {
        "infos": [
            {
                "details": [
                    {
                        "detail": [
                            {
                                "key1": "value1",
                                "key2": "value2"
                            }
                        ]
                    }
                ],
                "type": "unicast",
                "bundleName": "com.example.myApp"
            }
        ]
    }
      `
    ]
  let incrementalBackupDataArray: backup.IncrementalBackupData[] = [incrementalBackupData];
  // Appends the applications that require incremental backup.
  incrementalBackupSession.appendBundles(incrementalBackupDataArray, infos).then(() => {
    console.info('appendBundles success');
  }).catch((err: BusinessError) => {
    console.error('appendBundles failed with err: ' + JSON.stringify(err));
  });

release12+

release(): Promise&lt;void&gt;

Releases the session for the incremental backup. This API uses a promise to return the result.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Return value

Type Description
Promise&lt;void&gt; Promise that returns no value.

Error codes

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

ID Error Message
201 Permission verification failed, usually the result returned by VerifyAccessToken.
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.
13600001 IPC error.
13900001 Operation not permitted.
13900005 I/O error.
13900020 Invalid argument.
13900042 Unknown error.

Example

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

  let generalCallbacks: backup.GeneralCallbacks = {
    onFileReady: (err: BusinessError, file: backup.File) => {
      if (err) {
        console.error('onFileReady failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
        return;
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err.code: ' + JSON.stringify(err.code) + err.data);
        return;
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onAllBundlesEnd success');
    },
    onBackupServiceDied: () => {
      console.info('service died');
    },
    onResultReport: (bundleName: string, result: string) => {
      console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
    },
    onProcess: (bundleName: string, process: string) => {
      console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
    }
  };
  let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // Create a session for an incremental backup.
  incrementalBackupSession.release(); // End the incremental backup process.
  console.info('release success');

cancel18+

cancel(bundleName: string): number

Cancels the incremental backup of an application when data exceptions occur.

Required permissions: ohos.permission.BACKUP

System capability: SystemCapability.FileManagement.StorageService.Backup

Parameters

Name Type Mandatory Description
bundleName string Yes Application name.

Return value

Type Description
number Cancelled.
0: The task is successfully cancelled.
13500011: The task to be cancelled is not started.
13500012: The task to be cancelled does not exist.

Error codes

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

ID Error Message
201 Permission verification failed, usually the result returned by VerifyAccessToken.
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verifcation faild.

Example

  import fs from '@ohos.file.fs';
  import { BusinessError } from '@ohos.base';
  import backup from '@ohos.file.backup';

  let generalCallbacks: backup.GeneralCallbacks = {
    onFileReady: (err: BusinessError, file: backup.File) => {
      if (err) {
        // If the FD fails to be passed, call the cancel API to cancel the incremental backup task of the application.
        let result = incrementalBackupSession.cancel(err.name);
        console.info('cancel result:' + result);
        console.error('onFileReady failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleBegin failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error('onBundleEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + JSON.stringify(err));
        return;
      }
      console.info('onAllBundlesEnd success');
    },
    onBackupServiceDied: () => {
      console.info('service died');
    },
    onResultReport: (bundleName: string, result: string) => {
      console.info('onResultReport success, bundleName: ' + bundleName +'result: ' + result);
    },
    onProcess: (bundleName: string, process: string) => {
      console.info('onProcess success, bundleName: ' + bundleName +'process: ' + process);
    }
  };
  let incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); // Create a session for an incremental backup.
  let backupBundles: Array<backup.IncrementalBackupData> = [];
  let bundleData: backup.IncrementalBackupData = {
    bundleName: "com.example.helloWorld",
    lastIncrementalTime: 1700107870, // Timestamp of the last backup.
    manifestFd: 1 // FD of the manifest file of the last backup.
  }
  backupBundles.push(bundleData);
  incrementalBackupSession.appendBundles(backupBundles);

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Core File Kit

harmony 鸿蒙Environment

harmony 鸿蒙FileIO

harmony 鸿蒙FileShare_PolicyErrorResult

harmony 鸿蒙FileShare_PolicyInfo

harmony 鸿蒙error_code.h

harmony 鸿蒙File Management Error Codes

harmony 鸿蒙FileShare

harmony 鸿蒙FileUri

harmony 鸿蒙@ohos.application.BackupExtensionAbility (Backup and Restore Extension Capability) (System API)

0  赞
  • 所属分类： 后端技术
  • 本文标签：
  • 版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/maRcno
热门推荐
标签云
Linux Java Spring Spring Boot docker 大数据 前端 生活 maven golang 软件 spring cloud fintech mac vscode 其他 区块链 以太坊 V神 开发者 技术 股票 git greenplum 分布式事务 chrome mysql flink kafka 设计模式 原理 鸿蒙 seo
最新文章
本文目录