From db923db142cf7db72b2791357283bc306b8b87ad Mon Sep 17 00:00:00 2001 From: shawn_he Date: Tue, 13 Dec 2022 19:11:52 +0800 Subject: [PATCH] update doc Signed-off-by: shawn_he --- .../reference/apis/js-apis-hitracechain.md | 16 +- .../reference/apis/js-apis-inputconsumer.md | 99 +++++----- .../apis/js-apis-inputeventclient.md | 35 ++-- .../reference/apis/js-apis-inputmonitor.md | 186 +++++++++--------- .../reference/apis/js-apis-keyevent.md | 55 +++--- .../reference/apis/js-apis-mouseevent.md | 100 +++++----- .../reference/apis/js-apis-telephony-data.md | 48 ++--- en/device-dev/subsystems/subsys-ota-guide.md | 140 ++++++------- 8 files changed, 345 insertions(+), 334 deletions(-) diff --git a/en/application-dev/reference/apis/js-apis-hitracechain.md b/en/application-dev/reference/apis/js-apis-hitracechain.md index 198615d8bf..aaf38a1962 100644 --- a/en/application-dev/reference/apis/js-apis-hitracechain.md +++ b/en/application-dev/reference/apis/js-apis-hitracechain.md @@ -18,7 +18,7 @@ Enumerates trace flag types. **System capability**: SystemCapability.HiviewDFX.HiTrace -| Name | Default Value | Description | +| Name | Value | Description | | -------- | -------- | -------- | | DEFAULT | 0 | Default flag. | | INCLUDE_ASYNC | 1 | Asynchronous call flag. By default, only synchronous calls are traced. If this flag is set, both synchronous and asynchronous calls will be traced. | @@ -35,7 +35,7 @@ Enumerates trace point types. **System capability**: SystemCapability.HiviewDFX.HiTrace -| Name| Default Value | Description | +| Name| Value | Description | | -------- | -------- | -------- | | CS | 0 | Client Send (CS) trace point. | | CR | 1 | Client Receive (CS) trace point. | @@ -49,7 +49,7 @@ Enumerates communication modes. **System capability**: SystemCapability.HiviewDFX.HiTrace -| Name| Default Value | Description | +| Name| Value | Description | | -------- | -------- | -------- | | DEFAULT | 0 | Default communication mode. | | THREAD | 1 | Inter-thread communication. | @@ -84,7 +84,7 @@ Starts call chain tracing. This API works in synchronous manner. | name | string | Yes| Traced service name. | | flags | number | No| Trace flag combination. For details, see [HiTraceFlag](#hitraceflag). | -**Return Value** +**Return value** | Type | Description | | -------- | -------- | @@ -126,7 +126,7 @@ Obtains the trace ID. This API works in synchronous manner. **System capability**: SystemCapability.HiviewDFX.HiTrace -**Return Value** +**Return value** | Type | Description | | -------- | -------- | @@ -187,7 +187,7 @@ Creates a trace span. This API works in synchronous manner. **System capability**: SystemCapability.HiviewDFX.HiTrace -**Return Value** +**Return value** | Type | Description | | -------- | -------- | @@ -240,7 +240,7 @@ Checks whether a **HiTraceId** instance is valid. This API works in synchronous | -------- | -------- | -------- | -------- | | id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance. | -**Return Value** +**Return value** | Type | Description | | -------- | -------- | @@ -268,7 +268,7 @@ Checks whether the specified trace flag in the **HiTraceId** instance is enabled | id | [HiTraceId](#hitraceid) | Yes | **HiTraceId** instance. | | flag | [HiTraceFlag](#hitraceflag) | Yes | Specified trace flag. | -**Return Value** +**Return value** | Type | Description | | -------- | -------- | diff --git a/en/application-dev/reference/apis/js-apis-inputconsumer.md b/en/application-dev/reference/apis/js-apis-inputconsumer.md index 373fbf8fae..9f3972a318 100644 --- a/en/application-dev/reference/apis/js-apis-inputconsumer.md +++ b/en/application-dev/reference/apis/js-apis-inputconsumer.md @@ -1,18 +1,18 @@ # Input Consumer -The Input Consumer module implements listening for key events. +The Input Consumer module implements listening for combination key events. > **NOTE** > > - The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. > -> - The APIs of this module are system APIs and cannot be called by third-party applications. +> - The APIs provided by this module are system APIs. ## Modules to Import -``` +```js import inputConsumer from '@ohos.multimodalInput.inputConsumer'; ``` @@ -21,32 +21,29 @@ import inputConsumer from '@ohos.multimodalInput.inputConsumer'; on(type: "key", keyOptions: KeyOptions, callback: Callback<KeyOptions>): void -Enables listening for combination key events. When a combination key event that meets the specified conditions occurs, **keyOptions** will be passed as an input parameter to **callback**. - -This is a system API. +Enables listening for combination key events. This API uses an asynchronous callback to return the combination key data when a combination key event that meets the specified condition occurs. **System capability**: SystemCapability.MultimodalInput.Input.InputConsumer **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Type of the key input event to listen for. Only **key** is supported.| -| keyOptions | [keyOptions](#keyoptions) | Yes| Key option, which specifies the condition for combination key input.| -| callback | Callback<KeyOptions> | Yes| Callback used to return the result.
When a key input event that meets the specified options occurs, **keyOptions** will be passed as an input parameter to **callback**.| +| Name | Type | Mandatory | Description | +| ---------- | -------------------------- | ---- | ---------------------------------------- | +| type | string | Yes | Event type. Currently, only **key** is supported. | +| keyOptions | [KeyOptions](#keyoptions) | Yes | Combination key options. | +| callback | Callback<KeyOptions> | Yes | Callback used to return the combination key data when a combination key event that meets the specified condition occurs.| **Example** -``` -let keyOptions = { preKeys: [], finalKey: 18, isFinalKeyDown: true, finalKeyDownDuration: 0 } -let callback = function (keyOptions) { - console.info("preKeys: " + keyOptions.preKeys, "finalKey: " + keyOptions.finalKey, - "isFinalKeyDown: " + keyOptions.isFinalKeyDown, "finalKeyDownDuration: " + keyOptions.finalKeyDownDuration) -} +```js +let leftAltKey = 2045; +let tabKey = 2049; try { - inputConsumer.on(inputConsumer.SubscribeType.KEY, keyOptions, callback); + inputConsumer.on("key", {preKeys: [leftAltKey], finalKey: tabKey, isFinalKeyDown: true, finalKeyDownDuration: 0}, keyOptions => { + console.log(`keyOptions: ${JSON.stringify(keyOptions)}`); + }); } catch (error) { - console.info(`inputConsumer.on, error.code=${JSON.stringify(error.code)}, error.msg=${JSON.stringify(error.message)}`); + console.log(`Subscribe failed, error: ${JSON.stringify(error, [`code`, `message`])}`); } ``` @@ -55,49 +52,63 @@ try { off(type: "key", keyOptions: KeyOptions, callback?: Callback<KeyOptions>): void -Stops listening for combination key events. - -This is a system API. +Disables listening for combination key events. **System capability**: SystemCapability.MultimodalInput.Input.InputConsumer **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Type of the key input event to listen for. Only **key** is supported.| -| keyOptions | [keyOptions](#keyoptions) | Yes| Key options passed to the key input event when listening starts.| -| callback | Callback<KeyOptions> | Yes| Callback function passed to the key input event with **keyOptions** when listening starts.| +| Name | Type | Mandatory | Description | +| ---------- | -------------------------- | ---- | ------------------------------- | +| type | string | Yes | Event type. Currently, only **key** is supported. | +| keyOptions | [KeyOptions](#keyoptions) | Yes | Combination key options. | +| callback | Callback<KeyOptions> | No | Callback for which listening is disabled. If this parameter is not specified, listening will be disabled for all callbacks registered by the current application.| **Example** +```js +let leftAltKey = 2045; +let tabKey = 2049; +// Disable listening for a single callback function. +let callback = function (keyOptions) { + console.log(`keyOptions: ${JSON.stringify(keyOptions)}`); +} +let keyOption = {preKeys: [leftAltKey], finalKey: tabKey, isFinalKeyDown: true, finalKeyDownDuration: 0}; +try { + inputConsumer.on("key", keyOption, callback); + inputConsumer.off("key", keyOption, callback); + console.log(`Unsubscribe success`); +} catch (error) { + console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); +} ``` -let keyOptions = { preKeys: [], finalKey: 18, isFinalKeyDown: true, finalKeyDownDuration: 0 } +```js +let leftAltKey = 2045; +let tabKey = 2049; +// Disable listening for all callback functions. let callback = function (keyOptions) { - console.info("preKeys: " + keyOptions.preKeys, "finalKey: " + keyOptions.finalKey, - "isFinalKeyDown: " + keyOptions.isFinalKeyDown, "finalKeyDownDuration: " + keyOptions.finalKeyDownDuration) + console.log(`keyOptions: ${JSON.stringify(keyOptions)}`); } +let keyOption = {preKeys: [leftAltKey], finalKey: tabKey, isFinalKeyDown: true, finalKeyDownDuration: 0}; try { - inputConsumer.off(inputConsumer.SubscribeType.KEY, keyOptions, callback); + inputConsumer.on("key", keyOption, callback); + inputConsumer.off("key", keyOption); + console.log(`Unsubscribe success`); } catch (error) { - console.info(`inputConsumer.off, error.code=${JSON.stringify(error.code)}, error.msg=${JSON.stringify(error.message)}`); + console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); } ``` -## keyOptions +## KeyOptions -Defines the key options that are met when a combination key input event occurs. - -This is a system API. +Represents combination key options. **System capability**: SystemCapability.MultimodalInput.Input.InputConsumer -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| preKeys | Array | Yes| Array of precedent keys. This parameter can be left empty. There is no requirement on the sequence of precedent keys.| -| finalKey | Number | Yes| Final key in the combination key. This parameter cannot be left blank.| -| isFinalKeyDown | boolean | Yes| Whether the final key is pressed or released. By default, the final key is pressed.| -| finalKeyDownDuration | Number | Yes| Duration for pressing the final key. By default, there is no requirement on the duration.| +| Name | Type | Readable | Writable | Description | +| --------- | ------ | ---- | ---- | ------- | +| preKeys | Array\ | Yes | No| Front key set. The number of front keys ranges from 0 to 4. There is no requirement on the sequence of the keys.| +| finalKey | number | Yes | No| Final key. This parameter is mandatory. A callback function is triggered by the final key.| +| isFinalKeyDown | boolean | Yes | No| Whether the final key is pressed.| +| finalKeyDownDuration | number | Yes | No| Duration within which the final key is pressed. If the value is **0**, the callback function is triggered immediately. If the value is greater than **0** and the value of **isFinalKeyDown** is **true**, the callback function is triggered when the key press duration is longer than the value of this parameter. If the value of **isFinalKeyDown** is **false**, the callback function is triggered when the duration from key press to key release is less than the value of this parameter. | diff --git a/en/application-dev/reference/apis/js-apis-inputeventclient.md b/en/application-dev/reference/apis/js-apis-inputeventclient.md index 695a7a5bf4..f4372d664a 100644 --- a/en/application-dev/reference/apis/js-apis-inputeventclient.md +++ b/en/application-dev/reference/apis/js-apis-inputeventclient.md @@ -2,11 +2,11 @@ The Key Injection module implements injection of key events. -> **NOTE**
+> **NOTE** > > - The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. > -> - The APIs of this module are system APIs and cannot be called by third-party applications. +> - The APIs provided by this module are system APIs. ## Modules to Import @@ -21,9 +21,7 @@ import inputEventClient from '@ohos.multimodalInput.inputEventClient'; injectEvent({KeyEvent: KeyEvent}): void -Injects a key event. - -This is a system API. +Injects a key event. Currently, key injection is supported only for the **Back** key (key value 2). **System capability**: SystemCapability.MultimodalInput.Input.InputSimulator @@ -37,37 +35,36 @@ This is a system API. ```js try { - var keyEvent = { + let backKeyDown = { isPressed: true, keyCode: 2, keyDownDuration: 0, isIntercepted: false } - inputEventClient.injectKeyEvent({ KeyEvent: keyEvent }); - var keyEvent1 = { + inputEventClient.injectEvent({ KeyEvent: backKeyDown }); + + let backKeyUp = { isPressed: false, keyCode: 2, keyDownDuration: 0, isIntercepted: false }; - inputEventClient.injectKeyEvent({ KeyEvent: keyEvent1 }); + inputEventClient.injectEvent({ KeyEvent: backKeyUp }); } catch (error) { - console.info("injectKeyEvent " + error.code + " " + error.message); + console.log(`Failed to inject KeyEvent, error: ${JSON.stringify(error, [`code`, `message`])}`); } ``` ## KeyEvent -Defines the information about the key event to inject. +Represents information about the key event to inject. **System capability**: SystemCapability.MultimodalInput.Input.InputSimulator -**Parameters** - -| Name | Type | Mandatory | Description | -| --------------- | ------- | ---- | --------- | -| isPressed | boolean | Yes | Whether the key is pressed. | -| keyCode | number | Yes | Key code. | -| keyDownDuration | number | Yes | Duration within which the key is pressed. | -| isIntercepted | boolean | Yes | Whether the key can be intercepted.| +| Name | Type | Readable | Writable | Description | +| --------- | ------ | ---- | ---- | ------- | +| isPressed | boolean | Yes | No| Whether the key is pressed. | +| keyCode | number | Yes | No| Key value. Currently, only the **Back** key is supported.| +| keyDownDuration | number | Yes | No| Duration within which the key is pressed. | +| isIntercepted | boolean | Yes | No| Whether the key can be intercepted. | diff --git a/en/application-dev/reference/apis/js-apis-inputmonitor.md b/en/application-dev/reference/apis/js-apis-inputmonitor.md index 315e2d81f7..7bd41f5d0b 100644 --- a/en/application-dev/reference/apis/js-apis-inputmonitor.md +++ b/en/application-dev/reference/apis/js-apis-inputmonitor.md @@ -1,11 +1,12 @@ # Input Monitor -The Input Monitor module implements listening for global touch events. +The Input Monitor module implements listening for events of input devices (namely, touchscreen and mouse). -> **NOTE**
-> - The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> **NOTE** > -> - The APIs of this module are system APIs and cannot be called by third-party applications. +> - The initial APIs of this module are supported since API version 7. 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 @@ -16,80 +17,73 @@ import inputMonitor from '@ohos.multimodalInput.inputMonitor'; ``` -## Required Permissions - -ohos.permission.INPUT_MONITORING - - ## inputMonitor.on on(type: "touch", receiver: TouchEventReceiver): void Enables listening for global touch events. -This is a system API. - **Required permissions**: ohos.permission.INPUT_MONITORING **System capability**: SystemCapability.MultimodalInput.Input.InputMonitor **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ----------------------------------------- | ---- | ------------------------------- | -| type | string | Yes | Type of the input event to listen for. The value is **touch**.| -| receiver | [TouchEventReceiver](#toucheventreceiver) | Yes | Callback used to return the touch event. | +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | ------------------- | +| type | string | Yes | Type of the input device event. The value is **touch**.| +| receiver | [TouchEventReceiver](#toucheventreceiver) | Yes | Callback used to return the touch event.| - **Example** +**Example** ```js try { - inputMonitor.on("touch", (data)=> { - console.info(`monitorOnTouchEvent success ${JSON.stringify(data)}`); - return false; - }); + inputMonitor.on("touch", (touchEvent) => { + console.log(`Monitor on success ${JSON.stringify(touchEvent)}`); + return false; + }); } catch (error) { - console.info("onMonitor " + error.code + " " + error.message) + console.log(`Monitor on failed, error: ${JSON.stringify(error, [`code`, `message`])}`); } ``` +## inputMonitor.on9+ + on(type: "mouse", receiver: Callback<MouseEvent>): void Enables listening for global mouse events. -This is a system API. - **Required permissions**: ohos.permission.INPUT_MONITORING **System capability**: SystemCapability.MultimodalInput.Input.InputMonitor **Parameters** -| Name | Type | Mandatory| Description | -| -------- | -------------------- | ---- | ------------------------------- | -| type | string | Yes | Type of the input event to listen for. The value is **mouse**.| -| receiver | Callback<MouseEvent> | Yes | Callback used to return the mouse event. | +| Name | Type | Mandatory | Description | +| -------- | -------------------------- | ---- | ------------------- | +| type | string | Yes | Type of the input device event. The value is **mouse**.| +| receiver | Callback<MouseEvent> | Yes | Callback used to return the mouse event. | **Example** ```js try { - inputMonitor.on("mouse", (data)=> { - console.info(`monitorOnMouseEvent success ${JSON.stringify(data)}`); - return false; - }); + inputMonitor.on("mouse", (mouseEvent) => { + console.log(`Monitor on success ${JSON.stringify(mouseEvent)}`); + return false; + }); } catch (error) { - console.info("onMonitor " + error.code + " " + error.message) + console.log(`Monitor on failed, error: ${JSON.stringify(error, [`code`, `message`])}`); } ``` + + ## inputMonitor.off off(type: "touch", receiver?: TouchEventReceiver): void -Stops listening for global touch events. - -This is a system API. +Disables listening for global touch events. **Required permissions**: ohos.permission.INPUT_MONITORING @@ -97,41 +91,48 @@ This is a system API. **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ----------------------------------------- | ---- | ------------------------------- | -| type | string | Yes | Type of the input event to listen for. The value is **touch**.| -| receiver | [TouchEventReceiver](#toucheventreceiver) | No | Callback used to return the touch event. | +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | ------------------- | +| type | string | Yes | Type of the input device event. The value is **touch**.| +| receiver | [TouchEventReceiver](#toucheventreceiver) | No | Callback for which listening is disabled. If this parameter is not specified, listening will be disabled for all callbacks registered by the current application. | - **Example** +**Example** ```js -// Disable listening globally. +// Disable listening for a single callback function. +function callback(touchEvent) { + console.log(`Monitor on success ${JSON.stringify(touchEvent)}`); + return false; +}; try { - inputMonitor.off("touch"); + inputMonitor.on("touch", callback); + inputMonitor.off("touch", callback); + console.log(`Monitor off success`); } catch (error) { - console.info("offMonitor " + error.code + " " + error.message) + console.log(`Monitor execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); } -// Disable listening for this receiver. -callback:function(data) { - console.info(`call success ${JSON.stringify(data)}`); -}, -try { - inputMonitor.on("touch", this.callback); -} catch (error) { - console.info("onTouchMonitor " + error.code + " " + error.message) -}, +``` + +```js +// Cancel listening for all callback functions. +function callback(touchEvent) { + console.log(`Monitor on success ${JSON.stringify(touchEvent)}`); + return false; +}; try { - inputMonitor.off("touch",this.callback); + inputMonitor.on("touch", callback); + inputMonitor.off("touch"); + console.log(`Monitor off success`); } catch (error) { - console.info("offTouchMonitor " + error.code + " " + error.message) + console.log(`Monitor execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); } ``` -off(type: "mouse", receiver?:Callback\):void +## inputMonitor.off9+ -Stops listening for global mouse events. +off(type: "mouse", receiver?: Callback<MouseEvent>): void -This is a system API. +Stops listening for global mouse events. **Required permissions**: ohos.permission.INPUT_MONITORING @@ -139,43 +140,48 @@ This is a system API. **Parameters** -| Name | Type | Mandatory| Description | -| -------- | -------------------- | ---- | ------------------------------- | -| type | string | Yes | Type of the input event to listen for. The value is **mouse**.| -| receiver | Callback<MouseEvent> | No | Callback used to return the mouse event. | +| Name | Type | Mandatory | Description | +| -------- | -------------------------- | ---- | ------------------- | +| type | string | Yes | Type of the input device event. The value is **mouse**.| +| receiver | Callback<MouseEvent> | No | Callback for which listening is disabled. If this parameter is not specified, listening will be disabled for all callbacks registered by the current application.| **Example** ```js -// Disable listening globally. +// Disable listening for a single callback. +function callback(mouseEvent) { + console.log(`Monitor on success ${JSON.stringify(mouseEvent)}`); + return false; +}; try { - inputMonitor.off("mouse"); + inputMonitor.on("mouse", callback); + inputMonitor.off("mouse", callback); + console.log(`Monitor off success`); } catch (error) { - console.info("offMonitor " + error.code + " " + error.message) + console.log(`Monitor execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); } -// Disable listening for this receiver. -callback:function(data) { - console.info(`call success ${JSON.stringify(data)}`); -}, -try { - inputMonitor.on("mouse", this.callback); -} catch (error) { - console.info("onMouseMonitor " + error.code + " " + error.message) -}, +``` + +```js +// Disable listening for all callback functions. +function callback(mouseEvent) { + console.log(`Monitor on success ${JSON.stringify(mouseEvent)}`); + return false; +}; try { - inputMonitor.off("mouse", this.callback); + inputMonitor.on("mouse", callback); + inputMonitor.off("mouse"); + console.log(`Monitor off success`); } catch (error) { - console.info("offMouseMonitor " + error.code + " " + error.message) + console.log(`Monitor execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); } ``` - - ## TouchEventReceiver -Provides the callback of touch events. +Represents the callback used to return the touch event. -This is a system API. +**Required permissions**: ohos.permission.INPUT_MONITORING **System capability**: SystemCapability.MultimodalInput.Input.InputMonitor @@ -183,24 +189,26 @@ This is a system API. | Name | Type | Mandatory | Description | | ---------- | ---------------------------------------- | ---- | ---------------------------------------- | -| touchEvent | [TouchEvent](../arkui-js/js-components-common-events.md) | Yes | Callback used to return the touch event.| +| touchEvent | [TouchEvent](../arkui-js/js-components-common-events.md) | Yes | Touch event.| **Return value** -| Type | Description | -| ------- | -------------------------------------- | -| Boolean | Result indicating whether the touch event has been consumed by the input monitor. The value **true** indicates that the touch event has been consumed, and the value **false** indicates the opposite.| +| Type | Description | +| ------- | ---------------------------------------- | +| Boolean | Result indicating whether the touch event will be dispatched to the window. The value **true** indicates that the touch event will be dispatched to the window, and the value **false** indicates the opposite.| - **Example** +**Example** ```js try { - inputMonitor.on("touch", (event) => { - // If true is returned, all subsequent events of this operation will be consumed by the listener, instead of being distributed to the window. - return false; + inputMonitor.on("touch", touchEvent => { + if (touchEvent.touches.length == 3) {// Three fingers are pressed. + return true; + } else { + return false; + } }); - inputMonitor.off("touch"); } catch (error) { - console.info("offMonitor " + error.code + " " + error.message) + console.log(`Monitor on failed, error: ${JSON.stringify(error, [`code`, `message`])}`); } ``` diff --git a/en/application-dev/reference/apis/js-apis-keyevent.md b/en/application-dev/reference/apis/js-apis-keyevent.md index ded0aab53e..33d9daa72d 100644 --- a/en/application-dev/reference/apis/js-apis-keyevent.md +++ b/en/application-dev/reference/apis/js-apis-keyevent.md @@ -1,51 +1,52 @@ # Key Event -The Key Event module provides key events reported by an input device. +Represents key events reported by an input device. -> **NOTE**
+> **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. ## Modules to Import ```js -import {Action,Key,KeyEvent} from '@ohos.multimodalInput.keyEvent'; +import {Action, Key, KeyEvent} from '@ohos.multimodalInput.keyEvent'; ``` ## Action **System capability**: SystemCapability.MultimodalInput.Input.Core -| Name| Type| Readable| Writable| Description| -| -------- | -------- | -------- | -------- | -------- | -| CANCEL | number | Yes| No| Cancellation of a key action.| -| DOWN | number | Yes| No| Pressing of a key.| -| UP | number | Yes| No| Release of a key.| +| Name | Value | Description | +| ------ | ------- | -------- | +| CANCEL | 0 | Cancellation of a key action.| +| DOWN | 1 | Pressing of a key.| +| UP | 2 | Release of a key.| ## Key **System capability**: SystemCapability.MultimodalInput.Input.Core -| Name| Type| Readable| Writable| Description| -| -------- | -------- | -------- | -------- | -------- | -| code | KeyCode | Yes| No| Keycode.| -| pressedTime | number | Yes| No| Time when the key is pressed.| -| deviceId | number | Yes| No| Device to which the key belongs.| +| Name | Type| Readable| Writable| Description | +| ----------- | -------- | ---- | ---- | -------------- | +| code | KeyCode | Yes | No | Keycode. | +| pressedTime | number | Yes | No | Time when the key is pressed.| +| deviceId | number | Yes | No | ID of the device to which the key belongs. | ## KeyEvent **System capability**: SystemCapability.MultimodalInput.Input.Core -| Name| Type| Readable| Writable| Description| -| -------- | -------- | -------- | -------- | -------- | -| action | Action | Yes| No| Key action.| -| key | Key | Yes| No| Key that has changed.| -| unicodeChar | number | Yes| No| Unicode character corresponding to the key.| -| keys | Key[] | Yes| No| List of pressed keys.| -| ctrlKey | boolean | Yes| No| Whether ctrlKey is being pressed.| -| altKey | boolean | Yes| No| Whether altKey is being pressed.| -| shiftKey | boolean | Yes| No| Whether shiftKey is being pressed.| -| logoKey | boolean | Yes| No| Whether logoKey is being pressed.| -| fnKey | boolean | Yes| No| Whether fnKey is being pressed.| -| capsLock | boolean | Yes| No| Whether capsLock is active.| -| numLock | boolean | Yes| No| Whether numLock is active.| -| scrollLock | boolean | Yes| No| Whether scrollLock is active.| +| Name | Type| Readable| Writable| Description | +| ----------- | -------- | ---- | ---- | ------------------------------ | +| action | Action | Yes | No | Key action. | +| key | Key | Yes | No | Key for which the event is reported. | +| unicodeChar | number | Yes | No | Unicode character corresponding to the key. | +| keys | Key[] | Yes | No | List of pressed keys. | +| ctrlKey | boolean | Yes | No | Whether ctrlKey is being pressed. | +| altKey | boolean | Yes | No | Whether altKey is being pressed. | +| shiftKey | boolean | Yes | No | Whether shiftKey is being pressed. | +| logoKey | boolean | Yes | No | Whether logoKey is being pressed. | +| fnKey | boolean | Yes | No | Whether fnKey is being pressed. | +| capsLock | boolean | Yes | No | Whether capsLock is active. | +| numLock | boolean | Yes | No | Whether numLock is active. | +| scrollLock | boolean | Yes | No | Whether scrollLock is active.| diff --git a/en/application-dev/reference/apis/js-apis-mouseevent.md b/en/application-dev/reference/apis/js-apis-mouseevent.md index 86cf6b0640..d3d9e4c05e 100644 --- a/en/application-dev/reference/apis/js-apis-mouseevent.md +++ b/en/application-dev/reference/apis/js-apis-mouseevent.md @@ -2,7 +2,7 @@ Represents mouse events reported by an input device. -> **NOTE**
+> **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. ## Modules to Import @@ -15,75 +15,75 @@ import {Action,Button,Axis,AxisValue,MouseEvent} from '@ohos.multimodalInput.mou **System capability**: SystemCapability.MultimodalInput.Input.Core -| Name| Type| Readable| Writable| Description| -| -------- | -------- | -------- | -------- | -------- | -| CANCEL | number | Yes| No| Cancellation of a mouse action.| -| MOVE | number | Yes| No| Moving of the mouse pointer.| -| BUTTON_DOWN | number | Yes| No| Pressing of a mouse button.| -| BUTTON_UP | number | Yes| No| Release of a mouse button.| -| AXIS_BEGIN | number | Yes| No| Beginning of the axis event associated with the mouse.| -| AXIS_UPDATE | number | Yes| No| Updating of the axis event associated with the mouse.| -| AXIS_END | number | Yes| No| Ending of the axis event associated with the mouse.| +| Name | Value| Description | +| ----------- | -------- | -------------------- | +| CANCEL | 0 | Cancellation of a mouse action. | +| MOVE | 1 | Moving of the mouse pointer. | +| BUTTON_DOWN | 2 | Pressing of a mouse button. | +| BUTTON_UP | 3 | Release of a mouse button. | +| AXIS_BEGIN | 4 | Beginning of the axis event associated with the mouse.| +| AXIS_UPDATE | 5 | Updating of the axis event associated with the mouse.| +| AXIS_END | 6 | Ending of the axis event associated with the mouse.| ## Button **System capability**: SystemCapability.MultimodalInput.Input.Core -| Name| Type| Readable| Writable| Description| -| -------- | -------- | -------- | -------- | -------- | -| LEFT | number | Yes| No| Left button on the mouse.| -| MIDDLE | number | Yes| No| Middle button on the mouse.| -| RIGHT | number | Yes| No| Right button on the mouse.| -| SIDE | number | Yes| No| Side button on the mouse.| -| EXTRA | number | Yes| No| Extended button on the mouse.| -| FORWARD | number | Yes| No| Forward button on the mouse.| -| BACK | number | Yes| No| Back button on the mouse.| -| TASK | number | Yes| No| Task button on the mouse.| +| Name | Value | Description | +| ------- | ------| ----- | +| LEFT | 0 | Left button on the mouse. | +| MIDDLE | 1 | Middle button on the mouse. | +| RIGHT | 2 | Right button on the mouse. | +| SIDE | 3 | Side button on the mouse.| +| EXTRA | 4 | Extended button on the mouse.| +| FORWARD | 5 | Forward button on the mouse.| +| BACK | 6 | Back button on the mouse.| +| TASK | 7 | Task button on the mouse.| ## Axis **System capability**: SystemCapability.MultimodalInput.Input.Core -| Name| Type| Readable| Writable| Description| -| -------- | -------- | -------- | -------- | -------- | -| SCROLL_VERTICAL | number | Yes| No| Vertical scroll axis.| -| SCROLL_HORIZONTAL | number | Yes| No| Horizontal scroll axis.| -| PINCH | number | Yes| No| Pinch axis.| +| Name | Value | Description | +| ----------------- | ------- | ----- | +| SCROLL_VERTICAL | 0 | Vertical scroll axis.| +| SCROLL_HORIZONTAL | 1 | Horizontal scroll axis.| +| PINCH | 2 | Pinch axis. | ## AxisValue **System capability**: SystemCapability.MultimodalInput.Input.Core -| Name| Type| Readable| Writable| Description| -| -------- | -------- | -------- | -------- | -------- | -| axis | Axis | Yes| No| Axis type.| -| value | number | Yes| No| Axis value.| +| Name | Type | Readable | Writable | Description | +| ----- | ------ | ---- | ---- | ---- | +| axis | Axis | Yes | No | Axis type. | +| value | number | Yes | No | Axis value. | ## MouseEvent **System capability**: SystemCapability.MultimodalInput.Input.Core -| Name| Type| Readable| Writable| Description| -| -------- | -------- | -------- | -------- | -------- | -| action | Action | Yes| No| Mouse event action.| -| screenX | number | Yes| No| X coordinate of the mouse pointer on the screen.| -| screenY | number | Yes| No| Y coordinate of the mouse pointer on the screen.| -| windowX | number | Yes| No| X coordinate of the mouse pointer in the window.| -| windowY | number | Yes| No| Y coordinate of the mouse pointer in the window.| -| rawDeltaX | number | Yes| No| X axis offset relative to the previous reported mouse pointer position. When the mouse pointer is at the edge of the screen, the value may be less than the difference of the X coordinate reported twice.| -| rawDeltaY | number | Yes| No| Y axis offset relative to the previous reported mouse pointer position.| -| button | Button | Yes| No| Button that is currently pressed or released.| -| pressedButtons | Button[] | Yes| No| Button that is being pressed.| -| axes | AxisValue[] | Yes| No| All axis data contained in the event.| -| pressedKeys | KeyCode[] | Yes| No| List of pressed keys.| -| ctrlKey | boolean | Yes| No| Whether ctrlKey is being pressed.| -| altKey | boolean | Yes| No| Whether altKey is being pressed.| -| shiftKey | boolean | Yes| No| Whether shiftKey is being pressed.| -| logoKey | boolean | Yes| No| Whether logoKey is being pressed.| -| fnKey | boolean | Yes| No| Whether fnKey is being pressed.| -| capsLock | boolean | Yes| No| Whether capsLock is active.| -| numLock | boolean | Yes| No| Whether numLock is active.| -| scrollLock | boolean | Yes| No| Whether scrollLock is active.| +| Name | Type | Readable | Writable | Description | +| -------------- | ----------- | ---- | ---- | ---------------------------------------- | +| action | Action | Yes | No | Mouse event action. | +| screenX | number | Yes | No | Horizontal coordinate of the mouse pointer on the screen. | +| screenY | number | Yes | No | Vertical coordinate of the mouse pointer on the screen. | +| windowX | number | Yes | No | Horizontal coordinate of the mouse pointer in the window. | +| windowY | number | Yes | No | Vertical coordinate of the mouse pointer in the window. | +| rawDeltaX | number | Yes | No | Horizontal coordinate offset relative to the previous reported mouse pointer position.| +| rawDeltaY | number | Yes | No | Vertical coordinate offset relative to the previous reported mouse pointer position. | +| button | Button | Yes | No | Mouse button +| pressedButtons | Button[] | Yes | No | Button being pressed. | +| axes | AxisValue[] | Yes | No | All axis data contained in the event. | +| pressedKeys | KeyCode[] | Yes | No | List of pressed keys. | +| ctrlKey | boolean | Yes | No | Whether ctrlKey is being pressed. | +| altKey | boolean | Yes | No | Whether altKey is being pressed. | +| shiftKey | boolean | Yes | No | Whether shiftKey is being pressed. | +| logoKey | boolean | Yes | No | Whether logoKey is being pressed. | +| fnKey | boolean | Yes | No | Whether fnKey is being pressed. | +| capsLock | boolean | Yes | No | Whether capsLock is active. | +| numLock | boolean | Yes | No | Whether numLock is active. | +| scrollLock | boolean | Yes | No | Whether scrollLock is active. | diff --git a/en/application-dev/reference/apis/js-apis-telephony-data.md b/en/application-dev/reference/apis/js-apis-telephony-data.md index a8ea022b24..e9b54c774d 100644 --- a/en/application-dev/reference/apis/js-apis-telephony-data.md +++ b/en/application-dev/reference/apis/js-apis-telephony-data.md @@ -18,8 +18,6 @@ getDefaultCellularDataSlotId(callback: AsyncCallback\): void Obtains the default slot of the SIM card used for mobile data. This API uses an asynchronous callback to return the result. -**Required permission**: ohos.permission.GET_NETWORK_INFO - **System capability**: SystemCapability.Telephony.CellularData **Parameters** @@ -42,8 +40,6 @@ getDefaultCellularDataSlotId(): Promise\ Obtains the default slot of the SIM card used for mobile data. This API uses a promise to return the result. -**Required permission**: ohos.permission.GET_NETWORK_INFO - **System capability**: SystemCapability.Telephony.CellularData **Return value** @@ -63,14 +59,12 @@ promise.then((data) => { }); ``` -## data.getDefaultCellularDataSlotIdSync +## data.getDefaultCellularDataSlotIdSync9+ getDefaultCellularDataSlotIdSync(): number Obtains the default SIM card used for mobile data synchronously. -**Required permission**: ohos.permission.GET_NETWORK_INFO - **System capability**: SystemCapability.Telephony.CellularData **Return value** @@ -85,7 +79,6 @@ Obtains the default SIM card used for mobile data synchronously. console.log("Result: "+ data.getDefaultCellularDataSlotIdSync()) ``` - ## data.setDefaultCellularDataSlotId setDefaultCellularDataSlotId(slotId: number, callback: AsyncCallback\): void @@ -102,8 +95,8 @@ This is a system API. | Name | Type | Mandatory| Description | | -------- | --------------------- | ---- | ------------------------------------------------------------ | -| slotId | number | Yes | SIM card slot ID.
- **0**: card slot 1
- **1**: card slot 2
- **-1**: clearing the default configuration| -| callback | AsyncCallback\ | Yes | Callback used to return the result. | +| slotId | number | Yes | SIM card slot ID.
**0**: card slot 1
**1**: card slot 2
**-1**: Clears the default configuration.| +| callback | AsyncCallback\ | Yes | Callback used to return the result. | **Example** @@ -129,13 +122,13 @@ This is a system API. | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------------------------------------------------------------ | -| slotId | number | Yes | SIM card slot ID.
- **0**: card slot 1
- **1**: card slot 2
- **-1**: clearing the default configuration| +| slotId | number | Yes | SIM card slot ID.
**0**: card slot 1
**1**: card slot 2
**-1**: Clears the default configuration.| **Return value** -| Type | Description | -| -------------- | ------------------------------- | -| Promise<\void\> | Promise used to return the result. | +| Type | Description | +| --------------- | ------------------------------- | +| Promise\ | Promise used to return the result.| **Example** @@ -199,7 +192,7 @@ promise.then((data) => { getCellularDataState(callback: AsyncCallback\): void -Obtains the connection status of the PS domain. This API uses an asynchronous callback to return the result. +Obtains the connection status of the packet switched (PS) domain. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Telephony.CellularData @@ -256,7 +249,7 @@ Checks whether the cellular data service is enabled. This API uses an asynchrono | Name | Type | Mandatory| Description | | -------- | ------------------------ | ---- | ------------------------------------------------------------ | -| callback | AsyncCallback\ | Yes | Callback used to return the result.
- **true**: The cellular data service is enabled.
- **false**: The cellular data service is disabled.| +| callback | AsyncCallback\ | Yes | Callback used to return the result.
**true**: The cellular data service is enabled.
**false**: The cellular data service is disabled.| **Example** @@ -280,7 +273,7 @@ Checks whether the cellular data service is enabled. This API uses a promise to | Type | Description | | ------------------ | ------------------------------------------------------------ | -| Promise\ | Promise used to return the result.
- **true**: The cellular data service is enabled.
- **false**: The cellular data service is disabled.| +| Promise\ | Promise used to return the result.
**true**: The cellular data service is enabled.
**false**: The cellular data service is disabled.| **Example** @@ -297,7 +290,7 @@ promise.then((data) => { isCellularDataRoamingEnabled(slotId: number, callback: AsyncCallback\): void -Checks whether the cellular data roaming service is enabled. This API uses an asynchronous callback to return the result. +Checks whether roaming is enabled for the cellular data service. This API uses an asynchronous callback to return the result. **Required permission**: ohos.permission.GET_NETWORK_INFO @@ -308,7 +301,7 @@ Checks whether the cellular data roaming service is enabled. This API uses an as | Name | Type | Mandatory| Description | | -------- | ------------------------ | ---- | ------------------------------------------------------------ | | slotId | number | Yes | Card slot ID.
**0**: card slot 1
**1**: card slot 2 | -| callback | AsyncCallback\ | Yes | Callback used to return the result.
- **true**: The cellular data roaming service is enabled.
- **false**: The cellular data roaming service is disabled. | +| callback | AsyncCallback\ | Yes | Callback used to return the result.
**true**: Roaming is enabled for the cellular data service.
**false**: Roaming is disabled for the cellular data service.| **Example** @@ -322,7 +315,7 @@ data.isCellularDataRoamingEnabled(0, (err, data) => { isCellularDataRoamingEnabled(slotId: number): Promise\ -Checks whether the cellular data roaming service is enabled. This API uses a promise to return the result. +Checks whether roaming is enabled for the cellular data service. This API uses a promise to return the result. **Required permission**: ohos.permission.GET_NETWORK_INFO @@ -338,7 +331,7 @@ Checks whether the cellular data roaming service is enabled. This API uses a pro | Type | Description | | ------------------ | ------------------------------------------------------------ | -| Promise\ | Promise used to return the result.
- **true**: The cellular data roaming service is enabled.
- **false**: The cellular data roaming service is disabled.| +| Promise\ | Promise used to return the result.
**true**: Roaming is enabled for the cellular data service.
**false**: Roaming is disabled for the cellular data service.| **Example** @@ -585,7 +578,6 @@ promise.then((data) => { }); ``` - ## DataFlowType Defines the cellular data flow type. @@ -602,14 +594,14 @@ Defines the cellular data flow type. ## DataConnectState -Describes the connection status of a cellular data connection. +Describes the connection status of a cellular data link. **System capability**: SystemCapability.Telephony.CellularData | Name | Value | Description | | ----------------------- | ---- | -------------------------- | -| DATA_STATE_UNKNOWN | -1 | The status of the cellular data connection is unknown. | -| DATA_STATE_DISCONNECTED | 0 | The cellular data connection is disconnected. | -| DATA_STATE_CONNECTING | 1 | The cellular data connection is being established.| -| DATA_STATE_CONNECTED | 2 | The cellular data connection is established. | -| DATA_STATE_SUSPENDED | 3 | The cellular data connection is suspended. | +| DATA_STATE_UNKNOWN | -1 | The status of the cellular data link is unknown. | +| DATA_STATE_DISCONNECTED | 0 | The cellular data link is disconnected. | +| DATA_STATE_CONNECTING | 1 | The cellular data link is being connected.| +| DATA_STATE_CONNECTED | 2 | The cellular data link is connected. | +| DATA_STATE_SUSPENDED | 3 | The cellular data link is suspended. | diff --git a/en/device-dev/subsystems/subsys-ota-guide.md b/en/device-dev/subsystems/subsys-ota-guide.md index 9f10a82773..3b2e5d680d 100644 --- a/en/device-dev/subsystems/subsys-ota-guide.md +++ b/en/device-dev/subsystems/subsys-ota-guide.md @@ -6,7 +6,7 @@ ### Overview -With the rapid development of device systems, it has become a critical challenge for device vendors to help their users to access system updates in a timely manner to experience the new features and improve the system stability and security. +With the rapid development of device systems, it has become a critical challenge for device vendors to help their users to access system updates in a timely manner to experience the new features and improve the system stability and security Over the Air (OTA) answers this challenge with the support for remote updating of device systems. By providing unified update APIs externally, the update subsystem shields the differences of underlying chips. After secondary development based on the update APIs, device vendors can easily implement remote updating for their devices, such as IP cameras. @@ -18,51 +18,48 @@ Over the Air (OTA) answers this challenge with the support for remote updating o - Differential package: an update package that packs the differential images between the source version and target version. -### Implementation Principle +### Principles To implement an OTA update, you first need to use the packaging tool to pack the build version into an update package and upload the update package to the OTA server. Devices integrating the OTA update capability can then detect the update package and download it to implement a remote update. -A/B Update: a typical application of OTA update. In this update mode, a device has a backup system B. When system A is running, system B is updated silently. After the update is successful, the device restarts and switches to the new system. +A/B Update: a typical application of OTA update. In this update mode, a device has a backup system B. When system A is running, system B is updated silently. After the update is successful, the device restarts and switches to the new system. ### Constraints -- Only the open-source suites for devices powered by Hi3861, Hi3518E V300, and Hi3516D V300 are supported. +- Only the open-source suites for devices powered by Hi3861, Hi3516D V300, and RK3568 are supported. -- Devices developed based on Hi3518E V300 and Hi3516D V300 must support the SD card in the Virtual Festival of Aerobatic Teams (VFAT) format. +- Devices developed based on Hi3516D V300 and RK3568 must support the SD card in the Virtual Festival of Aerobatic Teams (VFAT) format. - Generation of update packages can only be performed on the Linux system. - Currently, the mini and small systems support update using a full package, but not a differential package or an update package with partitions changed. +- To implement an A/B update, ensure that the devices running the standard system support booting from partitions A and B. + -## Environment Preparation +## Preparations - On Windows, download and install the OpenSSL tool and configure environment variables. - Prepare the packaging tool. - Build version images using the packaging tool. -- On Linux, pack version images to generate the update package. -- To implement an A/B update, ensure that the devices running the standard system support booting from partitions A and B. - -## OTA Update Guide +## How to Develop -### Development Procedure - -1. Use the OpenSSL tool to generate a public/private key pair. +1. Use the OpenSSL tool to generate a public/private key pair. 2. Use the packaging tool to generate an update package. -  2.1 Mini and small systems +  2.1 Mini and small systems -  2.2 Standard system +  2.2 Standard system -3. Upload the update package to the vendor's OTA server. +3. Upload the update package to the vendor's OTA server. 4. Download the update package from the vendor's OTA server. -5. Integrate the OTA update capability. +5. Integrate the OTA update capability.   5.1 API application scenario (default) @@ -71,31 +68,33 @@ To implement an OTA update, you first need to use the packaging tool to pack the   5.3 A/B update scenario -### How to Develop +## How to Develop -#### Generating a Public/Private Key Pair +### Generating a Public/Private Key Pair 1. Use the OpenSSL tool to generate a public/private key pair. -3. Keep the private key file properly as this file stores the private key used to sign the update package. You need to specify the private key file in the command used for preparing the update package. The public key is used to verify the signature of the update package during the update. For the mini and small systems, the generated public key is preset in the code. You need to implement the **HotaHalGetPubKey** API to obtain the key. For the standard system, the generated public key is stored in the **./device/hisilicon/hi3516dv300/build/updater_config/signing_cert.crt** file. +3. Keep the private key file properly as this file stores the private key used to sign the update package. You need to specify the private key file in the command used for preparing the update package. The public key is used to verify the signature of the update package during the update. For the mini and small systems, the generated public key is preset in the code. The vendor needs to implement the **HotaHalGetPubKey** API to obtain the key. For the standard system, the generated public key is stored in the **/hisilicon/hi3516dv300/build/updater\_config/signing\_cert.crt** file in the **device** or **vendor** directory. -5. For the mini and small systems that use the Hi3518E V300 or Hi3516D V300 suite, use the content in **public\_arr.txt** to replace the content in **g\_pub\_key** in the **device\hisilicon\third_party\uboot\u-boot-2020.01\product\hiupdate\verify\update\_public\_key.c** file of the U-Boot module. +5. For the mini and small systems that use the Hi3516D V300 suite, use the content in **third\_party\u-boot\u-boot-2020.01\product\hiupdate\verify\update\_public\_key.c** file of the U-Boot module. Example configuration: ```c - static unsigned char g_pub_key[PUBKEY_LEN] = { + static unsigned char g_pub_key[] = { 0x30, 0x82, 0x01, 0x0A, 0x02, 0x82, 0x01, 0x01, 0x00, 0xBF, 0xAA, 0xA5, 0xB3, 0xC2, 0x78, 0x5E, } ``` -#### Making an Update Package +### Making an Update Package -##### Mini and Small Systems +#### Mini and Small Systems 1. Create the **target\_package** folder with the following directory structure: + + OTA.tag and config are not required for lightweight systems and small systems upgraded from AB. ```text target_package @@ -103,16 +102,15 @@ To implement an OTA update, you first need to use the packaging tool to pack the ├── config ├── {component_1} ├── {component_2} - ├── ... + ├── ...... ├── {component_N} └── updater_config └── updater_specified_config.xml ``` -2. Place the components to be updated, including the image file (for example, **rootfs.img**), as **{component\_N}** in the root directory of the **target\_package** folder. +2. Place the components to be updated, including the image file (for example, **rootfs.img**), as the substitute of **{component\_N}** in the root directory of the **target\_package** folder. 3. Configure the **updater\_specified\_config.xml** file in the **updater_config** folder. - Example configuration: @@ -130,17 +128,16 @@ To implement an OTA update, you first need to use the packaging tool to pack the ``` - - **Table 1** Description of nodes in the component configuration file + **Table 1** Description of nodes in the component configuration file | Type| Node Name| Node Label| Mandatory| Description| | -------- | -------- | -------- | -------- | -------- | | Header information (head node)| info| / | Yes| Content of this node: head info| | Header information (head node)| info| fileVersion | Yes| This field is reserved and does not affect the generation of the update package.| | Header information (head node)| info| prdID | Yes| This field is reserved and does not affect the generation of the update package.| - | Header information (head node)| info| softVersion | Yes| Software version number, that is, the version number of the update package. The version number must be within the range specified by **VERSION.mbn**. Otherwise, an update package will not be generated.| - | Header information (head node)| info| date| Yes| Date when the update package is generated. This field is reserved and does not affect the generation of the update package.| - | Header information (head node)| info| time| Yes| Time when the update package is generated. This field is reserved and does not affect the generation of the update package.| + | Header information (head node)| info| softVersion | Yes| Software version number, that is, the version number of the update package. Ensure that the version number is later than the basic version number and OpenHarmony is not followed by any other letter. Otherwise, the update cannot be performed.| + | Header information (head node)| info| *date* | Yes| Date when the update package is generated. This field is reserved and does not affect the generation of the update package.| + | Header information (head node)| info| *time* | Yes| Time when the update package is generated. This field is reserved and does not affect the generation of the update package.| | Component information (group node)| component| / | Yes| Content of this node: path of the component or image file to be packed into the update package. It is the root directory of the version package by default.| | Component information (group node)| component| compAddr | Yes| Name of the partition corresponding to the component, for example, **system** or **vendor**.| | Component information (group node)| component| compId | Yes| Component ID, which must be unique.| @@ -180,8 +177,7 @@ To implement an OTA update, you first need to use the packaging tool to pack the - -**nl2**: non-standard system mode -##### Standard System - +#### Standard System 1. Create the **target\_package** folder with the following directory structure: @@ -189,7 +185,7 @@ To implement an OTA update, you first need to use the packaging tool to pack the target_package ├── {component_1} ├── {component_2} - ├── ... + ├── ...... ├── {component_N} └── updater_config ├── BOARD.list @@ -197,7 +193,11 @@ To implement an OTA update, you first need to use the packaging tool to pack the └── updater_specified_config.xml ``` -2. Place the components to be updated, including the image file (for example, **system.img**), as **{component\_N}** in the root directory of the **target\_package** folder. +2. Place the components to be updated, including their image file and **updater_binary** file, as the substitute of **{component\_N}** in the root directory of the **target\_package** folder. + + Take RK3568 as an example. Place the image file in the following build directory: out/rk3568/packages/phone/images/. + + Place the **updater_binary** file in the following build directory: out/rk3568/packages/phone/system/bin/. 3. Configure the component configuration file in the **updater\_config** folder. @@ -208,9 +208,11 @@ To implement an OTA update, you first need to use the packaging tool to pack the ```text HI3516 - HI3518 + RK3568 ``` + Vendors can configure **Local BoardId** by calling **GetLocalBoardId()** in the **base/updater/updater/utils/utils.cpp** file. Ensure that **Local BoardId** configured in the **utils.cpp** file is present in **BOARD.list**. Otherwise, the update cannot be performed. + 5. Configure the versions supported by the current update package in **VERSION.mbn** in the **updater\_config** folder. Version number format: Hi3516DV300-eng 10 QP1A.XXXXXX.{Major version number (6 digits)}.XXX{Minor version number (3 digits)} @@ -223,10 +225,11 @@ To implement an OTA update, you first need to use the packaging tool to pack the ```text Hi3516DV300-eng 10 QP1A.190711.001 Hi3516DV300-eng 10 QP1A.190711.020 - Hi3518DV300-eng 10 QP1A.190711.021 ``` -6. For an update using the incremental (differential) package, also prepare a source version package (source\_package) in the same format as the target version package (target\_package), and then compress it as a **.zip** file, that is, **source\_package.zip**. + Ensure that the basic version number is contained in **VERSION.mbn**. + +6. For update using an incremental (differential) package, also prepare a source version package (source\_package) in the same format as the target version package (target\_package), and then compress it as a **.zip** file, that is, **source\_package.zip**. 7. If you create an update package with partitions changed, also provide the partition table file named **partition\_file.xml**. You can specify the file using the **-pf** parameter. For details about the configuration nodes, see the description below. @@ -243,8 +246,8 @@ To implement an OTA update, you first need to use the packaging tool to pack the **Table 2** Description of labels in the partition table - | Name | Description | - | ---- | ----------- | + | Name| Description| + | -------- | -------- | | Sel | Whether the partition is effective. The value **1** indicates that the partition is effective, and value **0** indicates the opposite.| | PartitionName | Partition name, for example, **fastboot** or **boot**.| | FlashType | Flash type, for example, **emmc** or **ufs**.| @@ -266,7 +269,7 @@ To implement an OTA update, you first need to use the packaging tool to pack the - **./target\_package/**: path of **target\_package** - **./output\_package/**: output path of the update package - - -**pk ./rsa\_private\_key3072.pem**: path of the private key file + - -**pk ./rsa\_private\_key2048.pem**: path of the private key file **Incremental (differential) package** @@ -280,7 +283,7 @@ To implement an OTA update, you first need to use the packaging tool to pack the - **./target\_package/**: path of **target\_package** - **./output\_package/**: output path of the update package - -**s ./source\_package.zip**: path of the **source\_package.zip** file. For update using a differential package, use the **-s** parameter to specify the source version package. - - -**pk ./rsa\_private\_key3072.pem**: path of the private key file + - -**pk ./rsa\_private\_key2048.pem**: path of the private key file **Update package with partitions changed** @@ -291,42 +294,42 @@ To implement an OTA update, you first need to use the packaging tool to pack the python build_update.py ./target_package/ ./output_package/ -pk ./rsa_private_key2048.pem -pf ./partition_file.xml ``` - - **./target\_package/**: path of **target_package** + - **./target\_package/**: path of **target\_package** - **./output\_package/**: output path of the update package - - -**pk ./rsa\_private_key3072.pem**: path of the private key file + - -**pk ./rsa\_private\_key2048.pem**: path of the private key file - -**pf ./partition\_file.xml**: path of the partition table file -#### **Uploading the Update Package** +### Uploading the Update Package Upload the update package to the vendor's OTA server. -#### **Downloading the Update Package** +### **Downloading the Update Package** 1. Download the update package from the OTA server. -2. (Optional) Insert an SD card (with a capacity greater than 100 MB) if the device is developed based on Hi3518E V300 or Hi3516D V300. +2. (Optional) Insert an SD card (with a capacity greater than 100 MB) if the device is developed based on Hi3516D V300. -#### Integrating OTA Update Capabilities +### Integrating OTA Update Capabilities 1. For mini and small systems - - Call the dynamic library **libhota.so**. The corresponding header files **hota\_partition.h** and **hota\_updater.h** are located in **base\update\sys_installer_lite\interfaces\kits**. - - The **libhota.so** source code is located in **base\update\sys_installer_lite\frameworks\source**. + - Call the dynamic library **libhota.so**. The corresponding header files **hota\_partition.h** and **hota\_updater.h** are located in **base\update\sys\_installer\_lite\interfaces\kits\**. + - The **libhota.so** source code is located in **base\update\sys\_installer\_lite\frameworks\source**. - For details about how to use APIs, see *API Application Scenarios* and update APIs in *API Reference*. - - If the development board needs to be adapted, see the **base\update\sys_installer_lite\hals\hal\_hota\_board.h** file. + - If the development board needs to be adapted, see the **base\update\sys\_installer\_lite\hals\hal\_hota\_board.h** file. 2. For the standard system, see the [JS API Reference](../../application-dev/reference/apis/js-apis-update.md) for details. -##### API Application Scenario (Default) +#### API Application Scenario (Default) The update package is generated by following the instructions provided in Generating a Public/Private Key Pair and Generating an Update Package. -###### How to Develop +##### How to Develop 1. Download the update package for the current device, and then call the **HotaInit** function to initialize the OTA module. @@ -335,7 +338,7 @@ The update package is generated by following the instructions provided in Genera 3. Call the **HotaRestart** function to restart the system for the update to take effect. Call the **HotaCancel** function if you want to cancel the update. -###### Sample Code +##### Sample Code Perform an OTA update using the update package format and verification method provided by OpenHarmony. @@ -390,12 +393,12 @@ int main(int argc, char **argv) ``` -##### API Application Scenario (Custom) +#### API Application Scenario (Custom) The update package is generated in other ways instead of following the instructions provided in "Generating a Public/Private Key Pair" and "Generating an Update Package." -###### How to Develop +##### **How to Develop** 1. Download the update package for the current device, and then call the **HotaInit** function to initialize the OTA module. @@ -410,7 +413,7 @@ The update package is generated in other ways instead of following the instructi 6. Call the **HotaRestart** function to restart the system for the update to take effect. Call the **HotaCancel** function if you want to cancel the update. -###### Sample Code +##### Sample Code Perform an OTA update using the update package format and verification method not provided by OpenHarmony. @@ -482,11 +485,11 @@ int main(int argc, char **argv) ``` -###### System Updating +##### Upgrading the System An application calls APIs of the OTA module to perform functions such as signature verification of the update package, anti-rollback, as well as burning and flushing to disk. After the update is complete, the system automatically restarts. -For the mini and small systems that use the Hi3518E V300 or Hi3516D V300 open source suite, add the value of **LOCAL\_VERSION** to the version that needs to implement the anti-rollback function. For example, for **"ohos default 1.0"->"ohos default 1.1"**, add the value of **LOCAL\_VERSION** in **device\hisilicon\third\_party\uboot\u-boot-2020.01\product\hiupdate\ota\_update\ota\_local_info.c**. +For the mini and small systems that use the Hi3516D V300 open source suite, add the value of **LOCAL\_VERSION** to the version that needs to implement the anti-rollback function. For example, for **"ohos default 1.0"->"ohos default 1.1"**, add the value of **LOCAL\_VERSION** in **device\hisilicon\third\_party\uboot\u-boot-2020.01\product\hiupdate\ota\_update\ota\_local_info.c**. Example configuration: @@ -494,16 +497,15 @@ For the mini and small systems that use the Hi3518E V300 or Hi3516D V300 open so const char *get_local_version(void) { #if defined(CONFIG_TARGET_HI3516EV200) || \ - defined(CONFIG_TARGET_HI3516DV300) || \ - defined(CONFIG_TARGET_HI3518EV300) + defined(CONFIG_TARGET_HI3516DV300) #define LOCAL_VERSION "ohos default 1.0" /* increase: default release version */ ``` -##### A/B Update Scenario +#### A/B Update Scenario -###### Development Procedure +##### How to Develop 1. Download the update package through the update application. 2. Invoke update_service to start the system installation service through SAMGR. @@ -511,7 +513,7 @@ const char *get_local_version(void) 4. Activate the new version upon restarting. -###### How to Develop +##### How to Develop - Invoke update_service to call JS APIs to implement the related service logic in an A/B update. @@ -530,7 +532,7 @@ const char *get_local_version(void) 1. Start the system installation service and set up an IPC connection. ```cpp - int SysInstallerInit(void * callback) + int SysInstallerInit(void* callback) ``` 2. Install the A/B update package in the specified path. @@ -540,7 +542,7 @@ const char *get_local_version(void) 3. Set the update progress callback. ```cpp - int SetUpdateProgressCallback(void * callback) + int SetUpdateProgressCallback(void* callback) ``` 4. Obtain the installation status of the update package (0: not started; 1: installing; 2: installed). @@ -572,7 +574,7 @@ const char *get_local_version(void) ``` -###### FAQs +##### FAQs 1. An exception occurs during installation of the update package.
The system keeps running with the current version. It will attempt a new update in the next package search period. @@ -581,6 +583,6 @@ const char *get_local_version(void)
Perform a rollback and set the partition to the **unbootable** state so that the system does not boot from this partition. -###### Verification +##### Verification In normal cases, the device can download the update package from the OTA server in the background, perform a silent update, and then restart according to the preconfigured activation policy for the new version to take effect. -- GitLab