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 16/** 17 * @file 18 * @kit AbilityKit 19 */ 20 21import UIAbilityContext from './application/UIAbilityContext'; 22import Want from './@ohos.app.ability.Want'; 23 24/** 25 * This module provides the capability of app recovery. 26 * You can use this capability to save state and restart the application 27 * which let end user continue their workflow when app error occurs. 28 * This api support restart the app when js crash or app freeze occurs currently. 29 * 30 * @namespace appRecovery 31 * @syscap SystemCapability.Ability.AbilityRuntime.Core 32 * @since 9 33 */ 34/** 35 * This module provides the capability of app recovery. 36 * You can use this capability to save state and restart the application 37 * which let end user continue their workflow when app error occurs. 38 * This api support restart the app when js crash or app freeze occurs currently. 39 * 40 * @namespace appRecovery 41 * @syscap SystemCapability.Ability.AbilityRuntime.Core 42 * @atomicservice 43 * @since 11 44 */ 45declare namespace appRecovery { 46 /** 47 * The flag that determines when to restart you app. 48 * 49 * @enum { number } 50 * @syscap SystemCapability.Ability.AbilityRuntime.Core 51 * @since 9 52 */ 53 /** 54 * The flag that determines when to restart you app. 55 * 56 * @enum { number } 57 * @syscap SystemCapability.Ability.AbilityRuntime.Core 58 * @atomicservice 59 * @since 11 60 */ 61 enum RestartFlag { 62 /** 63 * No restart restrictions. 64 * 65 * @syscap SystemCapability.Ability.AbilityRuntime.Core 66 * @since 9 67 */ 68 /** 69 * No restart restrictions. 70 * 71 * @syscap SystemCapability.Ability.AbilityRuntime.Core 72 * @atomicservice 73 * @since 11 74 */ 75 ALWAYS_RESTART = 0, 76 77 /** 78 * Restart if current app process encounter uncaught js/ts/ets exception. 79 * 80 * @syscap SystemCapability.Ability.AbilityRuntime.Core 81 * @since 9 82 */ 83 /** 84 * Restart if current app process encounter uncaught js/ts/ets exception. 85 * 86 * @syscap SystemCapability.Ability.AbilityRuntime.Core 87 * @atomicservice 88 * @since 11 89 */ 90 RESTART_WHEN_JS_CRASH = 0x0001, 91 92 /** 93 * Restart if the main thread of current app process block more than 6 seconds. 94 * 95 * @syscap SystemCapability.Ability.AbilityRuntime.Core 96 * @since 9 97 */ 98 /** 99 * Restart if the main thread of current app process block more than 6 seconds. 100 * 101 * @syscap SystemCapability.Ability.AbilityRuntime.Core 102 * @atomicservice 103 * @since 11 104 */ 105 RESTART_WHEN_APP_FREEZE = 0x0002, 106 107 /** 108 * Do not restart in any scenario. 109 * 110 * @syscap SystemCapability.Ability.AbilityRuntime.Core 111 * @since 9 112 */ 113 /** 114 * Do not restart in any scenario. 115 * 116 * @syscap SystemCapability.Ability.AbilityRuntime.Core 117 * @atomicservice 118 * @since 11 119 */ 120 NO_RESTART = 0xFFFF 121 } 122 123 /** 124 * The flag that determines when to save ability state. 125 * When start saving ability state, the { ohos.app.ability.UiAbility.onSaveState } will be called and 126 * the page stack of current ability will be saved automatically. 127 * 128 * @enum { number } 129 * @syscap SystemCapability.Ability.AbilityRuntime.Core 130 * @since 9 131 */ 132 /** 133 * The flag that determines when to save ability state. 134 * When start saving ability state, the { ohos.app.ability.UiAbility.onSaveState } will be called and 135 * the page stack of current ability will be saved automatically. 136 * 137 * @enum { number } 138 * @syscap SystemCapability.Ability.AbilityRuntime.Core 139 * @atomicservice 140 * @since 11 141 */ 142 enum SaveOccasionFlag { 143 /** 144 * Saving ability state when an error occurs. 145 * The error in current situation has the same semantic with { errorManager } defines 146 * which means the state that the application cannot continue to work but allows developer to handle. 147 * 148 * @syscap SystemCapability.Ability.AbilityRuntime.Core 149 * @since 9 150 */ 151 /** 152 * Saving ability state when an error occurs. 153 * The error in current situation has the same semantic with { errorManager } defines 154 * which means the state that the application cannot continue to work but allows developer to handle. 155 * 156 * @syscap SystemCapability.Ability.AbilityRuntime.Core 157 * @atomicservice 158 * @since 11 159 */ 160 SAVE_WHEN_ERROR = 0x0001, 161 162 /** 163 * Saving ability state when ability is in background. 164 * 165 * @syscap SystemCapability.Ability.AbilityRuntime.Core 166 * @since 9 167 */ 168 /** 169 * Saving ability state when ability is in background. 170 * 171 * @syscap SystemCapability.Ability.AbilityRuntime.Core 172 * @atomicservice 173 * @since 11 174 */ 175 SAVE_WHEN_BACKGROUND = 0x0002 176 } 177 178 /** 179 * The flag that determines how to save the ability state. 180 * 181 * @enum { number } 182 * @syscap SystemCapability.Ability.AbilityRuntime.Core 183 * @since 9 184 */ 185 /** 186 * The flag that determines how to save the ability state. 187 * 188 * @enum { number } 189 * @syscap SystemCapability.Ability.AbilityRuntime.Core 190 * @atomicservice 191 * @since 11 192 */ 193 enum SaveModeFlag { 194 /** 195 * Save state to file immediately. 196 * 197 * @syscap SystemCapability.Ability.AbilityRuntime.Core 198 * @since 9 199 */ 200 /** 201 * Save state to file immediately. 202 * 203 * @syscap SystemCapability.Ability.AbilityRuntime.Core 204 * @atomicservice 205 * @since 11 206 */ 207 SAVE_WITH_FILE = 0x0001, 208 209 /** 210 * Keep state in memory and flush to file when error occurs or { restartApp } is invoked. 211 * 212 * @syscap SystemCapability.Ability.AbilityRuntime.Core 213 * @since 9 214 */ 215 /** 216 * Keep state in memory and flush to file when error occurs or { restartApp } is invoked. 217 * 218 * @syscap SystemCapability.Ability.AbilityRuntime.Core 219 * @atomicservice 220 * @since 11 221 */ 222 SAVE_WITH_SHARED_MEMORY = 0x0002 223 } 224 225 /** 226 * Enable appRecovery function. 227 * 228 * @param { RestartFlag } [restart] - The flag that determines the restart cases of your app, default value is { ALWAYS_RESTART }. 229 * @param { SaveOccasionFlag } [saveOccasion] - The flag that determines when to save ability state, default value is { SAVE_WHEN_ERROR }. 230 * @param { SaveModeFlag } [saveMode] - The flag that determines how to save the ability state, default value is { SAVE_WITH_FILE }. 231 * @syscap SystemCapability.Ability.AbilityRuntime.Core 232 * @StageModelOnly 233 * @since 9 234 */ 235 /** 236 * Enable appRecovery function. 237 * 238 * @param { RestartFlag } [restart] - The flag that determines the restart cases of your app, default value is { ALWAYS_RESTART }. 239 * @param { SaveOccasionFlag } [saveOccasion] - The flag that determines when to save ability state, default value is { SAVE_WHEN_ERROR }. 240 * @param { SaveModeFlag } [saveMode] - The flag that determines how to save the ability state, default value is { SAVE_WITH_FILE }. 241 * @syscap SystemCapability.Ability.AbilityRuntime.Core 242 * @StageModelOnly 243 * @atomicservice 244 * @since 11 245 */ 246 function enableAppRecovery(restart?: RestartFlag, saveOccasion?: SaveOccasionFlag, saveMode?: SaveModeFlag): void; 247 248 /** 249 * Restart current process and launch the first ability(the entry ability in most cases) of current process. 250 * The previous saved state will be filled in the { want.wantParams } of { UIAbility.onCreate } interface. 251 * and the { param } of { UIAbility.onCreate } will be set to APP_RECOVERY. 252 * 253 * @syscap SystemCapability.Ability.AbilityRuntime.Core 254 * @StageModelOnly 255 * @since 9 256 */ 257 /** 258 * Restart current process and launch the first ability(the entry ability in most cases) of current process. 259 * The previous saved state will be filled in the { want.wantParams } of { UIAbility.onCreate } interface. 260 * and the { param } of { UIAbility.onCreate } will be set to APP_RECOVERY. 261 * 262 * @syscap SystemCapability.Ability.AbilityRuntime.Core 263 * @StageModelOnly 264 * @atomicservice 265 * @since 11 266 */ 267 function restartApp(): void; 268 269 /** 270 * Set the want that will be used when app restart initiated by appRecovery. 271 * 272 * @param { Want } want - that defines the ability you want to start 273 * @syscap SystemCapability.Ability.AbilityRuntime.Core 274 * @StageModelOnly 275 * @since 10 276 */ 277 /** 278 * Set the want that will be used when app restart initiated by appRecovery. 279 * 280 * @param { Want } want - that defines the ability you want to start 281 * @syscap SystemCapability.Ability.AbilityRuntime.Core 282 * @StageModelOnly 283 * @atomicservice 284 * @since 11 285 */ 286 function setRestartWant(want: Want): void; 287 288 /** 289 * Actively save application state. 290 * The ability framework will call { UIAbility.onSaveState } of first launched ability and 291 * persist state as { saveOccasion } flag from { enableAppRecovery } interface. 292 * 293 * @returns { boolean } true if save data successfully, otherwise false. 294 * @syscap SystemCapability.Ability.AbilityRuntime.Core 295 * @StageModelOnly 296 * @since 9 297 */ 298 /** 299 * Actively save application state. 300 * The ability framework will call { UIAbility.onSaveState } of first launched ability and 301 * persist state as { saveOccasion } flag from { enableAppRecovery } interface. 302 * 303 * @returns { boolean } true if save data successfully, otherwise false. 304 * @syscap SystemCapability.Ability.AbilityRuntime.Core 305 * @StageModelOnly 306 * @atomicservice 307 * @since 11 308 */ 309 function saveAppState(): boolean; 310 /** 311 * Save the ability state according to the context. 312 * 313 * @param { UIAbilityContext } [context] - context indicates the ability context you want to save state. 314 * If context is not specified, the onSaveState will be invoked on all the recoverable abilities in current process. 315 * @returns { boolean } true if save data successfully, otherwise false. 316 * @syscap SystemCapability.Ability.AbilityRuntime.Core 317 * @StageModelOnly 318 * @since 10 319 */ 320 /** 321 * Save the ability state according to the context. 322 * 323 * @param { UIAbilityContext } [context] - context indicates the ability context you want to save state. 324 * If context is not specified, the onSaveState will be invoked on all the recoverable abilities in current process. 325 * @returns { boolean } true if save data successfully, otherwise false. 326 * @syscap SystemCapability.Ability.AbilityRuntime.Core 327 * @StageModelOnly 328 * @atomicservice 329 * @since 11 330 */ 331 function saveAppState(context?: UIAbilityContext): boolean; 332} 333 334export default appRecovery; 335