1/* 2 * Copyright (c) 2022-2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"), 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16import UIAbilityContext from './application/UIAbilityContext'; 17import Want from './@ohos.app.ability.Want'; 18 19/** 20 * This module provides the capability of app recovery. 21 * You can use this capability to save state and restart the application 22 * which let end user continue their workflow when app error occurs. 23 * This api support restart the app when js crash or app freeze occurs currently. 24 * 25 * @namespace appRecovery 26 * @syscap SystemCapability.Ability.AbilityRuntime.Core 27 * @since 9 28 */ 29declare namespace appRecovery { 30 /** 31 * The flag that determines when to restart you app. 32 * 33 * @enum { number } 34 * @syscap SystemCapability.Ability.AbilityRuntime.Core 35 * @since 9 36 */ 37 enum RestartFlag { 38 /** 39 * No restart restrictions. 40 * 41 * @syscap SystemCapability.Ability.AbilityRuntime.Core 42 * @since 9 43 */ 44 ALWAYS_RESTART = 0, 45 46 /** 47 * Restart if current app process encounter uncaught js/ts/ets exception. 48 * 49 * @syscap SystemCapability.Ability.AbilityRuntime.Core 50 * @since 9 51 */ 52 RESTART_WHEN_JS_CRASH = 0x0001, 53 54 /** 55 * Restart if the main thread of current app process block more than 6 seconds. 56 * 57 * @syscap SystemCapability.Ability.AbilityRuntime.Core 58 * @since 9 59 */ 60 RESTART_WHEN_APP_FREEZE = 0x0002, 61 62 /** 63 * Do not restart in any scenario. 64 * 65 * @syscap SystemCapability.Ability.AbilityRuntime.Core 66 * @since 9 67 */ 68 NO_RESTART = 0xFFFF 69 } 70 71 /** 72 * The flag that determines when to save ability state. 73 * When start saving ability state, the { ohos.app.ability.UiAbility.onSaveState } will be called and 74 * the page stack of current ability will be saved automatically. 75 * 76 * @enum { number } 77 * @syscap SystemCapability.Ability.AbilityRuntime.Core 78 * @since 9 79 */ 80 enum SaveOccasionFlag { 81 /** 82 * Saving ability state when an error occurs. 83 * The error in current situation has the same semantic with { errorManager } defines 84 * which means the state that the application cannot continue to work but allows developer to handle. 85 * 86 * @syscap SystemCapability.Ability.AbilityRuntime.Core 87 * @since 9 88 */ 89 SAVE_WHEN_ERROR = 0x0001, 90 91 /** 92 * Saving ability state when ability is in background. 93 * 94 * @syscap SystemCapability.Ability.AbilityRuntime.Core 95 * @since 9 96 */ 97 SAVE_WHEN_BACKGROUND = 0x0002 98 } 99 100 /** 101 * The flag that determines how to save the ability state. 102 * 103 * @enum { number } 104 * @syscap SystemCapability.Ability.AbilityRuntime.Core 105 * @since 9 106 */ 107 enum SaveModeFlag { 108 /** 109 * Save state to file immediately. 110 * 111 * @syscap SystemCapability.Ability.AbilityRuntime.Core 112 * @since 9 113 */ 114 SAVE_WITH_FILE = 0x0001, 115 116 /** 117 * Keep state in memory and flush to file when error occurs or { restartApp } is invoked. 118 * 119 * @syscap SystemCapability.Ability.AbilityRuntime.Core 120 * @since 9 121 */ 122 SAVE_WITH_SHARED_MEMORY = 0x0002 123 } 124 125 /** 126 * Enable appRecovery function. 127 * 128 * @param { RestartFlag } [restart] - The flag that determines the restart cases of your app, default value is { ALWAYS_RESTART }. 129 * @param { SaveOccasionFlag } [saveOccasion] - The flag that determines when to save ability state, default value is { SAVE_WHEN_ERROR }. 130 * @param { SaveModeFlag } [saveMode] - The flag that determines how to save the ability state, default value is { SAVE_WITH_FILE }. 131 * @syscap SystemCapability.Ability.AbilityRuntime.Core 132 * @StageModelOnly 133 * @since 9 134 */ 135 function enableAppRecovery(restart?: RestartFlag, saveOccasion?: SaveOccasionFlag, saveMode?: SaveModeFlag): void; 136 137 /** 138 * Restart current process and launch the first ability(the entry ability in most cases) of current process. 139 * The previous saved state will be filled in the { want.wantParams } of { UIAbility.onCreate } interface. 140 * and the { param } of { UIAbility.onCreate } will be set to APP_RECOVERY. 141 * 142 * @syscap SystemCapability.Ability.AbilityRuntime.Core 143 * @StageModelOnly 144 * @since 9 145 */ 146 function restartApp(): void; 147 148 /** 149 * Set the want that will be used when app restart initiated by appRecovery. 150 * 151 * @param { Want } want - that defines the ability you want to start 152 * @syscap SystemCapability.Ability.AbilityRuntime.Core 153 * @StageModelOnly 154 * @since 10 155 */ 156 function setRestartWant(want: Want): void; 157 158 /** 159 * Actively save application state. 160 * The ability framework will call { UIAbility.onSaveState } of first launched ability and 161 * persist state as { saveOccasion } flag from { enableAppRecovery } interface. 162 * 163 * @returns { boolean } true if save data successfully, otherwise false. 164 * @syscap SystemCapability.Ability.AbilityRuntime.Core 165 * @StageModelOnly 166 * @since 9 167 */ 168 function saveAppState(): boolean; 169 /** 170 * Save the ability state according to the context. 171 * 172 * @param { UIAbilityContext } [context] - context indicates the ability context you want to save state. 173 * If context is not specified, the onSaveState will be invoked on all the recoverable abilities in current process. 174 * @returns { boolean } true if save data successfully, otherwise false. 175 * @syscap SystemCapability.Ability.AbilityRuntime.Core 176 * @StageModelOnly 177 * @since 10 178 */ 179 function saveAppState(context?: UIAbilityContext): boolean; 180} 181 182export default appRecovery; 183