diff --git a/en/application-dev/device/inputdevice-guidelines.md b/en/application-dev/device/inputdevice-guidelines.md index da6eef71d750b74e01d1ea8a9eaaf49b1bf598cb..c15955d9b01239605d0ce1afa9bfe5f693b22940 100644 --- a/en/application-dev/device/inputdevice-guidelines.md +++ b/en/application-dev/device/inputdevice-guidelines.md @@ -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. 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. ```js @@ -65,6 +64,4 @@ try { } catch (error) { console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); } - // 3. Determine whether to launch the virtual keyboard based on the value of isPhysicalKeyboardExist. - // TODO ``` diff --git a/en/application-dev/device/usb-guidelines.md b/en/application-dev/device/usb-guidelines.md index cdb6c325271099a38739eeaa87f2e36920b5d8e6..70258c31f55f6ea630ed7edc7a85e4b2e6e98d17 100644 --- a/en/application-dev/device/usb-guidelines.md +++ b/en/application-dev/device/usb-guidelines.md @@ -129,8 +129,6 @@ You can set a USB device as the USB host to connect to other USB devices for dat usb.bulkTransfer(pipe, inEndpoint, dataUint8Array, 15000).then(dataLength => { if (dataLength >= 0) { console.info("usb readData result Length : " + dataLength); - let resultStr = this.ab2str(dataUint8Array); // Convert uint8 data into a string. - console.info("usb readData buffer : " + resultStr); } else { console.info("usb readData failed : " + dataLength); } diff --git a/en/application-dev/dfx/apprecovery-guidelines.md b/en/application-dev/dfx/apprecovery-guidelines.md index cb009645b020c8dea95d41d71b75d4ff0f10d8fb..3ccac845bf8916c2d65f714474882f1c95848695 100644 --- a/en/application-dev/dfx/apprecovery-guidelines.md +++ b/en/application-dev/dfx/apprecovery-guidelines.md @@ -2,16 +2,16 @@ ## When to Use -During application running, some unexpected behaviors are inevitable. For example, unprocessed exceptions and errors are thrown, and the call or running constraints of the framework are violated. +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. Currently, the APIs support only the development of an application that adopts the stage model, single process, and single ability. ## Available APIs -The application recovery APIs are provided by the **appRecovery** module, which can be imported via **import**. For details, please refer to [Development Example](#development-example). This document describes behaviors of APIs in API version 9, and the content will update with changes. +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 @@ -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. -**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. -### 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 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. ![Fault rectification process](./figures/fault_rectification.png) -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 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. -| Fault | Fault Listening | Status Saving| Automatic Restart| Log Query| +| Fault | Fault Listening | State Saving| Automatic Restart| Log Query| | ----------|--------- |--------- |--------- |--------- | | [JS_CRASH](../reference/apis/js-apis-faultLogger.md#faulttype) | Supported|Supported|Supported|Supported| | [APP_FREEZE](../reference/apis/js-apis-faultLogger.md#faulttype) | Not supported|Not supported|Supported|Supported| | [CPP_CRASH](../reference/apis/js-apis-faultLogger.md#faulttype) | Not supported|Not supported|Not supported|Supported| -**Status Saving** in the table header means status saving when a fault occurs. To protect user data as much as possible in the application freezing fault, you can adopt either the periodic or automatic way, and the latter will save user data when an ability is switched to the background. +**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. @@ -81,7 +81,7 @@ export default class MyAbilityStage extends AbilityStage { ### Saving and Restoring Data -After enabling **appRecovery**, you can use this function by either actively or passively saving the status and restoring data in the ability. +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**: #### Importing the Service Package @@ -92,14 +92,14 @@ import appRecovery from '@ohos.app.ability.appRecovery' import AbilityConstant from '@ohos.app.ability.AbilityConstant' ``` -#### Actively Saving Status and Restoring Data +#### 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 var registerId = -1; var callback = { - onUnhandledException: function (errMsg) { + onUnhandledException(errMsg) { console.log(errMsg); appRecovery.saveAppState(); appRecovery.restartApp(); @@ -111,7 +111,7 @@ import AbilityConstant from '@ohos.app.ability.AbilityConstant' console.log("[Demo] MainAbility onWindowStageCreate") globalThis.registerObserver = (() => { - registerId = errorManager.registerErrorObserver(callback); + registerId = errorManager.on('error', callback); }) windowStage.loadContent("pages/index", null); @@ -127,7 +127,7 @@ After the callback triggers **appRecovery.saveAppState()**, **onSaveState(state, // Ability has called to save app data console.log("[Demo] MainAbility onSaveState") wantParams["myData"] = "my1234567"; - return AbilityConstant.onSaveResult.ALL_AGREE; + return AbilityConstant.OnSaveResult.ALL_AGREE; } ``` @@ -157,16 +157,16 @@ onWindowStageDestroy() { console.log("[Demo] MainAbility onWindowStageDestroy") globalThis.unRegisterObserver = (() => { - errorManager.unregisterErrorObserver(registerId, (result) => { - console.log("[Demo] result " + result.code + ";" + result.message) + errorManager.off('error', registerId, (err) => { + 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. ```ts export default class MainAbility extends Ability { @@ -186,7 +186,7 @@ export default class MainAbility extends Ability { // Ability has called to save app data console.log("[Demo] MainAbility onSaveState") wantParams["myData"] = "my1234567"; - return AbilityConstant.onSaveResult.ALL_AGREE; + return AbilityConstant.OnSaveResult.ALL_AGREE; } } ``` diff --git a/en/application-dev/internationalization/intl-guidelines.md b/en/application-dev/internationalization/intl-guidelines.md index fcac5325292b27f349f6c3dcadb627dca2dd0c03..5731421555d083f90464a0257a21c119ebd8ee3a 100644 --- a/en/application-dev/internationalization/intl-guidelines.md +++ b/en/application-dev/internationalization/intl-guidelines.md @@ -384,4 +384,4 @@ According to grammars in certain languages, the singular or plural form of a nou ```js let relativeTimeFormat = new Intl.RelativeTimeFormat("zh-CN", {numeric: "always", style: "long"}); let options = relativeTimeFormat.resolvedOptions(); // options = {"locale": "zh-CN", "style": "long", "numeric": "always", "numberingSystem": "latn"} - ``` + ``` \ No newline at end of file diff --git a/en/application-dev/reference/apis/Readme-EN.md b/en/application-dev/reference/apis/Readme-EN.md index 651c69e51fd2c528d49a7a748de7dc830f4f39f8..77e422bc59994de1f1d038d01c21fd0fef59e31f 100644 --- a/en/application-dev/reference/apis/Readme-EN.md +++ b/en/application-dev/reference/apis/Readme-EN.md @@ -400,7 +400,6 @@ - [@ohos.systemParameter (System Parameter)](js-apis-system-parameter.md) - [@ohos.systemTime (System Time and Time Zone)](js-apis-system-time.md) - [@ohos.usb (USB Management)](js-apis-usb-deprecated.md) - - [@ohos.usbV9 (USB Management)](js-apis-usb.md) - [@system.app (Application Context)](js-apis-system-app.md) - [@system.battery (Battery Information)](js-apis-system-battery.md) - [@system.bluetooth (Bluetooth)](js-apis-system-bluetooth.md) diff --git a/en/application-dev/reference/apis/js-apis-contact.md b/en/application-dev/reference/apis/js-apis-contact.md index c2386b6d6755e4268aa5830a89a87403ce18a533..581cff20d3209bfcd2fad92559f030436d515b05 100644 --- a/en/application-dev/reference/apis/js-apis-contact.md +++ b/en/application-dev/reference/apis/js-apis-contact.md @@ -1,5 +1,7 @@ # @ohos.contact (Contacts) +The **contact** module provides contact management functions, such as adding, deleting, and updating contacts. + >**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. @@ -7,7 +9,7 @@ ## Modules to Import -```js +``` import contact from '@ohos.contact'; ``` @@ -183,7 +185,7 @@ Updates a contact based on the specified contact information. This API uses an a updateContact(contact: Contact, attrs: ContactAttributes, callback: AsyncCallback<void>): void -Updates a contact based on the specified contact information and attributes. This API uses an asynchronous callback to return the result. +Updates a contact based on the specified contact information. This API uses an asynchronous callback to return the result. **Permission required**: ohos.permission.WRITE_CONTACTS @@ -234,7 +236,6 @@ Updates a contact based on the specified contact information and attributes. Thi | attrs | [ContactAttributes](#contactattributes) | No | List of contact attributes.| **Return Value** - | Type | Description | | ------------------- | ------------------------------------------------- | | Promise<void> | Promise used to return the result.| @@ -418,7 +419,7 @@ Queries my card. This API uses an asynchronous callback to return the result. queryMyCard(attrs: ContactAttributes, callback: AsyncCallback<Contact>): void -Queries my card based on the specified contact attributes. This API uses an asynchronous callback to return the result. +Queries my card. This API uses an asynchronous callback to return the result. **Permission required**: ohos.permission.READ_CONTACTS @@ -463,7 +464,6 @@ Queries my card based on the specified contact attributes. This API uses a promi | attrs | [ContactAttributes](#contactattributes) | No | List of contact attributes.| **Return Value** - | Type | Description | | ---------------------------------- | ------------------------------------------- | | Promise<[Contact](#contact)> | Promise used to return the result.| @@ -569,7 +569,7 @@ Queries a contact based on the specified key. This API uses an asynchronous call queryContact(key: string, holder: Holder, callback: AsyncCallback<Contact>): void -Queries contacts based on the specified key and application. This API uses an asynchronous callback to return the result. +Queries a contact based on the specified key. This API uses an asynchronous callback to return the result. **Permission required**: ohos.permission.READ_CONTACTS @@ -604,7 +604,7 @@ Queries contacts based on the specified key and application. This API uses an as queryContact(key: string, attrs: ContactAttributes, callback: AsyncCallback<Contact>): void -Queries contacts based on the specified key and attributes. This API uses an asynchronous callback to return the result. +Queries a contact based on the specified key. This API uses an asynchronous callback to return the result. **Permission required**: ohos.permission.READ_CONTACTS @@ -637,7 +637,7 @@ Queries contacts based on the specified key and attributes. This API uses an asy queryContact(key: string, holder: Holder, attrs: ContactAttributes, callback: AsyncCallback<Contact>): void -Queries contacts based on the specified key, application, and attributes. This API uses an asynchronous callback to return the result. +Queries a contact based on the specified key. This API uses an asynchronous callback to return the result. **Permission required**: ohos.permission.READ_CONTACTS @@ -656,7 +656,6 @@ Queries contacts based on the specified key, application, and attributes. This A ```js contact.queryContact('xxx', { - holderId: 0 holderId: 0, bundleName: "", displayName: "" @@ -691,7 +690,6 @@ Queries contacts based on the specified key, application, and attributes. This A | attrs | [ContactAttributes](#contactattributes) | No | List of contact attributes. | **Return Value** - | Type | Description | | ---------------------------------- | ----------------------------------------------- | | Promise<[Contact](#contact)> | Promise used to return the result.| @@ -700,7 +698,6 @@ Queries contacts based on the specified key, application, and attributes. This A ```js let promise = contact.queryContact('xxx', { - holderId: 0 holderId: 0, bundleName: "", displayName: "" @@ -748,7 +745,7 @@ Queries all contacts. This API uses an asynchronous callback to return the resul queryContacts(holder: Holder, callback: AsyncCallback<Array<Contact>>): void -Queries all contacts based on the specified application. This API uses an asynchronous callback to return the result. +Queries all contacts. This API uses an asynchronous callback to return the result. **Permission required**: ohos.permission.READ_CONTACTS @@ -782,7 +779,7 @@ Queries all contacts based on the specified application. This API uses an asynch queryContacts(attrs: ContactAttributes, callback: AsyncCallback<Array<Contact>>): void -Queries all contacts based on the specified attributes. This API uses an asynchronous callback to return the result. +Queries all contacts. This API uses an asynchronous callback to return the result. **Permission required**: ohos.permission.READ_CONTACTS @@ -814,7 +811,7 @@ Queries all contacts based on the specified attributes. This API uses an asynchr queryContacts(holder: Holder, attrs: ContactAttributes, callback: AsyncCallback<Array<Contact>>): void -Queries all contacts based on the specified application and attributes. This API uses an asynchronous callback to return the result. +Queries all contacts. This API uses an asynchronous callback to return the result. **Permission required**: ohos.permission.READ_CONTACTS @@ -865,7 +862,6 @@ Queries all contacts based on the specified application and attributes. This API | attrs | [ContactAttributes](#contactattributes) | No | List of contact attributes. | **Return Value** - | Type | Description | | ----------------------------------------------- | --------------------------------------------------- | | Promise<Array<[Contact](#contact)>> | Promise used to return the result.| @@ -922,7 +918,7 @@ Queries contacts based on the specified phone number. This API uses an asynchron queryContactsByPhoneNumber(phoneNumber: string, holder: Holder, callback: AsyncCallback<Array<Contact>>): void -Queries contacts based on the specified phone number and application. This API uses an asynchronous callback to return the result. +Queries contacts based on the specified phone number. This API uses an asynchronous callback to return the result. **Permission required**: ohos.permission.READ_CONTACTS @@ -957,7 +953,7 @@ Queries contacts based on the specified phone number and application. This API u queryContactsByPhoneNumber(phoneNumber: string, attrs: ContactAttributes, callback: AsyncCallback<Array<Contact>>): void -Queries contacts based on the specified phone number and attributes. This API uses an asynchronous callback to return the result. +Queries contacts based on the specified phone number. This API uses an asynchronous callback to return the result. **Permission required**: ohos.permission.READ_CONTACTS @@ -990,7 +986,7 @@ Queries contacts based on the specified phone number and attributes. This API us queryContactsByPhoneNumber(phoneNumber: string, holder: Holder, attrs: ContactAttributes, callback: AsyncCallback<Array<Contact>>): void -Queries contacts based on the specified phone number, application, and attributes. This API uses an asynchronous callback to return the result. +Queries contacts based on the specified phone number. This API uses an asynchronous callback to return the result. **Permission required**: ohos.permission.READ_CONTACTS @@ -1100,7 +1096,7 @@ Queries contacts based on the specified email address. This API uses an asynchro queryContactsByEmail(email: string, holder: Holder, callback: AsyncCallback<Array<Contact>>): void -Queries contacts based on the specified email address and application. This API uses an asynchronous callback to return the result. +Queries contacts based on the specified email address. This API uses an asynchronous callback to return the result. **Permission required**: ohos.permission.READ_CONTACTS @@ -1118,7 +1114,7 @@ Queries contacts based on the specified email address and application. This API ```js contact.queryContactsByEmail('xxx@email.com', { - holderId: 0, + holderId: 0, bundleName: "", displayName: "" }, (err, data) => { @@ -1135,7 +1131,7 @@ Queries contacts based on the specified email address and application. This API queryContactsByEmail(email: string, attrs: ContactAttributes, callback: AsyncCallback<Array<Contact>>): void -Queries contacts based on the specified email address and attributes. This API uses an asynchronous callback to return the result. +Queries contacts based on the specified email address. This API uses an asynchronous callback to return the result. **Permission required**: ohos.permission.READ_CONTACTS @@ -1168,7 +1164,7 @@ Queries contacts based on the specified email address and attributes. This API u queryContactsByEmail(email: string, holder: Holder, attrs: ContactAttributes, callback: AsyncCallback<Array<Contact>>): void -Queries contacts based on the specified email address, application, and attributes. This API uses an asynchronous callback to return the result. +Queries contacts based on the specified email address. This API uses an asynchronous callback to return the result. **Permission required**: ohos.permission.READ_CONTACTS @@ -1277,7 +1273,7 @@ Queries all groups of this contact. This API uses an asynchronous callback to re queryGroups(holder: Holder, callback: AsyncCallback<Array<Group>>): void -Queries all groups of this contact based on the specified application. This API uses an asynchronous callback to return the result. +Queries all groups of this contact. This API uses an asynchronous callback to return the result. **Permission required**: ohos.permission.READ_CONTACTS @@ -1436,7 +1432,7 @@ Queries the key of a contact based on the specified contact ID. This API uses an queryKey(id: number, holder: Holder, callback: AsyncCallback<string>): void -Queries the key of a contact based on the specified contact ID and application. This API uses an asynchronous callback to return the result. +Queries the key of a contact based on the specified contact ID. This API uses an asynchronous callback to return the result. **Permission required**: ohos.permission.READ_CONTACTS @@ -1521,7 +1517,7 @@ Defines a contact. ### Attributes -| Name | Type | Readable| Writable| Description | +| Name | Type | Readable| Writable| Description | | ----------------- | --------------------------------------- | ---- | ---- | -------------------------------------- | | id | number | Yes | No | Contact ID. | | key | string | Yes | No | Contact key. | @@ -1583,7 +1579,7 @@ If **null** is passed, all attributes are queried by default. **System capability**: SystemCapability.Applications.ContactsData -| Name | Type | Readable| Writable| Description | +| Name | Type | Readable| Writable| Description | | ---------- | ------------------------- | ---- | ---- | ---------------- | | attributes | [Attribute](#attribute)[] | Yes | Yes | List of contact attributes.| @@ -1664,7 +1660,7 @@ Defines a contact's email. ### Attributes -| Name | Type| Readable| Writable| Description | +| Name | Type | Readable| Writable| Description | | ----------- | -------- | ---- | ---- | ---------------- | | email | string | Yes | Yes | Email addresses | | labelName | string | Yes | Yes | Name of the mailbox type.| @@ -1698,9 +1694,9 @@ Defines an application that creates the contact. **System capability**: SystemCapability.Applications.ContactsData -| Name | Type| Readable| Writable| Description | +| Name | Type | Readable| Writable| Description | | ----------- | -------- | ---- | ---- | ---------- | -| bundleName | string | Yes | No | Bundle name. | +| bundleName | string | Yes | No | Bundle name of an application. | | displayName | string | Yes | No | Application name.| | holderId | number | Yes | Yes | Application ID. | @@ -1742,7 +1738,7 @@ Defines a contact's event. ### Attributes -| Name | Type| Readable| Writable| Description | +| Name | Type | Readable| Writable| Description | | --------- | -------- | ---- | ---- | -------------- | | eventDate | string | Yes | Yes | Event date. | | labelName | string | Yes | Yes | Event type.| @@ -1773,7 +1769,7 @@ Defines a contact group. **System capability**: SystemCapability.Applications.ContactsData -| Name | Type| Readable| Writable| Description | +| Name | Type | Readable| Writable| Description | | ------- | -------- | ---- | ---- | ------------------ | | groupId | number | Yes | Yes | ID of a contact group. | | title | string | Yes | Yes | Name of a contact group.| @@ -1821,7 +1817,7 @@ Enumerates IM addresses. ### Attributes -| Name | Type| Readable| Writable| Description | +| Name | Type | Readable| Writable| Description | | --------- | -------- | ---- | ---- | ------------------ | | imAddress | string | Yes | Yes | IM address. | | labelName | string | Yes | Yes | IM name.| @@ -1854,7 +1850,7 @@ Defines a contact's name. **System capability**: SystemCapability.Applications.ContactsData -| Name | Type| Readable| Writable| Description | +| Name | Type | Readable| Writable| Description | | ------------------ | -------- | ---- | ---- | --------------------------- | | familyName | string | Yes | Yes | Family name. | | familyNamePhonetic | string | Yes | Yes | Family name in pinyin. | @@ -1893,7 +1889,7 @@ Defines a contact's nickname. **System capability**: SystemCapability.Applications.ContactsData -| Name | Type| Readable| Writable| Description | +| Name | Type | Readable| Writable| Description | | -------- | -------- | ---- | ---- | -------------- | | nickName | string | Yes | Yes | Contact nickname.| @@ -1922,7 +1918,7 @@ Defines a contact's note. **System capability**: SystemCapability.Applications.ContactsData -| Name | Type| Readable| Writable| Description | +| Name | Type | Readable| Writable| Description | | ----------- | -------- | ---- | ---- | ------------------ | | noteContent | string | Yes | Yes | Notes of the contact.| @@ -1951,7 +1947,7 @@ Defines a contact's organization. **System capability**: SystemCapability.Applications.ContactsData -| Name | Type| Readable| Writable| Description | +| Name | Type | Readable| Writable| Description | | ----- | -------- | ---- | ---- | ---------- | | name | string | Yes | Yes | Organization name.| | title | string | Yes | Yes | Organization title.| @@ -2013,7 +2009,7 @@ Defines a contact's phone number. ### Attributes -| Name | Type| Readable| Writable| Description | +| Name | Type | Readable| Writable| Description | | ----------- | -------- | ---- | ---- | ------------------ | | labelName | string | Yes | Yes | Phone number type.| | phoneNumber | string | Yes | Yes | Phone number. | @@ -2045,7 +2041,7 @@ Defines a contact's portrait. **System capability**: SystemCapability.Applications.ContactsData -| Name| Type| Readable| Writable| Description | +| Name| Type | Readable| Writable| Description | | ---- | -------- | ---- | ---- | -------------- | | uri | string | Yes | Yes | Contact portrait.| @@ -2087,7 +2083,7 @@ Defines a contact's postal address. ### Attributes -| Name | Type| Readable| Writable| Description | +| Name | Type | Readable| Writable| Description | | ------------- | -------- | ---- | ---- | -------------------------- | | city | string | Yes | Yes | City where the contact is located. | | country | string | Yes | Yes | Country/Region where the contact is located. | @@ -2149,7 +2145,7 @@ Defines a contact's relationship. ### Attributes -| Name | Type| Readable| Writable| Description | +| Name | Type | Readable| Writable| Description | | ------------ | -------- | ---- | ---- | -------------- | | labelName | string | Yes | Yes | Relationship type.| | relationName | string | Yes | Yes | Relationship name. | @@ -2195,13 +2191,12 @@ Defines a contact's SIP address. ### Attributes -| Name | Type| Readable| Writable| Description | +| Name | Type | Readable| Writable| Description | | ---------- | -------- | ---- | ---- | --------------------------------- | | labelName | string | Yes | Yes | SIP address type.| | sipAddress | string | Yes | Yes | SIP address. | | labelId | number | Yes | Yes | SIP address ID. | - **Example** Create contact data in JSON format: @@ -2226,7 +2221,7 @@ Defines a contact's website. **System capability**: SystemCapability.Applications.ContactsData -| Name | Type| Readable| Writable| Description | +| Name | Type | Readable| Writable| Description | | ------- | -------- | ---- | ---- | ------------------ | | website | string | Yes | Yes | Website of the contact.| @@ -2246,4 +2241,4 @@ let website = { ```js let website = new contact.Website(); website.website = "website"; -``` \ No newline at end of file +``` diff --git a/en/application-dev/reference/apis/js-apis-geolocation.md b/en/application-dev/reference/apis/js-apis-geolocation.md index 3bf1e990cd2fcb0f2853c224d0adf70ce5e7b5dc..ea7aae418128f0724bbb62a7d84bd1e57b16f66f 100644 --- a/en/application-dev/reference/apis/js-apis-geolocation.md +++ b/en/application-dev/reference/apis/js-apis-geolocation.md @@ -1486,7 +1486,7 @@ Sets the priority of the location request. Enumerates error codes of the location service. > **NOTE**
-> This API is deprecated since API version 9. +> This API is deprecated since API version 9. You are advised to use [geoLocationManager](../errorcodes/errorcode-geoLocationManager.md). **Required permissions**: ohos.permission.LOCATION diff --git a/en/application-dev/reference/apis/js-apis-power.md b/en/application-dev/reference/apis/js-apis-power.md index 625f189f877a620b2238d3cb048ce314f6a2af03..28a334d2f2f6c6f4912bbd5c573b1c1ce457519c 100644 --- a/en/application-dev/reference/apis/js-apis-power.md +++ b/en/application-dev/reference/apis/js-apis-power.md @@ -1,8 +1,9 @@ -# @ohos.power (System Power Management) +# @ohos.power (Power Management) The **power** module provides APIs for rebooting and shutting down the system, as well as querying the screen status. -> **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. ## Modules to Import @@ -33,7 +34,7 @@ Shuts down the system. 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.| @@ -69,7 +70,7 @@ Reboots the system. 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.| @@ -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). -| Code | Error Message | +| ID | Error Message | |---------|---------| | 4900101 | Operation failed. Cannot connect to service.| @@ -130,7 +131,7 @@ Wakes up a device. 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.| @@ -158,7 +159,7 @@ Hibernates a device. 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.| @@ -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). -| Code | Error Message | +| ID | Error Message | |---------|---------| | 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 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.| @@ -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). -| Code | Error Message | +| ID | Error Message | |---------|---------| | 4900101 | Operation failed. Cannot connect to service.| @@ -292,8 +293,7 @@ power.setPowerMode(power.DevicePowerMode.MODE_PERFORMANCE) rebootDevice(reason: string): void -> NOTE
-> This API is deprecated since API version 9. You are advised to use [power.reboot](#powerreboot9) instead. +> **NOTE**
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. Reboots the system. @@ -317,8 +317,7 @@ power.rebootDevice('reboot_test'); isScreenOn(callback: AsyncCallback<boolean>): void -> NOTE
-> This API is deprecated since API version 9. You are advised to use [power.isActive](#powerisactive9) instead. +> **NOTE**
This API is deprecated since API version 9. You are advised to use [power.isActive](#powerisactive9). Checks the screen status of the current device. This API uses an asynchronous callback to return the result. @@ -328,7 +327,7 @@ Checks the screen status of the current device. This API uses an asynchronous ca | Name | Type | Mandatory| Description | | -------- | ---------------------------- | ---- | ------------------------------------------------------------ | -| 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.| **Example** @@ -346,8 +345,7 @@ power.isScreenOn((err, data) => { isScreenOn(): Promise<boolean> -> NOTE
-> This API is deprecated since API version 9. You are advised to use [power.isActive](#powerisactive9) instead. +> **NOTE**
This API is deprecated since API version 9. You are advised to use [power.isActive](#powerisactive9). Checks the screen status of the current device. This API uses a promise to return the result. diff --git a/en/application-dev/reference/apis/js-apis-resource-manager.md b/en/application-dev/reference/apis/js-apis-resource-manager.md index 9f259f378ac523284d4aa17bce9742ec9b812636..7a300c063955c3c0b33b0f628e5e8147ea8416cc 100644 --- a/en/application-dev/reference/apis/js-apis-resource-manager.md +++ b/en/application-dev/reference/apis/js-apis-resource-manager.md @@ -1543,7 +1543,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco ``` -### closeRawFd8+ +### closeRawFd9+ closeRawFd(path: string): Promise<void> diff --git a/en/application-dev/reference/apis/js-apis-sim.md b/en/application-dev/reference/apis/js-apis-sim.md index 5c13c134789a04415e1bd7cf95d8954b22a342ae..15e1504a1647b47d6b3b46eb30cb148e8eb02d89 100644 --- a/en/application-dev/reference/apis/js-apis-sim.md +++ b/en/application-dev/reference/apis/js-apis-sim.md @@ -1,6 +1,6 @@ -# @ohos.telephony.sim (SIM) +# @ohos.telephony.sim (SIM Management) -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. >**NOTE** > diff --git a/en/application-dev/reference/apis/js-apis-system-brightness.md b/en/application-dev/reference/apis/js-apis-system-brightness.md index 94b06d824bdfc06d34796629d74fe2556a90946a..8053c8f0c73d190d33e547ff9f0227df5c6db06a 100644 --- a/en/application-dev/reference/apis/js-apis-system-brightness.md +++ b/en/application-dev/reference/apis/js-apis-system-brightness.md @@ -3,7 +3,8 @@ The **brightness** module provides APIs for querying and adjusting the screen brightness and mode. > **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. @@ -132,8 +133,7 @@ Sets the screen brightness adjustment mode. setKeepScreenOn(options?: SetKeepScreenOnOptions): void -> NOTE
-> 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()**. @@ -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.| | 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 @@ -179,21 +179,23 @@ Defines the options for setting the screen brightness. | Name | Type | Mandatory| Description | | -------- | ------------------------------------ | ---- | ------------------------------------------------------------ | | value | number | Yes | Screen brightness. The value is an integer ranging from **1** to **255**.
- If the value is less than or equal to **0**, value **1** will be used.
- If the value is greater than **255**, value **255** will be used.
- 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. | -| complete | () => void | No | Called when API call is complete. | +| complete | () => void | No | Called when the API call is complete. | ## BrightnessResponse Defines a response that returns the screen brightness. -| Parameter| Type | Readable | Writable | Description| +**System capability**: SystemCapability.PowerManager.DisplayPowerManager + +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| value | number | Yes | No | Screen brightness. The value ranges from 1 to 255.| +| value | number | Yes| No| Screen brightness. The value ranges from **1** to **255**.| ## GetBrightnessModeOptions -Gets the options of the screen brightness mode. +Defines the options for obtaining the screen brightness mode. **System capability**: SystemCapability.PowerManager.DisplayPowerManager @@ -201,38 +203,40 @@ Gets the options of the screen brightness mode. | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | 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. | -| complete | () => void | No | Called when API call is complete. | +| complete | () => void | No | Called when the API call is complete. | ## SetBrightnessModeOptions -Sets the options of the screen brightness mode. +Defines the options for setting the screen brightness mode. **System capability**: SystemCapability.PowerManager.DisplayPowerManager | Name | Type | Mandatory| Description | | -------- | ------------------------------------ | ---- | ------------------------------------------------------ | | 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.| -| complete | () => void | No | Called when API call is complete. | +| complete | () => void | No | Called when the API call is complete. | ## BrightnessModeResponse Defines a response that returns the screen brightness mode. -| Parameter| Type | Readable | Writable | Description| +**System capability**: SystemCapability.PowerManager.DisplayPowerManager + +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| mode | number | Yes | No | The value **0** indicates the manual adjustment mode, and the value **1** indicates the automatic adjustment mode.| +| mode | number | Yes| No| The value **0** indicates the manual adjustment mode, and the value **1** indicates the automatic adjustment mode.| ## SetKeepScreenOnOptions -Sets the options for keeping the screen steady on. +Defines the options for setting the screen to be steady on. **System capability**: SystemCapability.PowerManager.DisplayPowerManager | Name | Type | Mandatory| Description | | ------------ | ------------------------------------ | ---- | ------------------------------------------------------ | | 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.| -| complete | () => void | No | Called when API call is complete. | +| complete | () => void | No | Called when the API call is complete. | diff --git a/en/application-dev/reference/apis/js-apis-usb.md b/en/application-dev/reference/apis/js-apis-usb.md deleted file mode 100644 index 6ec6637ea6f7695da77e2e28ee9823785a84c20d..0000000000000000000000000000000000000000 --- a/en/application-dev/reference/apis/js-apis-usb.md +++ /dev/null @@ -1,948 +0,0 @@ -# @ohos.usbV9 (USB) - -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). - -## Modules to Import - -```js -import usb from "@ohos.usbV9"; -``` - -## usb.getDevices - -getDevices(): Array<Readonly<USBDevice>> - -Obtains the list of USB devices connected to the host. If no device is connected, an empty list is returned. - -**System capability**: SystemCapability.USB.USBManager - -**Return value** - -| Type | Description | -| ---------------------------------------------------- | ------- | -| Array<Readonly<[USBDevice](#usbdevice)>> | USB device list.| - -**Example** - -```js -let devicesList = usb.getDevices(); -console.log(`devicesList = ${devicesList}`); -// devicesList is a list of USB devices. -// A simple example of devicesList is provided as follows: -[ - { - name: "1-1", - serial: "", - manufacturerName: "", - productName: "", - version: "", - vendorId: 7531, - productId: 2, - clazz: 9, - subClass: 0, - protocol: 1, - devAddress: 1, - busNum: 1, - configs: [ - { - id: 1, - attributes: 224, - isRemoteWakeup: true, - isSelfPowered: true, - maxPower: 0, - name: "1-1", - interfaces: [ - { - id: 0, - protocol: 0, - clazz: 9, - subClass: 0, - alternateSetting: 0, - name: "1-1", - endpoints: [ - { - address: 129, - attributes: 3, - interval: 12, - maxPacketSize: 4, - direction: 128, - number: 1, - type: 3, - interfaceId: 0, - }, - ], - }, - ], - }, - ], - }, -] -``` - -## usb.connectDevice - -connectDevice(device: USBDevice): Readonly<USBDevicePipe> - -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. - -**System capability**: SystemCapability.USB.USBManager - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| 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 -let devicesList = usb.getDevices(); -if (devicesList.length == 0) { - console.log(`device list is empty`); -} - -let device = devicesList[0]; -usb.requestRight(device.name); -let devicepipe = 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. - -**System capability**: SystemCapability.USB.USBManager - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| deviceName | string | Yes| Device name.| - -**Return value** - -| Type| Description| -| -------- | -------- | -| boolean | Returns **true** if the application has the permission to access the device; returns **false** otherwise.| - -**Example** - -```js -let devicesName="1-1"; -let bool = usb.hasRight(devicesName); -console.log(bool); -``` - -## usb.requestRight - -requestRight(deviceName: string): Promise<boolean> - -Requests the temporary permission for the application to access a USB device. This API uses a promise to return the result. - -**System capability**: SystemCapability.USB.USBManager - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| deviceName | string | Yes| Device name.| - -**Return value** - -| Type| Description| -| -------- | -------- | -| 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 -let devicesName="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. - -**System capability**: SystemCapability.USB.USBManager - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| deviceName | string | Yes| Device name.| - -**Return value** - -| Type| Description| -| -------- | -------- | -| boolean | Permission removal result. The value **true** indicates that the access permission is removed successfully; and the value **false** indicates the opposite.| - -**Example** - -```js -let devicesName="1-1"; -if usb.removeRight(devicesName) { - console.log(`Succeed in removing right`); -} -``` - -## usb.addRight - -addRight(bundleName: string, deviceName: string): boolean - -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. - -**System API**: This is a system API. - -**System capability**: SystemCapability.USB.USBManager - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| deviceName | string | Yes| Device name.| -| 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 -let devicesName = "1-1"; -let bundleName = "com.example.hello"; -if usb.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. - -**System capability**: SystemCapability.USB.USBManager - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| 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 -let ret = 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). - -**System capability**: SystemCapability.USB.USBManager - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| 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 release.| - -**Return value** - -| Type| Description| -| -------- | -------- | -| number | Returns **0** if the USB interface is successfully released; returns an error code otherwise.| - -**Example** - -```js -let ret = usb.releaseInterface(devicepipe, interfaces); -console.log(`releaseInterface = ${ret}`); -``` - -## usb.setConfiguration - -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. - -**System capability**: SystemCapability.USB.USBManager - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| 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 -let ret = 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. - -**System capability**: SystemCapability.USB.USBManager - -**Parameters** - -| Name | Type | Mandatory | Description | -| ----- | ------------------------------- | --- | ------------- | -| 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 -let ret = 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. - -**System capability**: SystemCapability.USB.USBManager - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| 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 -let ret = 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. - -**System capability**: SystemCapability.USB.USBManager - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address.| - -**Return value** - -| Type | Description | -| ------ | -------------------- | -| number | Returns the file descriptor of the USB device if the operation is successful; returns **-1** otherwise.| - -**Example** - -```js -let ret = usb.getFileDescriptor(devicepipe); -``` - -## usb.controlTransfer - -controlTransfer(pipe: USBDevicePipe, controlparam: USBControlParams, timeout ?: number): Promise<number> - -Performs control 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. - -**System capability**: SystemCapability.USB.USBManager - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| 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.| - -**Example** - -```js -let param = new usb.USBControlParams(); -usb.controlTransfer(devicepipe, param).then((ret) => { - console.log(`controlTransfer = ${ret}`); -}) -``` - -## usb.bulkTransfer - -bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, timeout ?: number): Promise<number> - -Performs bulk transfer. - -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. - -**System capability**: SystemCapability.USB.USBManager - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| 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. -usb.bulkTransfer(devicepipe, endpoint, buffer).then((ret) => { - console.log(`bulkTransfer = ${ret}`); -}); -``` - -## usb.closePipe - -closePipe(pipe: USBDevicePipe): number - -Closes a USB device pipe. - -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. - -**System capability**: SystemCapability.USB.USBManager - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe.| - -**Return value** - -| Type| Description| -| -------- | -------- | -| number | Returns **0** if the USB device pipe is closed successfully; returns an error code otherwise.| - -**Example** - -```js -let ret = usb.closePipe(devicepipe); -console.log(`closePipe = ${ret}`); -``` - -## usb.usbFunctionsFromString - -usbFunctionsFromString(funcs: string): number - -Converts the USB function list in the string format to a numeric mask in Device mode. - -**System API**: This is a system API. - -**System capability**: SystemCapability.USB.USBManager - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ---------------------- | -| funcs | string | Yes | Function list in string format.| - -**Return value** - -| Type | Description | -| ------ | ------------------ | -| number | Function list in numeric mask format.| - -**Example** - -```js -let funcs = "acm"; -let ret = usb.usbFunctionsFromString(funcs); -``` - -## usb.usbFunctionsToString - -usbFunctionsToString(funcs: FunctionType): string - -Converts the USB function list in the numeric mask format to a string in Device mode. - -**System API**: This is a system API. - -**System capability**: SystemCapability.USB.USBManager - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------------------------------ | ---- | ----------------- | -| funcs | [FunctionType](#functiontype) | Yes | USB function list in numeric mask format.| - -**Return value** - -| Type | Description | -| ------ | ------------------------------ | -| string | Function list in string format.| - -**Example** - -```js -let funcs = usb.ACM | usb.ECM; -let ret = usb.usbFunctionsToString(funcs); -``` - -## usb.setCurrentFunctions - -setCurrentFunctions(funcs: FunctionType): Promise\ - -Sets the current USB function list in Device mode. - -**System API**: This is a system API. - -**System capability**: SystemCapability.USB.USBManager - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------------------------------ | ---- | ----------------- | -| funcs | [FunctionType](#functiontype) | Yes | USB function list in numeric mask format.| - -**Return value** - -| Type | Description | -| ------------------ | ------------------------------------------------------------ | -| Promise\ | Promise used to return the result. The value **true** indicates that the operation is successful, and the value **false** indicates the opposite.| - -**Example** - -```js -let funcs = usb.HDC; -let ret = usb.setCurrentFunctions(funcs); -``` - -## usb.getCurrentFunctions - -getCurrentFunctions(): FunctionType - -Obtains the numeric mask combination for the USB function list in Device mode. - -**System API**: This is a system API. - -**System capability**: SystemCapability.USB.USBManager - -**Return value** - -| Type | Description | -| ------------------------------ | --------------------------------- | -| [FunctionType](#functiontype) | Numeric mask combination for the USB function list.| - -**Example** - -```js -let ret = usb.getCurrentFunctions(); -``` - -## usb.getPorts - -getPorts(): Array\ - -Obtains the list of all physical USB ports. - -**System API**: This is a system API. - -**System capability**: SystemCapability.USB.USBManager - -**Return value** - -| Type | Description | -| ----------------------------- | --------------------- | -| [Array\](#usbport) | List of physical USB ports.| - -**Example** - -```js -let ret = usb.getPorts(); -``` - -## usb.getSupportedModes - -getSupportedModes(portId: number): PortModeType - -Obtains the mask combination for the supported mode list of a given USB port. - -**System API**: This is a system API. - -**System capability**: SystemCapability.USB.USBManager - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | -------- | -| portId | number | Yes | Port number.| - -**Return value** - -| Type | Description | -| ------------------------------ | -------------------------- | -| [PortModeType](#portmodetype) | Mask combination for the supported mode list.| - -**Example** - -```js -let ret = usb.getSupportedModes(0); -``` - -## usb.setPortRoles - -setPortRoles(portId: number, powerRole: PowerRoleType, dataRole: DataRoleType): Promise\ - -Sets the role types supported by a specified port, which can be **powerRole** (for charging) and **dataRole** (for data transfer). - -**System API**: This is a system API. - -**System capability**: SystemCapability.USB.USBManager - -**Parameters** - -| Name | Type | Mandatory| Description | -| --------- | -------------------------------- | ---- | ---------------- | -| portId | number | Yes | Port number. | -| powerRole | [PowerRoleType](#powerroletype) | Yes | Role for charging. | -| dataRole | [DataRoleType](#dataroletype) | Yes | Role for data transfer.| - -**Return value** - -| Type | Description | -| ------------------ | ------------------------------------------------------------ | -| Promise\ | Promise used to return the result. The value **true** indicates that the operation is successful, and the value **false** indicates the opposite.| - -**Example** - -```js -let portId = 1; -usb.setPortRoles(portId, usb.PowerRoleType.SOURCE, usb.DataRoleType.HOST).then(() => { - console.info('usb setPortRoles successfully.'); -}).catch(err => { - console.error('usb setPortRoles failed: ' + err.code + ' message: ' + err.message); -}); -``` - -## USBEndpoint - -Represents the USB endpoint from which data is sent or received. You can obtain the USB endpoint through [USBInterface](#usbinterface). - -**System capability**: SystemCapability.USB.USBManager - -| Name | Type | Mandatory |Description | -| ------------- | ------------------------------------------- | ------------- |------------- | -| address | number | Yes|Endpoint address. | -| attributes | number | Yes|Endpoint attributes. | -| interval | number | Yes|Endpoint interval. | -| maxPacketSize | number | Yes|Maximum size of data packets on the endpoint. | -| direction | [USBRequestDirection](#usbrequestdirection) | Yes|Endpoint direction. | -| number | number | Yes|Endpoint number. | -| type | number | Yes|Endpoint type. | -| interfaceId | number | Yes|Unique ID of the interface to which the endpoint belongs.| - -## USBInterface - -Represents a USB interface. One [USBConfig](#usbconfig) can contain multiple **USBInterface** instances, each providing a specific function. - -**System capability**: SystemCapability.USB.USBManager - -| Name | Type | Mandatory |Description | -| ---------------- | ---------------------------------------- | ------------- |--------------------- | -| id | number | Yes|Unique ID of the USB interface. | -| protocol | number | Yes|Interface protocol. | -| clazz | number | Yes|Device type. | -| subClass | number | Yes|Device subclass. | -| alternateSetting | number | Yes|Settings for alternating between descriptors of the same USB interface.| -| name | string | Yes|Interface name. | -| endpoints | Array<[USBEndpoint](#usbendpoint)> | Yes|Endpoints that belong to the USB interface. | - -## USBConfig - -Represents the USB configuration. One [USBDevice](#usbdevice) can contain multiple **USBConfig** instances. - -**System capability**: SystemCapability.USB.USBManager - -| Name | Type | Mandatory |Description | -| -------------- | ------------------------------------------------ | --------------- |--------------- | -| id | number | Yes|Unique ID of the USB configuration. | -| attributes | number | Yes|Configuration attributes. | -| maxPower | number | Yes|Maximum power consumption, in mA. | -| name | string | Yes|Configuration name, which can be left empty. | -| isRemoteWakeup | boolean | Yes|Support for remote wakeup.| -| isSelfPowered | boolean | Yes| Support for independent power supplies.| -| interfaces | Array <[USBInterface](#usbinterface)> | Yes|Supported interface attributes. | - -## USBDevice - -Represents the USB device information. - -**System capability**: SystemCapability.USB.USBManager - -| Name | Type | Mandatory |Description | -| ---------------- | ------------------------------------ | ---------- |---------- | -| busNum | number | Yes|Bus address. | -| devAddress | number | Yes|Device address. | -| serial | string | Yes|Sequence number. | -| name | string | Yes|Device name. | -| manufacturerName | string | Yes| Device manufacturer. | -| productName | string | Yes|Product name. | -| version | string | Yes|Version number. | -| vendorId | number | Yes|Vendor ID. | -| productId | number | Yes|Product ID. | -| clazz | number | Yes|Device class. | -| subClass | number | Yes|Device subclass. | -| protocol | number | Yes|Device protocol code. | -| configs | Array<[USBConfig](#usbconfig)> | Yes|Device configuration descriptor information.| - -## USBDevicePipe - -Represents a USB device pipe, which is used to determine a USB device. - -**System capability**: SystemCapability.USB.USBManager - -| Name | Type | Mandatory |Description | -| ---------- | ------ | ----- |----- | -| busNum | number |Yes| Bus address.| -| devAddress | number |Yes| Device address.| - -## USBControlParams - -Represents control transfer parameters. - -**System capability**: SystemCapability.USB.USBManager - -| Name | Type | Mandatory |Description | -| ------- | ----------------------------------------------- | ---------------- |---------------- | -| request | number | Yes |Request type. | -| target | [USBRequestTargetType](#usbrequesttargettype) | Yes |Request target type. | -| reqType | [USBControlRequestType](#usbcontrolrequesttype) | Yes |Control request type. | -| value | number | Yes |Request parameter value. | -| index | number | Yes |Index of the request parameter value.| -| data | Uint8Array | Yes |Buffer for writing or reading data. | - -## USBPort - -Represents a USB port. - -**System API**: This is a system API. - -**System capability**: SystemCapability.USB.USBManager - -| Name | Type | Mandatory |Description | -| -------------- | ------------------------------- | ------------------- |------------------------ | -| id | number | Yes |Unique identifier of a USB port. | -| supportedModes | [PortModeType](#portmodetype) | Yes |Numeric mask combination for the supported mode list.| -| status | [USBPortStatus](#usbportstatus) | Yes |USB port role. | - -## USBPortStatus - -Enumerates USB port roles. - -**System API**: This is a system API. - -**System capability**: SystemCapability.USB.USBManager - -| Name | Type| Mandatory |Description | -| ---------------- | -------- | ---------------- |---------------------- | -| currentMode | number | Yes|Current USB mode. | -| currentPowerRole | number | Yes |Current power role. | -| currentDataRole | number | Yes |Current data role.| - -## USBRequestTargetType - -Enumerates request target types. - -**System capability**: SystemCapability.USB.USBManager - -| Name | Value | Description | -| ---------------------------- | ---- | ------ | -| USB_REQUEST_TARGET_DEVICE | 0 | Device| -| USB_REQUEST_TARGET_INTERFACE | 1 | Interface| -| USB_REQUEST_TARGET_ENDPOINT | 2 | Endpoint| -| USB_REQUEST_TARGET_OTHER | 3 | Other| - -## USBControlRequestType - -Enumerates control request types. - -**System capability**: SystemCapability.USB.USBManager - -| Name | Value | Description | -| ------------------------- | ---- | ------ | -| USB_REQUEST_TYPE_STANDARD | 0 | Standard| -| USB_REQUEST_TYPE_CLASS | 1 | Class | -| USB_REQUEST_TYPE_VENDOR | 2 | Vendor| - -## USBRequestDirection - -Enumerates request directions. - -**System capability**: SystemCapability.USB.USBManager - -| Name | Value | Description | -| --------------------------- | ---- | ------------------------ | -| USB_REQUEST_DIR_TO_DEVICE | 0 | Request for writing data from the host to the device.| -| USB_REQUEST_DIR_FROM_DEVICE | 0x80 | Request for reading data from the device to the host.| - -## FunctionType - -Enumerates USB device function types. - -**System API**: This is a system API. - -**System capability**: SystemCapability.USB.USBManager - -| Name | Value | Description | -| ------------ | ---- | ---------- | -| NONE | 0 | No function.| -| ACM | 1 | ACM function. | -| ECM | 2 | ECM function. | -| HDC | 4 | HDC function. | -| MTP | 8 | Not supported currently.| -| PTP | 16 | Not supported currently.| -| RNDIS | 32 | Not supported currently.| -| MIDI | 64 | Not supported currently.| -| AUDIO_SOURCE | 128 | Not supported currently.| -| NCM | 256 | Not supported currently.| - -## PortModeType - -Enumerates USB port mode types. - -**System API**: This is a system API. - -**System capability**: SystemCapability.USB.USBManager - -| Name | Value | Description | -| --------- | ---- | ---------------------------------------------------- | -| NONE | 0 | None. | -| UFP | 1 | Upstream facing port, which functions as the sink of power supply. | -| DFP | 2 | Downstream facing port, which functions as the source of power supply. | -| DRP | 3 | Dynamic reconfiguration port (DRP), which can function as the DFP (host) or UFP (device). It is not supported currently.| -| NUM_MODES | 4 | Not supported currently. | - -## PowerRoleType - -Enumerates power role types. - -**System API**: This is a system API. - -**System capability**: SystemCapability.USB.USBManager - -| Name | Value | Description | -| ------ | ---- | ---------- | -| NONE | 0 | None. | -| SOURCE | 1 | External power supply.| -| SINK | 2 | Internal power supply.| - -## DataRoleType - -Enumerates data role types. - -**System API**: This is a system API. - -**System capability**: SystemCapability.USB.USBManager - -| Name | Value | Description | -| ------ | ---- | ------------ | -| NONE | 0 | None. | -| HOST | 1 | USB host.| -| DEVICE | 2 | USB device.| diff --git a/en/device-dev/get-code/sourcecode-acquire.md b/en/device-dev/get-code/sourcecode-acquire.md index a0b3092138741214444a518d9e668fd65cce0085..61b63e1f9f5824530c630fa641cba0d1f75ba85d 100644 --- a/en/device-dev/get-code/sourcecode-acquire.md +++ b/en/device-dev/get-code/sourcecode-acquire.md @@ -182,12 +182,12 @@ The table below provides only the sites for downloading the latest OpenHarmony L | Hi3516 solution-Linux (binary)| 3.0 | [Download](https://repo.huaweicloud.com/openharmony/os/3.0/hispark_taurus_linux.tar.gz)| [Download](https://repo.huaweicloud.com/openharmony/os/3.0/hispark_taurus_linux.tar.gz.sha256) | 418.1 MB | | RELEASE-NOTES | 3.0 | [Download](https://gitee.com/openharmony/docs/blob/OpenHarmony-3.0-LTS/en/release-notes/OpenHarmony-v3.0-LTS.md)| - | - | | **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 | -| 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 | -| Hi3861 solution (binary)| 3.2 Beta4 | [Download](https://repo.huaweicloud.com/harmonyos/os/3.2-Beta4/hispark_pegasus.tar.gz) | [Download](https://repo.huaweicloud.com/harmonyos/os/3.2-Beta4/hispark_pegasus.tar.gz.sha256) | 22.6 MB | -| Hi3516 solution-LiteOS (binary)| 3.2 Beta4 | [Download](https://repo.huaweicloud.com/harmonyos/os/3.2-Beta4/hispark_taurus_LiteOS.tar.gz)| [Download](https://repo.huaweicloud.com/harmonyos/os/3.2-Beta4/hispark_taurus_LiteOS.tar.gz.sha256)| 293.9 MB | -| Hi3516 solution-Linux (binary)| 3.2 Beta4 | [Download](https://repo.huaweicloud.com/harmonyos/os/3.2-Beta4/hispark_taurus_Linux.tar.gz)| [Download](https://repo.huaweicloud.com/harmonyos/os/3.2-Beta4/hispark_taurus_Linux.tar.gz.sha256)| 173.2 MB | -| RELEASE-NOTES | 3.2 Beta4 | [Download](../../release-notes/OpenHarmony-v3.2-beta4.md)| - | - | +| 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 | +| Hi3861 solution (binary) | 3.2 Release| [Download](https://repo.huaweicloud.com/harmonyos/os/3.2-Release/hispark_pegasus.tar.gz)| [Download](https://repo.huaweicloud.com/harmonyos/os/3.2-Release/hispark_pegasus.tar.gz.sha256)| 22.9 MB | +| Hi3516 solution-LiteOS (binary)| 3.2 Release| [Download](https://repo.huaweicloud.com/openharmony/os/3.2-Release/hispark_taurus_LiteOS.tar.gz)| [Download](https://repo.huaweicloud.com/openharmony/os/3.2-Release/hispark_taurus_LiteOS.tar.gz.sha256)| 294.3 MB | +| Hi3516 solution-Linux (binary) | 3.2 Release| [Download](https://repo.huaweicloud.com/openharmony/os/3.2-Release/hispark_taurus_Linux.tar.gz)| [Download](https://repo.huaweicloud.com/openharmony/os/3.2-Release/hispark_taurus_Linux.tar.gz.sha256)| 174.3 MB | +| RK3568 standard system solution (binary) | 3.2 Release| [Download](https://repo.huaweicloud.com/harmonyos/os/3.2-Release//dayu200_standard_arm32.tar.gz)| [Download](https://repo.huaweicloud.com/harmonyos/os/3.2-Release//dayu200_standard_arm32.tar.gz.sha256)| 3.9 GB | +| RELEASE-NOTES | 3.2 Release| [Download](../../release-notes/OpenHarmony-v3.2-release.md)| - | - | | **Compiler Toolchain**| **Version**| **Site**| **SHA-256 Checksum**| **Software Package Size**| | Compiler toolchain| - | [Download](https://repo.huaweicloud.com/openharmony/os/2.0/tool_chain/)| - | - | diff --git a/en/device-dev/subsystems/Readme-EN.md b/en/device-dev/subsystems/Readme-EN.md index 81fb9648c011a9591bfa6616e4a24950bcc34669..143f21ed1f8033676f1a3513a7176f0217b0e170 100644 --- a/en/device-dev/subsystems/Readme-EN.md +++ b/en/device-dev/subsystems/Readme-EN.md @@ -41,7 +41,9 @@ - [Utils Overview](subsys-utils-overview.md) - [Utils Development](subsys-utils-guide.md) - [Utils FAQ](subsys-utils-faqs.md) -- [AI Framework Development](subsys-ai-aiframework-devguide.md) +- AI + - [AI Framework Development](subsys-ai-aiframework-devguide.md) + - [NNRt Development](subsys-ai-nnrt-guide.md) - Data Management - RDB - [RDB Overview](subsys-data-relational-database-overview.md) diff --git a/en/device-dev/subsystems/figures/nnrt_arch_diagram.png b/en/device-dev/subsystems/figures/nnrt_arch_diagram.png new file mode 100644 index 0000000000000000000000000000000000000000..8a4a218f519c5707fbb2d5724b6c1a731d76f911 Binary files /dev/null and b/en/device-dev/subsystems/figures/nnrt_arch_diagram.png differ diff --git a/en/device-dev/subsystems/figures/nnrt_dev_flow.png b/en/device-dev/subsystems/figures/nnrt_dev_flow.png new file mode 100644 index 0000000000000000000000000000000000000000..612ae5fe5abfb3df5936c314672cf1877ee5404d Binary files /dev/null and b/en/device-dev/subsystems/figures/nnrt_dev_flow.png differ diff --git a/en/device-dev/subsystems/subsys-ai-nnrt-guide.md b/en/device-dev/subsystems/subsys-ai-nnrt-guide.md new file mode 100644 index 0000000000000000000000000000000000000000..63980a887c9f0ca5d45cd99f96808cf435c8d012 --- /dev/null +++ b/en/device-dev/subsystems/subsys-ai-nnrt-guide.md @@ -0,0 +1,404 @@ +# NNRt Development + +## Overview + +### Function Introduction + +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. + +**Figure 1** NNRt architecture + +![NNRt architecture](./figures/nnrt_arch_diagram.png) + +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**
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 + +![NNRt development flowchart](./figures/nnrt_dev_flow.png) + +### 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). + +2. Build the IDL file of the HDI. + ```shell + ./build.sh --product-name productname –ccache --build-target drivers_interface_nnrt + ``` + > **NOTE**
**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: + ```text + out/rk3568/gen/drivers/interface/nnrt + └── v1_0 + ├── drivers_interface_nnrt__libnnrt_proxy_1.0_external_deps_temp.json + ├── drivers_interface_nnrt__libnnrt_stub_1.0_external_deps_temp.json + ├── innrt_device.h # Header file of the HDI + ├── 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). + + ```shell + import("//build/ohos.gni") + import("//drivers/hdf_core/adapter/uhdf2/uhdf.gni") + + ohos_shared_library("libnnrt_service_1.0") { + include_dirs = [] + sources = [ + "src/nnrt_device_service.cpp", + "src/prepared_model_service.cpp", + "src/node_registry.cpp", + "src/node_functions.cpp", + "src/node_attr_types.cpp" + ] + public_deps = [ "//drivers/interface/nnrt/v1_0:nnrt_idl_headers" ] + external_deps = [ + "hdf_core:libhdf_utils", + "hiviewdfx_hilog_native:libhilog", + "ipc:ipc_single", + "c_utils:utils", + ] + + install_images = [ chipset_base_dir ] + subsystem_name = "hdf" + part_name = "drivers_peripheral_nnrt" + } + + ohos_shared_library("libnnrt_driver") { + include_dirs = [] + sources = [ "src/nnr_device_driver.cpp" ] + deps = [ "//drivers/peripheral/nnrt/hdi_cpu_service:libnnrt_service_1.0" ] + + external_deps = [ + "hdf_core:libhdf_host", + "hdf_core:libhdf_ipc_adapter", + "hdf_core:libhdf_utils", + "hiviewdfx_hilog_native:libhilog", + "ipc:ipc_single", + "c_utils:utils", + ] + + install_images = [ chipset_base_dir ] + subsystem_name = "hdf" + part_name = "drivers_peripheral_nnrt" + } + + group("hdf_nnrt_service") { + deps = [ + ":libnnrt_driver", + ":libnnrt_service_1.0", + ] + } + ``` + + Add `group("hdf_nnrt_service")` to the `drivers/peripheral/nnrt/BUILD.gn` file so that it can be referenced at a higher directory level. + ```shell + if (defined(ohos_lite)) { + group("nnrt_entry") { + deps = [ ] + } + } else { + group("nnrt_entry") { + deps = [ + "./hdi_cpu_service:hdf_nnrt_service", + ] + } + } + ``` + + Create the `drivers/peripheral/nnrt/bundle.json` file to define the new `drivers_peripheral_nnrt` component. + ```json + { + "name": "drivers_peripheral_nnrt", + "description": "Neural network runtime device driver", + "version": "3.2", + "license": "Apache License 2.0", + "component": { + "name": "drivers_peripheral_nnrt", + "subsystem": "hdf", + "syscap": [""], + "adapter_system_type": ["standard"], + "rom": "1024KB", + "ram": "2048KB", + "deps": { + "components": [ + "ipc", + "hdf_core", + "hiviewdfx_hilog_native", + "c_utils" + ], + "third_part": [ + "bounds_checking_function" + ] + }, + "build": { + "sub_component": [ + "//drivers/peripheral/nnrt:nnrt_entry" + ], + "test": [ + ], + "inner_kits": [ + ] + } + } + } + ``` + +#### Declaring the HDI Service + + 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**
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). + ```shell + hdc_std shell + dmesg | grep nnrt + ``` + +3. Create the `nnrt_host.te` file. + ```shell + # Create the nnrt folder. + mkdir base/security/selinux/sepolicy/ohos_policy/drivers/peripheral/nnrt + + # Create the vendor folder. + mkdir base/security/selinux/sepolicy/ohos_policy/drivers/peripheral/nnrt/vendor + + # Create the nnrt_host.te file. + touch base/security/selinux/sepolicy/ohos_policy/drivers/peripheral/nnrt/vendor/nnrt_host.te + ``` + +4. Add the required permissions to the `nnrt_host.te` file. For example: + ```text + allow nnrt_host dev_hdf_kevent:chr_file { ioctl }; + allow nnrt_host hilog_param:file { read }; + allow nnrt_host sh:binder { transfer }; + allow nnrt_host dev_ashmem_file:chr_file { open }; + allow sh nnrt_host:fd { use }; + ``` + +#### Configuring the Component Build Entry +Access the `chipset_common.json` file. +```shell +vim //productdefine/common/inherit/chipset_common.json +``` +Add the following to `"subsystems"`, `"subsystem":"hdf"`, `"components"`: +```shell +{ + "component": "drivers_peripheral_foo", + "features": [] +} +``` + +#### Deleting the out Directory and Building the Entire System +```shell +# Delete the out directory. +rm -rf ./out + +# Build the entire system. +./build.sh --product-name rk3568 –ccache --jobs=4 +``` + + +### Commissioning and Verification +On completion of service development, you can use XTS to verify its basic functions and compatibility. + +1. Build the **hats** test cases of NNRt in the `test/xts/hats/hdf/nnrt` directory. + ```shell + # Go to the hats directory. + cd test/xts/hats + + # Build the hats test cases. + ./build.sh suite=hats system_size=standard --product-name rk3568 + + # Return to the root directory. + cd - + ``` + The hats test cases are exported to `out/rk3568/suites/hats/testcases/HatsHdfNnrtFunctionTest` in the relative code root directory. + +2. Push the test cases to the device. + ```shell + # Push the executable file of test cases to the device. In this example, the executable file is HatsHdfNnrtFunctionTest. + hdc_std file send out/rk3568/suites/hats/testcases/HartsHdfNnrtFunctionTest /data/local/tmp/ + + # Grant required permissions to the executable file of test cases. + hdc_std shell "chmod +x /data/local/tmp/HatsHdfNnrtFunctionTest" + ``` + +3. Execute the test cases and view the result. + ```shell + # Execute the test cases. + hdc_std shell "/data/local/tmp/HatsHdfNnrtFunctionTest" + ``` + + 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. + ```shell + # Create the mindspore_schema directory. + mkdir drivers/peripheral/nnrt/hdi_cpu_service/include/mindspore_schema + + # Copy the schema file of MindSpore Lite. + cp third_party/mindspore/mindspore/lite/schema/* drivers/peripheral/nnrt/hdi_cpu_service/include/mindspore_schema/ + ``` + - Build the dynamic library of MindSpore Lite, and put the dynamic library in the `mindspore`directory. + ```shell + # Build the dynamic library of MindSpore Lite. + ./build.sh --product-name rk3568 -ccaache --jobs 4 --build-target mindspore_lib + + # Create the mindspore subdirectory. + mkdir drivers/peripheral/nnrt/mindspore/mindspore + + # Copy the dynamic library to drivers/peripheral/nnrt/mindspore/mindspore. + cp out/rk3568/package/phone/system/lib/libmindspore-lite.huawei.so drivers/peripheral/nnrt/mindspore/mindspore/ + ``` +4. Follow the [development procedure](#development-procedure) to complete other configurations. diff --git a/en/device-dev/website.md b/en/device-dev/website.md index 0880175f99c9a1a61b30f2ce181358ae22284c92..b0a4b5f6c9a94cec2aa8ae2158da36ef73218d7b 100644 --- a/en/device-dev/website.md +++ b/en/device-dev/website.md @@ -415,7 +415,9 @@ - [Utils Overview](subsystems/subsys-utils-overview.md) - [Utils Development](subsystems/subsys-utils-guide.md) - [Utils FAQ](subsystems/subsys-utils-faqs.md) - - [AI Framework Development](subsystems/subsys-ai-aiframework-devguide.md) + - AI + - [AI Framework Development](subsys-ai-aiframework-devguide.md) + - [NNRt Development](subsys-ai-nnrt-guide.md) - Data Management - RDB - [RDB Overview](subsystems/subsys-data-relational-database-overview.md)