@@ -29,7 +29,6 @@ When a user enters text, the input method determines whether to launch the virtu
...
@@ -29,7 +29,6 @@ When a user enters text, the input method determines whether to launch the virtu
1. Call the **getDeviceList** API to obtain the list of connected input devices. Call the **getKeyboardType** API to traverse all connected devices to check whether a physical keyboard exists. If a physical keyboard exists, mark the physical keyboard as connected. This step ensures that your application detects all inserted input devices before listening for device hot swap events.
1. Call the **getDeviceList** API to obtain the list of connected input devices. Call the **getKeyboardType** API to traverse all connected devices to check whether a physical keyboard exists. If a physical keyboard exists, mark the physical keyboard as connected. This step ensures that your application detects all inserted input devices before listening for device hot swap events.
2. Call the **on** API to listen for device hot swap events. If a physical keyboard is inserted, mark the physical keyboard as connected. If a physical keyboard is removed, mark the physical keyboard as disconnected.
2. Call the **on** API to listen for device hot swap events. If a physical keyboard is inserted, mark the physical keyboard as connected. If a physical keyboard is removed, mark the physical keyboard as disconnected.
3. When a user enters text, check whether a physical keyboard is connected. If a physical keyboard is not connected, launch the virtual keyboard.
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.
During application running, some unexpected behaviors are inevitable. For example, unprocessed exceptions and errors are thrown, and the call or running constraints of the recovery 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.
Process exit is treated as the default exception handling method. However, if user data is generated during application use, process exit 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.
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.
Currently, the APIs support only the development of an application that adopts the stage model, single process, and single ability.
## Available APIs
## 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.
The application recovery APIs are provided by the **appRecovery** module, which can be imported via **import**. For details, see[Development Example](#development-example). This document describes behaviors of APIs in API version 9, and the content will update with changes.
### Available APIs
### Available APIs
...
@@ -23,39 +23,39 @@ The application recovery APIs are provided by the **appRecovery** module, which
...
@@ -23,39 +23,39 @@ The application recovery APIs are provided by the **appRecovery** module, which
The APIs are used for troubleshooting and do not return any exception. Therefore, you need to be familiar with when they are used.
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).
**enableAppRecovery**: This API should be called during application initialization. For example, you can call this API in **onCreate** of **AbilityStage**. For details, see [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.
**saveAppState**: After this API is called, the framework calls back **onSaveState** of the ability. If data saving is accepted in this API, 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.
**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
### Framework Fault Management
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 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-inner-application-errorObserver.md) via [errorManager](../reference/apis/js-apis-app-ability-errorManager.md), listening for fault occurrence, and notifying the fault listener.
- Fault listening refers to the process of registering an [ErrorObserver](../reference/apis/js-apis-inner-application-errorObserver.md) via [errorManager](../reference/apis/js-apis-app-ability-errorManager.md), listening for faults, and notifying the listener of the faults.
- 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 rectification refers to the process of restoring the application state and data through [appRecovery](../reference/apis/js-apis-app-ability-appRecovery.md).
- Fault query indicates that [faultLogger](../reference/apis/js-apis-faultLogger.md) obtains the fault information using its query API.
- Fault query is the process of calling APIs of [faultLogger](../reference/apis/js-apis-faultLogger.md) to obtain the fault information.
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-app-ability-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.
The figure below does not illustrate the time when [faultLogger](../reference/apis/js-apis-faultLogger.md) is called. You can refer to the [LastExitReason](../reference/apis/js-apis-app-ability-abilityConstant.md#abilityconstantlastexitreason) passed during application initialization to determine whether to call [faultLogger](../reference/apis/js-apis-faultLogger.md) to query information about the previous fault.
It is recommended that you call [errorManager](../reference/apis/js-apis-app-ability-errorManager.md) to process the exception. After the processing is complete, you can call the status saving API and restart the application.
It is recommended that you call [errorManager](../reference/apis/js-apis-app-ability-errorManager.md) to handle the exception. After the processing is complete, you can call the **saveAppState** API and restart the application.
If you do not register [ErrorObserver](../reference/apis/js-apis-inner-application-errorObserver.md) 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 do not register [ErrorObserver](../reference/apis/js-apis-inner-application-errorObserver.md) 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-app-ability-uiAbility.md#uiabilityonsavestate) of [Ability](../reference/apis/js-apis-app-ability-uiAbility.md) is called back. Finally, the application is restarted.
If you have enabled application recovery, the recovery framework first checks whether application state saving is supported and whether the application state saving is enabled. If so, the recovery framework invokes [onSaveState](../reference/apis/js-apis-app-ability-uiAbility.md#uiabilityonsavestate) of the [Ability](../reference/apis/js-apis-app-ability-uiAbility.md). Finally, the application is restarted.
### Scenarios Supported by Application Fault Management APIs
### Supported Application Recovery Scenarios
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.
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.
| [APP_FREEZE](../reference/apis/js-apis-faultLogger.md#faulttype) | Not supported|Not 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|
| [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.
**State Saving** in the table header means saving of the application state when a fault occurs. To protect user data as much as possible when an AppFreeze occurs, you can adopt either the periodic or automatic way, and the latter will save user data when an ability is switched to the background.
After enabling **appRecovery**, you can use this function by either actively or passively saving the status and restoring data in the ability.
After enabling **appRecovery**, you can use this function by either actively or passively saving the application state and restoring data in the ability.
The following is an example of **MainAbility**:
The following is an example of **MainAbility**:
#### Importing the Service Package
#### Importing the Service Package
...
@@ -92,14 +92,14 @@ import appRecovery from '@ohos.app.ability.appRecovery'
...
@@ -92,14 +92,14 @@ import appRecovery from '@ohos.app.ability.appRecovery'
#### Actively Saving the Application State and Restoring Data
- Define and register the [ErrorObserver](../reference/apis/js-apis-inner-application-errorObserver.md) callback.
- Define and register the [ErrorObserver](../reference/apis/js-apis-inner-application-errorObserver.md) callback. For details about its usage, see [errorManager](../reference/apis/js-apis-app-ability-errorManager.md).
```ts
```ts
varregisterId=-1;
varregisterId=-1;
varcallback={
varcallback={
onUnhandledException:function(errMsg){
onUnhandledException(errMsg){
console.log(errMsg);
console.log(errMsg);
appRecovery.saveAppState();
appRecovery.saveAppState();
appRecovery.restartApp();
appRecovery.restartApp();
...
@@ -111,7 +111,7 @@ import AbilityConstant from '@ohos.app.ability.AbilityConstant'
...
@@ -111,7 +111,7 @@ import AbilityConstant from '@ohos.app.ability.AbilityConstant'
console.log("[Demo] result "+result.code+";"+result.message)
console.error("[Demo] err:",err);
});
});
})
})
}
}
```
```
#### Passively Saving Status and Restoring Data
#### Passively Saving the Application State and Restoring Data
This is triggered by the recovery framework. You do not need to register an **ErrorObserver** callback. You only need to implement **onSaveState**of the ability for status saving and **onCreate** of the ability for data restoration.
This is triggered by the recovery framework. You do not need to register an **ErrorObserver** callback. You only need to implement **onSaveState**for application state saving and **onCreate** for data restore.
The **contact** module provides contact management functions, such as adding, deleting, and updating contacts.
>**NOTE**
>**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.
>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.
...
@@ -7,7 +9,7 @@
...
@@ -7,7 +9,7 @@
## Modules to Import
## Modules to Import
```js
```
import contact from '@ohos.contact';
import contact from '@ohos.contact';
```
```
...
@@ -183,7 +185,7 @@ Updates a contact based on the specified contact information. This API uses an a
...
@@ -183,7 +185,7 @@ Updates a contact based on the specified contact information. This API uses an a
The **power** module provides APIs for rebooting and shutting down the system, as well as querying the screen status.
The **power** module provides APIs for rebooting and shutting down the system, as well as querying the screen status.
> **NOTE**<br>
> **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.
> 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.
## Modules to Import
## Modules to Import
...
@@ -33,7 +34,7 @@ Shuts down the system.
...
@@ -33,7 +34,7 @@ Shuts down the system.
For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
| Code | Error Message |
| ID | Error Message |
|---------|---------|
|---------|---------|
| 4900101 | Operation failed. Cannot connect to service.|
| 4900101 | Operation failed. Cannot connect to service.|
...
@@ -69,7 +70,7 @@ Reboots the system.
...
@@ -69,7 +70,7 @@ Reboots the system.
For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
| Code | Error Message |
| ID | Error Message |
|---------|---------|
|---------|---------|
| 4900101 | Operation failed. Cannot connect to service.|
| 4900101 | Operation failed. Cannot connect to service.|
...
@@ -95,7 +96,7 @@ Checks whether the current device is active.
...
@@ -95,7 +96,7 @@ Checks whether the current device is active.
For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
| Code | Error Message |
| ID | Error Message |
|---------|---------|
|---------|---------|
| 4900101 | Operation failed. Cannot connect to service.|
| 4900101 | Operation failed. Cannot connect to service.|
...
@@ -130,7 +131,7 @@ Wakes up a device.
...
@@ -130,7 +131,7 @@ Wakes up a device.
For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
| Code | Error Message |
| ID | Error Message |
|---------|---------|
|---------|---------|
| 4900101 | Operation failed. Cannot connect to service.|
| 4900101 | Operation failed. Cannot connect to service.|
...
@@ -158,7 +159,7 @@ Hibernates a device.
...
@@ -158,7 +159,7 @@ Hibernates a device.
For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
| Code | Error Message |
| ID | Error Message |
|---------|---------|
|---------|---------|
| 4900101 | Operation failed. Cannot connect to service.|
| 4900101 | Operation failed. Cannot connect to service.|
...
@@ -190,7 +191,7 @@ Obtains the power mode of this device.
...
@@ -190,7 +191,7 @@ Obtains the power mode of this device.
For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
| Code | Error Message |
| ID | Error Message |
|---------|---------|
|---------|---------|
| 4900101 | Operation failed. Cannot connect to service.|
| 4900101 | Operation failed. Cannot connect to service.|
...
@@ -228,7 +229,7 @@ Sets the power mode of this device. This API uses an asynchronous callback to re
...
@@ -228,7 +229,7 @@ Sets the power mode of this device. This API uses an asynchronous callback to re
For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
| Code | Error Message |
| ID | Error Message |
|---------|---------|
|---------|---------|
| 4900101 | Operation failed. Cannot connect to service.|
| 4900101 | Operation failed. Cannot connect to service.|
...
@@ -272,7 +273,7 @@ Sets the power mode of this device. This API uses a promise to return the result
...
@@ -272,7 +273,7 @@ Sets the power mode of this device. This API uses a promise to return the result
For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
For details about the error codes, see [Power Manager Error Codes](../errorcodes/errorcode-power.md).
| Code | Error Message |
| ID | Error Message |
|---------|---------|
|---------|---------|
| 4900101 | Operation failed. Cannot connect to service.|
| 4900101 | Operation failed. Cannot connect to service.|
> **NOTE**<br>This API is supported since API version 7 and is deprecated since API version 9. You are advised to use [power.reboot](#powerreboot9). The substitute API is available only for system applications.
> This API is deprecated since API version 9. You are advised to use [power.reboot](#powerreboot9) instead.
| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the screen status obtained, where the value **true** indicates on and the value **false** indicates the opposite. Otherwise, **err** is an error object.|
| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the screen status obtained, where the value **true** indicates on and the value **false** indicates off. Otherwise, **err** is an error object.|
The SIM management module provides basic SIM card management functions. You can obtain the name, number, ISO country code, home PLMN number, service provider name, SIM card status, type, installation status, activation status, and lock status of the SIM card in the specified slot. Besides, you can set the name, number, and lock status of the SIM card, activate or deactivate the SIM card, and change the PIN or unlock the PIN or PUK of the SIM card.
The **sim** module provides basic SIM card management functions. You can obtain the name, number, ISO country code, home PLMN number, service provider name, SIM card status, type, installation status, activation status, and lock status of the SIM card in the specified slot. Besides, you can set the name, number, and lock status of the SIM card, activate or deactivate the SIM card, and change the PIN or unlock the PIN or PUK of the SIM card.
The **brightness** module provides APIs for querying and adjusting the screen brightness and mode.
The **brightness** module provides APIs for querying and adjusting the screen brightness and mode.
> **NOTE**
> **NOTE**
> - The APIs of this module are no longer maintained since API version 7. It is recommended that you use [`@ohos.brightness`](js-apis-brightness.md) instead.
>
> - The APIs of this module are no longer maintained since API version 7. You are advised to use APIs of [`@ohos.brightness`](js-apis-brightness.md). The substitute APIs are available only for system applications.
> - The initial APIs of this module are supported since API version 3. 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 3. Newly added APIs will be marked with a superscript to indicate their earliest API version.
...
@@ -132,8 +133,7 @@ Sets the screen brightness adjustment mode.
...
@@ -132,8 +133,7 @@ Sets the screen brightness adjustment mode.
>This API is no longer maintained since API version 7. It is recommended that you use [window.setKeepScreenOn](js-apis-window.md#setkeepscreenon) instead.
> This API is no longer maintained since API version 7. It is recommended that you use [window.setKeepScreenOn](js-apis-window.md#setkeepscreenon) instead.
Sets whether to always keep the screen on. Call this API in **onShow()**.
Sets whether to always keep the screen on. Call this API in **onShow()**.
...
@@ -168,7 +168,7 @@ Defines the options for obtaining the screen brightness.
...
@@ -168,7 +168,7 @@ Defines the options for obtaining the screen brightness.
| success | (data: [BrightnessResponse](#brightnessresponse)) => void | No | Called when API call is successful. **data** is a return value of the [BrightnessResponse](#brightnessresponse) type.|
| success | (data: [BrightnessResponse](#brightnessresponse)) => void | No | Called when API call is successful. **data** is a return value of the [BrightnessResponse](#brightnessresponse) type.|
| fail | (data: string, code: number) => void | No | Called when API call has failed. **data** indicates the error information, and **code** indicates the error code. |
| fail | (data: string, code: number) => void | No | Called when API call has failed. **data** indicates the error information, and **code** indicates the error code. |
| complete | () => void | No | Called when API call is complete. |
| complete | () => void | No | Called when the API call is complete. |
## SetBrightnessOptions
## SetBrightnessOptions
...
@@ -179,21 +179,23 @@ Defines the options for setting the screen brightness.
...
@@ -179,21 +179,23 @@ Defines the options for setting the screen brightness.
| value | number | Yes | Screen brightness. The value is an integer ranging from **1** to **255**.<br>- If the value is less than or equal to **0**, value **1** will be used.<br>- If the value is greater than **255**, value **255** will be used.<br>- If the value contains decimals, the integral part of the value will be used. For example, if value **8.1** is set, value **8** will be used.|
| value | number | Yes | Screen brightness. The value is an integer ranging from **1** to **255**.<br>- If the value is less than or equal to **0**, value **1** will be used.<br>- If the value is greater than **255**, value **255** will be used.<br>- If the value contains decimals, the integral part of the value will be used. For example, if value **8.1** is set, value **8** will be used.|
| success | () => void | No | Called when API call is successful. |
| success | () => void | No | Callback upon a successful API call. |
| fail | (data: string, code: number) => void | No | Called when API call has failed. **data** indicates the error information, and **code** indicates the error code. |
| fail | (data: string, code: number) => void | No | Called when API call has failed. **data** indicates the error information, and **code** indicates the error code. |
| complete | () => void | No | Called when API call is complete. |
| complete | () => void | No | Called when the API call is complete. |
## BrightnessResponse
## BrightnessResponse
Defines a response that returns the screen brightness.
Defines a response that returns the screen brightness.
| Parameter| Type | Readable | Writable | Description|
| success | (data: [BrightnessModeResponse](#brightnessmoderesponse)) => void | No | Called when API call is successful. **data** is a return value of the [BrightnessModeResponse](#brightnessmoderesponse) type.|
| success | (data: [BrightnessModeResponse](#brightnessmoderesponse)) => void | No | Called when API call is successful. **data** is a return value of the [BrightnessModeResponse](#brightnessmoderesponse) type.|
| fail | (data: string, code: number) => void | No | Called when API call has failed. **data** indicates the error information, and **code** indicates the error code. |
| fail | (data: string, code: number) => void | No | Called when API call has failed. **data** indicates the error information, and **code** indicates the error code. |
| complete | () => void | No | Called when API call is complete. |
| complete | () => void | No | Called when the API call is complete. |
## SetBrightnessModeOptions
## SetBrightnessModeOptions
Sets the options of the screen brightness mode.
Defines the options for setting the screen brightness mode.
| mode | number | Yes | The value **0** indicates the manual adjustment mode, and the value **1** indicates the automatic adjustment mode.|
| mode | number | Yes | The value **0** indicates the manual adjustment mode, and the value **1** indicates the automatic adjustment mode.|
| success | () => void | No | Called when API call is successful. |
| success | () => void | No | Callback upon a successful API call. |
| fail | (data: string, code: number) => void | No | Called when API call has failed. **data** indicates the error information, and **code** indicates the error code.|
| fail | (data: string, code: number) => void | No | Called when API call has failed. **data** indicates the error information, and **code** indicates the error code.|
| complete | () => void | No | Called when API call is complete. |
| complete | () => void | No | Called when the API call is complete. |
## BrightnessModeResponse
## BrightnessModeResponse
Defines a response that returns the screen brightness mode.
Defines a response that returns the screen brightness mode.
| Parameter| Type | Readable | Writable | Description|
| keepScreenOn | boolean | Yes | The value **true** means to keep the screen steady on, and the value **false** indicates the opposite. |
| keepScreenOn | boolean | Yes | The value **true** means to keep the screen steady on, and the value **false** indicates the opposite. |
| success | () => void | No | Called when API call is successful. |
| success | () => void | No | Callback upon a successful API call. |
| fail | (data: string, code: number) => void | No | Called when API call has failed. **data** indicates the error information, and **code** indicates the error code.|
| fail | (data: string, code: number) => void | No | Called when API call has failed. **data** indicates the error information, and **code** indicates the error code.|
| complete | () => void | No | Called when API call is complete. |
| complete | () => void | No | Called when the API call is complete. |
The USB module provides USB device management functions, including USB device list query, bulk data transfer, control transfer, and permission control on the host side as well as port management, and function switch and query on the device side.
> **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 APIs provided by this module are no longer maintained since API version 9. You are advised to use [`@ohos.usbManager`](js-apis-usbManager.md).
Connects to the USB device based on the device information returned by **getDevices()**.
Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list and device information, and then call [usb.requestRight](#usbrequestright) to request the device access permission.
| device | [USBDevice](#usbdevice) | Yes| USB device information.|
**Return value**
| Type| Description|
| -------- | -------- |
| Readonly<[USBDevicePipe](#usbdevicepipe)> | USB device pipe for data transfer.|
**Error codes**
For details about the error codes, see [USB Error Codes](../errorcodes/errorcode-usb.md).
| ID| Error Message|
| -------- | -------- |
| 14400001 |Permission denied. Need call requestRight to get permission. |
**Example**
```js
letdevicesList=usb.getDevices();
if(devicesList.length==0){
console.log(`device list is empty`);
}
letdevice=devicesList[0];
usb.requestRight(device.name);
letdevicepipe=usb.connectDevice(device);
console.log(`devicepipe = ${devicepipe}`);
```
## usb.hasRight
hasRight(deviceName: string): boolean
Checks whether the application has the permission to access the device.
Checks whether the user, for example, the application or system, has the device access permissions. The value **true** is returned if the user has the device access permissions; the value **false** is returned otherwise.
| Promise<boolean> | Promise used to return the result. The value **true** indicates that the temporary device access permissions are granted; and the value **false** indicates the opposite.|
**Example**
```js
letdevicesName="1-1";
usb.requestRight(devicesName).then((ret)=>{
console.log(`requestRight = ${ret}`);
});
```
## usb.removeRight
removeRight(deviceName: string): boolean
Removes the permission for the application to access a USB device.
| boolean | Permission removal result. The value **true** indicates that the access permission is removed successfully; and the value **false** indicates the opposite.|
Adds the permission for the application to access a USB device.
[requestRight](#usbrequestright) triggers a dialog box to request for user authorization, whereas **addRight** adds the access permission directly without displaying a dialog box.
| bundleName | string | Yes| Bundle name of the application.|
**Return value**
| Type| Description|
| -------- | -------- |
| boolean | Permission addition result. The value **true** indicates that the access permission is added successfully; and the value **false** indicates the opposite.|
**Example**
```js
letdevicesName="1-1";
letbundleName="com.example.hello";
ifusb.addRight(bundleName,devicesName){
console.log(`Succeed in adding right`);
}
```
## usb.claimInterface
claimInterface(pipe: USBDevicePipe, iface: USBInterface, force ?: boolean): number
Claims a USB interface.
Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list and USB interfaces, call [usb.requestRight](#usbrequestright) to request the device access permission, and call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter.
| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address.|
| iface | [USBInterface](#usbinterface) | Yes| USB interface, which is used to determine the index of the interface to claim.|
| force | boolean | No| Whether to forcibly claim the USB interface. The default value is **false**, indicating not to forcibly claim the USB interface.|
**Return value**
| Type| Description|
| -------- | -------- |
| number | Returns **0** if the USB interface is successfully claimed; returns an error code otherwise.|
**Example**
```js
letret=usb.claimInterface(devicepipe,interfaces);
console.log(`claimInterface = ${ret}`);
```
## usb.releaseInterface
releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number
Releases a USB interface.
Before you do this, ensure that you have claimed the interface by calling [usb.claimInterface](#usbclaiminterface).
setConfiguration(pipe: USBDevicePipe, config: USBConfig): number
Sets the device configuration.
Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list and device configuration, call [usb.requestRight](#usbrequestright) to request the device access permission, and call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter.
| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address.|
| config | [USBConfig](#usbconfig) | Yes| USB configuration to set.|
**Return value**
| Type| Description|
| -------- | -------- |
| number | Returns **0** if the USB configuration is successfully set; returns an error code otherwise.|
**Example**
```js
letret=usb.setConfiguration(devicepipe,config);
console.log(`setConfiguration = ${ret}`);
```
## usb.setInterface
setInterface(pipe: USBDevicePipe, iface: USBInterface): number
Sets a USB interface.
Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list and interfaces, call [usb.requestRight](#usbrequestright) to request the device access permission, call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter, and call [usb.claimInterface](#usbclaiminterface) to claim the USB interface.
| pipe | [USBDevicePipe](#usbdevicepipe) | Yes | Device pipe, which is used to determine the bus number and device address.|
| iface | [USBInterface](#usbinterface) | Yes | USB interface to set. |
**Return value**
| Type| Description|
| -------- | -------- |
| number | Returns **0** if the USB interface is successfully set; returns an error code otherwise.|
**Example**
```js
letret=usb.setInterface(devicepipe,interfaces);
console.log(`setInterface = ${ret}`);
```
## usb.getRawDescriptor
getRawDescriptor(pipe: USBDevicePipe): Uint8Array
Obtains the raw USB descriptor.
Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list, call [usb.requestRight](#usbrequestright) to request the device access permission, and call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter.
| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address.|
**Return value**
| Type| Description|
| -------- | -------- |
| Uint8Array | Returns the raw USB descriptor if the operation is successful; returns **undefined** otherwise.|
**Example**
```js
letret=usb.getRawDescriptor(devicepipe);
```
## usb.getFileDescriptor
getFileDescriptor(pipe: USBDevicePipe): number
Obtains the file descriptor.
Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list, call [usb.requestRight](#usbrequestright) to request the device access permission, and call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter.
Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list, call [usb.requestRight](#usbrequestright) to request the device access permission, and call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter.
| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe, which is used to determine the USB device.|
| controlparam | [USBControlParams](#usbcontrolparams) | Yes| Control transfer parameters.|
| timeout | number | No| Timeout duration in ms. This parameter is optional. The default value is **0**, indicating no timeout.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise<number> | Promise used to return the result, which is the size of the transmitted or received data block if the transfer is successful, or **-1** if an exception has occurred.|
Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list and endpoints, call [usb.requestRight](#usbrequestright) to request the device access permission, call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter, and call [usb.claimInterface](#usbclaiminterface) to claim the USB interface.
| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe, which is used to determine the USB device.|
| endpoint | [USBEndpoint](#usbendpoint) | Yes| USB endpoint, which is used to determine the USB port for data transfer.|
| buffer | Uint8Array | Yes| Buffer for writing or reading data.|
| timeout | number | No| Timeout duration in ms. This parameter is optional. The default value is **0**, indicating no timeout.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise<number> | Promise used to return the result, which is the size of the transmitted or received data block if the transfer is successful, or **-1** if an exception has occurred.|
**Example**
```js
// Call usb.getDevices to obtain a data set. Then, obtain a USB device and its access permission.
// Pass the obtained USB device as a parameter to usb.connectDevice. Then, call usb.connectDevice to connect the USB device.
// Call usb.claimInterface to claim the USB interface. After that, call usb.bulkTransfer to start bulk transfer.
Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list, call [usb.requestRight](#usbrequestright) to request the device access permission, and call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter.
| Promise\<boolean\> | Promise used to return the result. The value **true** indicates that the operation is successful, and the value **false** indicates the opposite.|
**Example**
```js
letfuncs=usb.HDC;
letret=usb.setCurrentFunctions(funcs);
```
## usb.getCurrentFunctions
getCurrentFunctions(): FunctionType
Obtains the numeric mask combination for the USB function list in Device mode.
| Promise\<boolean\> | Promise used to return the result. The value **true** indicates that the operation is successful, and the value **false** indicates the opposite.|
| **Source Code of the Latest Release**| **Version**| **Site**| **SHA-256 Checksum**| **Software Package Size**|
| **Source Code of the Latest Release**| **Version**| **Site**| **SHA-256 Checksum**| **Software Package Size**|
| Full code base (for mini, small, and standard systems)| 3.2 Beta4 | [Download](https://repo.huaweicloud.com/harmonyos/os/3.2-Beta4/code-v3.2-Beta4.tar.gz) | [Download](https://repo.huaweicloud.com/harmonyos/os/3.2-Beta4/code-v3.2-Beta4.tar.gz.sha256) | 19.0 GB |
| Full code base (for mini, small, and standard systems)| 3.2 Release | [Download](https://repo.huaweicloud.com/harmonyos/os/3.2-Release/code-v3.2-Release.tar.gz)| [Download](https://repo.huaweicloud.com/harmonyos/os/3.2-Release/code-v3.2-Release.tar.gz.sha256)| 21.8 GB |
| RK3568 standard system solution (binary)| 3.2 Beta4 | [Download](https://repo.huaweicloud.com/harmonyos/os/3.2-Beta4/dayu200_standard_arm32.tar.gz) | [Download](https://repo.huaweicloud.com/harmonyos/os/3.2-Beta4/dayu200_standard_arm32.tar.gz.sha256) | 3.2 GB |
Neural Network Runtime (NNRt) functions as a bridge to connect the upper-layer AI inference framework and bottom-layer acceleration chips, implementing cross-chip inference computing of AI models.
With the open APIs provided by NNRt, chip vendors can connect their dedicated acceleration chips to NNRt to access the OpenHarmony ecosystem.
### Basic Concepts
Before you get started, it would be helpful for you to have a basic understanding of the following concepts:
- Hardware Device Interface (HDI): defines APIs for cross-process communication between services in OpenHarmony.
- Interface Description Language (IDL): defines the HDI language format.
### Constraints
- System version: OpenHarmony trunk version.
- Development environment: Ubuntu 18.04 or later.
- Access device: a chip with AI computing capabilities.
### Working Principles
NNRt connects to device chips through HDIs, which implement cross-process communication between services.
The NNRt architecture consists of three layers: AI applications at the application layer, AI inference framework and NNRt at the system layer, and device services at the chip layer. To use a dedicated acceleration chip model for inference, an AI application needs to call the dedicated acceleration chip at the bottom layer through the AI inference framework and NNRt. NNRt is responsible for adapting to various dedicated acceleration chips at the bottom layer. It opens standard and unified HDIs for various chips to access the OpenHarmony ecosystem.
During program running, the AI application, AI inference framework, and NNRt reside in the user process, and the underlying device services reside in the service process. NNRt implements the HDI client and the service side implements HDI Service to fulfill cross-process communication.
## How to Develop
### Application Scenario
Suppose you are connecting an AI acceleration chip, for example, RK3568, to NNRt. The following describes how to connect the RK3568 chip to NNRt through the HDI to implement AI model inference.
> **NOTE**<br>In this application scenario, the connection of the RK3568 chip to NNRt is implemented by utilizing the CPU operator of MindSpore Lite, instead of writing the CPU driver. This is the reason why the following development procedure depends on the dynamic library and header file of MindSpore Lite. In practice, the development does not depend on any library or header file of MindSpore Lite.
### Development Flowchart
The following figure shows the process of connecting a dedicated acceleration chip to NNRt.
**Figure 2** NNRt development flowchart
### Development Procedure
To connect the acceleration chip to NNRt, perform the development procedure below.
#### Generating the HDI Header File
Download the OpenHarmony source code from the open source community, build the `drivers_interface` component, and generate the HDI header file.
1.[Download the source code](../get-code/sourcecode-acquire.md).
> **NOTE**<br>**productname** indicates the product name. In this example, the product name is **RK3568**.
When the build is complete, the HDI header file is generated in `out/rk3568/gen/drivers/interface/nnrt`. The default programming language is C++. To generate a header file for the C programming language, run the following command to set the `language` field in the `drivers/interface/nnrt/v1_0/BUILD.gn` file before starting the build:
```shell
language = "c"
```
The directory of the generated header file is as follows:
├── iprepared_model.h # Header file of the AI model
├── libnnrt_proxy_1.0__notice.d
├── libnnrt_stub_1.0__notice.d
├── model_types.cpp # Implementation file for AI model structure definition
├── model_types.h # Header file for AI model structure definition
├── nnrt_device_driver.cpp # Device driver implementation example
├── nnrt_device_proxy.cpp
├── nnrt_device_proxy.h
├── nnrt_device_service.cpp # Implementation file for device services
├── nnrt_device_service.h # Header file for device services
├── nnrt_device_stub.cpp
├── nnrt_device_stub.h
├── nnrt_types.cpp # Implementation file for data type definition
├── nnrt_types.h # Header file for data type definition
├── node_attr_types.cpp # Implementation file for AI model operator attribute definition
├── node_attr_types.h # Header file for AI model operator attribute definition
├── prepared_model_proxy.cpp
├── prepared_model_proxy.h
├── prepared_model_service.cpp # Implementation file for AI model services
├── prepared_model_service.h # Header file for AI model services
├── prepared_model_stub.cpp
└── prepared_model_stub.h
```
#### Implementing the HDI Service
1. Create a development directory in `drivers/peripheral`. The structure of the development directory is as follows:
```text
drivers/peripheral/nnrt
├── BUILD.gn # Code build script
├── bundle.json
└── hdi_cpu_service # Customized directory
├── BUILD.gn # Code build script
├── include
│ ├── nnrt_device_service.h # Header file for device services
│ ├── node_functions.h # Optional, depending on the actual implementation
│ ├── node_registry.h # Optional, depending on the actual implementation
│ └── prepared_model_service.h # Header file for AI model services
└── src
├── nnrt_device_driver.cpp # Implementation file for the device driver
├── nnrt_device_service.cpp # Implementation file for device services
├── nnrt_device_stub.cpp # Optional, depending on the actual implementation
├── node_attr_types.cpp # Optional, depending on the actual implementation
├── node_functions.cpp # Optional, depending on the actual implementation
├── node_registry.cpp # Optional, depending on the actual implementation
└── prepared_model_service.cpp # Implementation file for AI model services
```
2. Implement the device driver. Unless otherwise required, you can directly use the `nnrt_device_driver.cpp` file generated in step 1.
3. Implement service APIs. For details, see the `nnrt_device_service.cpp` and `prepared_model_service.cpp` implementation files. For details about the API definition, see [NNRt HDI Definitions](https://gitee.com/openharmony/drivers_interface/tree/master/nnrt).
4. Build the implementation files for device drivers and services as shared libraries.
Create the `BUILD.gn` file with the following content in `drivers/peripheral/nnrt/hdi_cpu_service/`. For details about how to set related parameters, see [Compilation and Building](https://gitee.com/openharmony/build).
In the uhdf directory, declare the user-mode driver and services in the **.hcs** file of the corresponding product. For example, for the RK3568 chip, add the following configuration to the `vendor/hihope/rk3568/hdf_config/uhdf/device_info.hcs` file:
```text
nnrt :: host {
hostName = "nnrt_host";
priority = 50;
uid = "";
gid = "";
caps = ["DAC_OVERRIDE", "DAC_READ_SEARCH"];
nnrt_device :: device {
device0 :: deviceNode {
policy = 2;
priority = 100;
moduleName = "libnnrt_driver.z.so";
serviceName = "nnrt_device_service";
}
}
}
```
> **NOTE**<br>After modifying the `.hcs` file, you need to delete the `out` directory and build the file again for the modification to take effect.
#### Configuring the User ID and Group ID of the Host Process
In the scenario of creating an nnrt_host process, you need to configure the user ID and group ID of the corresponding process. The user ID is configured in the `base/startup/init/services/etc/passwd` file, and the group ID is configured in the `base/startup/init/services/etc/group` file.
```text
# Add the user ID in base/startup/init/services/etc/passwd.
nnrt_host:x:3311:3311:::/bin/false
# Add the group ID in base/startup/init/services/etc/group.
nnrt_host:x:3311:
```
#### Configuring SELinux
The SELinux feature has been enabled for the OpenHarmony. You need to configure SELinux rules for the new processes and services so that they can run the host process to access certain resources and release HDI services.
1. Configure the security context of the **nnrt_host** process in the `base/security/selinux/sepolicy/ohos_policy/drivers/adapter/vendor/type.te` file.
```text
# Add the security context configuration.
type nnrt_host, hdfdomain, domain;
```
> In the preceding command, **nnrt_host** indicates the process name previously configured.
2. Configure access permissions because SELinux uses the trustlist access permission mechanism. Upon service startup, run the `dmesg` command to view the AVC alarm,
which provides a list of missing permissions. For details about the SELinux configuration, see [security_selinux] (https://gitee.com/openharmony/security_selinux/blob/master/README-en.md).
The test report below shows that all 47 test cases are successful, indicating that the service has passed the compatibility test.
```text
...
[----------] Global test environment tear-down
Gtest xml output finished
[==========] 47 tests from 3 test suites ran. (515 ms total)
[ PASSED ] 47 tests.
```
### Development Example
For the complete demo code, see [NNRt Service Implementation Example](https://gitee.com/openharmony/ai_neural_network_runtime/tree/master/example/drivers).
1. Copy the `example/driver/nnrt` directory to `drivers/peripheral`.
```shell
cp-r example/driver/nnrt drivers/peripheral
```
2. Add the `bundle.json` file to `drivers/peripheral/nnrt`. For details about the `bundle.json` file, see [Development Procedure](#development-procedure).
3. Add the dependency files of MindSpore Lite because the demo depends on the CPU operator of MindSpore Lite.
- Download the header file of [MindSpore Lite 1.5.0](https://ms-release.obs.cn-north-4.myhuaweicloud.com/1.5.0/MindSpore/lite/release/linux/mindspore-lite-1.5.0-linux-x64.tar.gz).
- Create the `mindspore` directory in `drivers/peripheral/nnrt`.
```shell
mkdir drivers/peripheral/nnrt/mindspore
```
- Decompress the `mindspore-lite-1.5.0-linux-x64.tar.gz` file, and copy the `runtime/include` directory to `drivers/peripheral/nnrt/mindspore`.
- Create and copy the `schema` file of MindSpore Lite.
