@ohos.usbV9 (USB Management)

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.

Modules to Import

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>>	USB device list.

Example

let devicesList = usb.getDevices();
console.log(`devicesList = ${JSON.stringify(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 a USB device based on the device list obtained by using getDevices().

Before you do this, call usb.getDevices to obtain the USB device list and device information, and then call usb.requestRight to request the device access permission.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
device	USBDevice	Yes	USB device information.

Return value

Type	Description
Readonly<USBDevicePipe>	USB device pipe for data transfer.

Error codes

For details about the error codes, see USB Error Codes.

ID	Error Message
14400001	Permission denied. Need call requestRight to get permission.

Example

let devicesList = usb.getDevices();
if (devicesList.length == 0) {
  console.log(`device list is empty`);
  return;
}

let device = devicesList[0];
usb.requestRight(device.name);
let devicepipe = usb.connectDevice(device);
console.log(`devicepipe = ${JSON.stringify(devicepipe)}`);

usb.hasRight

hasRight(deviceName: string): boolean

Checks whether the application has the permission to access the device.

The value true is returned if the device access permission is available; 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

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

let devicesName="1-1";
usb.requestRight(devicesName).then((ret) => {
  console.log(`requestRight = ${JSON.stringify(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

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 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

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 to obtain the USB device list and USB interfaces, call usb.requestRight to request the device access permission, and call usb.connectDevice to obtain devicepipe as an input parameter.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
pipe	USBDevicePipe	Yes	Device pipe, which is used to determine the bus number and device address.
iface	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

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.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
pipe	USBDevicePipe	Yes	Device pipe, which is used to determine the bus number and device address.
iface	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

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 to obtain the USB device list and device configuration, call usb.requestRight to request the device access permission, and call usb.connectDevice to obtain devicepipe as an input parameter.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
pipe	USBDevicePipe	Yes	Device pipe, which is used to determine the bus number and device address.
config	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

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 to obtain the USB device list and interfaces, call usb.requestRight to request the device access permission, call usb.connectDevice to obtain devicepipe as an input parameter, and call usb.claimInterface to claim the USB interface.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
pipe	USBDevicePipe	Yes	Device pipe, which is used to determine the bus number and device address.
iface	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

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 to obtain the USB device list, call usb.requestRight to request the device access permission, and call usb.connectDevice to obtain devicepipe as an input parameter.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
pipe	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

let ret = usb.getRawDescriptor(devicepipe);

usb.getFileDescriptor

getFileDescriptor(pipe: USBDevicePipe): number

Obtains the file descriptor.

Before you do this, call usb.getDevices to obtain the USB device list, call usb.requestRight to request the device access permission, and call usb.connectDevice to obtain devicepipe as an input parameter.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
pipe	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

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 to obtain the USB device list, call usb.requestRight to request the device access permission, and call usb.connectDevice to obtain devicepipe as an input parameter.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
pipe	USBDevicePipe	Yes	USB device pipe, which is used to determine the USB device.
controlparam	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

usb.controlTransfer(devicepipe, USBControlParams).then((ret) => {
 console.log(`controlTransfer = ${JSON.stringify(ret)}`);
})

usb.bulkTransfer

bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, timeout ?: number): Promise<number>

Performs bulk transfer.

Before you do this, call usb.getDevices to obtain the USB device list and endpoints, call usb.requestRight to request the device access permission, call usb.connectDevice to obtain devicepipe as an input parameter, and call usb.claimInterface to claim the USB interface.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
pipe	USBDevicePipe	Yes	USB device pipe, which is used to determine the USB device.
endpoint	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

// 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 = ${JSON.stringify(ret)}`);
});

usb.closePipe

closePipe(pipe: USBDevicePipe): number

Closes a USB device pipe.

Before you do this, call usb.getDevices to obtain the USB device list, call usb.requestRight to request the device access permission, and call usb.connectDevice to obtain devicepipe as an input parameter.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
pipe	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

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

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	Yes	USB function list in numeric mask format.

Return value

Type	Description
string	Function list in string format.

Example

let funcs = ACM|ECM;
let ret = usb.usbFunctionsToString(funcs);

usb.setCurrentFunctions

setCurrentFunctions(funcs: FunctionType): Promise<void>

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	Yes	USB function list in numeric mask format.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Example

let funcs = HDC;
usb.setCurrentFunctions(funcs).then(() => {
    console.info('usb setCurrentFunctions successfully.');
}).catch(err => {
    console.error('usb setCurrentFunctions failed: ' + err.code + ' message: ' + err.message);
});

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	Numeric mask combination for the USB function list.

Example

let ret = usb.getCurrentFunctions();

usb.getPorts

getPorts(): Array<USBPort>

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

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	Mask combination for the supported mode list.

Example

let ret = usb.getSupportedModes(0);

usb.setPortRoles

setPortRoles(portId: number, powerRole: PowerRoleType, dataRole: DataRoleType): Promise<void>

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	Yes	Role for charging.
dataRole	DataRoleType	Yes	Role for data transfer.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Example

let portId = 1;
usb.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.

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	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 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>	Yes	Endpoints that belong to the USB interface.

USBConfig

Represents the USB configuration. One 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>	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>	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	Yes	Request target type.
reqType	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	Yes	Numeric mask combination for the supported mode list.
status	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.

你可能感兴趣的鸿蒙文章

harmony 鸿蒙APIs

harmony 鸿蒙System Common Events

harmony 鸿蒙System Common Events

harmony 鸿蒙API Reference Document Description

harmony 鸿蒙BundleStatusCallback

harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager)

harmony 鸿蒙@ohos.distributedBundle (Distributed Bundle Management)

harmony 鸿蒙@ohos.bundle (Bundle)

harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (EnterpriseAdminExtensionAbility)

harmony 鸿蒙@ohos.WorkSchedulerExtensionAbility (Work Scheduler Callbacks)