diff --git a/en/application-dev/reference/apis/js-apis-usb.md b/en/application-dev/reference/apis/js-apis-usb.md index 83ed07f3f720da23ff5c006938d15bd2ea660751..82932c99be0a0c8c39ab989d656cb6b0fcde99f5 100644 --- a/en/application-dev/reference/apis/js-apis-usb.md +++ b/en/application-dev/reference/apis/js-apis-usb.md @@ -1,6 +1,9 @@ # USB -> **NOTE**
+This module provides USB device management functions, including USB device list query, bulk data transfer, control transfer, and permission control. + +> **NOTE** +> > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## Modules to Import @@ -23,6 +26,7 @@ Obtains the USB device list. | Array<Readonly<[USBDevice](#usbdevice)>> | Device information list. | - **Example** + ```js let devicesList = usb.getDevices(); console.log(`devicesList = ${JSON.stringify(devicesList)}`); @@ -90,16 +94,19 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi **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. | - **Example** + ```js let devicepipe= usb.connectDevice(device); console.log(`devicepipe = ${JSON.stringify(devicepipe)}`); @@ -115,16 +122,19 @@ Checks whether the application has the permission to access the device. **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); @@ -141,16 +151,19 @@ Requests the temporary permission for the application to access the USB device. **System capability**: SystemCapability.USB.USBManager - **Parameters** + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | deviceName | string | Yes| Device name. | - **Return value** + | Type| Description| | -------- | -------- | | Promise<boolean> | Returns **true** if the temporary device access permissions are granted; returns **false** otherwise. | - **Example** + ```js let devicesName="1-1"; usb.requestRight(devicesName).then((ret) => { @@ -169,6 +182,7 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi **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. | @@ -176,11 +190,13 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi | 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}`); @@ -198,17 +214,20 @@ Before you do this, ensure that you have claimed the interface by calling [usb.c **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}`); @@ -226,17 +245,20 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi **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}`); @@ -253,17 +275,20 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi **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}`); @@ -281,16 +306,19 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi **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 | Raw descriptor data. The value **undefined** indicates that the operation has failed. | - **Example** + ```js let ret = usb.getRawDescriptor(devicepipe); ``` @@ -307,16 +335,19 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi **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 | File descriptor of the USB device. The value **-1** indicates that the operation has failed. | - **Example** + ```js let ret = usb.getFileDescriptor(devicepipe); ``` @@ -333,6 +364,7 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi **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. | @@ -340,11 +372,13 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi | timeout | number | No| Timeout duration. The default value is **0**, indicating no timeout. | - **Return value** + | Type| Description| | -------- | -------- | | Promise<number> | Returns the size of the transmitted or received data block if the control transfer is successful; returns **-1** if an exception occurs. | - **Example** + ```js usb.controlTransfer(devicepipe, USBControlParams).then((ret) => { console.log(`controlTransfer = ${JSON.stringify(ret)}`); @@ -363,6 +397,7 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi **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. | @@ -371,11 +406,13 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi | timeout | number | No| Timeout duration. The default value is **0**, indicating no timeout. | - **Return value** + | Type| Description| | -------- | -------- | | Promise<number> | Returns the size of the transmitted or received data block if the control transfer is successful; returns **-1** if an exception occurs. | - **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. @@ -397,16 +434,19 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi **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}`); @@ -553,3 +593,68 @@ Enumerates request directions. | -------- | -------- | -------- | | 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. | + +## FunctionType9+ + +Enumerates function types for the USB device. + +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.| + +## PortModeType9+ + +Enumerates USB port mode types. + +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. | + +## PowerRoleType9+ + +Enumerates power role types. + +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.| + +## DataRoleType9+ + +Enumerates data role types. + +This is a system API. + +**System capability**: SystemCapability.USB.USBManager + +| Name | Value | Description | +| ------ | ---- | ------------ | +| NONE | 0 | None. | +| HOST | 1 | USB host.| +| DEVICE | 2 | USB device.|