diff --git a/en/application-dev/dfx/Readme-EN.md b/en/application-dev/dfx/Readme-EN.md index b8c6422a63e1f3fb8bd012a3e4175de1da055d8f..af9e5d190ab515b61be1c7441d72e264c87ca310 100644 --- a/en/application-dev/dfx/Readme-EN.md +++ b/en/application-dev/dfx/Readme-EN.md @@ -11,3 +11,4 @@ - [Development of Distributed Call Chain Tracing](hitracechain-guidelines.md) - Error Management - [Development of Error Manager](errormanager-guidelines.md) + - [Development of Application Recovery](apprecovery-guidelines.md) diff --git a/en/application-dev/dfx/apprecovery-guidelines.md b/en/application-dev/dfx/apprecovery-guidelines.md new file mode 100644 index 0000000000000000000000000000000000000000..0e4e7c257cbde0853a36bd8a3729ee707a4b2391 --- /dev/null +++ b/en/application-dev/dfx/apprecovery-guidelines.md @@ -0,0 +1,193 @@ +# Development of Application Recovery + +## When to Use + +During application running, some unexpected behaviors are inevitable. For example, unprocessed exceptions and errors are thrown, and the call or running constraints of the framework are violated. + +By default, the processes will exit as exception handling. However, if user data is generated during application use, process exits may interrupt user operations and cause data loss. +In this way, application recovery APIs may help you save temporary data, restart an application after it exits, and restore its status and data, which deliver a better user experience. + +Currently, the APIs support only the development of an application that adopts the stage model, single process, and single ability. + +## Available APIs + +The application recovery APIs are provided by the **appRecovery** module, which can be imported via **import**. For details, please refer to [Development Example](#development-example). This document describes behaviors of APIs in API version 9, and the content will update with changes. + +### Available APIs + +| API | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| enableAppRecovery(restart?: RestartFlag, saveOccasion?: SaveOccasionFlag, saveMode?: SaveModeFlag) : void; | Enables the application recovery function. | +| saveAppState(): boolean; | Saves the ability status of an application. | +| restartApp(): void; | Restarts the current process. If there is saved ability status, it will be passed to the **want** parameter's **wantParam** attribute of the **onCreate** lifecycle callback of the ability.| + +The APIs are used for troubleshooting and do not return any exception. Therefore, you need to be familiar with when they are used. + +**enableAppRecovery**: This API should be called during application initialization. For example, you can call this API in **onCreate** of **AbilityStage**. For details, please refer to the [parameter description](../reference/apis/js-apis-app-ability-appRecovery.md). + +**saveAppState**: After this API is called, the framework calls back **onSaveState** of the ability. If data saving is agreed to in this method, relevant data and the page stack of the ability are persisted to the local cache of the application. + +**restartApp**: After this API is called, the framework kills the current application process and restarts the ability in the foreground, with **APP_RECOVERY** specified as the startup cause. + +### Framework Fault Management Process + +Fault management is an important way for applications to deliver a better user experience. The application framework offers three methods for application fault management: fault listening, fault rectification, and fault query. + +- Fault listening refers to the process of registering [ErrorObserver](../reference/apis/js-apis-application-errorManager.md#errorobserver) via [errorManager](../reference/apis/js-apis-application-errorManager.md), listening for fault occurrence, and notifying the fault listener. + +- Fault rectification refers to [appRecovery](../reference/apis/js-apis-app-ability-appRecovery.md) and restarts an application to restore its status previous to a fault. + +- Fault query indicates that [faultLogger](../reference/apis/js-apis-faultLogger.md) obtains the fault information using its query API. + +The figure below does not illustrate the time when [faultLogger](../reference/apis/js-apis-faultLogger.md) is called. You can refer to [LastExitReason](../reference/apis/js-apis-application-abilityConstant.md#abilityconstantlastexitreason) passed during application initialization to determine whether to call [faultLogger](../reference/apis/js-apis-faultLogger.md) to query the information about the last fault. +![Fault rectification process](./figures/fault_rectification.png) + +It is recommended that you call [errorManager](../reference/apis/js-apis-application-errorManager.md) to process the exception. After the processing is complete, you can call the status saving API and restart the application. +If you do not register [ErrorObserver](../reference/apis/js-apis-application-errorManager.md#errorobserver) or enable application recovery, the application process will exit according to the default processing logic of the system. Users can restart the application from the home screen. +If you have enabled application recovery, the framework first checks whether a fault allows for ability status saving and whether you have configured ability status saving. If so, [onSaveState](../reference/apis/js-apis-application-ability.md#abilityonsavestate) of [Ability](../reference/apis/js-apis-application-ability.md#ability) is called back. Finally, the application is restarted. + +### Scenarios Supported by Application Fault Management APIs + +Common fault types include JavaScript application crash, application freezing, and C++ application crash. Generally, an application is closed when a crash occurs. Application freezing occurs when the application does not respond. The fault type can be ignored for the upper layer of an application. The recovery framework implements fault management in different scenarios based on the fault type. + +| Fault | Fault Listening| Status Saving| Automatic Restart| Log Query| +| ------------------------------------------------------------ | -------- | -------- | -------- | -------- | +| [JS_CRASH](../reference/apis/js-apis-faultLogger.md#faulttype) | Supported | Supported | Supported | Supported | +| [APP_FREEZE](../reference/apis/js-apis-faultLogger.md#faulttype) | Not supported | Not supported | Supported | Supported | +| [CPP_CRASH](../reference/apis/js-apis-faultLogger.md#faulttype) | Not supported | Not supported | Not supported | Supported | + +**Status Saving** in the table header means status saving when a fault occurs. To protect user data as much as possible in the application freezing fault, you can adopt either the periodic or automatic way, and the latter will save user data when an ability is switched to the background. + + + +## Development Example + +### Enabling Application Recovery + + Enable **appRecovery** during application initialization. The following is an example of **AbilityStage**: + +```ts +import AbilityStage from '@ohos.app.ability.AbilityStage' +import appRecovery from '@ohos.app.ability.appRecovery' + +export default class MyAbilityStage extends AbilityStage { + onCreate() { + console.info("[Demo] MyAbilityStage onCreate") + appRecovery.enableAppRecovery(appRecovery.RestartFlag.ALWAYS_RESTART, + appRecovery.SaveOccasionFlag.SAVE_WHEN_ERROR | appRecovery.SaveOccasionFlag.SAVE_WHEN_BACKGROUND, + appRecovery.SaveModeFlag.SAVE_WITH_FILE); + } +} +``` + +### Saving and Restoring Data + +After enabling **appRecovery**, you can use this function by either actively or passively saving the status and restoring data in the ability. +The following is an example of **MainAbility**: + +#### Importing the Service Package + +```ts +import errorManager from '@ohos.app.ability.errorManager' +import appRecovery from '@ohos.app.ability.appRecovery' +import AbilityConstant from '@ohos.app.ability.AbilityConstant' +``` + +#### Actively Saving Status and Restoring Data + +- Define and register the [ErrorObserver](../reference/apis/js-apis-application-errorManager.md#errorobserver) callback. + +```ts + var registerId = -1; + var callback = { + onUnhandledException: function (errMsg) { + console.log(errMsg); + appRecovery.saveAppState(); + appRecovery.restartApp(); + } + } + + onWindowStageCreate(windowStage) { + // Main window is created. Set a main page for this ability. + console.log("[Demo] MainAbility onWindowStageCreate") + + globalThis.registerObserver = (() => { + registerId = errorManager.registerErrorObserver(callback); + }) + + windowStage.loadContent("pages/index", null); + } +``` + +- Save data. + +After the callback triggers **appRecovery.saveAppState()**, **onSaveState(state, wantParams)** of **MainAbility** is triggered. + +```ts + onSaveState(state, wantParams) { + // Save application data. + console.log("[Demo] MainAbility onSaveState") + wantParams["myData"] = "my1234567"; + return AbilityConstant.onSaveResult.ALL_AGREE; + } +``` + +- Restore data. + +After the callback triggers **appRecovery.restartApp()**, the application is restarted. After the restart, **onSaveState(state, wantParams)** of **MainAbility** is called, and the saved data is in **parameters** of **want**. + +```ts +storage: LocalStorage +onCreate(want, launchParam) { + console.log("[Demo] MainAbility onCreate") + globalThis.abilityWant = want; + if (launchParam.launchReason == AbilityConstant.LaunchReason.APP_RECOVERY) { + this.storage = new LocalStorage(); + let recoveryData = want.parameters["myData"]; + this.storage.setOrCreate("myData", recoveryData); + this.context.restoreWindowStage(this.storage); + } +} +``` + +- Deregister **ErrorObserver callback**. + +```ts +onWindowStageDestroy() { + // Main window is destroyed to release UI resources. + console.log("[Demo] MainAbility onWindowStageDestroy") + + globalThis.unRegisterObserver = (() => { + errorManager.unregisterErrorObserver(registerId, (result) => { + console.log("[Demo] result " + result.code + ";" + result.message) + }); + }) +} +``` + +#### Passively Saving Status and Restoring Data + +This is triggered by the recovery framework. You do not need to register **ErrorObserver callback**. You only need to implement **onSaveState** of the ability for status saving and **onCreate** of the ability for data restoration. + +```ts +export default class MainAbility extends Ability { + storage: LocalStorage + onCreate(want, launchParam) { + console.log("[Demo] MainAbility onCreate") + globalThis.abilityWant = want; + if (launchParam.launchReason == AbilityConstant.LaunchReason.APP_RECOVERY) { + this.storage = new LocalStorage(); + let recoveryData = want.parameters["myData"]; + this.storage.setOrCreate("myData", recoveryData); + this.context.restoreWindowStage(this.storage); + } + } + + onSaveState(state, wantParams) { + // Save application data. + console.log("[Demo] MainAbility onSaveState") + wantParams["myData"] = "my1234567"; + return AbilityConstant.onSaveResult.ALL_AGREE; + } +} +``` diff --git a/en/application-dev/dfx/figures/fault_rectification.png b/en/application-dev/dfx/figures/fault_rectification.png new file mode 100644 index 0000000000000000000000000000000000000000..63ac5e5f666d5c23c9e9ea3123a9566013336aba Binary files /dev/null and b/en/application-dev/dfx/figures/fault_rectification.png differ diff --git a/en/application-dev/reference/apis/js-apis-cooperate.md b/en/application-dev/reference/apis/js-apis-cooperate.md index 6a90edc0c791cc97d9a23be5a0a1e9cff9e68337..92a153e5eb2a190a01f96ee4ff8ebfe7fac653ad 100644 --- a/en/application-dev/reference/apis/js-apis-cooperate.md +++ b/en/application-dev/reference/apis/js-apis-cooperate.md @@ -2,9 +2,11 @@ The Screen Hopping module enables two or more networked devices to share the keyboard and mouse for collaborative operations. -> **Description** +> **NOTE** > -> 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. +> - 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. +> - The APIs provided by this module are system APIs. + ## Modules to Import @@ -18,7 +20,7 @@ enable(enable: boolean, callback: AsyncCallback<void>): void Specifies whether to enable screen hopping. This API uses an asynchronous callback to return the result. -**System capability**: SystemCapability.MultimodalInput.Input.InputDeviceCooperate +**System capability**: SystemCapability.MultimodalInput.Input.Cooperate **Parameters** @@ -52,7 +54,7 @@ enable(enable: boolean): Promise<void> Specifies whether to enable screen hopping. This API uses a promise to return the result. -**System capability**: SystemCapability.MultimodalInput.Input.InputDeviceCooperate +**System capability**: SystemCapability.MultimodalInput.Input.Cooperate **Parameters** @@ -90,7 +92,7 @@ start(sinkDeviceDescriptor: string, srcInputDeviceId: number, callback: AsyncCal Starts screen hopping. This API uses an asynchronous callback to return the result. -**System capability**: SystemCapability.MultimodalInput.Input.InputDeviceCooperate +**System capability**: SystemCapability.MultimodalInput.Input.Cooperate **Parameters** @@ -133,7 +135,7 @@ start(sinkDeviceDescriptor: string, srcInputDeviceId: number): Promise\ Starts screen hopping. This API uses a promise to return the result. -**System capability**: SystemCapability.MultimodalInput.Input.InputDeviceCooperate +**System capability**: SystemCapability.MultimodalInput.Input.Cooperate **Parameters** @@ -181,7 +183,7 @@ stop(callback: AsyncCallback\): void Stops screen hopping. This API uses an asynchronous callback to return the result. -**System capability**: SystemCapability.MultimodalInput.Input.InputDeviceCooperate +**System capability**: SystemCapability.MultimodalInput.Input.Cooperate **Parameters** @@ -213,9 +215,9 @@ stop(): Promise\ Stops screen hopping. This API uses a promise to return the result. -**System capability**: SystemCapability.MultimodalInput.Input.InputDeviceCooperate +**System capability**: SystemCapability.MultimodalInput.Input.Cooperate -**Parameters** +**Return value** | Name | Description | | -------- | ---------------------------- | @@ -241,7 +243,7 @@ getState(deviceDescriptor: string, callback: AsyncCallback<{ state: boolean }>): Checks whether screen hopping is enabled. This API uses an asynchronous callback to return the result. -**System capability**: SystemCapability.MultimodalInput.Input.InputDeviceCooperate +**System capability**: SystemCapability.MultimodalInput.Input.Cooperate **Parameters** @@ -273,7 +275,7 @@ getState(deviceDescriptor: string): Promise<{ state: boolean }> Checks whether screen hopping is enabled. This API uses a promise to return the result. -**System capability**: SystemCapability.MultimodalInput.Input.InputDeviceCooperate +**System capability**: SystemCapability.MultimodalInput.Input.Cooperate **Parameters** @@ -311,7 +313,7 @@ on(type: 'cooperation', callback: AsyncCallback<{ deviceDescriptor: string, even Enables listening for screen hopping events. -**System capability**: SystemCapability.MultimodalInput.Input.InputDeviceCooperate +**System capability**: SystemCapability.MultimodalInput.Input.Cooperate **Parameters** @@ -340,7 +342,7 @@ off(type: 'cooperation', callback?: AsyncCallback\): void Disables listening for screen hopping events. -**System capability**: SystemCapability.MultimodalInput.Input.InputDeviceCooperate +**System capability**: SystemCapability.MultimodalInput.Input.Cooperate **Parameters** @@ -384,7 +386,7 @@ try { Enumerates screen hopping event. -**System capability**: SystemCapability.MultimodalInput.Input.InputDeviceCooperate +**System capability**: SystemCapability.MultimodalInput.Input.Cooperate | Name | Value | Description | | -------- | --------- | ----------------- | diff --git a/en/application-dev/reference/apis/js-apis-inputdevice.md b/en/application-dev/reference/apis/js-apis-inputdevice.md index 5b8764a13f7c9be2eabc47f67a6f34df29e110a9..e1fff14e45650672227184add159a891657bab56 100644 --- a/en/application-dev/reference/apis/js-apis-inputdevice.md +++ b/en/application-dev/reference/apis/js-apis-inputdevice.md @@ -460,10 +460,10 @@ Defines the listener for hot swap events of an input device. **System capability**: SystemCapability.MultimodalInput.Input.InputDevice -| Name | Type | Description | -| -------- | ------------------------- | --------------------------------- | -| type | [ChangedType](#changedtype) | Device change type, which indicates whether an input device is inserted or removed. | -| deviceId | number | Unique ID of the input device. If the same physical device is repeatedly inserted and removed, its ID changes.| +| Name | Type | Readable | Writable | Description | +| --------- | ------ | ---- | ---- | ------- | +| type | [ChangedType](#changedtype) | Yes| No| Device change type, which indicates whether an input device is inserted or removed.| +| deviceId | number | Yes| No| Unique ID of the input device. If the same physical device is repeatedly inserted and removed, its ID changes.| ## InputDeviceData @@ -471,18 +471,18 @@ Defines the information about an input device. **System capability**: SystemCapability.MultimodalInput.Input.InputDevice -| Name | Type | Description | -| -------------------- | -------------------------------------- | ---------------------------------------- | -| id | number | Unique ID of the input device. If the same physical device is repeatedly inserted and removed, its ID changes. | -| name | string | Name of the input device. | -| sources | Array<[SourceType](#sourcetype)> | Source type of the input device. For example, if a keyboard is attached with a touchpad, the device has two input sources: keyboard and touchpad.| -| axisRanges | Array<[axisRanges](#axisrange)> | Axis information of the input device. | -| bus9+ | number | Bus type of the input device. | -| product9+ | number | Product information of the input device. | -| vendor9+ | number | Vendor information of the input device. | -| version9+ | number | Version information of the input device. | -| phys9+ | string | Physical address of the input device. | -| uniq9+ | string | Unique ID of the input device. | +| Name | Type | Readable | Writable | Description | +| --------- | ------ | ---- | ---- | ------- | +| id | number | Yes| No| Unique ID of the input device. If the same physical device is repeatedly inserted and removed, its ID changes.| +| name | string | Yes| No| Name of the input device. | +| sources | Array<[SourceType](#sourcetype)> | Yes| No| Source type of the input device. For example, if a keyboard is attached with a touchpad, the device has two input sources: keyboard and touchpad.| +| axisRanges | Array<[axisRanges](#axisrange)> | Yes| No| Axis information of the input device. | +| bus9+ | number | Yes| No| Bus type of the input device. | +| product9+ | number | Yes| No| Product information of the input device. | +| vendor9+ | number | Yes| No| Vendor information of the input device. | +| version9+ | number | Yes| No| Version information of the input device. | +| phys9+ | string | Yes| No| Physical address of the input device. | +| uniq9+ | string | Yes| No| Unique ID of the input device. | ## AxisType9+ @@ -490,17 +490,17 @@ Defines the axis type of an input device. **System capability**: SystemCapability.MultimodalInput.Input.InputDevice -| Name | Type | Description | -| ----------- | ------ | --------------- | -| touchMajor | string | touchMajor axis. | -| touchMinor | string | touchMinor axis. | -| toolMinor | string | toolMinor axis. | -| toolMajor | string | toolMajor axis. | -| orientation | string | Orientation axis.| -| pressure | string | Pressure axis. | -| x | string | X axis. | -| y | string | Y axis. | -| NULL | string | None. | +| Name | Type | Readable | Writable | Description | +| --------- | ------ | ---- | ---- | ------- | +| touchMajor | string | Yes| No| touchMajor axis. | +| touchMinor | string | Yes| No| touchMinor axis. | +| toolMinor | string | Yes| No| toolMinor axis. | +| toolMajor | string | Yes| No| toolMajor axis. | +| orientation | string | Yes| No| Orientation axis.| +| pressure | string | Yes| No| Pressure axis. | +| x | string | Yes| No| X axis. | +| y | string | Yes| No| Y axis. | +| NULL | string | Yes| No| None. | ## AxisRange @@ -508,41 +508,41 @@ Defines the axis range of an input device. **System capability**: SystemCapability.MultimodalInput.Input.InputDevice -| Name | Type | Description | -| ----------------------- | ------------------------- | -------- | -| source | [SourceType](#sourcetype) | Input source type of the axis.| -| axis | [AxisType](#axistype9) | Axis type. | -| max | number | Maximum value of the axis. | -| min | number | Minimum value of the axis. | -| fuzz9+ | number | Fuzzy value of the axis. | -| flat9+ | number | Benchmark value of the axis. | -| resolution9+ | number | Resolution of the axis. | +| Name | Type | Readable | Writable | Description | +| --------- | ------ | ---- | ---- | ------- | +| source | [SourceType](#sourcetype) | Yes| No| Input source type of the axis.| +| axis | [AxisType](#axistype9) | Yes| No| Axis type. | +| max | number | Yes| No| Maximum value of the axis. | +| min | number | Yes| No| Minimum value of the axis. | +| fuzz9+ | number | Yes| No| Fuzzy value of the axis. | +| flat9+ | number | Yes| No| Benchmark value of the axis. | +| resolution9+ | number | Yes| No| Resolution of the axis. | -## SourceType +## SourceType9+ Enumerates the input source types. For example, if a mouse reports an x-axis event, the source of the x-axis is the mouse. **System capability**: SystemCapability.MultimodalInput.Input.InputDevice -| Name | Type | Description | -| ----------- | ------ | ----------- | -| keyboard | string | The input device is a keyboard. | -| touchscreen | string | The input device is a touchscreen.| -| mouse | string | The input device is a mouse. | -| trackball | string | The input device is a trackball.| -| touchpad | string | The input device is a touchpad.| -| joystick | string | The input device is a joystick.| +| Name | Type | Readable | Writable | Description | +| --------- | ------ | ---- | ---- | ------- | +| keyboard | string | Yes| No| The input device is a keyboard. | +| touchscreen | string | Yes| No| The input device is a touchscreen.| +| mouse | string | Yes| No| The input device is a mouse. | +| trackball | string | Yes| No| The input device is a trackball.| +| touchpad | string | Yes| No| The input device is a touchpad.| +| joystick | string | Yes| No| The input device is a joystick.| -## ChangedType +## ChangedType9+ Defines the change type for the hot swap event of an input device. **System capability**: SystemCapability.MultimodalInput.Input.InputDevice -| Name | Type | Description | -| ------ | ------ | --------- | -| add | string | An input device is inserted.| -| remove | string | An input device is removed.| +| Name | Type | Readable | Writable | Description | +| --------- | ------ | ---- | ---- | ------- | +| add | string | Yes| No| An input device is inserted.| +| remove | string | Yes| No| An input device is removed.| ## KeyboardType9+ @@ -550,11 +550,11 @@ Enumerates the keyboard types. **System capability**: SystemCapability.MultimodalInput.Input.InputDevice -| Name | Type | Value | Description | -| ------------------- | ------ | ---- | --------- | -| NONE | number | 0 | Keyboard without keys. | -| UNKNOWN | number | 1 | Keyboard with unknown keys.| -| ALPHABETIC_KEYBOARD | number | 2 | Full keyboard. | -| DIGITAL_KEYBOARD | number | 3 | Keypad. | -| HANDWRITING_PEN | number | 4 | Stylus. | -| REMOTE_CONTROL | number | 5 | Remote control. | +| Name | Value | Description | +| ------------------- | ---- | --------- | +| NONE | 0 | Keyboard without keys. | +| UNKNOWN | 1 | Keyboard with unknown keys.| +| ALPHABETIC_KEYBOARD | 2 | Full keyboard. | +| DIGITAL_KEYBOARD | 3 | Keypad. | +| HANDWRITING_PEN | 4 | Stylus. | +| REMOTE_CONTROL | 5 | Remote control. | diff --git a/en/application-dev/reference/apis/js-apis-pointer.md b/en/application-dev/reference/apis/js-apis-pointer.md index ea2d452000bb542e55232a29456d3811fd24526c..06bb32eecce0d9b40133160a8689c6b80c27ad61 100644 --- a/en/application-dev/reference/apis/js-apis-pointer.md +++ b/en/application-dev/reference/apis/js-apis-pointer.md @@ -135,6 +135,8 @@ Sets the mouse movement speed. This API uses an asynchronous callback to return **System capability**: SystemCapability.MultimodalInput.Input.Pointer +**System API**: This is a system API. + **Parameters** | Name | Type | Mandatory | Description | @@ -166,6 +168,8 @@ Sets the mouse movement speed. This API uses a promise to return the result. **System capability**: SystemCapability.MultimodalInput.Input.Pointer +**System API**: This is a system API. + **Parameters** | Name | Type | Mandatory | Description | @@ -198,6 +202,8 @@ Obtains the mouse movement speed. This API uses an asynchronous callback to retu **System capability**: SystemCapability.MultimodalInput.Input.Pointer +**System API**: This is a system API. + **Parameters** | Name | Type | Mandatory | Description | @@ -254,6 +260,8 @@ Obtains the mouse pointer style. This API uses an asynchronous callback to retur **System capability**: SystemCapability.MultimodalInput.Input.Pointer +**System API**: This is a system API. + **Parameters** | Name | Type | Mandatory | Description |