harmony 鸿蒙@ohos.file.backup (备份恢复)(系统接口)

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

@ohos.file.backup (备份恢复)(系统接口)

该模块为应用提供备份/恢复数据的能力。

说明：

  • 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
  • 本模块为系统接口。

导入模块

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

FileMeta

文件的元数据，包含一个应用名称以及文件uri。FileMeta在执行备份/恢复时是不可缺少的对象。

系统能力：SystemCapability.FileManagement.StorageService.Backup

名称 类型 必填 说明
bundleName string 是 应用名称，可通过bundleManager.BundleInfo提供的获取方式获取。
uri string 是 应用沙箱内待传输文件的名称，当前uri尚未升级为标准格式，仅接受0-9a-zA-Z下划线(_)点(.)组成的名称。

FileData

文件的元数据，包含一个已经打开的文件描述符。FileData在执行备份/恢复时是不可缺少的对象。

说明：

FileData使用完成后必须关闭，如不关闭会出现内存泄露问题。关闭的方法可参考由@ohos.file.fs提供的fs.closeSync等相关关闭接口。

系统能力：SystemCapability.FileManagement.StorageService.Backup

名称 类型 必填 说明
fd number 是 已经打开的文件描述符，通过备份服务获取。

FileManifestData12+

文件的元数据，包含一个已经打开的文件描述符。FileManifestData所打开的内容是一个清单文件，用于描述应用增量备份/恢复时对应文件的基础信息。FileManifestData在执行增量备份/恢复时是不可缺少的对象。

说明：

关闭的方法可参考fs.closeSync等关闭接口。

系统能力：SystemCapability.FileManagement.StorageService.Backup

名称 类型 必填 说明
manifestFd number 是 已经打开的文件描述符，通过备份服务获取。

IncrementalBackupTime12+

用于记录最后一次的增量备份时间，用于描述备份增量的时间点。

系统能力：SystemCapability.FileManagement.StorageService.Backup

名称 类型 必填 说明
bundleName string 是 应用名称，可通过bundleManager.BundleInfo提供的获取方式获取。
lastIncrementalTime number 是 最后一次的增量备份时间。

BackupParams12+

为备份恢复提供可选配置参数以json格式的字符串形式存在。

系统能力：SystemCapability.FileManagement.StorageService.Backup

名称 类型 必填 说明
parameters string 否 以json格式为配置项的字符串，为备份恢复提供可选选项。默认为空。

BackupPriority12+

为备份恢复提供优先级配置。

系统能力：SystemCapability.FileManagement.StorageService.Backup

名称 类型 必填 说明
priority number 否 数值越大优先级越高；优先级相同的情况下，先调用的先执行。默认为0。

IncrementalBackupData12+

一次增量备份对象。继承IncrementalBackupTime，FileManifestData，BackupParams，BackupPriority。

说明：

记录应用最后一次的增量时间以及增量备份清单文件的文件描述符，清单文件中记录着增量时间内已备份的文件信息。可选参数包含了备份恢复的可选配置项，优先级配置项。

系统能力：SystemCapability.FileManagement.StorageService.Backup

File

一个文件对象。 继承FileMeta和FileData。

说明：

file.backup.File与@ohos.file.fs中的提供的File是带有不同的涵义，前者是继承FileMeta和FileData的对象而后者只有一个文件描述符的对象。请注意区分，不要混淆。

系统能力：SystemCapability.FileManagement.StorageService.Backup

File12+

一个文件对象。 继承FileMeta和FileData和FileManifestData。

说明：

file.backup.File与@ohos.file.fs中的提供的File是带有不同的涵义，前者是继承FileMeta和FileData的对象而后者只有一个文件描述符的对象。请注意区分，不要混淆。

系统能力：SystemCapability.FileManagement.StorageService.Backup

GeneralCallbacks

备份/恢复过程中的通用回调，备份服务将通过这些回调通知客户端其应用的备份/恢复阶段。

系统能力：SystemCapability.FileManagement.StorageService.Backup

属性

系统能力：SystemCapability.FileManagement.StorageService.Backup

名称 类型 只读 可选 说明
onBackupSizeReport18+ OnBackupSizeReport 否 是 框架获取到的待备份的数据量大小的信息。

onFileReady

onFileReady : AsyncCallback<File>

回调函数。当服务端返向客户端发送文件，如果成功触发回调，返回对应文件的File内容；如果触发失败，则返回err错误对象。

说明：

AsyncCallback回调中返回的File所属file.backup.File类型。返回的文件归备份服务所有，一旦文件关闭，备份服务将选择合适的时机去清理，但客户端必须关闭文件句柄。

系统能力：SystemCapability.FileManagement.StorageService.Backup

返回值：

参数名 类型 必填 说明
File File 是 返回对应文件的File内容。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
13600001 IPC error.
13900005 I/O error.
13900011 Out of memory.
13900020 Invalid argument.
13900025 No space left on device.
13900042 Unknown error.

示例：

  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>

回调函数。当应用备份/恢复开始时，如果成功触发回调，返回对应的bundleName；如果触发失败，则返回err错误对象。从API version 12开始，返回err的同时，将同时返回第二个string参数bundleName。

系统能力：SystemCapability.FileManagement.StorageService.Backup

返回值：

参数名 类型 必填 说明
bundleName string 是 服务返回的应用名称。
err BusinessError 否 当发生err时，为错误对象；否则为undefined data为bundle名称。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
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.

示例：

  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;

回调函数。当应用备份/恢复结束后，如果成功触发回调，返回对应的bundleName；如果触发失败，则返回err错误对象。从API version 12开始，返回err的同时，将同时返回第二个string参数bundleName。

系统能力：SystemCapability.FileManagement.StorageService.Backup

返回值：

参数名 类型 必填 说明
bundleName string 是 服务返回的应用名称。
err BusinessError 否 当发生err时，为错误对象，否则为undefined data为bundle名称。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
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.

示例：

  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;

回调函数。当所有bundle的备份/恢复过程结束成功时触发回调，如果触发失败，则返回err错误对象。

系统能力：SystemCapability.FileManagement.StorageService.Backup

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
13600001 IPC error.
13900005 I/O error.
13900011 Out of memory.
13900020 Invalid argument.
13900025 No space left on device.
13900042 Unknown error.

示例：

  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;

回调函数。备份服务死亡时触发回调，如果触发失败，则返回err错误对象。

系统能力：SystemCapability.FileManagement.StorageService.Backup

示例：

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

onResultReport12+

onResultReport (bundleName: string, result: string)

回调函数。当应用备份/恢复结束后，如果成功触发回调，返回应用包名及应用备份/恢复信息（备份/恢复数量或异常信息等）。

系统能力：SystemCapability.FileManagement.StorageService.Backup

返回值：

参数名 类型 必填 说明
bundleName string 是 应用包名。
result string 是 json格式返回的应用备份/恢复信息。

示例：

  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)

回调函数。应用备份/恢复过程中进度信息的回调，返回应用执行业务的进度信息和异常信息等。

系统能力：SystemCapability.FileManagement.StorageService.Backup

返回值：

参数名 类型 必填 说明
bundleName string 是 应用包名。
process string 是 json格式返回应用备份/恢复的进度信息。

示例：

  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

获取备份恢复版本号信息。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

返回值：

类型 说明
string 返回备份恢复版本号信息。
版本号格式为API版本。内部版本，例如API16，则版本号为16.0。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
201 Permission verification failed, usually the result returned by VerifyAccessToken.
202 Permission verification failed, application which is not a system application uses system API.

示例：

  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));
    }
  }

内容示例：

  { "backupVersion" : "16.0" }

backup.getLocalCapabilities

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

用于获取一个描述本地能力的Json文件。使用callback异步回调。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
callback AsyncCallback&lt;FileData&gt; 是 异步获取本地能力文件之后的回调。返回FileData对象。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
13600001 IPC error.
13900005 I/O error.
13900011 Out of memory.
13900025 No space left on device.
13900042 Unknown error.

示例：

  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));
  }

能力文件可以通过@ohos.file.fs提供的fs.stat等相关接口获取，能力文件内容示例：

 {
  "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;

用于获取一个描述本地能力的Json文件。使用Promise异步回调。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

返回值：

类型 说明
Promise&lt;FileData&gt; Promise对象。返回FileData对象。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
13600001 IPC error.
13900005 I/O error.
13900011 Out of memory.
13900025 No space left on device.
13900042 Unknown error.

示例：

  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));
    }
  }

能力文件可以通过@ohos.file.fs提供的fs.stat等相关接口获取，能力文件内容示例：

 {
  "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;

用于获取一个描述本地能力的Json文件，根据dataList内传递的参数查询对应应用的本地能力数据。使用Promise异步回调。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
dataList Array&lt;IncrementalBackupTime&gt; 是 增量备份数据列表，用于描述增量备份的文件信息。

返回值：

类型 说明
Promise&lt;FileData&gt; Promise对象。返回FileData对象。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
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.

示例：

  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 //调用者根据上次记录的增量备份时间
      }];
      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

获取需要备份的应用信息。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
bundleToBackup string 是 需要备份的应用名称。

返回值：

类型 说明
string 返回应用上报的信息。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
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.

示例：

  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

调用时机为onBundleBegin之后，onBundleEnd之前。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
bundleName string 是 需要设置备份或恢复时长的应用名称。
timeout number 是 备份或恢复的限制时长，入参范围[0,14400000]，单位：ms。

返回值：

类型 说明
boolean 超时时间是否设置成功。true为设置成功；false为设置失败。

错误码：

错误码ID 错误信息
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.

示例：

  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

调用时机为onBundleBegin之后，onBundleEnd之前。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
bundleName string 是 需要控制速率对应的应用名称。
sendRate number 是 需要应用设置的fd发送速率大小，以秒为单位，范围0~800，默认60/秒。当为0时，表示停止发送，等到设置非0值时激活发送。如果设置值超过最大值800，按照800进行发送。

返回值：

类型 说明
boolean 发送速率是否设置成功。true为设置成功；false为设置失败。

错误码：

错误码ID 错误信息
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.

示例：

  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

框架返回的应用待备份的数据量大小。

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数名 类型 必填 说明
reportInfo string 是 框架获取到的应用待备份数据量大小的信息。

示例：

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

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

SessionBackup

备份流程对象，用来支撑应用备份的流程。在使用前，需要先创建SessionBackup实例。

constructor

constructor(callbacks: GeneralCallbacks)

备份流程的构造函数，用于获取SessionBackup类的实例。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
callback GeneralCallbacks 是 备份流程所需的回调。

示例：

  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); // 创建备份流程

getLocalCapabilities18+

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

用于在备份业务中获取一个描述本地能力的Json文件。使用Promise异步回调。

需要权限：ohos.permission.BACKUP

系统接口：此接口为系统接口

系统能力：SystemCapability.FileManagement.StorageService.Backup

返回值：

类型 说明
Promise&lt;FileData&gt; Promise对象。返回FileData对象。

错误码：

以下错误码的详细介绍请参见通用错误码和文件管理子系统错误码。

错误码ID 错误信息
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.

示例：

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

  interface test { // 用于解析能力文件
    bundleInfos: [];
    deviceType: string;
    systemFullName: string;
  }

  interface BundleInfo { // 用于获取单个应用的本地能力信息
    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 = { // 定义备份/恢复过程中的通用回调
    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); // 创建备份流程
  let basePath = '/data/storage/el2/base/backup'; 
  let path = basePath + '/localCapabilities.json'; // 本地保存能力文件的路径
  try {
    let fileData = await sessionBackup.getLocalCapabilities(); // 获取本地能力文件
    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); // 将获取的本地能力文件保存到本地
      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'); // 从本地的能力文件中获取信息
  try {
    const jsonsObj: test|null = JSON.parse(data); // 解析本地的能力文件并打印部分信息
    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));
  }

能力文件可以通过@ohos.file.fs提供的fs.stat等相关接口获取，能力文件内容示例：

 {
  "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;

用于获取应用待备份数据量，在appendBundles之前调用。以异步callback方式（generalCallbacks中的onBackupSizeReport）每隔固定时间（每隔5秒返回一次，如果5秒内获取完则立即返回）返回一次扫描结果，直到datalist中所有的应用数据量全部返回。

需要权限：ohos.permission.BACKUP

系统接口：此接口为系统接口

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
isPreciseScan boolean 是 是否精确扫描。true为精确扫描，false为非精确扫描。非精确扫描速度快，为估算数据量；精确扫描速度慢，结果更准确。但由于在实际备份过程中待备份数据可能发生变动，精确扫描结果和实际备份数据量不保证完全匹配。
dataList Array<IncrementalBackupTime> 是 备份应用列表，用于描述待获取数据量的应用和上一次备份时间（全量备份填0）。

返回值：

类型 说明
Promise&lt;void&gt; Promise对象。无返回值。

错误码：

以下错误码的详细介绍请参见通用错误码和文件管理子系统错误码。

错误码ID 错误信息
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.

示例：

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

  interface scanedInfos { //用于解析扫描结果
    scaned: [];
    scanning: string;
  }

  interface ScanedInfo { //用于解析单个应用的扫描结果
    bundleName: string;
    dataSize: number;
    incDataSize: number;
  }

  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);
    },
    onBackupSizeReport: (OnBackupSizeReport) => { // 回调函数 与getBackupDataSize配套使用，返回已获取到应用的数据量大小和正在获取数据量的应用的包名
      console.info('dataSizeCallback success');
      const jsonObj: scanedInfos|null = JSON.parse(OnBackupSizeReport); // 解析返回的信息并打印
      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); // 创建备份流程
  let backupApps: backup.IncrementalBackupTime[] = [{
    bundleName: "com.example.hiworld",
    lastIncrementalTime: 0 // 调用者根据上次记录的增量备份时间，全量时为0
  }];
  try {
    sessionBackup.getBackupDataSize(false, backupApps); // 获取backupApps中指定应用的待备份的数据量大小，false表示使用非精确扫描
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('getBackupDataSize failed with err: ' + JSON.stringify(err));
  }

异步返回JSON串示例：

{
 "scaned" :[ // 本次扫描完成的应用，已返回结果的应用在下一次回调中不会再继续返回
     {
         "name": "com.example.hiworld", // 应用名称
         "dataSize": 1006060, // 数据量大小
         "incDataSize":-1 // 增量数据量大小，全量扫描、非精确扫描时为-1，增量精确扫描时为实际增量数据量大小
     },
     {
         "name": "com.example.myAPP",
         "dataSize": 5000027,
         "incDataSize": -1
     }
 ],
 "scanning" :"com.example.smartAPP" // 正在扫描的应用，在最后一次结果返回时，该字段为空
}

appendBundles

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

添加需要备份的应用。当前整个流程中，在获取SessionBackup类的实例后只能调用一次。使用callback异步回调。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
bundlesToBackup string[] 是 需要备份的应用名称的数组。
callback AsyncCallback&lt;void&gt; 是 异步添加备份应用之后的回调。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
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

示例：

  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); // 创建备份流程
  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;

添加需要备份的应用。当前整个流程中，在获取SessionBackup类的实例后只能调用一次。使用Promise异步回调。

从API version 12开始, 新增可选参数infos, 可携带备份时各应用所需要的扩展信息, infos和bundlesToBackup根据索引一一对应。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
bundlesToBackup string[] 是 需要备份的应用名称的数组。
infos string[] 否 备份时各应用所需扩展信息的数组, 与bundlesToBackup根据索引一一对应。默认值为空。从API version 12开始支持。

返回值：

类型 说明
Promise&lt;void&gt; Promise对象。无返回值。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
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

示例：

  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); // 创建备份流程
  async function appendBundles() {
    try {
      let backupApps: Array<string> = [
        "com.example.hiworld",
        "com.example.myApp"
      ];
      await sessionBackup.appendBundles(backupApps);
      console.info('appendBundles success');
      // 携带扩展参数, 其中infos,details和外层的type节点为固定节点
      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;

备份流程结束后，应用与服务断开连接，使备份恢复服务退出。使用Promise异步回调。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

返回值：

类型 说明
Promise&lt;void&gt; Promise对象。无返回值。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
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.

示例：

  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); // 创建备份流程
  sessionBackup.release(); // 备份业务执行完成后，释放session
  console.info('release success');

cancel18+

cancel(bundleName: string): number

备份任务过程中，工具应用发现数据异常，需要取消某应用的备份时调用此接口，使此应用的备份任务终止。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
bundleName string 是 需要取消备份的应用名称。

返回值：

类型 说明
number 返回取消状态。
0：取消任务下发成功；
13500011：想要取消的任务未开始；
13500012：想要取消的任务不存在。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
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.

示例：

  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) {
        // 文件fd传输失败，调用取消接口，取消此应用的备份任务
        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); // 创建备份流程
  let backupBundles: Array<string> = ["com.example.helloWorld"];
  sessionBackup.appendBundles(backupBundles);

cleanBundleTempDir20+

cleanBundleTempDir(bundleName: string): Promise&lt;boolean&gt;

备份任务结束后，提供给工具用于清理当前应用临时目录数据（./backup目录下的backup和restore目录）的接口。使用Promise异步回调。

系统接口：此接口为系统接口。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
bundleName string 是 需要清理临时目录数据的应用名称。

返回值：

类型 说明
Promise&lt;boolean&gt; Promise对象。返回true表示清理成功；返回false表示清理失败。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID 错误信息
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.

示例：

  import { fileIo, backup} from '@kit.CoreFilekit';
  import { BusinessError } from '@kit.BasicServicesKit';

  sessionBackup?: backup.SessionBackup;

  async cleanBundleTempDir(bundleName: string) {
    try {
      let res = await this.sessionBackup.cleanBundleTempDir(bundleName);
      if (res) {
        console.info(`cleanBundleTempDir succeeded.`);
      } else {
        console.info(`cleanBundleTempDir fail.`);
      }
    } catch (error) {
      let err: BusinessError = error as BusinessError;
      console.error(`cleanBundleTempDir failed. Code: ${err.code}, message: ${err.message}`);
    }
  }

  let generalCallbacks: backup.GeneralCallbacks = { // 定义备份/恢复过程中的通用回调
    // 文件发送成功回调
    onFileReady: (err: BusinessError, file: backup.File) => {
      if (err) {
        console.error(`onFileReady failed. Code: ${err.code}, message: ${err.message}`);
        return;
      }
      console.info(`onFileReady succeeded.`);
      fileIo.closeSync(file.fd);
    },
    // 应用备份/恢复开始回调
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error(`onBundleBegin failed. Code: ${err.code}, message: ${err.message}`);
        return;
      }
      console.info(`onBundleBegin succeeded.`);
    },
    // 应用备份/恢复结束回调，在此处调用cleanBundleTempDir进行清理
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error(`onBundleEnd failed. Code: ${err.code}, message: ${err.message}`);
        return;
      }
      this.cleanBundleTempDir(bundleName);
    }
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error(`onAllBundlesEnd failed. Code: ${err.code}, message: ${err.message}`);
        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}`);
    }
  };
  this.sessionBackup = new backup.SessionBackup(generalCallbacks); // 创建备份流程

SessionRestore

恢复流程对象，用来支撑应用恢复的流程。在使用前，需要先创建SessionRestore实例。

constructor

constructor(callbacks: GeneralCallbacks)

恢复流程的构造函数，用于获取SessionRestore类的实例。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
callback GeneralCallbacks 是 恢复流程所需的回调。

示例：

  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); // 创建恢复流程

getLocalCapabilities18+

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

用于在恢复业务中获取一个描述本地能力的Json文件。使用Promise异步回调。

需要权限：ohos.permission.BACKUP

系统接口：此接口为系统接口

系统能力：SystemCapability.FileManagement.StorageService.Backup

返回值：

类型 说明
Promise&lt;FileData&gt; Promise对象。返回FileData对象。

错误码：

以下错误码的详细介绍请参见通用错误码和文件管理子系统错误码。

错误码ID 错误信息
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.

示例：

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

  interface test { // 用于解析能力文件
    bundleInfos: [];
    deviceType: string;
    systemFullName: string;
  }

  interface BundleInfo { // 用于获取单个应用的本地能力信息
    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 = { // 定义备份/恢复过程中的通用回调
    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); // 创建恢复流程
  let basePath = '/data/storage/el2/base/backup';
  let path = basePath + '/localCapabilities.json'; // 本地保存能力文件的路径
  try {
    let fileData = await sessionRestore.getLocalCapabilities(); // 获取本地能力文件
    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); // 将获取的本地能力文件保存到本地
      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'); // 从本地的能力文件中获取信息
  try {
    const jsonsObj: test|null = JSON.parse(data); // 解析本地的能力文件并打印部分信息
    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));
  }

能力文件可以通过@ohos.file.fs提供的fs.stat等相关接口获取，能力文件内容示例：

 {
  "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

添加需要恢复的应用。当前整个流程中，在获取SessionRestore类的实例后只能调用一次，使用callback异步回调。

说明：

  • 服务在恢复时需要其能力文件进行相关校验。
  • 因此remoteCapabilitiesFd可通过备份端服务所提供的getLocalCapabilities接口获取，可对其内容根据恢复应用的实际状况修改参数。也可通过getLocalCapabilities提供的json示例自行生成能力文件。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
remoteCapabilitiesFd number 是 用于恢复所需能力文件的文件描述符。
bundlesToBackup string[] 是 需要恢复的应用名称的数组。
callback AsyncCallback&lt;void&gt; 是 异步添加需要恢复的应用之后的回调。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
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.

示例：

  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); // 创建恢复流程
  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;

添加需要恢复的应用。从API version 12开始，新增可选参数infos，可携带应用恢复所需信息，infos和bundlesToBackup根据索引一一对应。 当前整个流程中，在获取SessionRestore类的实例后只能调用一次。使用Promise异步回调。

说明：

  • 服务在恢复时需要其能力文件进行相关校验。
  • 因此remoteCapabilitiesFd可通过备份端服务所提供的getLocalCapabilities接口获取， 可对其内容根据恢复应用的实际状况修改参数。也可通过getLocalCapabilities提供的json示例自行生成能力文件。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
remoteCapabilitiesFd number 是 用于恢复所需能力文件的文件描述符。
bundlesToBackup string[] 是 需要恢复的应用包名称的数组。
infos12+ string[] 否 恢复时各应用所需要扩展信息的数组，与bundlesToBackup根据索引一一对应。默认值为空。从API version 12开始支持。

返回值：

类型 说明
Promise&lt;void&gt; Promise对象。无返回值。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
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.

示例：

  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); // 创建恢复流程
  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');
      // 携带扩展参数的调用
      let infos: Array<string> = [
        `
         {
          "infos":[
            {
              "details": [
                {
                  "detail": [
                    {
                      "source": "com.example.hiworld", // 应用旧系统包名
                      "target": "com.example.helloworld" // 应用新系统包名
                    }
                  ]，
                  "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

用于请求从服务中获取共享文件。使用callback异步回调。

说明：

  • 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由@ohos.file.fs提供的fs.copyFile等相关零拷贝接口。
  • 使用getFileHandle前需要获取SessionRestore类的实例，并且成功通过appendBundles添加需要待恢复的应用。
  • 开发者可以通过onFileReady回调来获取文件句柄，当客户端完成文件操作时，需要使用publishFile来进行发布。
  • 根据所需要恢复的文件个数，可以多次调用getFileHandle。
  • 所需恢复的文件，不支持使用相对路径（../）和软链接。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
fileMeta FileMeta 是 恢复文件的元数据。
callback AsyncCallback&lt;void&gt; 是 异步请求文件句柄成功之后的回调。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
13600001 IPC error.
13900001 Operation not permitted.
13900020 Invalid argument.
13900042 Unknown error.

示例：

  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); // 创建恢复流程
  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;

用于请求从服务中获取共享文件。使用Promise异步回调。

说明：

  • 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由@ohos.file.fs提供的fs.copyFile等相关零拷贝接口。
  • 使用getFileHandle前需要获取SessionRestore类的实例，并且成功通过appendBundles添加需要待恢复的应用。
  • 开发者可以通过onFileReady回调来获取文件句柄，当客户端完成文件操作时，需要使用publishFile来进行发布。
  • 根据所需要恢复的文件个数，可以多次调用getFileHandle。
  • 所需恢复的文件，不支持使用相对路径（../）和软链接。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
fileMeta FileMeta 是 恢复文件的元数据。

返回值：

类型 说明
Promise&lt;void&gt; Promise对象。无返回值。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
13600001 IPC error.
13900001 Operation not permitted.
13900020 Invalid argument.
13900042 Unknown error.

示例：

  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); // 创建恢复流程
  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

用于将FileMeta发布到备份服务，使服务知道文件的内容已经准备完成。使用callback异步回调。

说明：

  • 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由@ohos.file.fs提供的fs.copyFile等相关零拷贝接口。
  • 服务端通过onFileReady返回文件句柄后，客户端可通过零拷贝操作将其对应的文件内容拷贝到服务端提供的文件句柄中。
  • 这个接口仅在调用方完成所有待恢复数据的写入操作后才能调用，且调用方需要确保待写入恢复数据的一致性与完整性。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
fileMeta FileMeta 是 恢复文件元数据。
callback AsyncCallback&lt;void&gt; 是 异步发布文件成功之后的回调。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
13600001 IPC error.
13900001 Operation not permitted.
13900020 Invalid argument.
13900042 Unknown error.

示例：

  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; // 123: 恢复所需文件个数示例
  let testBundleName = 'com.example.myapplication'; // 测试包名
  initMap.set(testBundleName, testFileNum);
  let countMap = new Map<string, number>();
  countMap.set(testBundleName, 0); // 实际写入文件个数初始化
  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]++; // 实际写入文件个数更新
        // 恢复所需文件个数与实际写入文件个数相等时调用，保证数据的一致性和完整性
        if (countMap[file.bundleName] == initMap[file.bundleName]) { // 每个包的所有文件收到后触发publishFile
          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); // 创建恢复流程
    return sessionRestore;
  }
  g_session = createSessionRestore();

publishFile

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

用于将FileMeta发布到备份服务，使服务知道文件的内容已经准备完成。使用Promise异步回调。

说明：

  • 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由@ohos.file.fs提供的fs.copyFile等相关零拷贝接口。
  • 服务端通过onFileReady返回文件句柄后，客户端可通过零拷贝操作将其对应的文件内容拷贝到服务端提供的文件句柄中。
  • 这个接口仅在调用方完成所有待恢复数据的写入操作后才能调用，且调用方需要确保待写入恢复数据的一致性与完整性。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
fileMeta FileMeta 是 恢复文件元数据。

返回值：

类型 说明
Promise&lt;void&gt; Promise对象。无返回值。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
13600001 IPC error.
13900001 Operation not permitted.
13900020 Invalid argument.
13900042 Unknown error.

示例：

  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; // 123: 恢复所需文件个数示例
  let testBundleName = 'com.example.myapplication'; // 测试包名
  initMap.set(testBundleName, testFileNum);
  let countMap = new Map<string, number>();
  countMap.set(testBundleName, 0); // 实际写入文件个数初始化
  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]++; // 实际写入文件个数更新
        // 恢复所需文件个数与实际写入文件个数相等时调用，保证数据的一致性和完整性
        if (countMap[file.bundleName] == initMap[file.bundleName]) { // 每个包的所有文件收到后触发publishFile
          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); // 创建恢复流程
    return sessionRestore;
  }
  g_session = createSessionRestore();

release12+

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

恢复流程结束后，应用与服务断开连接，使备份恢复服务退出。使用Promise异步回调。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

返回值：

类型 说明
Promise&lt;void&gt; Promise对象。无返回值。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
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.

示例：

  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; // 123: 恢复所需文件个数示例
  let testBundleName = 'com.example.myapplication'; // 测试包名
  initMap.set(testBundleName, testFileNum);
  let countMap = new Map<string, number>();
  countMap.set(testBundleName, 0); // 实际写入文件个数初始化
  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]++; // 实际写入文件个数更新
        // 恢复所需文件个数与实际写入文件个数相等时调用，保证数据的一致性和完整性
        if (countMap[file.bundleName] == initMap[file.bundleName]) { // 每个包的所有文件收到后触发publishFile
          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); // 创建恢复流程
    return sessionRestore;
  }
  g_session = createSessionRestore();
  g_session.release();
  console.info('release success');

cancel18+

cancel(bundleName: string): number

恢复任务过程中，工具应用发现数据异常，需要取消某应用的恢复时调用此接口，使此应用的恢复任务终止。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
bundleName string 是 需要取消备份的应用名称。

返回值：

类型 说明
number 返回取消状态。
0：取消任务下发成功；
13500011：想要取消的任务未开始；
13500012：想要取消的任务不存在。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
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.

示例：

  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) {
        // 文件fd传输失败，调用取消接口，取消此应用的恢复任务
        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); // 创建恢复流程
  let fileData: backup.FileData = {
    fd: -1
  }
  fileData = await backup.getLocalCapabilities(); //备份恢复框架提供的getLocalCapabilities接口获取能力集文件。
  let backupBundles: Array<string> = ["com.example.helloWorld"];
  sessionRestore.appendBundles(fileData.fd, backupBundles);

cleanBundleTempDir20+

cleanBundleTempDir(bundleName: string): Promise&lt;boolean&gt;

恢复任务结束后，提供给工具用于清理当前应用临时目录数据（./backup目录下的backup和restore目录）的接口。使用Promise异步回调。

系统接口：此接口为系统接口。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
bundleName string 是 需要清理临时目录数据的应用名称。

返回值：

类型 说明
Promise&lt;boolean&gt; Promise对象。返回true表示清理成功；返回false表示清理失败。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID 错误信息
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.

示例：

  import { fileIo, backup} from '@kit.CoreFilekit';
  import { BusinessError } from '@kit.BasicServicesKit';

  sessionRestore?: backup.SessionRestore;

  async cleanBundleTempDir(bundleName: string) {
    try {
      let res = await this.sessionRestore.cleanBundleTempDir(bundleName);
      if (res) {
        console.info(`cleanBundleTempDir succeeded.`);
      } else {
        console.info(`cleanBundleTempDir fail.`);
      }
    } catch (error) {
      let err: BusinessError = error as BusinessError;
      console.error(`cleanBundleTempDir failed. Code: ${err.code}, message: ${err.message}`);
    }
  }

  let generalCallbacks: backup.GeneralCallbacks = { // 定义备份/恢复过程中的通用回调
    // 文件发送成功回调
    onFileReady: (err: BusinessError, file: backup.File) => {
      if (err) {
        console.error(`onFileReady failed. Code: ${err.code}, message: ${err.message}`);
        return;
      }
      console.info(`onFileReady succeeded.`);
      fileIo.closeSync(file.fd);
    },
    // 应用备份/恢复开始回调
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error(`onBundleBegin failed. Code: ${err.code}, message: ${err.message}`);
        return;
      }
      console.info(`onBundleBegin succeeded.`);
    },
    // 应用备份/恢复结束回调，在此处调用cleanBundleTempDir进行清理
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error(`onBundleEnd failed. Code: ${err.code}, message: ${err.message}`);
        return;
      }
      this.cleanBundleTempDir(bundleName);
    }
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error(`onAllBundlesEnd failed. Code: ${err.code}, message: ${err.message}`);
        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}`);
    }
  };
  this.sessionRestore = new backup.SessionRestore(generalCallbacks); //  创建恢复流程

IncrementalBackupSession12+

增量备份流程对象，用来支撑应用增量备份的流程。在使用前，需要先创建IncrementalBackupSession实例。

constructor12+

constructor(callbacks: GeneralCallbacks)

增量备份流程的构造函数，用于获取IncrementalBackupSession类的实例。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
callback GeneralCallbacks 是 增量备份流程所需的回调。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
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.

示例：

  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); // 创建增量备份流程

getLocalCapabilities18+

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

用于在增量备份业务中获取一个描述本地能力的Json文件。使用Promise异步回调。

需要权限：ohos.permission.BACKUP

系统接口：此接口为系统接口

系统能力：SystemCapability.FileManagement.StorageService.Backup

返回值：

类型 说明
Promise&lt;FileData&gt; Promise对象。返回FileData对象。

错误码：

以下错误码的详细介绍请参见通用错误码和文件管理子系统错误码。

错误码ID 错误信息
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.

示例：

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

  interface test { // 用于解析能力文件
    bundleInfos: [];
    deviceType: string;
    systemFullName: string;
  }

  interface BundleInfo { // 用于获取单个应用的本地能力信息
    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 = { // 定义备份/恢复过程中的通用回调
    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); // 创建增量备份流程
  let basePath = '/data/storage/el2/base/backup';
  let path = basePath + '/localCapabilities.json'; // 本地保存能力文件的路径
  try {
    let fileData = await incrementalBackupSession.getLocalCapabilities(); // 获取本地能力文件
    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); // 将获取的本地能力文件保存到本地
      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'); // 从本地的能力文件中获取信息
  try {
    const jsonsObj: test|null = JSON.parse(data); // 解析本地的能力文件并打印部分信息
    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));
  }

能力文件可以通过@ohos.file.fs提供的fs.stat等相关接口获取，能力文件内容示例：

 {
  "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;

用于获取应用待备份数据量，在appendBundles之前调用。以异步callback方式（generalCallbacks中的onBackupSizeReport）每隔固定时间（每隔5秒返回一次，如果5秒内获取完则立即返回）返回一次扫描结果，直到datalist中所有的应用数据量全部返回。

需要权限：ohos.permission.BACKUP

系统接口：此接口为系统接口

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
isPreciseScan boolean 是 是否精确扫描。true为精确扫描，false为非精确扫描。非精确扫描速度快，为估算数据量；精确扫描速度慢，结果更准确。但由于在实际备份过程中待备份数据可能发生变动，精确扫描结果和实际备份数据量不保证完全匹配。
dataList Array<IncrementalBackupTime> 是 备份应用列表，用于描述待获取数据量的应用和上一次备份时间（全量备份填0）。

返回值：

类型 说明
Promise&lt;void&gt; Promise对象。无返回值。

错误码：

以下错误码的详细介绍请参见通用错误码和文件管理子系统错误码。

错误码ID 错误信息
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.

示例：

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

  interface scanedInfos { // 用于解析扫描结果
    scaned: [];
    scanning: string;
  }

  interface ScanedInfo { // 用于解析单个应用的扫描结果
    bundleName: string;
    dataSize: number;
    incDataSize: number;
  }

  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);
    },
    onBackupSizeReport: (OnBackupSizeReport) => { // 回调函数 与getBackupDataSize配套使用，返回已获取到应用的数据量大小和正在获取数据量的应用的包名
      console.info('dataSizeCallback success');
      const jsonObj: scanedInfos|null = JSON.parse(OnBackupSizeReport); // 解析返回的信息并打印
      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); // 创建增量备份流程

  let backupApps: backup.IncrementalBackupTime[] = [{
    bundleName: "com.example.hiworld",
    lastIncrementalTime: 1700107870 // 调用者根据上次记录的增量备份时间
  }];
  try {
    incrementalBackupSession.getBackupDataSize(true, backupApps); // 获取backupApps中指定应用的待备份的数据量大小，true表示使用精确扫描
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('getBackupDataSize failed with err: ' + JSON.stringify(err));
  }

异步返回JSON串示例：

{
 "scaned" :[ // 本次扫描完成的应用，已返回结果的应用在下一次回调中不会再继续返回
     {
         "name": "com.example.hiworld", // 应用名称
         "dataSize": 1006060, // 数据量大小
         "incDataSize": 50800 // 增量数据量大小
     },
     {
         "name": "com.example.myAPP",
         "dataSize": 5000027,
         "incDataSize": 232344
     }
 ],
 "scanning" :"com.example.smartAPP" // 正在扫描的应用，在最后一次结果返回时，该字段为空
}

appendBundles12+

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

添加需要增量备份的应用。当前整个流程中，触发Release接口之前都可以进行appendBundles的调用。使用Promise异步回调。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
bundlesToBackup Array&lt;IncrementalBackupData&gt; 是 需要增量备份的应用的数组。

返回值：

类型 说明
Promise&lt;void&gt; Promise对象。无返回值。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
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.

示例：

  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); // 创建增量备份流程
  let incrementalBackupData: backup.IncrementalBackupData = {
    bundleName: "com.example.hiworld",
    lastIncrementalTime: 1700107870, // 调用者传递上一次备份的时间戳
    manifestFd:1 // 调用者传递上一次备份的manifest文件句柄
  }
  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));
  }); // 添加需要增量备份的应用

appendBundles12+

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

添加需要增量备份的应用。当前整个流程中，触发Release接口之前都可以进行appendBundles的调用。使用Promise异步回调。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
bundlesToBackup Array&lt;IncrementalBackupData&gt; 是 需要增量备份的应用的数组。
infos string[] 是 备份时各应用所需要扩展信息的数组, 与bundlesToBackup根据索引一一对应。从API version 12开始支持。

返回值：

类型 说明
Promise&lt;void&gt; Promise对象。无返回值。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
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.

示例：

  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); // 创建增量备份流程
  let incrementalBackupData: backup.IncrementalBackupData = {
    bundleName: "com.example.hiworld",
    lastIncrementalTime: 1700107870, // 调用者传递上一次备份的时间戳
    manifestFd:1 // 调用者传递上一次备份的manifest文件句柄
  }
      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];
  // 添加需要增量备份的应用
  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;

结束增量备份流程。使用Promise异步回调。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

返回值：

类型 说明
Promise&lt;void&gt; Promise对象。无返回值。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
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.

示例：

  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); // 创建增量备份流程
  incrementalBackupSession.release(); // 结束增量备份流程
  console.info('release success');

cancel18+

cancel(bundleName: string): number

增量备份任务过程中，工具应用发现数据异常，需要取消某应用的增量备份时调用此接口，使此应用的增量备份任务终止。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
bundleName string 是 需要取消备份的应用名称。

返回值：

类型 说明
number 返回取消状态。
0：取消任务下发成功；
13500011：想要取消的任务未开始；
13500012：想要取消的任务不存在。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID 错误信息
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.

示例：

  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) {
        // 文件fd传输失败，调用取消接口，取消此应用的增量备份任务
        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); // 创建增量备份流程
  let backupBundles: Array<backup.IncrementalBackupData> = [];
  let bundleData: backup.IncrementalBackupData = {
    bundleName: "com.example.helloWorld",
    lastIncrementalTime: 1700107870, //调用者传递上一次备份的时间戳
    manifestFd: 1 // 调用者传递上一次备份的manifest文件句柄
  }
  backupBundles.push(bundleData);
  incrementalBackupSession.appendBundles(backupBundles);

cleanBundleTempDir20+

cleanBundleTempDir(bundleName: string): Promise&lt;boolean&gt;

增量备份任务结束后，提供给工具用于清理当前应用临时目录数据（./backup目录下的backup和restore目录）的接口。使用Promise异步回调。

系统接口：此接口为系统接口。

需要权限：ohos.permission.BACKUP

系统能力：SystemCapability.FileManagement.StorageService.Backup

参数：

参数名 类型 必填 说明
bundleName string 是 需要清理临时目录数据的应用名称。

返回值：

类型 说明
Promise&lt;boolean&gt; Promise对象。返回true表示清理成功；返回false表示清理失败。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID 错误信息
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.

示例：

  import { fileIo, backup} from '@kit.CoreFilekit';
  import { BusinessError } from '@kit.BasicServicesKit';

  incrementalBackupSession?: backup.IncrementalBackupSession;

  async cleanBundleTempDir(bundleName: string) {
    try {
      let res = await this.incrementalBackupSession.cleanBundleTempDir(bundleName);
      if (res) {
        console.info(`cleanBundleTempDir succeeded.`);
      } else {
        console.info(`cleanBundleTempDir fail.`);
      }
    } catch (error) {
      let err: BusinessError = error as BusinessError;
      console.error(`cleanBundleTempDir failed. Code: ${err.code}, message: ${err.message}`);
    }
  }

  let generalCallbacks: backup.GeneralCallbacks = { // 定义备份/恢复过程中的通用回调
    // 文件发送成功回调
    onFileReady: (err: BusinessError, file: backup.File) => {
      if (err) {
        console.error(`onFileReady failed. Code: ${err.code}, message: ${err.message}`);
        return;
      }
      console.info(`onFileReady succeeded.`);
      fileIo.closeSync(file.fd);
    },
    // 应用备份/恢复开始回调
    onBundleBegin: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error(`onBundleBegin failed. Code: ${err.code}, message: ${err.message}`);
        return;
      }
      console.info(`onBundleBegin succeeded.`);
    },
    // 应用备份/恢复结束回调，在此处调用cleanBundleTempDir进行清理
    onBundleEnd: (err: BusinessError<string|void>, bundleName: string) => {
      if (err) {
        console.error(`onBundleEnd failed. Code: ${err.code}, message: ${err.message}`);
        return;
      }
      this.cleanBundleTempDir(bundleName);
    }
    onAllBundlesEnd: (err: BusinessError) => {
      if (err) {
        console.error(`onAllBundlesEnd failed. Code: ${err.code}, message: ${err.message}`);
        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}`);
    }
  };
  this.incrementalBackupSession = new backup.IncrementalBackupSession(generalCallbacks); //  创建增量备份流程

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Core File Kit（文件基础服务）

harmony 鸿蒙Environment

harmony 鸿蒙FileIO

harmony 鸿蒙FileShare_PolicyErrorResult

harmony 鸿蒙FileShare_PolicyInfo

harmony 鸿蒙error_code.h

harmony 鸿蒙文件管理错误码

harmony 鸿蒙FileShare

harmony 鸿蒙FileUri

harmony 鸿蒙@ohos.application.BackupExtensionAbility (备份恢复扩展能力)(系统接口)

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