!21347 [翻译完成】PR21132

Merge pull request !21347 from Annie_wang/PR21132

en/application-dev/device/Readme-EN.md

@@ -19,3 +19,5 @@
   - [Sample Server Development](sample-server-guidelines.md)
 - Stationary
   - [Stationary Development](stationary-guidelines.md)
+- Peripheral
+  - [Peripheral Management Development](externaldevice-guidelines.md)

en/application-dev/device/externaldevice-guidelines.md

+# Peripheral Management Development
+
+
+## When to Use
+
+Peripheral devices (or simply peripherals) are auxiliary devices connected to a device through physical ports, such as handwriting tablets, printers, and scanners. Applications can query and bind peripherals by using the peripheral management capabilities, so that the device can use the customized capabilities provided by the peripheral drivers, such as the printer software.
+
+
+## Available APIs
+
+The following table lists the open capabilities of peripheral management. For more information, see [Peripheral Management](../reference/apis/js-apis-driver-deviceManager.md).
+
+**Table 1** Open APIs for peripheral management
+
+| API                                                                                                                                                     | Description                                                                                   |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| queryDevices(busType?: number): Array<Readonly<Device>>                                                                                         | Queries the peripheral list.                                                                       |
+| bindDevice(deviceId: number, onDisconnect: AsyncCallback<number>, callback: AsyncCallback<{deviceId: number, remote: rpc.IRemoteObject}>): void | Binds a peripheral device. This API uses an asynchronous callback to return the result. If the peripheral device is bound, the **IRemoteObject** of the device driver is returned for subsequent interaction with the device driver.|
+| bindDevice(deviceId: number, onDisconnect: AsyncCallback<number>): Promise<{deviceId: number, remote: rpc.IRemoteObject}>                       | Binds a peripheral device. This API uses a promise to return the result.                                                                 |
+| unbindDevice(deviceId: number, callback: AsyncCallback<number>): void                                                                                 | Unbinds a peripheral device. This API uses an asynchronous callback to return the result.                                                                             |
+| unbindDevice(deviceId: number): Promise<number>                                                                                                       | Unbinds a peripheral device. This API uses a promise to return the result.                                                                             |
+
+
+## How to Develop
+
+You can use the APIs to query and bind peripheral devices so as to use the customized driver capabilities of the peripherals. The development procedure is as follows:
+
+
+1. Query the peripheral device list.
+
+  ```js
+  var matchDevice;
+  try {
+    let devices = deviceManager.queryDevices(deviceManager.BusType.USB);
+    for (let item of devices) {
+      let device = item as deviceManager.USBDevice;
+      // Match the USB device based on productId and vendorId.
+      if (device.productId == 1234 && device.vendorId === 2345) {
+        matchDevice = device;
+        break;
+      }
+    }
+  } catch (error) {
+    console.error('Failed to query device. Code is ${error.code}, message is ${error.message}');
+  }
+  if (!matchDevice) {
+    console.error('No match device');
+    return;
+  }
+  ```
+
+2. Bind a peripheral device.
+
+  ```js
+  var remoteObject;
+  try {
+    deviceManager.bindDevice(matchDevice.deviceId, (error, data) => {
+      console.error('Device is disconnected');
+    }, (error, data) => {
+      if (error) {
+        console.error('bindDevice async fail. Code is ${error.code}, message is ${error.message}');
+        return;
+      }
+      console.info('bindDevice success');
+      remoteObject = data.remote;
+    });
+  } catch (error) {
+    console.error('bindDevice fail. Code is ${error.code}, message is ${error.message}');
+  }
+  ```
+
+3. Use the capabilities provided by the peripheral device driver.
+
+  ```js
+  let option = new rpc.MessageOption();
+  let data = rpc.MessageSequence.create();
+  let repy = rpc.MessageSequence.create();
+  data.writeString('hello');
+  let code = 1;
+  // The code and data content varies depending on the interface provided by the driver.
+  remoteObject.sendMessageRequest(code, data, reply, option)
+    .then(result => {
+      console.info('sendMessageRequest finish.');
+    }).catch(error => {
+      console.error('sendMessageRequest fail. code:' + error.code);
+    });
+  ```
+
+4. Unbind the peripheral device after the device is used.
+
+  ```js
+  try {
+    deviceManager.unbindDevice(matchDevice.deviceId, (error, data) => {
+      if (error) {
+        console.error('unbindDevice async fail. Code is ${error.code}, message is ${error.message}');
+        return;
+      }
+      console.info('unbindDevice success');
+    });
+  } catch (error) {
+    console.error('unbindDevice fail. Code is ${error.code}, message is ${error.message}');
+  }
+  ```

en/application-dev/reference/apis/js-apis-driver-deviceManager.md

+# @ohos.driver.deviceManager (Peripheral Management)
+
+The **deviceManager** module provides APIs for managing peripheral devices, including querying the peripheral device list and binding or unbinding a peripheral device.
+
+>  **NOTE**
+> 
+> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
+
+## Modules to Import
+
+```js
+import deviceManager from "@ohos.driver.deviceManager";
+```
+
+## deviceManager.queryDevices
+
+queryDevices(busType?: number): Array<Readonly<Device>>
+
+Queries the list of peripheral devices. If the device has no peripheral device connected, an empty list is returned.
+
+**System capability**: SystemCapability.Driver.ExternalDevice
+
+**Parameters**
+
+| Name | Type  | Mandatory| Description                                |
+| ------- | ------ | ---- | ------------------------------------ |
+| busType | number | No  | Bus type of the peripheral device. If this parameter is left blank, all types of peripheral devices are queried.|
+
+**Return value**
+
+| Type                                          | Description          |
+| ---------------------------------------------- | -------------- |
+| Array<Readonly<[Device](#device)>> | List of peripheral devices obtained.|
+
+**Error codes**
+
+| ID| Error Message                                |
+| -------- | ---------------------------------------- |
+| 401      | The parameter check failed.              |
+| 22900001 | ExternalDeviceManager service exception. |
+
+**Example**
+
+```js
+try {
+  let devices = deviceManager.queryDevices(deviceManager.BusType.USB);
+  for (let item of devices) {
+    console.info('Device id is ${item.deviceId}')
+  }
+} catch (error) {
+  console.error('Failed to query device. Code is ${error.code}, message is ${error.message}');
+}
+```
+
+## deviceManager.bindDevice
+
+bindDevice(deviceId: number, onDisconnect: AsyncCallback<number>,
+  callback: AsyncCallback<{deviceId: number, remote: rpc.IRemoteObject}>): void;
+
+Binds a peripheral device based on the device information returned by **queryDevices()**. This API uses an asynchronous callback to return the result.
+
+You need to use [deviceManager.queryDevices](#devicemanagerquerydevices) to obtain the peripheral device information first.
+
+**System capability**: SystemCapability.Driver.ExternalDevice
+
+**Parameters**
+
+| Name      | Type                                                                                                | Mandatory| Description                                  |
+| ------------ | ---------------------------------------------------------------------------------------------------- | ---- | -------------------------------------- |
+| deviceId     | number                                                                                               | Yes  | ID of the device to bind. It can be obtained by **queryDevices()**.          |
+| onDisconnect | AsyncCallback<number>                                                                          | Yes  | Callback to be invoked when the bound peripheral device is disconnected.                    |
+| callback     | AsyncCallback<{deviceId: number, remote: [rpc.IRemoteObject](./js-apis-rpc.md#iremoteobject)}> | Yes  | Callback invoked to return the communication object of the peripheral device bound.|
+
+**Error codes**
+
+| ID| Error Message                                |
+| -------- | ---------------------------------------- |
+| 401      | The parameter check failed.              |
+| 22900001 | ExternalDeviceManager service exception. |
+
+**Example**
+
+```js
+try {
+  deviceManager.bindDevice(device.deviceId, (error, data) => {
+    console.error('Device is disconnected');
+  }, (error, data) => {
+    if (error) {
+      console.error('bindDevice async fail. Code is ${error.code}, message is ${error.message}');
+      return;
+    }
+    console.info('bindDevice success');
+  });
+} catch (error) {
+  console.error('bindDevice fail. Code is ${error.code}, message is ${error.message}');
+}
+```
+
+## deviceManager.bindDevice
+
+bindDevice(deviceId: number, onDisconnect: AsyncCallback<number>): Promise<{deviceId: number,
+  remote: rpc.IRemoteObject}>;
+
+Binds a peripheral device based on the device information returned by **queryDevices()**. This API uses a promise to return the result.
+
+You need to use [deviceManager.queryDevices](#devicemanagerquerydevices) to obtain the peripheral device information first.
+
+**System capability**: SystemCapability.Driver.ExternalDevice
+
+**Parameters**
+
+| Name      | Type                       | Mandatory| Description                        |
+| ------------ | --------------------------- | ---- | ---------------------------- |
+| deviceId     | number                      | Yes  | ID of the device to bind. It can be obtained by **queryDevices()**.|
+| onDisconnect | AsyncCallback<number> | Yes  | Callback to be invoked when the bound peripheral device is disconnected.          |
+
+**Return value**
+
+| Type                                                                                          | Description                                        |
+| ---------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| Promise<{deviceId: number, remote: [rpc.IRemoteObject](./js-apis-rpc.md#iremoteobject)}> | Promise used to return the device ID and **IRemoteObject** object.|
+
+**Error codes**
+
+| ID| Error Message                                |
+| -------- | ---------------------------------------- |
+| 401      | The parameter check failed.              |
+| 22900001 | ExternalDeviceManager service exception. |
+
+**Example**
+
+```js
+try {
+  deviceManager.bindDevice(matchDevice.deviceId, (error, data) => {
+    console.error('Device is disconnected');
+  }).then(data => {
+    console.info('bindDevice success');
+  }, error => {
+    console.error('bindDevice async fail. Code is ${error.code}, message is ${error.message}');
+  });
+} catch (error) {
+  console.error('bindDevice fail. Code is ${error.code}, message is ${error.message}');
+}
+```
+
+## deviceManager.unbindDevice
+
+unbindDevice(deviceId: number, callback: AsyncCallback<number>): void
+
+Unbinds a peripheral device. This API uses an asynchronous callback to return the result.
+
+**System capability**: SystemCapability.Driver.ExternalDevice
+
+**Parameters**
+
+| Name  | Type                       | Mandatory| Description                          |
+| -------- | --------------------------- | ---- | ------------------------------ |
+| deviceId | number                      | Yes  | ID of the device to unbind. It can be obtained by **queryDevices()**.|
+| callback | AsyncCallback<number> | Yes  | Callback invoked to return the result.              |
+
+**Error codes**
+
+| ID| Error Message                                |
+| -------- | ---------------------------------------- |
+| 401      | The parameter check failed.              |
+| 22900001 | ExternalDeviceManager service exception. |
+
+**Example**
+
+```js
+try {
+  deviceManager.unbindDevice(matchDevice.deviceId, (error, data) => {
+  if (error) {
+    console.error('unbindDevice async fail. Code is ${error.code}, message is ${error.message}');
+    return;
+  }
+  console.info('unbindDevice success');
+  });
+} catch (error) {
+  console.error('unbindDevice fail. Code is ${error.code}, message is ${error.message}');
+}
+```
+## deviceManager.unbindDevice
+
+unbindDevice(deviceId: number): Promise<number>
+
+Unbinds a peripheral device. This API uses a promise to return the result.
+
+**System capability**: SystemCapability.Driver.ExternalDevice
+
+**Parameters**
+
+| Name  | Type  | Mandatory| Description                          |
+| -------- | ------ | ---- | ------------------------------ |
+| deviceId | number | Yes  | ID of the device to unbind. It can be obtained by **queryDevices()**.|
+
+**Error codes**
+
+| ID| Error Message                                |
+| -------- | ---------------------------------------- |
+| 401      | The parameter check failed.              |
+| 22900001 | ExternalDeviceManager service exception. |
+
+**Return value**
+
+| Type                 | Description                     |
+| --------------------- | ------------------------- |
+| Promise<number> | Promise used to return the device ID.|
+
+**Example**
+
+```js
+try {
+  deviceManager.unbindDevice(matchDevice.deviceId).then(data => {
+    console.info('unbindDevice success');
+  }, error => {
+    console.error('unbindDevice async fail. Code is ${error.code}, message is ${error.message}');
+  });
+} catch (error) {
+  console.error('unbindDevice fail. Code is ${error.code}, message is ${error.message}');
+}
+```
+
+## Device
+
+Represents the peripheral device information.
+
+**System capability**: SystemCapability.Driver.ExternalDevice
+
+| Name       | Type               | Mandatory| Description      |
+| ----------- | ------------------- | ---- | ---------- |
+| busType     | [BusType](#bustype) | Yes  | Bus type.|
+| deviceId    | number              | Yes  | ID of the peripheral device.  |
+| description | string              | Yes  | Description of the peripheral device.|
+
+## USBDevice
+
+Represents the USB device information.
+
+**System capability**: SystemCapability.Driver.ExternalDevice
+
+| Name     | Type  | Mandatory| Description               |
+| --------- | ------ | ---- | ------------------- |
+| vendorId  | number | Yes  | Vendor ID of the USB device. |
+| productId | number | Yes  | Product ID of the USB device.|
+
+## BusType
+
+Enumerates the device bus types.
+
+**System capability**: SystemCapability.Driver.ExternalDevice
+
+| Name| Value | Description         |
+| ---- | --- | ------------- |
+| USB  | 1   | USB bus.|