@ohos.usbManager (USB Manager)

The usbManager 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 USB interface 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 { usbManager } from '@kit.BasicServicesKit';

How to Use

Perform the following steps when using the APIs with the USBDevicePipe parameter:

Before use:

Call usbManager.getDevices to obtain the USB device list.
Call usbManager.requestRight to request the device access permission.
Call usbManager.connectDevice to obtain USBDevicePipe as an input parameter.

After use:

Call usbManager.closePipe to close a USB device pipe.

usbManager.getDevices

getDevices(): Array<Readonly<USBDevice>>

Obtains the list of USB devices connected to the host.

NOTE

Third-party applications are not allowed to obtain the device serial number from the serial field. They need to request permission using requestRight and then initiate a control transfer to obtain it.

System capability: SystemCapability.USB.USBManager

Return value

Type	Description
Array<Readonly<USBDevice>>	USB device list.

Error codes

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

ID	Error Message
801	Capability not supported.

Example

let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
console.info(`devicesList = ${devicesList}`);
/*
  The following is a simple example of the data structure for devicesList:
  [
    {
      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,
                },
              ],
            },
          ],
        },
      ],
    },
  ]
 */

usbManager.connectDevice

connectDevice(device: USBDevice): Readonly<USBDevicePipe>

Connects to the USB device based on the device information returned by getDevices(). If the USB service is abnormal, undefined may be returned. Check whether the return value of the API is empty.

Call usbManager.getDevices to obtain the USB device list.
Call usbManager.requestRight to request the device access permission.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
device	USBDevice	Yes	USB device. The busNum and devAddress parameters obtained by getDevices are used to determine a USB device. Other parameters are passed transparently.

Return value

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

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.
14400001	Access right denied. Call requestRight to get the USBDevicePipe access right first.

Example

function connectDevice() {
  let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
  if (!devicesList || devicesList.length == 0) {
    console.info(`device list is empty`);
    return;
  }

  let device: usbManager.USBDevice = devicesList?.[0];
  usbManager.requestRight(device.name);
  let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device);
  console.info(`devicepipe = ${devicepipe}`);
}

usbManager.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, which comes from the USB device name obtained by getDevices.

Return value

Type	Description
boolean	Returns true if the application has the permission to access the device; returns false otherwise.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.

Example

function hasRight(): boolean {
  let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
  if (!devicesList || devicesList.length == 0) {
    console.info(`device list is empty`);
    return false;
  }

  let device: usbManager.USBDevice = devicesList?.[0];
  usbManager.requestRight(device.name);
  let right: boolean = usbManager.hasRight(device.name);
  console.info(`${right}`);
  return right;
}

usbManager.requestRight

requestRight(deviceName: string): Promise<boolean>

Requests the temporary device access permission for the application. This API uses a promise to return the result. System applications are granted the device access permission by default, and you do not need to apply for the permission separately.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
deviceName	string	Yes	Device name, which comes from the USB device name obtained by getDevices.

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.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.

Example

function requestRight() {
  let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
  if (!devicesList || devicesList.length == 0) {
    console.info(`device list is empty`);
    return;
  }

  let device: usbManager.USBDevice = devicesList?.[0];
  usbManager.requestRight(device.name).then(ret => {
    console.info(`requestRight = ${ret}`);
  }).catch((error: BusinessError) => {
    console.error(`requestRight failed : ${error}`);
  });
}

usbManager.removeRight

removeRight(deviceName: string): boolean

Removes the device access permission for the application. System applications are granted the device access permission by default, and calling this API will not revoke the permission.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
deviceName	string	Yes	Device name, which comes from the USB device name obtained by getDevices.

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.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.

Example

function removeRight(): boolean {
  let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
  if (!devicesList || devicesList.length == 0) {
    console.info(`device list is empty`);
    return false;
  }

  let device: usbManager.USBDevice = devicesList?.[0];
  if (usbManager.removeRight(device.name)) {
    console.info(`Succeed in removing right`);
    return true;
  }
  return false;
}

usbManager.claimInterface

claimInterface(pipe: USBDevicePipe, iface: USBInterface, force ?: boolean): number

Claims a USB device interface.

NOTE

In USB programming, claimInterface is a common operation, which indicates that an application requests the operating system to release a USB interface from the kernel driver and hand over the USB interface to a user space program for control.
All the claim communication interfaces used below refer to the claim interface operations.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
pipe	USBDevicePipe	Yes	Bus address and device address, which are obtained by calling connectDevice.
iface	USBInterface	Yes	Index of the target USB interface. You can use getDevices to obtain device information and identify the USB interface based on the ID.
force	boolean	No	Whether to forcibly claim a USB interface. The default value is false, which means not to forcibly claim a USB interface. You can set the value as required.

Return value

Type	Description
number	Returns 0 if the claim interface is called successfully; returns an error code otherwise. The error codes are as follows: - 88080389: The service is not started. Possible causes: 1. No device is inserted. 2. The service exits abnormally. - 88080486: The service is being initialized. Try again later. - 88080488: No device access permission. Call the requestRight API to request authorization. - -1: The driver is abnormal.

Type

Description

number

Returns 0 if the claim interface is called successfully; returns an error code otherwise. The error codes are as follows:
- 88080389: The service is not started. Possible causes: 1. No device is inserted. 2. The service exits abnormally.
- 88080486: The service is being initialized. Try again later.
- 88080488: No device access permission. Call the requestRight API to request authorization.
- -1: The driver is abnormal.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.

Example

function claimInterface() {
  let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
  if (!devicesList || devicesList.length == 0) {
    console.info(`device list is empty`);
    return;
  }

  let device: usbManager.USBDevice = devicesList?.[0];
  usbManager.requestRight(device.name);
  let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device);
  let interfaces: usbManager.USBInterface = device.configs?.[0]?.interfaces?.[0];
  let ret: number= usbManager.claimInterface(devicepipe, interfaces);
  console.info(`claimInterface = ${ret}`);
}

usbManager.releaseInterface

releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number

Releases the claimed communication interface.

NOTE

Before calling this API, call the usbManager.claimInterface API to claim a communication interface.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
pipe	USBDevicePipe	Yes	Bus address and device address, which are obtained by calling connectDevice.
iface	USBInterface	Yes	Index of the target USB interface. You can use getDevices to obtain device information and identify the USB interface based on the ID.

Return value

Type	Description
number	Returns 0 if the USB interface is successfully released; returns an error code otherwise. The error codes are as follows: - 88080389: The service is not started. Possible causes: 1. No device is inserted. 2. The service exits abnormally. - 88080486: The service is being initialized. Try again later. - 88080488: No device access permission. Call the requestRight API to request authorization. - -1: The driver is abnormal.

Type

Description

number

Returns 0 if the USB interface is successfully released; returns an error code otherwise. The error codes are as follows:
- 88080389: The service is not started. Possible causes: 1. No device is inserted. 2. The service exits abnormally.
- 88080486: The service is being initialized. Try again later.
- 88080488: No device access permission. Call the requestRight API to request authorization.
- -1: The driver is abnormal.

Error codes

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

ID	Error Message
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified.2.Incorrect parameter types.
801	Capability not supported.

Example

function releaseInterface() {
  let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
  if (!devicesList || devicesList.length == 0) {
    console.info(`device list is empty`);
    return;
  }

  let device: usbManager.USBDevice = devicesList?.[0];
  usbManager.requestRight(device.name);
  let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device);
  let interfaces: usbManager.USBInterface = device.configs?.[0]?.interfaces?.[0];
  let ret: number = usbManager.claimInterface(devicepipe, interfaces);
  ret = usbManager.releaseInterface(devicepipe, interfaces);
  console.info(`releaseInterface = ${ret}`);
}

usbManager.setConfiguration

setConfiguration(pipe: USBDevicePipe, config: USBConfiguration): number

Sets the device configuration.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
pipe	USBDevicePipe	Yes	Bus address and device address, which are obtained by calling connectDevice.
config	USBConfiguration	Yes	USB configuration. You can use getDevices to obtain device information and identify the USB configuration based on the ID.

Return value

Type	Description
number	Returns 0 if the USB configuration is successfully set; returns an error code otherwise. The error codes are as follows: - 88080389: The service is not started. Possible causes: 1. No device is inserted. 2. The service exits abnormally. - 88080486: The service is being initialized. Try again later. - 88080488: No device access permission. Call the requestRight API to request authorization. - -1: The driver is abnormal. - -17: I/O failure.

Type

Description

number

Returns 0 if the USB configuration is successfully set; returns an error code otherwise. The error codes are as follows:
- 88080389: The service is not started. Possible causes: 1. No device is inserted. 2. The service exits abnormally.
- 88080486: The service is being initialized. Try again later.
- 88080488: No device access permission. Call the requestRight API to request authorization.
- -1: The driver is abnormal.
- -17: I/O failure.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.

Example

function setConfiguration() {
  let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
  if (!devicesList || devicesList.length == 0) {
    console.info(`device list is empty`);
    return;
  }

  let device: usbManager.USBDevice = devicesList?.[0];
  usbManager.requestRight(device.name);
  let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device);
  let config: usbManager.USBConfiguration = device.configs?.[0];
  let ret: number= usbManager.setConfiguration(devicepipe, config);
  console.info(`setConfiguration = ${ret}`);
}

usbManager.setInterface

setInterface(pipe: USBDevicePipe, iface: USBInterface): number

Sets a USB interface.

NOTE

A USB interface may have multiple selection modes and supports dynamic switching. It is used to reset the endpoint to match the transmission type during data transmission.

Before calling this API, call the usbManager.claimInterface API to claim a communication interface.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
pipe	USBDevicePipe	Yes	Bus address and device address, which are obtained by calling connectDevice.
iface	USBInterface	Yes	USB interface. You can use getDevices to obtain device information and identify the USB interface based on its id and alternateSetting.

Return value

Type	Description
number	Returns 0 if the USB interface is successfully set; returns an error code otherwise. The error codes are as follows: - 88080389: The service is not started. Possible causes: 1. No device is inserted. 2. The service exits abnormally. - 88080486: The service is being initialized. Try again later. - 88080488: No device access permission. Call the requestRight API to request authorization. - -1: The driver is abnormal.

Type

Description

number

Returns 0 if the USB interface is successfully set; returns an error code otherwise. The error codes are as follows:
- 88080389: The service is not started. Possible causes: 1. No device is inserted. 2. The service exits abnormally.
- 88080486: The service is being initialized. Try again later.
- 88080488: No device access permission. Call the requestRight API to request authorization.
- -1: The driver is abnormal.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.

Example

function setInterface() {
  let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
  if (!devicesList || devicesList.length == 0) {
    console.info(`device list is empty`);
    return;
  }

  let device: usbManager.USBDevice = devicesList?.[0];
  usbManager.requestRight(device.name);
  let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device);
  let interfaces: usbManager.USBInterface = device.configs?.[0]?.interfaces?.[0];
  let ret: number = usbManager.claimInterface(devicepipe, interfaces);
  ret = usbManager.setInterface(devicepipe, interfaces);
  console.info(`setInterface = ${ret}`);
}

usbManager.getRawDescriptor

getRawDescriptor(pipe: USBDevicePipe): Uint8Array

Obtains a raw USB descriptor. If the USB service is abnormal, undefined may be returned. Check whether the return value of the API is empty.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
pipe	USBDevicePipe	Yes	Bus address and device address, which are obtained by calling connectDevice.

Return value

Type	Description
Uint8Array	Returns a raw USB descriptor if the operation is successful; returns undefined otherwise.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.

Example

function getRawDescriptor() {
  let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
  if (!devicesList || devicesList.length == 0) {
    console.info(`device list is empty`);
    return;
  }

  usbManager.requestRight(devicesList?.[0]?.name);
  let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList?.[0]);
  let ret: Uint8Array = usbManager.getRawDescriptor(devicepipe);
}

usbManager.getFileDescriptor

getFileDescriptor(pipe: USBDevicePipe): number

Obtains a file descriptor.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
pipe	USBDevicePipe	Yes	Bus address and device address, which are obtained by calling connectDevice.

Return value

Type	Description
number	Returns the file descriptor corresponding to the device if this API is successfully called; returns an error code otherwise. The error codes are as follows: - 88080486: The service is being initialized. Try again later. - 88080488: No device access permission. Call the requestRight API to request authorization. - -1: The driver is abnormal.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.

Example

function getFileDescriptor() {
  let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
  if (!devicesList || devicesList.length == 0) {
    console.info(`device list is empty`);
    return;
  }

  usbManager.requestRight(devicesList?.[0]?.name);
  let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList?.[0]);
  let ret: number = usbManager.getFileDescriptor(devicepipe);
  console.info(`getFileDescriptor = ${ret}`);
  let closeRet: number = usbManager.closePipe(devicepipe);
  console.info(`closePipe = ${closeRet}`);
}

usbManager.usbControlTransfer¹²⁺

usbControlTransfer(pipe: USBDevicePipe, requestparam: USBDeviceRequestParams, timeout ?: number): Promise<number>

Performs control transfer. This API uses a promise to return the result.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
pipe	USBDevicePipe	Yes	USB device pipe, which is obtained by calling connectDevice.
requestparam	USBDeviceRequestParams	Yes	Control transfer parameters. Set the parameters as required. For details, see the USB protocol.
timeout	number	No	Timeout interval, in milliseconds. This parameter is optional. If the control transfer is complete within the specified time, the size of the transferred or received data block is returned; otherwise, a timeout error is returned. The default value is 0, indicating that the system waits infinitely until the control transfer is complete. Set this parameter as required.

Return value

Type	Description
Promise<number>	Promise used to return the result, which is the size of the transferred or received data block if the transfer is successful. If the API call fails, the following error codes are returned: - -1: The driver is abnormal.

Error codes

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

ID	Error Message
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified.2.Incorrect parameter types.
801	Capability not supported.

Example

class PARA {
  bmRequestType: number = 0
  bRequest: number = 0
  wValue: number = 0
  wIndex: number = 0
  wLength: number = 0
  data: Uint8Array = new Uint8Array()
}

let param: PARA = {
  bmRequestType: 0x80,
  bRequest: 0x06,

  wValue:0x01 << 8 | 0,
  wIndex: 0,
  wLength: 18,
  data: new Uint8Array(18)
};

function usbControlTransfer() {
  let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
  if (!devicesList || devicesList.length == 0) {
    console.info(`device list is empty`);
    return;
  }

  usbManager.requestRight(devicesList?.[0]?.name);
  let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList?.[0]);
  usbManager.usbControlTransfer(devicepipe, param).then((ret: number) => {
  console.info(`usbControlTransfer = ${ret}`);
  })
}

usbManager.bulkTransfer

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

Performs bulk transfer. This API uses a promise to return the result.

NOTE

The total size of data (including pipe, endpoint, buffer, and timeout) to be transferred in a single bulk transfer must be less than 200 KB. Otherwise, the transfer fails and -1 is returned.

Before calling this API, call the usbManager.claimInterface API to claim a communication interface.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
pipe	USBDevicePipe	Yes	USB device pipe, which is obtained by calling connectDevice.
endpoint	USBEndpoint	Yes	USB endpoint, which is used to determine the USB interface for data transfer. You need to call getDevices to obtain the device information list and endpoint. Wherein, address is used to determine the endpoint address, direction is used to determine the endpoint direction, and interfaceId is used to determine the USB interface to which the endpoint belongs. Other parameters are passed transparently.
buffer	Uint8Array	Yes	Buffer for writing or reading data.
timeout	number	No	Timeout interval, in milliseconds. This parameter is optional. If the bulk transfer is complete within the specified time, the size of the transferred or received data block is returned; otherwise, a timeout error is returned. The default value is 0, indicating that the system waits infinitely until the control transfer is complete. Set this parameter as required.

Return value

Type	Description
Promise<number>	Promise used to return the result, which is the size of the transferred or received data block if the transfer is successful. If the API call fails, the following error codes are returned: - -1: The driver is abnormal.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.

Example

NOTE

The following sample code is only a basic process for calling the bulkTransfer API. In actual calling, you must comply with the device-related protocols to ensure correct data transfer and device compatibility.

// Call usbManager.getDevices to obtain a data set. Then, obtain a USB device and its access permission.
// Pass the obtained USB device as a parameter to usbManager.connectDevice. Then, call usbManager.connectDevice to connect the USB device.
// Call usbManager.claimInterface to claim a USB interface. After that, call usbManager.bulkTransfer to start bulk transfer.
function bulkTransfer() {
  let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
  if (!devicesList || devicesList.length == 0) {
    console.info(`device list is empty`);
    return;
  }

  let device: usbManager.USBDevice = devicesList?.[0];
  usbManager.requestRight(device.name);
  if (!usbManager.hasRight(device.name)) {
    console.error(`request right fail`);
    return;
  }
  let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device);
  for (let i = 0; i < device.configs?.[0]?.interfaces.length; i++) {
    if (device.configs?.[0]?.interfaces?.[i]?.endpoints?.[0]?.attributes == 2) {
      let endpoint: usbManager.USBEndpoint = device.configs?.[0]?.interfaces?.[i]?.endpoints?.[0];
      let interfaces: usbManager.USBInterface = device.configs?.[0]?.interfaces?.[i];
      let ret: number = usbManager.claimInterface(devicepipe, interfaces);
      let buffer =  new Uint8Array(128);
      usbManager.bulkTransfer(devicepipe, endpoint, buffer).then((ret: number) => {
        console.info(`bulkTransfer = ${ret}`);
      }).catch((error: BusinessError) => {
        console.error(`bulkTransfer failed : ${error}`);
      });
    }
  }
}

usbManager.usbSubmitTransfer¹⁸⁺

usbSubmitTransfer(transfer: UsbDataTransferParams): void

Requests a USB data transfer.

NOTE

This API uses an asynchronous callback to return the result.

Before calling this API, call the usbManager.claimInterface API to claim a communication interface.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
transfer	UsbDataTransferParams	Yes	As a USB data transfer interface, it is required for a client to initiate a transfer request.

Error codes

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

ID	Error Message
801	Capability not supported.
14400001	Access right denied. Call requestRight to get the USBDevicePipe access right first.
14400007	Resource busy. Possible causes: 1. The transfer has already been submitted. 2. The interface is claimed by another program or driver.
14400008	No such device (it may have been disconnected).
14400009	Insufficient memory. Possible causes: 1. Memory allocation failed.
14400012	Transmission I/O error.

Example

NOTE

The following sample code shows the basic process for calling the usbSubmitTransfer API and it needs to be executed in a specific method. In actual calling, you must comply with the device-related protocols to ensure correct data transfer and device compatibility.

// Call usbManager.getDevices to obtain a data set. Then, obtain a USB device and its access permission.
// Pass the obtained USB device as a parameter to usbManager.connectDevice. Then, call usbManager.connectDevice to connect the USB device.
// Call usbManager.claimInterface to claim a USB interface. After that, call usbManager.bulkTransfer to start bulk transfer.
function usbSubmitTransfer() {
  let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
  if (!devicesList || devicesList.length == 0) {
    console.info(`device list is empty`);
    return;
  }
  let device: usbManager.USBDevice = devicesList?.[0];
  usbManager.requestRight(device.name);
  if (!usbManager.hasRight(device.name)) {
    console.info(`request right fail`);
    return;
  }
  let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device);
  // Obtain the endpoint address.
  let endpoint = device.configs?.[0]?.interfaces?.[0]?.endpoints.find((value) => {
    return value.direction === 0 && value.type === 2
  })
  // Obtain the first ID of the device.
  let ret: number = usbManager.claimInterface(devicepipe, device.configs?.[0]?.interfaces?.[0], true);

  let transferParams: usbManager.UsbDataTransferParams = {
    devPipe: devicepipe,
    flags: usbManager.UsbTransferFlags.USB_TRANSFER_SHORT_NOT_OK,
    endpoint: 1,
    type: usbManager.UsbEndpointTransferType.TRANSFER_TYPE_BULK,
    timeout: 2000,
    length: 10, 
    callback: () => {},
    userData: new Uint8Array(10),
    buffer: new Uint8Array(10),
    isoPacketCount: 0,
  };
  try {
    transferParams.endpoint=endpoint?.address as number;
    transferParams.callback=(err, callBackData: usbManager.SubmitTransferCallback)=>{
      console.info('callBackData =' +JSON.stringify(callBackData));
    }
    usbManager.usbSubmitTransfer(transferParams); 
    console.info('USB transfer request submitted.');
  } catch (error) {
    console.error('USB transfer failed:', error);
  }
}

usbManager.usbCancelTransfer¹⁸⁺

usbCancelTransfer(transfer: UsbDataTransferParams): void

Cancels an asynchronous USB data transfer request.

NOTE

This API is used to proactively cancel an unfinished USB data transfer request (for example, the one submitted by usbSubmitTransfer).
Before calling this API, call the usbManager.claimInterface API to claim a communication interface.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
transfer	UsbDataTransferParams	Yes	This parameter is the same as the input parameter object of the usbManager.usbSubmitTransfer API.

Error codes

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

ID	Error Message
801	Capability not supported.
14400001	Access right denied. Call requestRight to get the USBDevicePipe access right first.
14400008	No such device (it may have been disconnected).
14400010	Other USB error. Possible causes: 1.Unrecognized discard error code.
14400011	The transfer is not in progress, or is already complete or cancelled.

Example

NOTE

The following sample code shows the basic process for calling the usbCancelTransfer API and it needs to be executed in a specific method. In actual calling, you must comply with the device-related protocols to ensure correct data transfer and device compatibility.

// Call usbManager.getDevices to obtain a data set. Then, obtain a USB device and its access permission.
// Pass the obtained USB device as a parameter to usbManager.connectDevice. Then, call usbManager.connectDevice to connect the USB device.
// Call usbManager.claimInterface to claim a USB interface. After that, call usbManager.bulkTransfer to start bulk transfer.
function usbCancelTransfer() {
  let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
  if (!devicesList || devicesList.length == 0) {
    console.info(`device list is empty`);
    return;
  }
  let device: usbManager.USBDevice = devicesList?.[0];
  usbManager.requestRight(device.name);
  let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device);
  if (devicepipe === undefined) {
    console.info(`connect device fail`);
    return;
  }
  // Obtain the endpoint address.
  let endpoint = device.configs?.[0]?.interfaces?.[0]?.endpoints.find((value) => {
    return value.direction === 0 && value.type === 2
  })
  if (endpoint === undefined) {
    console.info(`invalid endpoint`);
    return;
  }
  // Obtain the first ID of the device.
  let ret: number = usbManager.claimInterface(devicepipe, device.configs?.[0]?.interfaces?.[0], true);
  let transferParams: usbManager.UsbDataTransferParams = {
    devPipe: devicepipe,
    flags: usbManager.UsbTransferFlags.USB_TRANSFER_SHORT_NOT_OK,
    endpoint: 1,
    type: usbManager.UsbEndpointTransferType.TRANSFER_TYPE_BULK,
    timeout: 2000,
    length: 10, 
    callback: () => {},
    userData: new Uint8Array(10),
    buffer: new Uint8Array(10),
    isoPacketCount: 0,
  };
  try {
    transferParams.endpoint=endpoint?.address as number;
    transferParams.callback=(err, callBackData: usbManager.SubmitTransferCallback)=>{
      console.info('callBackData =' +JSON.stringify(callBackData));
    }
    usbManager.usbSubmitTransfer(transferParams);
    usbManager.usbCancelTransfer(transferParams);
    console.info('USB transfer request submitted.');
  } catch (error) {
    console.error('USB transfer failed:', error);
  }
}

usbManager.closePipe

closePipe(pipe: USBDevicePipe): number

Closes a USB device pipe.

Call usbManager.getDevices to obtain the USB device list.
Call usbManager.requestRight to request the device access permission.
Call usbManager.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 message control channel. You need to call connectDevice to obtain its value.

Return value

Type	Description
number	Returns 0 if the USB device pipe is closed successfully; returns an error code otherwise. The error codes are as follows: - 22: The service is abnormal.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.

Example

function closePipe() {
  let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
  if (!devicesList || devicesList.length == 0) {
    console.info(`device list is empty`);
    return;
  }

  usbManager.requestRight(devicesList?.[0]?.name);
  let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList?.[0]);
  let ret: number = usbManager.closePipe(devicepipe);
  console.info(`closePipe = ${ret}`);
}

usbManager.hasAccessoryRight¹⁴⁺

hasAccessoryRight(accessory: USBAccessory): boolean

Checks whether the application has the permission to access the USB accessory.

You need to call usbManager.getAccessoryList to obtain the accessory list and use USBAccessory as a parameter.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
accessory	USBAccessory	Yes	USB accessory, which is obtained through getAccessoryList.

Return value

Type	Description
boolean	The value true indicates that the application has the permission to access the USB accessory; false indicates the opposite.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.
14400004	Service exception. Possible causes: 1. No accessory is plugged in.
14400005	Database operation exception.
14401001	The target USBAccessory not matched.

Example

import { hilog } from '@kit.PerformanceAnalysisKit';
try {
  let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList()
  let flag = usbManager.hasAccessoryRight(accList?.[0])
  hilog.info(0, 'testTag ui', `hasAccessoryRight success, ret:${flag}`)
} catch (error) {
  hilog.error(0, 'testTag ui', `hasAccessoryRight error ${error.code}, message is ${error.message}`)
}

usbManager.requestAccessoryRight¹⁴⁺

requestAccessoryRight(accessory: USBAccessory): Promise<boolean>

Requests the permission to access a USB accessory for a specified application. This API uses a promise to return the result.

You need to call usbManager.getAccessoryList to obtain the accessory list and use USBAccessory as a parameter.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
accessory	USBAccessory	Yes	USB accessory, which is obtained through getAccessoryList.

Return value

Type	Description
Promise<boolean>	Promise used to return the application result. The value true indicates that the device access permissions are granted; false indicates the opposite.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.
14400004	Service exception. Possible causes: 1. No accessory is plugged in.
14400005	Database operation exception.
14401001	The target USBAccessory not matched.

Example

import { hilog } from '@kit.PerformanceAnalysisKit';
try {
  let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList()
  let flag = usbManager.requestAccessoryRight(accList?.[0])
  hilog.info(0, 'testTag ui', `requestAccessoryRight success, ret:${flag}`)
} catch (error) {
  hilog.error(0, 'testTag ui', `requestAccessoryRight error ${error.code}, message is ${error.message}`)
}

usbManager.cancelAccessoryRight¹⁴⁺

cancelAccessoryRight(accessory: USBAccessory): void

Cancels the permission of the current application to access USB accessories.

You need to call usbManager.getAccessoryList to obtain the accessory list and use USBAccessory as a parameter.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
accessory	USBAccessory	Yes	USB accessory, which is obtained through getAccessoryList.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.
14400004	Service exception. Possible causes: 1. No accessory is plugged in.
14400005	Database operation exception.
14401001	The target USBAccessory not matched.

Example

import { hilog } from '@kit.PerformanceAnalysisKit';
try {
  let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList()
  let flag = usbManager.requestAccessoryRight(accList?.[0])
  usbManager.cancelAccessoryRight(accList?.[0])
  hilog.info(0, 'testTag ui', `cancelAccessoryRight success`)
} catch (error) {
  hilog.error(0, 'testTag ui', `cancelAccessoryRight error ${error.code}, message is ${error.message}`)
}

usbManager.getAccessoryList¹⁴⁺

getAccessoryList(): Array<Readonly<USBAccessory>>

Obtains the list of USB accessories connected to the host.

System capability: SystemCapability.USB.USBManager

Return value

Type	Description
Array<Readonly<USBAccessory>>	List of USB accessories (read-only). Currently, only one USB accessory is contained in the list.

Error codes

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

ID	Error Message
801	Capability not supported.
14400004	Service exception. Possible causes: 1. No accessory is plugged in.

Example

import { hilog } from '@kit.PerformanceAnalysisKit';
try {
  let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList()
  hilog.info(0, 'testTag ui', `getAccessoryList success, accList: ${JSON.stringify(accList)}`)
} catch (error) {
  hilog.error(0, 'testTag ui', `getAccessoryList error ${error.code}, message is ${error.message}`)
}

usbManager.openAccessory¹⁴⁺

openAccessory(accessory: USBAccessory): USBAccessoryHandle

Obtains the accessory handle and opens the accessory file descriptor. Then, the host can communicate with the accessory through the read and write APIs provided by Core File Kit.

You need to call usbManager.getAccessoryList to obtain the accessory list and use USBAccessory as a parameter.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
accessory	USBAccessory	Yes	USB accessory, which is obtained through getAccessoryList.

Return value

Type	Description
USBAccessoryHandle	USB accessory handle.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.
14400001	Access right denied. Call requestRight to get the USBDevicePipe access right first.
14400004	Service exception. Possible causes: 1. No accessory is plugged in.
14401001	The target USBAccessory not matched.
14401002	Failed to open the native accessory node.
14401003	Cannot reopen the accessory.

Example

import { hilog } from '@kit.PerformanceAnalysisKit';
import { fileIo } from '@kit.CoreFileKit';
try {
  let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList()
  let flag = usbManager.requestAccessoryRight(accList?.[0])
  let handle = usbManager.openAccessory(accList?.[0])
  hilog.info(0, 'testTag ui', `openAccessory success`)
  let arrayBuffer = new ArrayBuffer(4096);
  let readLength = fileIo.readSync(handle.accessoryFd, arrayBuffer, {offset: 0, length: 4096});
  hilog.info(0, 'testTag ui', 'readSync ret: ' + readLength.toString(10));
} catch (error) {
  hilog.error(0, 'testTag ui', `openAccessory error ${error.code}, message is ${error.message}`)
}

usbManager.closeAccessory¹⁴⁺

closeAccessory(accessoryHandle: USBAccessoryHandle): void

Closes the accessory file descriptor.

You need to call usbManager.openAccessory to obtain the accessory list and use USBAccessoryHandle as a parameter.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
accessoryHandle	USBAccessoryHandle	Yes	USB accessory handle, which is obtained through openAccessory.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.
14400004	Service exception. Possible causes: 1. No accessory is plugged in.

Example

import { hilog } from '@kit.PerformanceAnalysisKit';
try {
  let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList()
  let flag = usbManager.requestAccessoryRight(accList?.[0])
  let handle = usbManager.openAccessory(accList?.[0])
  usbManager.closeAccessory(handle)
  hilog.info(0, 'testTag ui', `closeAccessory success`)
} catch (error) {
  hilog.error(0, 'testTag ui', `closeAccessory error ${error.code}, message is ${error.message}`)
}

usbManager.resetUsbDevice²⁰⁺

resetUsbDevice(pipe: USBDevicePipe): boolean

Resets a USB peripheral.

NOTE

Previous configurations and APIs will be reset. Ensure that the related services have been completed before calling this API.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
pipe	USBDevicePipe	Yes	Bus address and device address, which are obtained by calling connectDevice.

Return value

Type	Description
boolean	Returns true if the device is reset successfully; returns false otherwise.

Error codes

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

ID	Error Message
801	Capability not supported.
14400001	Access right denied. Call requestRight to get the USBDevicePipe access right first.
14400004	Service exception. Possible causes: 1. No accessory is plugged in.
14400008	No such device (it may have been disconnected).
14400010	Other USB error. Possible causes: 1.Unrecognized discard error code.
14400013	The USBDevicePipe validity check failed. Possible causes: 1. The input parameters fail the validation check. 2. The call chain used to obtain the input parameters is not reasonable.

Example

function resetUsbDevice() {
  let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
  if (!devicesList || devicesList.length == 0) {
    console.error(`device list is empty`);
    return;
  }

  usbManager.requestRight(devicesList?.[0]?.name);
  let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList?.[0]);
  try {
    let ret: boolean = usbManager.resetUsbDevice(devicepipe);
    console.info(`resetUsbDevice  = ${ret}`);
  } catch (err) {
    console.error(`resetUsbDevice failed: ` + err);
  }
}

usbManager.controlTransfer^(deprecated)

controlTransfer(pipe: USBDevicePipe, controlparam: USBControlParams, timeout ?: number): Promise<number>

Performs control transfer. This API uses a promise to return the result.

NOTE

This API is supported since API version 9 and deprecated since API version 12. You are advised to use usbControlTransfer.

System capability: SystemCapability.USB.USBManager

Parameters

Name	Type	Mandatory	Description
pipe	USBDevicePipe	Yes	USB device pipe, which is obtained by calling connectDevice.
controlparam	USBControlParams	Yes	Control transfer parameters. Set the parameters as required. For details, see the USB protocol.
timeout	number	No	Timeout interval, in milliseconds. This parameter is optional. If the control transfer is complete within the specified time, the size of the transferred or received data block is returned; otherwise, a timeout error is returned. The default value is 0, indicating that the system waits infinitely until the control transfer is complete. Set this parameter as required.

Return value

Type	Description
Promise<number>	Promise used to return the result, which is the size of the transferred or received data block if the transfer is successful. If the API call fails, the following error codes are returned: - -1: The driver is abnormal.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.

Example

class PARA {
  request: number = 0
  reqType: usbManager.USBControlRequestType = 0
  target: usbManager.USBRequestTargetType = 0
  value: number = 0
  index: number = 0
  data: Uint8Array = new Uint8Array()
}

let param: PARA = {
  request: 0x06,
  reqType: 0x80,
  target:0,
  value: 0x01 << 8 | 0,
  index: 0,
  data: new Uint8Array(18)
};

function controlTransfer() {
  let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
  if (!devicesList || devicesList.length == 0) {
    console.info(`device list is empty`);
    return;
  }

  usbManager.requestRight(devicesList[0].name);
  let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]);
  usbManager.controlTransfer(devicepipe, param).then((ret: number) => {
  console.info(`controlTransfer = ${ret}`);
  })
}

USBEndpoint

Describes the USB endpoint from which data is sent or received. You can obtain the USB endpoint through USBInterface.

NOTE

The host controller schedules the endpoint based on the endpoint type.

The transmission characteristics are determined by the type during protocol layer packaging.

System capability: SystemCapability.USB.USBManager

Name	Type	Read-Only	Optional	Description
address	number	No	No	Endpoint address.
attributes	number	No	No	Endpoint attributes.
interval	number	No	No	Endpoint interval.
maxPacketSize	number	No	No	Maximum size of data packets on the endpoint.
direction	USBRequestDirection	No	No	Endpoint direction.
number	number	No	No	Endpoint number.
type	number	No	No	Endpoint type. For details, see UsbEndpointTransferType.
interfaceId	number	No	No	Unique ID of the interface to which the endpoint belongs.

USBInterface

Describes a USB interface. One USBConfiguration object can contain multiple USBInterface instances, each providing a specific function.

System capability: SystemCapability.USB.USBManager

Name	Type	Read-Only	Optional	Description
id	number	No	No	Unique ID of the USB interface.
protocol	number	No	No	Interface protocol.
clazz	number	No	No	Device type.
subClass	number	No	No	Device subclass.
alternateSetting	number	No	No	Settings for alternating between descriptors of the same USB interface. The value size indicates the number of optional modes. The value 0 indicates that no optional mode is supported.
name	string	No	No	Interface name.
endpoints	Array<USBEndpoint>	No	No	Endpoints that belong to the USB interface.

USBConfiguration

Describes the USB configuration. One USBDevice can contain multiple USBConfig instances.

System capability: SystemCapability.USB.USBManager

Name	Type	Read-Only	Optional	Description
id	number	No	No	Unique ID of the USB configuration.
attributes	number	No	No	Configuration attributes.
maxPower	number	No	No	Maximum power consumption, in mA.
name	string	No	No	Configuration name, which can be left empty.
isRemoteWakeup	boolean	No	No	Whether remote wakeup is supported. true if supported, false otherwise.
isSelfPowered	boolean	No	No	Whether an independent power supply is supported. true if supported, false otherwise.
interfaces	Array <USBInterface>	No	No	Supported interface attributes.

USBDevice

Describes the USB device information.

System capability: SystemCapability.USB.USBManager

Name	Type	Read-Only	Optional	Description
busNum	number	No	No	Bus address.
devAddress	number	No	No	Device address.
serial	string	No	No	Sequence number.
name	string	No	No	Device name.
manufacturerName	string	No	No	Device manufacturer.
productName	string	No	No	Product name.
version	string	No	No	Version number.
vendorId	number	No	No	Vendor ID.
productId	number	No	No	Product ID.
clazz	number	No	No	Device class.
subClass	number	No	No	Device subclass.
protocol	number	No	No	Device protocol code.
configs	Array<USBConfiguration>	No	No	Device configuration descriptor information.

USBDevicePipe

Describes a USB device pipe, which is used to determine a USB device.

System capability: SystemCapability.USB.USBManager

Name	Type	Read-Only	Optional	Description
busNum	number	No	No	Bus address.
devAddress	number	No	No	Device address.

USBDeviceRequestParams¹²⁺

Describes control transfer parameters.

System capability: SystemCapability.USB.USBManager

Name	Type	Read-Only	Optional	Description
bmRequestType	number	No	No	Control request type.
bRequest	number	No	No	Request type.
wValue	number	No	No	Request parameter.
wIndex	number	No	No	Index of the request parameter.
wLength	number	No	No	Length of the requested data.
data	Uint8Array	No	No	Buffer for writing or reading data.

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

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.

USBAccessory¹⁴⁺

Describes the USB accessory information.

System capability: SystemCapability.USB.USBManager

Name	Type	Read-Only	Optional	Description
manufacturer	string	No	No	Manufacturer of an accessory.
product	string	No	No	Product type of an accessory.
description	string	No	No	Description of an accessory.
version	string	No	No	Version of an accessory.
serialNumber	string	No	No	SN of an accessory.

USBAccessoryHandle¹⁴⁺

Describes the USB accessory handle.

System capability: SystemCapability.USB.USBManager

Name	Type	Read-Only	Optional	Description
accessoryFd	number	No	No	Accessory file descriptor. A valid accessoryFd is a positive integer.

UsbDataTransferParams¹⁸⁺

As a USB data transfer interface, it is required for a client to initiate a transfer request.

System capability: SystemCapability.USB.USBManager

Name	Type	Read-Only	Optional	Description
devPipe	USBDevicePipe	No	No	Bus address and device address, which are obtained by calling connectDevice.
flags	UsbTransferFlags	No	No	USB transfer flag.
endpoint	number	No	No	Endpoint address, which is a positive integer.
type	UsbEndpointTransferType	No	No	Transfer type.
timeout	number	No	No	Timeout interval, in milliseconds.
length	number	No	No	Expected length of the data buffer, in bytes. The value must be a non-negative number.
callback	AsyncCallback<SubmitTransferCallback>	No	No	Information returned by the callback.
userData	Uint8Array	No	No	User data.
buffer	Uint8Array	No	No	Buffer, which is used to store data for read or write requests.
isoPacketCount	number	No	No	Number of data packets during real-time transfer, used only for I/Os with real-time transfer endpoints. The value must be a non-negative integer.

UsbTransferFlags¹⁸⁺

Enumerates USB transfer flags.

System capability: SystemCapability.USB.USBManager

Name	Value	Description
USB_TRANSFER_SHORT_NOT_OK	0	Reports short frames as errors.
USB_TRANSFER_FREE_BUFFER	1	Automatically releases the transfer buffer.
USB_TRANSFER_FREE_TRANSFER	2	Automatically transfers after the callback is complete.
USB_TRANSFER_ADD_ZERO_PACKET	3	Adds an additional data packet to the transfer.

UsbEndpointTransferType¹⁸⁺

Enumerates USB transfer types.

System capability: SystemCapability.USB.USBManager

Name	Value	Description
TRANSFER_TYPE_ISOCHRONOUS	0x1	Real-time transfer.
TRANSFER_TYPE_BULK	0x2	Performs bulk transfer.
TRANSFER_TYPE_INTERRUPT	0x3	Interrupt transfer.

SubmitTransferCallback¹⁸⁺

Transfers USB data packets in an asynchronous manner.

System capability: SystemCapability.USB.USBManager

Name	Type	Read-Only	Optional	Description
actualLength	number	No	No	Actual length of data to be read or written, in bytes.
status	UsbTransferStatus	No	No	Status after reading or writing is complete.
isoPacketDescs	Array<Readonly<UsbIsoPacketDescriptor>>	No	No	Packet information transferred in real time.

UsbTransferStatus¹⁸⁺

Enumerates the status code returned after data processing is complete.

System capability: SystemCapability.USB.USBManager

Name	Value	Description
TRANSFER_COMPLETED	0	Transfer completed.
TRANSFER_ERROR	1	Transfer failed.
TRANSFER_TIMED_OUT	2	Transfer timeout.
TRANSFER_CANCELED	3	Transfer canceled.
TRANSFER_STALL	4	Transfer stalled (at bulk/interrupt endpoint).
TRANSFER_NO_DEVICE	5	Device disconnected.
TRANSFER_OVERFLOW	6	Data overflow.

UsbIsoPacketDescriptor¹⁸⁺

Describes packet information returned in real time by the transfer callback.

System capability: SystemCapability.USB.USBManager

Name	Type	Read-Only	Optional	Description
length	number	No	No	Expected length of data to be read or written, in bytes.
actualLength	number	No	No	Actual length of data to be read or written, in bytes.
status	UsbTransferStatus	No	No	Status returned by callback.

USBControlParams^(deprecated)

Describes control transfer parameters.

NOTE

This API is supported since API version 9 and deprecated since API version 18. You are advised to use USBDeviceRequestParams instead.

System capability: SystemCapability.USB.USBManager

Name	Type	Read-Only	Optional	Description
request	number	No	No	Request type.
target	USBRequestTargetType	No	No	Request target type.
reqType	USBControlRequestType	No	No	Control request type.
value	number	No	No	Request parameter.
index	number	No	No	Index of the request parameter.
data	Uint8Array	No	No	Buffer for writing or reading data.

@ohos.usbManager (USB Manager)

Modules to Import

How to Use

usbManager.getDevices

usbManager.connectDevice

usbManager.hasRight

usbManager.requestRight

usbManager.removeRight

usbManager.claimInterface

usbManager.releaseInterface

usbManager.setConfiguration

usbManager.setInterface

usbManager.getRawDescriptor

usbManager.getFileDescriptor

usbManager.usbControlTransfer12+

usbManager.bulkTransfer

usbManager.usbSubmitTransfer18+

usbManager.usbCancelTransfer18+

usbManager.closePipe

usbManager.hasAccessoryRight14+

usbManager.requestAccessoryRight14+

usbManager.cancelAccessoryRight14+

usbManager.getAccessoryList14+

usbManager.openAccessory14+

usbManager.closeAccessory14+

usbManager.resetUsbDevice20+

usbManager.controlTransfer(deprecated)

USBEndpoint

USBInterface

USBConfiguration

USBDevice

USBDevicePipe

USBDeviceRequestParams12+

USBRequestTargetType

USBControlRequestType

USBRequestDirection

USBAccessory14+

USBAccessoryHandle14+

UsbDataTransferParams18+

UsbTransferFlags18+

UsbEndpointTransferType18+

SubmitTransferCallback18+

UsbTransferStatus18+

UsbIsoPacketDescriptor18+

USBControlParams(deprecated)

usbManager.usbControlTransfer¹²⁺

usbManager.usbSubmitTransfer¹⁸⁺

usbManager.usbCancelTransfer¹⁸⁺

usbManager.hasAccessoryRight¹⁴⁺

usbManager.requestAccessoryRight¹⁴⁺

usbManager.cancelAccessoryRight¹⁴⁺

usbManager.getAccessoryList¹⁴⁺

usbManager.openAccessory¹⁴⁺

usbManager.closeAccessory¹⁴⁺

usbManager.resetUsbDevice²⁰⁺

usbManager.controlTransfer^(deprecated)

USBDeviceRequestParams¹²⁺

USBAccessory¹⁴⁺

USBAccessoryHandle¹⁴⁺

UsbDataTransferParams¹⁸⁺

UsbTransferFlags¹⁸⁺

UsbEndpointTransferType¹⁸⁺

SubmitTransferCallback¹⁸⁺

UsbTransferStatus¹⁸⁺

UsbIsoPacketDescriptor¹⁸⁺

USBControlParams^(deprecated)