1# @ohos.application.BackupExtensionAbility (BackupExtensionAbility)
2
3The **BackupExtensionAbility** module provides extended backup and restore capabilities for applications.
4
5> **NOTE**
6>
7> - 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.
8>
9> - The APIs of this module can be used only in the stage model.
10
11## Modules to Import
12
13```ts
14import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
15```
16
17## BundleVersion
18
19Defines the version information required for data restore. You can determine the application data to be restored based on the version information.
20
21**System capability**: SystemCapability.FileManagement.StorageService.Backup
22
23| Name| Type  | Mandatory| Description            |
24| ---- | ------ | ---- | ---------------- |
25| code | number | Yes  | Internal version number of the application.  |
26| name | string | Yes  | Version name of the application.|
27
28## BackupExtensionAbility
29
30Implements backup and restore for application access data. You can use [onBackup](#onbackup) and [onRestore](#onrestore) to implement custom backup and restore operations.
31
32### Properties
33
34**System capability**: SystemCapability.FileManagement.StorageService.Backup
35
36| Name                 | Type                                                             | Mandatory| Description                                               |
37| --------------------- | ----------------------------------------------------------------- | ---- | --------------------------------------------------- |
38| context<sup>11+</sup> | [BackupExtensionContext](js-apis-file-backupextensioncontext.md) | Yes | Context of the BackupExtensionAbility. This context is inherited from [ExtensionContext](../apis-ability-kit/js-apis-inner-application-extensionContext.md).|
39
40### onBackup
41
42onBackup(): void;
43
44Called when data is being backed up. You need to implement extended data backup operations.
45
46**System capability**: SystemCapability.FileManagement.StorageService.Backup
47
48**Example**
49
50  ```ts
51  class BackupExt extends BackupExtensionAbility {
52    async onBackup() {
53      console.log('onBackup');
54    }
55  }
56  ```
57
58### onBackupEx<sup>12+</sup>
59
60onBackupEx(backupInfo: string): string | Promise&lt;string&gt;
61
62Called to pass parameters to the application during the application backup or restore process.
63**onBackupEx()** and **onBackup()** are mutually exclusive. If **onBackupEx()** needs to be overridden, call **onBackupEx()** preferentially.
64The return value of **onBackupEx()** cannot be an empty string. If an empty string is returned, **onRestore** will be called.
65
66**System capability**: SystemCapability.FileManagement.StorageService.Backup
67
68**Parameters**
69
70| Name          | Type                           | Mandatory| Description                         |
71|---------------| ------------------------------- | ---- |-----------------------------|
72| backupInfo    |string | Yes  | Package information to be passed by the third-party application.|
73
74> **NOTE**
75>
76> The following shows the sample code for synchronous implementation.
77
78**Example**
79
80  ```ts
81  import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
82
83  interface ErrorInfo {
84    type: string,
85    errorCode: number,
86    errorInfo: string
87  }
88
89  class BackupExt extends BackupExtensionAbility {
90    onBackupEx(backupInfo: string): string {
91      console.log(`onBackupEx ok`);
92      let errorInfo: ErrorInfo = {
93        type: "ErrorInfo",
94        errorCode: 0,
95        errorInfo: "app customized error info"
96      }
97      return JSON.stringify(errorInfo);
98    }
99  }
100  ```
101
102> **NOTE**
103>
104> The following shows the sample code for asynchronous implementation.
105
106
107
108
109**Example**
110
111  ```ts
112  import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
113
114  interface ErrorInfo {
115    type: string,
116    errorCode: number,
117    errorInfo: string
118  }
119
120  class BackupExt extends BackupExtensionAbility {
121    // Asynchronous implementation.
122    async onBackupEx(backupInfo: string): Promise<string> {
123      console.log(`onBackupEx ok`);
124      let errorInfo: ErrorInfo = {
125        type: "ErrorInfo",
126        errorCode: 0,
127        errorInfo: "app customized error info"
128      }
129      return JSON.stringify(errorInfo);
130    }
131  }
132  ```
133
134### onRestore
135
136onRestore(bundleVersion: BundleVersion): void;
137
138Called when data is being restored. You need to implement extended data restore operations.
139
140**System capability**: SystemCapability.FileManagement.StorageService.Backup
141
142**Parameters**
143
144| Name       | Type                           | Mandatory| Description                          |
145| ------------- | ------------------------------- | ---- | ------------------------------ |
146| bundleVersion | [BundleVersion](#bundleversion) | Yes  | Version information of the application data to be restored.|
147
148**Example**
149
150  ```ts
151  import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
152
153  class BackupExt extends BackupExtensionAbility {
154    async onRestore(bundleVersion : BundleVersion) {
155      console.log(`onRestore ok ${JSON.stringify(bundleVersion)}`);
156    }
157  }
158  ```
159
160### onRestoreEx<sup>12+</sup>
161
162onRestoreEx(bundleVersion: BundleVersion, restoreInfo: string): string | Promise&lt;string&gt;
163
164Called when data is being restored. You need to implement the extended data restore operation. Asynchronous implementation is supported.
165**onRestoreEx** and **onRestore** are mutually exclusive. Call **onRestoreEx** preferentially if it is overridden.
166The return value of **onRestoreEx** cannot be an empty string. If an empty string is returned, the system will attempt to call **onRestore**.
167The return value of **onRestoreEx()** is in JSON format. For details, see the sample code.
168
169**System capability**: SystemCapability.FileManagement.StorageService.Backup
170
171**Parameters**
172
173| Name       | Type                           | Mandatory| Description                          |
174| ------------- | ------------------------------- | ---- | ------------------------------ |
175| bundleVersion | [BundleVersion](#bundleversion) | Yes  | Version information of the application data to be restored.|
176| restoreInfo |string | Yes  | Parameter to be passed in the restore process. This field is reserved.|
177
178> **NOTE**
179>
180> The following shows the sample code for asynchronous implementation.
181
182**Example**
183
184  ```ts
185  import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
186  interface ErrorInfo {
187    type: string,
188    errorCode: number,
189    errorInfo: string
190  }
191
192  class BackupExt extends BackupExtensionAbility {
193    // Asynchronous implementation
194    async onRestoreEx(bundleVersion : BundleVersion, restoreInfo: string): Promise<string> {
195      console.log(`onRestoreEx ok ${JSON.stringify(bundleVersion)}`);
196      let errorInfo: ErrorInfo = {
197        type: "ErrorInfo",
198        errorCode: 0,
199        errorInfo: "app customized error info"
200      }
201      return JSON.stringify(errorInfo);
202    }
203  }
204  ```
205
206> **NOTE**
207>
208> The following shows the sample code for synchronous implementation.
209
210**Example**
211
212```ts
213  import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
214  interface ErrorInfo {
215    type: string,
216    errorCode: number,
217    errorInfo: string
218  }
219
220  class BackupExt extends BackupExtensionAbility {
221    // Synchronous implementation
222    onRestoreEx(bundleVersion : BundleVersion, restoreInfo: string): string {
223      console.log(`onRestoreEx ok ${JSON.stringify(bundleVersion)}`);
224      let errorInfo: ErrorInfo = {
225        type: "ErrorInfo",
226        errorCode: 0,
227        errorInfo: "app customized error info"
228      }
229      return JSON.stringify(errorInfo);
230    }
231  }
232```
233
234### onProcess<sup>12+</sup>
235
236onProcess(): string;
237
238Called to report the progress information. This callback is executed synchronously and implemented during the execution of **onBackup/onBackupEx** or **onRestore/onRestoreEx**.
239This callback returns the service processing progress of the application. The return value is in JSON format. For details, see the sample code.
240
241**System capability**: SystemCapability.FileManagement.StorageService.Backup
242
243> **NOTE**
244>
245> - The system provides the default processing mechanism if **onProcess** is not implemented. If **onProcess** is used, the return value must strictly comply with that in the sample code. If **onProcess** is used, **onBackup/onBackupEx** and **onRestore/onRestoreEx** must be asynchronously executed
246>   in a dedicated thread. Otherwise, **onProcess** cannot run properly. For details, see the sample code.
247> - The following example shows the recommended use of **onProcess**.
248
249**Example**
250
251  ```ts
252  import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
253  import { taskpool } from '@kit.ArkTS';
254
255  interface ProgressInfo {
256    progressed: number,
257    total: number
258  }
259
260  class BackupExt extends BackupExtensionAbility {
261    // In the following code, the appJob method is the simulated service code, and args specifies the parameters of appJob(). This method is used to start a worker thread in the task pool.
262    async onBackup() {
263      console.log(`onBackup begin`);
264      let jobTask: taskpool.Task = new taskpool.LongTask(appJob, args);
265      try {
266        await taskpool.execute(jobTask, taskpool.Priority.HIGH);
267      } catch (error) {
268        console.error("onBackup error." + error.message);
269      }
270      console.log(`onBackup end`);
271    }
272
273    async onRestore() {
274      console.log(`onRestore begin`);
275      let jobTask: taskpool.Task = new taskpool.LongTask(appJob, args);
276      try {
277        await taskpool.execute(jobTask, taskpool.Priority.HIGH);
278      } catch (error) {
279        console.error("onRestore error." + error.message);
280      }
281      console.log(`onRestore end`);
282    }
283
284
285    onProcess(): string {
286      console.log(`onProcess begin`);
287      let processInfo: ProgressInfo = {
288        progressed: 100, // Processed data.
289        total: 1000, // Total data.
290      }
291      console.log(`onProcess end`);
292      return JSON.stringify(processInfo);
293    }
294  }
295
296  @Concurrent
297  function appJob(args: number) : string {
298    // Service logic.
299    console.log(`appJob begin, args is: ` + args);
300    return "ok";
301  }
302  ```
303