# @ohos.file.backup (备份恢复)

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

> **说明：**
> - 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
> - 本模块接口为系统接口。
> - 本模块支持对错误码进行处理，错误码及其适配方式[参考文档](../errorcodes/errorcode-filemanagement.md#错误码适配指导)。

## 导入模块

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

## FileMeta

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

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

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

## FileData

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

> **说明：**
> - FileData使用完成后必须关闭，如不关闭会出现内存泄露问题。关闭的方法可参考由[@ohos.file.fs](./js-apis-file-fs.md)提供的[fs.closeSync](js-apis-file-fs.md#fsclosesync)等相关关闭接口

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

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

## File

一个文件对象。
继承[FileMeta](#filemeta)和[FileData](#filedata)

> **说明：**
> - file.backup.File与@ohos.file.fs中的提供的[File](js-apis-file-fs.md#file)是带有不同的涵义，前者是继承[FileMeta](#filemeta)和[FileData](#filedata)的对象而后者只有一个文件描述符的对象。请注意做区分，不要混淆。

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

## GeneralCallbacks

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

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

### onFileReady

onFileReady : AsyncCallback<File>

回调函数。当服务端返向客户端发送文件成功，err为undefined，否则为错误对象。

> **说明：**
> - AsyncCallback回调中返回的File 所属file.backup.[File](#file)类型，返回的文件归备份服务所有，一旦文件关闭，备份服务将选择合适的实际去清理，但客户端必须关闭文件句柄。

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

**示例：**

  ```js
  import fs from '@ohos.file.fs';
  onFileReady: (err, file) => {
    if (err) {
      console.error('onFileReady failed with err: ' + err);
    }
    console.info('onFileReady success with file: ' + file.bundleName + ' ' + file.uri);
    fs.closeSync(file.fd);
  }
  ```

### onBundleBegin

onBundleBegin : AsyncCallback<string>

 回调函数。当应用备份/恢复开始时返回bundle名称成功，err为undefined，否则为错误对象。

> **说明：**
> - 回调函数。当应用备份/恢复开始时，err为undefined，否则为错误对象。

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

**示例：**

  ```js
  onBundleBegin: (err, bundleName) => {
    if (err) {
      console.error('onBundleBegin failed with err: ' + err);
    }
    console.info('onBundleBegin success with bundleName: ' + bundleName);
  }
  ```

### onBundleEnd

onBundleEnd : AsyncCallback<string>

回调函数。当应用备份/恢复结束后返回bundle名称成功，err为undefined，否则为错误对象。

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

**示例：**

  ```js
  onBundleEnd: (err, bundleName) => {
    if (err) {
      console.error('onBundleEnd failed with err: ' + err);
    }
    console.info('onBundleEnd success with bundleName: ' + bundleName);
  }
  ```

### onAllBundlesEnd

onAllBundlesEnd : AsyncCallback<undefined>

回调函数。当所有bundle的备份/恢复过程结束成功，err为undefined，否则为错误对象。

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

**示例：**

  ```js
  onAllBundlesEnd: (err) => {
    if (err) {
      console.error('onAllBundlesEnd failed with err: ' + err);
    }
    console.info('onAllBundlesEnd success');
  }
  ```

### onBackupServiceDied

onBackupServiceDied : Callback<undefined>

回调函数，返回备份服务死亡。

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

**示例：**

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

## getLocalCapabilities

getLocalCapabilities(callback: AsyncCallback<FileData>): void;

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

**需要权限**：ohos.permission.BACKUP

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

**参数：**
| 参数名   | 类型                                       | 必填 | 说明                                                   |
| -------- | ------------------------------------------ | ---- | ------------------------------------------------------ |
| callback | AsyncCallback<[FileData](#filedata)> | 是   | 回调函数。当获取成功，err为undefined，否则为错误对象。 |

**示例：**

  ```js
  import fs from '@ohos.file.fs';
  try {
    backup.getLocalCapabilities((err, fileData) => {
      if (err) {
        console.error('getLocalCapabilities failed with err: ' + err);
      }
      console.info('getLocalCapabilities success');
      fs.closeSync(fileData.fd);
    });
  } catch (err) {
    console.error('getLocalCapabilities failed with err: ' + err);
  }
  ```

  
**返回的能力文件内容示例：**

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

## getLocalCapabilities

getLocalCapabilities(): Promise<FileData>;

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

**需要权限**：ohos.permission.BACKUP

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

**返回值：**

| 类型                                 | 说明                                                |
| ------------------------------------ | --------------------------------------------------- |
| Promise<[FileData](#filedata)> | Promise对象，返回描述本地能力的Json文件的FileData。 |

**示例：**

  ```js
  import fs from '@ohos.file.fs';
  try {
    let fileData = await backup.getLocalCapabilities();
    console.info('getLocalCapabilities success');
    fs.closeSync(fileData.fd);
  } catch (err) {
    console.error('getLocalCapabilities failed with err: ' + err);
  }
  ```

  **返回的能力文件内容示例：**

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

## SessionBackup

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

### constructor

constructor(callbacks: GeneralCallbacks);

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

**需要权限**：ohos.permission.BACKUP

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

**参数：**

| 参数名   | 类型                                  | 必填 | 说明                 |
| -------- | ------------------------------------- | ---- | -------------------- |
| callback | [GeneralCallbacks](#generalcallbacks) | 是   | 备份流程所需的回调。 |

**示例：**

  ```js
  import fs from '@ohos.file.fs';
  let sessionBackup = new backup.SessionBackup({
    onFileReady: (err, file) => {
      if (err) {
        console.error('onFileReady failed with err: ' + err);
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err, bundleName) => {
      if (err) {
        console.error('onBundleBegin failed with err: ' + err);
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err, bundleName) => {
      if (err) {
        console.error('onBundleEnd failed with err: ' + err);
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + err);
      }
      console.info('onAllBundlesEnd success');
    },
    onBackupServiceDied: () => {
      console.info('service died');
    }
  });
  ```

### appendBundles

appendBundles(bundlesToBackup: string[], callback: AsyncCallback<void>): void;

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

**需要权限**：ohos.permission.BACKUP

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

**参数：**

| 参数名          | 类型                      | 必填 | 说明                                                           |
| --------------- | ------------------------- | ---- | -------------------------------------------------------------- |
| bundlesToBackup | string[]                  | 是   | 需要备份的应用名称的数组。                                     |
| callback        | AsyncCallback<void> | 是   | 回调函数。当添加备份应用成功，err为undefined，否则为错误对象。 |

**示例：**

  ```js
  try {
    sessionBackup.appendBundles(['com.example.hiworld'], (err) => {
      if (err) {
        console.error('appendBundles failed with err: ' + err);
      }
      console.info('appendBundles success');
    });
  } catch (err) {
    console.error('appendBundles failed with err: ' + err);
  }
  ```

### appendBundles

appendBundles(bundlesToBackup: string[]): Promise<void>;

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

**需要权限**：ohos.permission.BACKUP

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

**参数：**

| 参数名          | 类型     | 必填 | 说明                       |
| --------------- | -------- | ---- | -------------------------- |
| bundlesToBackup | string[] | 是   | 需要备份的应用名称的数组。 |

**返回值：**

| 类型                | 说明                                   |
| ------------------- | -------------------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |

**示例：**

  ```js
  try {
    await sessionBackup.appendBundles(['com.example.hiworld']);
    console.info('appendBundles success');
  } catch (err) {
    console.error('appendBundles failed with err: ' + err);
  }
  ```

## SessionRestore

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

### constructor

constructor(callbacks: GeneralCallbacks);

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

**需要权限**：ohos.permission.BACKUP

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

**参数：**

| 参数名   | 类型                                  | 必填 | 说明                 |
| -------- | ------------------------------------- | ---- | -------------------- |
| callback | [GeneralCallbacks](#generalcallbacks) | 是   | 恢复流程所需的回调。 |

**示例：**

  ```js
  import fs from '@ohos.file.fs';
  let sessionRestore = new backup.SessionRestore({
    onFileReady: (err, file) => {
      if (err) {
        console.error('onFileReady failed with err: ' + err);
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
    },
    onBundleBegin: (err, bundleName) => {
      if (err) {
        console.error('onBundleBegin failed with err: ' + err);
      }
      console.info('onBundleBegin success');
    },
    onBundleEnd: (err, bundleName) => {
      if (err) {
        console.error('onBundleEnd failed with err: ' + err);
      }
      console.info('onBundleEnd success');
    },
    onAllBundlesEnd: (err) => {
      if (err) {
        console.error('onAllBundlesEnd failed with err: ' + err);
      }
      console.info('onAllBundlesEnd success');
    },
    onRestoreServiceDied: () => {
      console.info('service died');
    }
  });
  ```

### appendBundles

appendBundles(remoteCapabilitiesFd: number, bundlesToBackup: string[], callback: AsyncCallback<void>): void;

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

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

**需要权限**：ohos.permission.BACKUP

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

**参数：**

| 参数名               | 类型                      | 必填 | 说明                                                           |
| -------------------- | ------------------------- | ---- | -------------------------------------------------------------- |
| remoteCapabilitiesFd | number                    | 是   | 用于恢复所需能力文件的文件描述符。                             |
| bundlesToBackup      | string[]                  | 是   | 需要恢复的应用名称的数组。                                     |
| callback             | AsyncCallback<void> | 是   | 回调函数。当添加恢复应用成功，err为undefined，否则为错误对象。 |

**示例：**

  ```js
  try {
    let fileData = await backup.getLocalCapabilities();
    console.info('getLocalCapabilities success');
    sessionRestore.appendBundles(fileData.fd, ['com.example.hiworld'], (err) => {
      if (err) {
        console.error('appendBundles failed with err: ' + err);
      }
      console.info('appendBundles success');
    });
  } catch (err) {
    console.error('appendBundles failed with err: ' + err);
  }
  ```

### appendBundles

appendBundles(remoteCapabilitiesFd: number, bundlesToBackup: string[]): Promise<void>;

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

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

**需要权限**：ohos.permission.BACKUP

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

**参数：**

| 参数名               | 类型     | 必填 | 说明                               |
| -------------------- | -------- | ---- | ---------------------------------- |
| remoteCapabilitiesFd | number   | 是   | 用于恢复所需能力文件的文件描述符。 |
| bundlesToBackup      | string[] | 是   | 需要恢复的应用包名称的数组。       |

**返回值：**

| 类型                | 说明                                   |
| ------------------- | -------------------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |

**示例：**

  ```js
  try {
    let fileData = await backup.getLocalCapabilities();
    console.info('getLocalCapabilities success');
    await sessionRestore.appendBundles(fileData.fd, ['com.example.hiworld']);
    console.info('appendBundles success');
  } catch (err) {
    console.error('appendBundles failed with err: ' + err);
  }
  ```

### getFileHandle

getFileHandle(fileMeta: FileMeta, callback: AsyncCallback<void>): void;

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

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

**需要权限**：ohos.permission.BACKUP

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

**参数：**

| 参数名   | 类型                      | 必填 | 说明                                                           |
| -------- | ------------------------- | ---- | -------------------------------------------------------------- |
| fileMeta | [FileMeta](#filemeta)     | 是   | 恢复文件的元数据。                                             |
| callback | AsyncCallback<void> | 是   | 回调函数。当请求文件句柄成功，err为undefined，否则为错误对象。 |

**示例：**

  ```js
  try {
    sessionRestore.getFileHandle({
      bundleName: "com.example.hiworld",
      uri: "test.txt"
      }, (err, file) => {
      if (err) {
        console.error('getFileHandle failed with err: ' + err);
      }
      console.info('getFileHandle success');
    });
  } catch (err) {
    console.error('getFileHandle failed with err: ' + err);
  }
  ```

### getFileHandle

getFileHandle(fileMeta: FileMeta): Promise<void>;

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

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

**需要权限**：ohos.permission.BACKUP

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

**参数：**

| 参数名   | 类型                  | 必填 | 说明               |
| -------- | --------------------- | ---- | ------------------ |
| fileMeta | [FileMeta](#filemeta) | 是   | 恢复文件的元数据。 |

**返回值：**

| 类型                | 说明                                   |
| ------------------- | -------------------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |

**示例：**

  ```js
  try {
    await sessionRestore.getFileHandle({
      bundleName: "com.example.hiworld",
      uri: "test.txt"
      });
    console.info('getFileHandle success');
  } catch (err) {
    console.error('getFileHandle failed with err: ' + err);
  }
  ```

### publishFile

publishFile(fileMeta: FileMeta, callback: AsyncCallback<void>): void;

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

> **说明：**
> - 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由[@ohos.file.fs](./js-apis-file-fs.md)提供的[fs.copyFile](js-apis-file-fs.md#fscopyfile)等相关零拷贝接口。
> - 服务端通过onFileReady返回文件句柄后，客户端可通过零拷贝操作将其对应的文件内容拷贝到服务端提供的文件句柄中。
> - 在完成拷贝操作后可使用publishFile通知备份服务文件已经准备完成。

**需要权限**：ohos.permission.BACKUP

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

**参数：**

| 参数名   | 类型                      | 必填 | 说明                                                       |
| -------- | ------------------------- | ---- | ---------------------------------------------------------- |
| fileMeta | [FileMeta](#filemeta)     | 是   | 恢复文件元数据。                                           |
| callback | AsyncCallback<void> | 是   | 回调函数。当发布文件成功，err为undefined，否则为错误对象。 |

**示例：**

  ```js
  try {
    onFileReady: (err, file) => {
      if (err) {
        console.error('onFileReady failed with err: ' + err);
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
      sessionRestore.publishFile({
      bundleName: file.bundleName,
      uri: file.uri
      }, (err) => {
        if (err) {
          console.error('publishFile failed with err: ' + err);
        }
        console.info('publishFile success');
      });
    }
  } catch (err) {
    console.error('publishFile failed with err: ' + err);
  }
  ```

### publishFile

publishFile(fileMeta: FileMeta): Promise<void>;

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

> **说明：**
> - 这个接口是零拷贝特性（减少不必要的内存拷贝，实现了更高效率的传输）的一部分。零拷贝方法可参考由[@ohos.file.fs](./js-apis-file-fs.md)提供的[fs.copyFile](js-apis-file-fs.md#fscopyfile)等相关零拷贝接口。
> - 服务端通过onFileReady返回文件句柄后，客户端可通过零拷贝操作将其对应的文件内容拷贝到服务端提供的文件句柄中。
> - 在完成拷贝操作后可使用publishFile通知备份服务文件已经准备完成。

**需要权限**：ohos.permission.BACKUP

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

**参数：**

| 参数名   | 类型                  | 必填 | 说明             |
| -------- | --------------------- | ---- | ---------------- |
| fileMeta | [FileMeta](#filemeta) | 是   | 恢复文件元数据。 |

**返回值：**

| 类型                | 说明                                   |
| ------------------- | -------------------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |

**示例：**

  ```js
  try {
    onFileReady: (err, file) => {
      if (err) {
        console.error('onFileReady failed with err: ' + err);
      }
      console.info('onFileReady success');
      fs.closeSync(file.fd);
      await sessionRestore.publishFile({
      bundleName: file.bundleName,
      uri: file.uri
      });
      console.info('publishFile success');
    },
  } catch (err) {
    console.error('publishFile failed with err: ' + err);
  }
  ```