• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.app.ability.appRecovery (appRecovery)
2
3The **appRecovery** module provides APIs for recovering faulty applications.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. In the current version, only applications with a single ability in a single process can be recovered.
8
9## Modules to Import
10```ts
11import appRecovery from '@ohos.app.ability.appRecovery';
12```
13
14## appRecovery.RestartFlag
15
16Enumerates the application restart flags. This enum is used as an input parameter of [enableAppRecovery](#apprecoveryenableapprecovery).
17
18**System capability**: SystemCapability.Ability.AbilityRuntime.Core
19
20| Name      | Value  | Description      |
21| ---------- | ---- | ---------- |
22| ALWAYS_RESTART   | 0    | The application is restarted in all cases.|
23| RESTART_WHEN_JS_CRASH   | 0x0001    | The application is restarted in the case of JS_CRASH. |
24| RESTART_WHEN_APP_FREEZE   | 0x0002    | The application is restarted in the case of APP_FREEZE. |
25| NO_RESTART           | 0xFFFF    | The application is not restarted in any case.|
26
27## appRecovery.SaveOccasionFlag
28
29Enumerates the scenarios for saving the application state. This enum is used as an input parameter of [enableAppRecovery](#apprecoveryenableapprecovery).
30
31**System capability**: SystemCapability.Ability.AbilityRuntime.Core
32
33| Name                         | Value  | Description                                                        |
34| ----------------------------- | ---- | ------------------------------------------------------------ |
35| SAVE_WHEN_ERROR            | 0x0001    | Saving the application state when an application fault occurs.|
36| SAVE_WHEN_BACKGROUND            | 0x0002    | Saving the application state when the application is switched to the background.|
37
38## appRecovery.SaveModeFlag
39
40Enumerates the application state saving modes. This enum is used as an input parameter of [enableAppRecovery](#apprecoveryenableapprecovery).
41
42**System capability**: SystemCapability.Ability.AbilityRuntime.Core
43
44| Name                         | Value  | Description                                                        |
45| ----------------------------- | ---- | ------------------------------------------------------------ |
46| SAVE_WITH_FILE             | 0x0001    | The application state is saved and written to the local file cache.|
47| SAVE_WITH_SHARED_MEMORY             | 0x0002    | The application state is saved in the memory. When the application exits due to a fault, it is written to the local file cache.|
48
49## appRecovery.enableAppRecovery
50
51enableAppRecovery(restart?: [RestartFlag](#apprecoveryrestartflag), saveOccasion?: [SaveOccasionFlag](#apprecoverysaveoccasionflag), saveMode?: [SaveModeFlag](#apprecoverysavemodeflag)) : void;
52
53Enables application recovery. After this API is called, the first ability that is displayed when the application is started from the initiator can be restored.
54
55**System capability**: SystemCapability.Ability.AbilityRuntime.Core
56
57**Parameters**
58
59| Name| Type| Mandatory| Description|
60| -------- | -------- | -------- | -------- |
61| restart | [RestartFlag](#apprecoveryrestartflag) | No| Whether the application is restarted upon a fault. By default, the application is not restarted.|
62| saveOccasion | [SaveOccasionFlag](#apprecoverysaveoccasionflag) | No| Scenario for saving the application state. By default, the state is saved when a fault occurs.|
63| saveMode | [SaveModeFlag](#apprecoverysavemodeflag) | No| Application state saving mode. By default, the application state is written to the local file cache.|
64
65**Example**
66
67```ts
68import appRecovery from '@ohos.app.ability.appRecovery';
69import AbilityStage from '@ohos.app.ability.AbilityStage';
70
71export default class MyAbilityStage extends AbilityStage {
72    onCreate() {
73        appRecovery.enableAppRecovery(
74            appRecovery.RestartFlag.ALWAYS_RESTART,
75            appRecovery.SaveOccasionFlag.SAVE_WHEN_ERROR,
76            appRecovery.SaveModeFlag.SAVE_WITH_FILE
77        );
78    }
79}
80```
81
82## appRecovery.restartApp
83
84restartApp(): void;
85
86Restarts the application. This API can be used together with APIs of [errorManager](js-apis-app-ability-errorManager.md).
87
88**System capability**: SystemCapability.Ability.AbilityRuntime.Core
89
90
91**Example**
92
93```ts
94import appRecovery from '@ohos.app.ability.appRecovery';
95import errorManager from '@ohos.app.ability.errorManager';
96
97let observer = {
98    onUnhandledException(errorMsg) {
99        console.log('onUnhandledException, errorMsg: ', errorMsg);
100        appRecovery.restartApp();
101    }
102};
103
104try {
105    errorManager.on('error', observer);
106} catch (paramError) {
107    console.log('error: ' + paramError.code + ', ' + paramError.message);
108}
109```
110
111## appRecovery.saveAppState
112
113saveAppState(): boolean;
114
115Saves the application state. This API can be used together with APIs of [errorManager](js-apis-app-ability-errorManager.md).
116
117**System capability**: SystemCapability.Ability.AbilityRuntime.Core
118
119**Return value**
120
121| Type| Description|
122| -------- | -------- |
123| boolean | Whether the application state is saved. The value **true** is returned if the application state is saved, and **false** is returned otherwise.|
124
125**Example**
126
127```ts
128import appRecovery from '@ohos.app.ability.appRecovery';
129import errorManager from '@ohos.app.ability.errorManager';
130
131let observer = {
132    onUnhandledException(errorMsg) {
133        console.log('onUnhandledException, errorMsg: ', errorMsg);
134        appRecovery.saveAppState();
135    }
136};
137
138try {
139    errorManager.on('error', observer);
140} catch (paramError) {
141    console.log('error: ' + paramError.code + ', ' + paramError.message);
142}
143```
144