The **file.backup** module provides APIs for backing up and restoring data for applications.
> **NOTE**
>
> - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> - The APIs provided by this module are system APIs.
## Modules to Import
```js
importbackupfrom'@ohos.file.backup';
```
## FileMeta
Defines a file metadata object, which includes the application name and file URI. **FileMeta** is an indispensable object for data backup and restoration.
| bundleName | string | Yes | Bundle name of the application, which can be obtained by using the method provided by [bundle.BundleInfo](js-apis-bundle-BundleInfo.md). |
| uri | string | Yes | Name of the file in the application sandbox.<br>Currently, the URI has not been upgraded to the standard format. It can consist of digits (0–9), letters (a–z and A–Z), underscores (_), and period (.) only.|
## FileData
Defines a file data object, which includes the file descriptor (FD) of the file opened. **FileData** is an indispensable object for data backup and restoration.
> **NOTE**
>
> The **FileData** must be closed after being used. Otherwise, memory leakage may occur. For details about how to close a **FileData** object, see [fs.closeSync](js-apis-file-fs.md#fsclosesync) provided by [@ohos.file.fs](js-apis-file-fs.md).
| fd | number | Yes | FD, which can be obtained through the backup service.|
## File
Defines a file object, which
inherits from [FileMeta](#filemeta) and [FileData](#filedata).
> **NOTE**
>
> **file.backup.File** is different from [File](js-apis-file-fs.md#file) provided in @ohos.file.fs. The former is an object that inherits from [FileMeta](#filemeta) and [FileData](#filedata), while the latter has only one FD object. Pay attention to the difference between them.
Provides general callbacks invoked during the backup or restoration process. The backup service uses these callbacks to notify the client of the backup/restoration phase of the application.
Called when the server sends a file to the client. If the file is sent successfully, **err** is **undefined**. Otherwise, **err** is an error object.
> **NOTE**
>
> The **File** returned by **AsyncCallback** is the file.backup.[File](#file). The returned file belongs to the backup service. Once the file is closed, the backup service shall clear the resources used by the file. However, the client must close the file handle first.
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID | Error Message |
| ---------------------------- | ---------- |
| 13600001 | IPC error |
| 13900005 | I/O error |
| 13900011 | Out of memory |
| 13900020 | Invalid argument |
| 13900025 | No space left on device |
| 13900042 | Unknown error |
**Example**
```js
importfsfrom'@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>
Called when the backup or restoration of an application begins. If the backup or restoration begins, **err** is undefined. Otherwise, **err** is an error object.
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID | Error Message |
| ---------------------------- | ---------- |
| 13600001 | IPC error |
| 13900005 | I/O error |
| 13900011 | Out of memory |
| 13900020 | Invalid argument |
| 13900025 | No space left on device |
| 13900042 | Unknown error |
**Example**
```js
onBundleBegin:(err,bundleName)=>{
if(err){
console.error('onBundleBegin failed with err: '+err);
}
console.info('onBundleBegin success with bundleName: '+bundleName);
}
```
### onBundleEnd
onBundleEnd : AsyncCallback<string>
Called when the backup or restoration of an application ends. If the backup or restoration ends successfully, **err** is undefined. Otherwise, **err** is an error object.
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID | Error Message |
| ---------------------------- | ---------- |
| 13600001 | IPC error |
| 13900005 | I/O error |
| 13900011 | Out of memory |
| 13900020 | Invalid argument |
| 13900025 | No space left on device |
| 13900042 | Unknown error |
**Example**
```js
onBundleEnd:(err,bundleName)=>{
if(err){
console.error('onBundleEnd failed with err: '+err);
}
console.info('onBundleEnd success with bundleName: '+bundleName);
}
```
### onAllBundlesEnd
onAllBundlesEnd : AsyncCallback<undefined>
Called when the backup or restoration of all bundles ends. If the backup or restoration of all bundles ends, **err** is **undefined**. Otherwise, **err** is an error object.
| callback | AsyncCallback<[FileData](#filedata)> | Yes | Callback invoked to return the result. If the file is obtained, **err** is **undefined**. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID | Error Message |
| ---------------------------- | ---------- |
| 13600001 | IPC error |
| 13900005 | I/O error |
| 13900011 | Out of memory |
| 13900025 | No space left on device |
| 13900042 | Unknown error |
**Example**
```js
importfsfrom'@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);
}
```
The following is an example of the file obtained:
```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"
}
```
## backup.getLocalCapabilities
getLocalCapabilities(): Promise<FileData>
Obtains a JSON file that describes local capabilities. This API uses a promise to return the result.
| Promise<[FileData](#filedata)> | Promise used to return the **FileData** of the JSON file obtained.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID | Error Message |
| ---------------------------- | ---------- |
| 13600001 | IPC error |
| 13900005 | I/O error |
| 13900011 | Out of memory |
| 13900025 | No space left on device |
| 13900042 | Unknown error |
**Example**
```js
importfsfrom'@ohos.file.fs';
try{
letfileData=awaitbackup.getLocalCapabilities();
console.info('getLocalCapabilities success');
fs.closeSync(fileData.fd);
}catch(err){
console.error('getLocalCapabilities failed with err: '+err);
}
```
The following is an example of the file obtained:
```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
Provides a backup process object to support the application backup process. Before using the APIs of this class, you need to create a **SessionBackup** instance.
### constructor
constructor(callbacks: GeneralCallbacks);
A constructor used to create a **SessionBackup** instance.
Appends the applications whose data needs to be backed up. Currently, the obtained **SessionBackup** instance can be called only once in the entire backup process. This API uses an asynchronous callback to return the result.
| bundlesToBackup | string[] | Yes | Array of the application names to append. |
| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the applications are appended successfully, **err** is **undefined**. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
Appends the applications whose data needs to be backed up. Currently, the obtained **SessionBackup** instance can be called only once in the entire backup process. This API uses a promise to return the result.
console.error('appendBundles failed with err: '+err);
}
```
## SessionRestore
Provides a restoration process object to support the data restoration process of applications. Before using the APIs of this class, you need to create a **SessionRestore** instance.
### constructor
constructor(callbacks: GeneralCallbacks);
A constructor used to create a **SessionRestore** instance.
Appends the applications whose data needs to be restored. Currently, the obtained **SessionRestore** instance can be called only once in the entire restoration process. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> - During the data restoration, the capability file needs to be verified.
> - Therefore, **remoteCapabilitiesFd** can be obtained by using the [getLocalCapabilities](#backupgetlocalcapabilities) API provided by the backup service. You can modify the parameters based on the actual situation of your application. You can also use the JSON file example provided by **getLocalCapabilities** to generate a capability file.
| remoteCapabilitiesFd | number | Yes | FD of the file containing the capabilities to be restored. |
| bundlesToBackup | string[] | Yes | Array of the application names to append. |
| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the applications are appended successfully, **err** is **undefined**. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
Appends the applications whose data needs to be restored. Currently, the obtained **SessionRestore** instance can be called only once in the entire restoration process. This API uses a promise to return the result.
> **NOTE**
>
> - During the data restoration, the capability file needs to be verified.
> - Therefore, **remoteCapabilitiesFd** can be obtained by using the [getLocalCapabilities](#backupgetlocalcapabilities) API provided by the backup service. You can modify the parameters based on the actual situation of your application. You can also use the JSON file example provided by **getLocalCapabilities** to generate a capability file.
Obtains the handle of the shared file from the service. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> - This interface is part of the zero-copy feature, which reduces unnecessary memory copies and increases transmission efficiency. For details about the zero-copy methods, see the zero-copy APIs such as [fs.copyFile](js-apis-file-fs.md#fscopyfile) provided by [@ohos.file.fs](js-apis-file-fs.md).
> - Before using **getFileHandle**, you need to obtain a **SessionRestore** instance and add the applications with data to be restored by using **appendBundles**.
> - You can use **onFileReady** to obtain the file handle. When file operations are completed at the client, you need to use **publishFile** to publish the file.
> - **getFileHandle** can be called multiple times based on the number of files to be restored.
| fileMeta | [FileMeta](#filemeta) | Yes | Metadata of the file to restore. |
| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the file handle is obtained, **err** is **undefined**. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID | Error Message |
| ---------------------------- | ---------- |
| 13600001 | IPC error |
| 13900001 | Operation not permitted |
| 13900020 | Invalid argument |
| 13900042 | Unknown error |
**Example**
```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);
Obtains the handle of the shared file from the service. This API uses a promise to return the result.
> **NOTE**
>
> - This interface is part of the zero-copy feature, which reduces unnecessary memory copies and increases transmission efficiency. For details about the zero-copy methods, see the zero-copy APIs such as [fs.copyFile](js-apis-file-fs.md#fscopyfile) provided by [@ohos.file.fs](js-apis-file-fs.md).
> - Before using **getFileHandle**, you need to obtain a **SessionRestore** instance and add the applications with data to be restored by using **appendBundles**.
> - You can use **onFileReady** to obtain the file handle. When file operations are completed at the client, you need to use **publishFile** to publish the file.
> - **getFileHandle** can be called multiple times based on the number of files to be restored.
Publishes **FileMeta** to the backup service to indicate that the file content is ready. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> - This interface is part of the zero-copy feature, which reduces unnecessary memory copies and increases transmission efficiency. For details about the zero-copy methods, see the zero-copy APIs such as [fs.copyFile](js-apis-file-fs.md#fscopyfile) provided by [@ohos.file.fs](js-apis-file-fs.md).
> - After the server returns a file handle through **onFileReady**, the client can copy data to the file corresponding to the file handle provided by the server through zero-copy operations.
> - After the copy is complete, you can use **publishFile** to notify the backup service that the file is ready.
| fileMeta | [FileMeta](#filemeta) | Yes | Metadata of the file to restore. |
| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the file is published successfully, **err** is **undefined**. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID | Error Message |
| ---------------------------- | ---------- |
| 13600001 | IPC error |
| 13900001 | Operation not permitted |
| 13900020 | Invalid argument |
| 13900042 | Unknown error |
**Example**
```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);
Publishes **FileMeta** to the backup service to indicate that the file content is ready. This API uses a promise to return the result.
> **NOTE**
>
> - This interface is part of the zero-copy feature, which reduces unnecessary memory copies and increases transmission efficiency. For details about the zero-copy methods, see the zero-copy APIs such as [fs.copyFile](js-apis-file-fs.md#fscopyfile) provided by [@ohos.file.fs](js-apis-file-fs.md).
> - After the server returns a file handle through **onFileReady**, the client can copy data to the file corresponding to the file handle provided by the server through zero-copy operations.
> - After the copy is complete, you can use **publishFile** to notify the backup service that the file is ready.
