本模块主要提供管理USB设备的相关功能,包括主机端的查询USB设备列表、批量数据传输、控制命令传输、权限控制等;设备端的端口管理、功能切换及查询等。适用于需要与USB设备进行数据交互、管理USB设备权限、动态切换USB设备模式等场景。
本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
凡是参数类型为USBDevicePipe的接口,都需要执行如下操作:
在使用接口前:
调用usbManager.getDevices获取设备列表。
调用usbManager.requestRight获取请求权限。
调用usbManager.connectDevice得到USBDevicePipe作为参数。
在使用接口后:
调用usbManager.closePipe关闭设备连接通道。
图1 usbManager接口使用流程图

getDevices(): Array<Readonly<USBDevice>>
获取接入主机的USB设备列表。调用成功后返回已连接设备的详细信息列表,包括设备名称、厂商产品信息等。
三方应用无法通过getDevices()接口直接获取serial字段的设备序列号信息(该字段对三方应用不可用)。如需获取序列号,需要在申请设备访问权限后,自行发起控制传输获取。
如果设备已通过企业设备管理(EDM)限制策略管控USB(如禁用USB能力、设置USB设备可用名单、禁用特定USB设备类型等),获取的设备列表可能为空或仅包含被允许的设备。具体情况请参考@ohos.enterprise.restrictions (限制类策略)和@ohos.enterprise.usbManager (USB管理)。
系统能力: SystemCapability.USB.USBManager
返回值:
| 类型 | 说明 |
|---|---|
| Array<Readonly<USBDevice>> | 设备信息列表。 |
错误码:
以下错误码的详细介绍请参见通用错误码。
| 错误码ID | 错误信息 |
|---|---|
| 801 | Capability not supported. 适用版本:18+ |
示例:
try {
let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
console.info(`devicesList = ${JSON.stringify(devicesList)}`);
} catch (err) {
console.error(`getDevices failed. Code: ${err.code}, message: ${err.message}`);
}
/*
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,
},
],
},
],
},
],
},
]
*/ connectDevice(device: USBDevice): Readonly<USBDevicePipe>
根据getDevices()返回的设备信息打开USB设备,调用成功后建立设备连接通道,可以进行后续的数据传输和设备控制操作。使用完后需要调用usbManager.closePipe关闭设备连接通道。如果USB服务异常,会返回undefined,注意需要对接口返回值做判空处理。
系统能力: SystemCapability.USB.USBManager
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| device | USBDevice | 是 | USB设备信息,用getDevices获取的busNum和devAddress确定设备,当前其他属性(如name、vendorId等)不参与设备匹配。 |
返回值:
| 类型 | 说明 |
|---|---|
| Readonly<USBDevicePipe> | USB设备连接通道对象,用于后续的数据传输和设备控制操作。 |
错误码:
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
| 801 | Capability not supported. 适用版本:18+ |
| 14400001 | Access right denied. Call requestRight to get the USBDevicePipe access right first. |
示例:
async 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];
try {
let rightResult = await usbManager.requestRight(device.name);
} catch (err) {
console.error(`request right failed. Code: ${err.code}, message: ${err.message}`);
return;
}
// 打开USB设备并建立连接通道,若USB服务异常会返回undefined,使用完后需调用closePipe关闭
let devicePipe: usbManager.USBDevicePipe = usbManager.connectDevice(device);
if (devicePipe == undefined) {
console.error(`connect device failed`);
return;
}
console.info(`devicePipe = ${devicePipe}`);
usbManager.closePipe(devicePipe);
} hasRight(deviceName: string): boolean
判断是否有权访问该设备。适用于在调用requestRight申请权限或connectDevice建立连接前,先确认应用是否已拥有该设备的访问权限,避免重复申请的场景。
如果应用有权访问设备则返回true;无权访问设备则返回false。
系统能力: SystemCapability.USB.USBManager
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| deviceName | string | 是 | 设备名称,来自getDevices获取的设备列表USBDevice的name。 |
返回值:
| 类型 | 说明 |
|---|---|
| boolean | true表示有访问设备的权限,false表示没有访问设备的权限。 |
错误码:
以下错误码的详细介绍请参见通用错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
| 801 | Capability not supported. 适用版本:18+ |
示例:
async function hasRight(): Promise<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];
try {
await usbManager.requestRight(device.name);
} catch (err) {
console.error(`request right failed. Code: ${err.code}, message: ${err.message}`);
return false;
}
let right: boolean = usbManager.hasRight(device.name);
console.info(`${right}`);
return right;
} requestRight(deviceName: string): Promise<boolean>
请求应用访问设备的临时权限。使用Promise异步回调返回结果。系统应用默认拥有访问设备权限,无需调用此接口。
系统能力: SystemCapability.USB.USBManager
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| deviceName | string | 是 | 设备名称,来自getDevices获取的设备列表USBDevice的name。 |
返回值:
| 类型 | 说明 |
|---|---|
| Promise<boolean> | Promise对象,返回临时权限的申请结果。返回true表示临时权限申请成功;返回false则表示临时权限申请失败。 |
错误码:
以下错误码的详细介绍请参见通用错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
| 801 | Capability not supported. 适用版本:18+ |
示例:
import {BusinessError} from '@kit.BasicServicesKit';
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}`);
});
} removeRight(deviceName: string): boolean
移除应用访问设备的权限。系统应用默认拥有访问设备权限,调用此接口不会产生影响。返回true表示权限移除成功;返回false则表示权限移除失败。
系统能力: SystemCapability.USB.USBManager
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| deviceName | string | 是 | 设备名称,来自getDevices获取的设备列表USBDevice的name。 |
返回值:
| 类型 | 说明 |
|---|---|
| boolean | 返回权限移除结果。返回true表示权限移除成功;返回false则表示权限移除失败。 |
错误码:
以下错误码的详细介绍请参见通用错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
| 801 | Capability not supported. 适用版本:18+ |
示例:
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];
try {
if (usbManager.removeRight(device.name)) {
console.info(`Succeed in removing right`);
return true;
}
} catch (err) {
console.error(`remove right failed. Code: ${err.code}, message: ${err.message}`);
}
return false;
} claimInterface(pipe: USBDevicePipe, iface: USBInterface, force?: boolean): number
声明对USB设备某个接口的控制权。UsbManager获得独占权,可以通过UsbManager提供的接口进行数据传输等操作。如需声明独占接口,并感知其它应用声明冲突,请使用claimInterfaceExclusive。使用完后需调用releaseInterface释放该接口的控制权。
在USB编程中,claim interface是一个常见操作,指的是应用请求操作系统将某个USB接口从内核驱动中释放并交由用户空间程序控制。
下面用到的claim通信接口都表示claim interface操作。
使用场景: 在需要进行USB数据传输时,需要先声明接口控制权以独占访问该接口。例如,在USB存储设备读写、USB摄像头数据采集、USB串口通信等场景中,都需要先声明接口控制权。
系统能力: SystemCapability.USB.USBManager
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pipe | USBDevicePipe | 是 | 用于确定总线地址和设备地址,需要调用connectDevice获取。 |
| iface | USBInterface | 是 | 用于确定需要获取控制的接口对象,需要调用getDevices获取设备信息并通过id确定唯一接口。 |
| force | boolean | 否 | 可选参数,是否强制获取。默认值为false,表示不强制获取,如果无内核驱动占用该接口,则获取成功,否则获取失败;设置为true时,将强制释放内核驱动对该接口的控制权并交由用户空间程序控制。 |
返回值:
| 类型 | 说明 |
|---|---|
| number | claim通信接口成功返回0;claim通信接口失败返回其他错误码如下: - 88080389:服务未启动,可能原因:1.无设备插入;2.服务异常退出。 - 88080486:服务初始化中,请稍后重试。 - 88080488:无设备访问权限,请先调用requestRight接口申请授权。 - -1:驱动异常。可能原因:1、设备连接不稳定或已断开;2、USB驱动加载失败;3、内核USB模块异常。 |
错误码:
以下错误码的详细介绍请参见通用错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
| 801 | Capability not supported. 适用版本:18+ |
示例:
async 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];
let rightResult = await usbManager.requestRight(device.name);
if (!rightResult) {
console.error(`request right failed`);
return;
}
let devicePipe: usbManager.USBDevicePipe = usbManager.connectDevice(device);
if (devicePipe == undefined) {
console.error(`connect device failed`);
return;
}
let interfaces: usbManager.USBInterface = device.configs?.[0]?.interfaces?.[0];
// 声明接口控制权,返回0表示声明成功,失败时需关闭设备通道并退出
let ret: number = usbManager.claimInterface(devicePipe, interfaces);
if (ret !== 0) {
console.error(`claim interface failed`);
usbManager.closePipe(devicePipe);
return;
}
console.info(`claimInterface = ${ret}`);
// 释放此前声明的接口控制权
ret = usbManager.releaseInterface(devicePipe, interfaces);
console.info(`releaseInterface = ${ret}`);
usbManager.closePipe(devicePipe);
} claimInterfaceExclusive(pipe: USBDevicePipe, iface: USBInterface, force?: boolean, onConflict?: Callback<InterfaceConflictInfo>): void
以独占方式声明USB设备接口。本接口在调用时检查其他进程是否已占用指定的USB接口,避免声明时发生冲突。设置force为true时,操作系统会先从内核驱动程序中释放该接口,再将控制权授予调用方应用。独占声明成功后,其他进程仍可通过usbManager.claimInterface声明同一接口(即本接口的独占声明不会阻止其他进程的声明行为,与claimInterface声明成功后其他程序无法访问该接口的独占语义不同);可使用onConflict回调接收此类冲突通知。使用完后需调用releaseInterface释放该接口的控制权。
使用场景: 适用于需要独占访问USB接口并及时感知其他进程访问冲突的场景(如多进程竞争使用同一USB接口);若无需感知其他进程的冲突访问,直接使用usbManager.claimInterface即可。
起始版本: 26.0.1
系统能力: SystemCapability.USB.USBManager
模型约束: 此接口仅可在Stage模型下使用。
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pipe | USBDevicePipe | 是 | 总线地址和设备地址,通过调用connectDevice获取。 |
| iface | USBInterface | 是 | 目标USB接口对象。可以使用getDevices获取设备信息,并根据ID识别USB接口。 |
| force | boolean | 否 | 是否强制声明USB接口。默认值为false,表示不强制声明USB接口。 |
| onConflict | Callback<InterfaceConflictInfo> | 否 | 回调函数,返回独占声明成功后其他进程通过非独占的usbManager.claimInterface接口声明同一USB接口时的冲突信息。如果不指定此参数,则发生此类冲突时不发送通知。 |
错误码:
| 错误码ID | 错误信息 |
|---|---|
| 14400001 | Permission denied. |
| 14400004 | Service exception. |
| 14400007 | Resource busy. Possible cause: The interface is claimed by another program or driver. |
| 14400010 | USB driver error. Possible causes: 1. The device is not connected using connectDevice. 2. The USB device state is abnormal. |
示例:
async function claimInterfaceExclusive() {
// 获取USB设备列表
let devicesList: Array<usbManager.USBDevice>;
try {
devicesList = usbManager.getDevices();
} catch (err) {
console.error(`getDevices failed, err=${JSON.stringify(err)}`);
return;
}
if (!devicesList || devicesList.length == 0) {
console.info(`device list is empty`);
return;
}
let device: usbManager.USBDevice = devicesList?.[0];
// 申请设备访问权限
let rightResult: boolean;
try {
rightResult = await usbManager.requestRight(device.name);
} catch (err) {
console.error(`requestRight failed, err=${JSON.stringify(err)}`);
return;
}
if (!rightResult) {
console.error(`request right failed`);
return;
}
// 建立设备连接
let devicePipe: usbManager.USBDevicePipe;
try {
devicePipe = usbManager.connectDevice(device);
} catch (err) {
console.error(`connectDevice failed, err=${JSON.stringify(err)}`);
return;
}
if (devicePipe == undefined) {
console.error(`connect device failed`);
return;
}
let interfaces: usbManager.USBInterface = device.configs?.[0]?.interfaces?.[0];
// 独占声明接口,并注册冲突回调
try {
usbManager.claimInterfaceExclusive(devicePipe, interfaces, false, (conflictInfo: usbManager.InterfaceConflictInfo) => {
console.info(`interface conflict: busNum=${conflictInfo.busNum}, devAddr=${conflictInfo.devAddr}, interfaceId=${conflictInfo.interfaceId}`);
});
} catch (err) {
console.error(`claimInterfaceExclusive failed, err=${JSON.stringify(err)}`);
}
console.info(`claimInterfaceExclusive success`);
// 释放接口并关闭连接
try {
let ret: number = usbManager.releaseInterface(devicePipe, interfaces);
console.info(`releaseInterface = ${ret}`);
} catch (err) {
console.error(`releaseInterface failed, err=${JSON.stringify(err)}`);
}
try {
usbManager.closePipe(devicePipe);
} catch (err) {
console.error(`closePipe failed, err=${JSON.stringify(err)}`);
}
} releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number
释放claim过的通信接口。
系统能力: SystemCapability.USB.USBManager
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pipe | USBDevicePipe | 是 | 用于确定总线地址和设备地址,需要调用connectDevice获取。 |
| iface | USBInterface | 是 | 用于确定需要释放控制的接口对象,需要调用getDevices获取设备信息并通过id确定唯一接口。 |
返回值:
| 类型 | 说明 |
|---|---|
| number | 释放接口成功返回0;释放接口失败返回其他错误码。 - 88080389:服务未启动,可能原因:1.无设备插入;2.服务异常退出。 - 88080486:服务初始化中,请稍后重试。 - 88080488:无设备访问权限,请先调用requestRight接口申请授权。 - -1:驱动异常。可能原因:1、设备连接不稳定或已断开;2、USB驱动加载失败;3、内核USB模块异常。 |
错误码:
以下错误码的详细介绍请参见通用错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
| 801 | Capability not supported. 适用版本:18+ |
示例:
async 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];
let rightResult = await usbManager.requestRight(device.name);
if (!rightResult) {
console.error(`request right failed`);
return;
}
let devicePipe: usbManager.USBDevicePipe = usbManager.connectDevice(device);
if (devicePipe == undefined) {
console.error(`connect device failed`);
return;
}
let interfaces: usbManager.USBInterface = device.configs?.[0]?.interfaces?.[0];
let ret: number = usbManager.claimInterface(devicePipe, interfaces);
if (ret !== 0) {
console.error(`claim interface failed`);
usbManager.closePipe(devicePipe);
return;
}
ret = usbManager.releaseInterface(devicePipe, interfaces);
console.info(`releaseInterface = ${ret}`);
usbManager.closePipe(devicePipe);
} setConfiguration(pipe: USBDevicePipe, config: USBConfiguration): number
设置设备配置。适用于多功能USB设备需要切换工作模式的场景,如打印机+扫描仪组合设备切换为打印模式或扫描模式、设备从低功耗配置切换到高功耗配置以启用全部功能等。调用成功后系统会将设备配置切换为指定的配置,后续的数据传输和设备操作将基于新配置进行。
系统能力: SystemCapability.USB.USBManager
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pipe | USBDevicePipe | 是 | 用于确定总线地址和设备地址,需要调用connectDevice获取。 |
| config | USBConfiguration | 是 | 用于确定需要设置的配置,需要调用getDevices获取设备信息并通过id确定唯一配置。 |
返回值:
| 类型 | 说明 |
|---|---|
| number | 返回设置设备配置操作的结果。设置设备配置成功返回0;设置设备配置失败返回其他错误码。 - 88080389:服务未启动,可能原因:1.无设备插入;2.服务异常退出。 - 88080486:服务初始化中,请稍后重试。 - 88080488:无设备访问权限,请先调用requestRight接口申请授权。 - -1:驱动异常。可能原因:1、设备连接不稳定或已断开;2、USB驱动加载失败;3、内核USB模块异常。 - -17:I/O(Input/Output)失败。可能原因:1.设备通信异常导致I/O操作失败;2.数据传输过程中发生中断。 |
错误码:
以下错误码的详细介绍请参见通用错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
| 801 | Capability not supported. 适用版本:18+ |
示例:
async 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];
let rightResult = await usbManager.requestRight(device.name);
if (!rightResult) {
console.error(`request right failed`);
return;
}
let devicePipe: usbManager.USBDevicePipe = usbManager.connectDevice(device);
if (devicePipe == undefined) {
console.error(`connect device failed`);
return;
}
let config: usbManager.USBConfiguration = device.configs?.[0];
let interfaces: usbManager.USBInterface = device.configs?.[0]?.interfaces?.[0];
let claimRet: number = usbManager.claimInterface(devicePipe, interfaces);
if (claimRet !== 0) {
console.error(`claim interface failed`);
usbManager.closePipe(devicePipe);
return;
}
// 设置设备配置,将设备切换为指定的配置
let ret: number = usbManager.setConfiguration(devicePipe, config);
console.info(`setConfiguration = ${ret}`);
usbManager.closePipe(devicePipe);
} setInterface(pipe: USBDevicePipe, iface: USBInterface): number
设置设备接口。调用成功后系统会将接口切换到指定的替代设置,端点配置将随之改变以匹配传输类型要求。
一个USB接口可能存在多重选择模式(alternateSetting),支持动态切换。使用的场景:数据传输时,通过该接口可重新设置端点,使端点与传输类型匹配;在调用该接口前需要通过usbManager.claimInterface claim通信接口。
系统能力: SystemCapability.USB.USBManager
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pipe | USBDevicePipe | 是 | 用于确定总线地址和设备地址,需要调用connectDevice获取。 |
| iface | USBInterface | 是 | 用于确定需要设置的接口,需要调用getDevices获取设备信息,通过接口的id和alternateSetting共同确定唯一接口。其中id为接口的唯一标识符,alternateSetting用于在同一接口的多个可选模式间切换,为0时表示不支持可选模式。 |
返回值:
| 类型 | 说明 |
|---|---|
| number | 返回设置设备接口操作的结果。设置设备接口成功返回0;设置设备接口失败返回其他错误码。 - 88080389:服务未启动,可能原因:1.无设备插入;2.服务异常退出。 - 88080486:服务初始化中,请稍后重试。 - 88080488:无设备访问权限,请先调用requestRight接口申请授权。 - -1:驱动异常。可能原因:1、设备连接不稳定或已断开;2、USB驱动加载失败;3、内核USB模块异常。 |
错误码:
以下错误码的详细介绍请参见通用错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
| 801 | Capability not supported. 适用版本:18+ |
示例:
async 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];
let rightResult = await usbManager.requestRight(device.name);
if (!rightResult) {
console.error(`request right failed`);
return;
}
let devicePipe: usbManager.USBDevicePipe = usbManager.connectDevice(device);
if (devicePipe == undefined) {
console.error(`connect device failed`);
return;
}
let interfaces: usbManager.USBInterface = device.configs?.[0]?.interfaces?.[0];
let ret: number = usbManager.claimInterface(devicePipe, interfaces);
if (ret !== 0) {
console.error(`claim interface failed`);
usbManager.closePipe(devicePipe);
return;
}
// 切换接口到指定的备用设置,使端点配置与传输类型匹配
ret = usbManager.setInterface(devicePipe, interfaces);
console.info(`setInterface = ${ret}`);
ret = usbManager.releaseInterface(devicePipe, interfaces);
console.info(`releaseInterface = ${ret}`);
usbManager.closePipe(devicePipe);
} getRawDescriptor(pipe: USBDevicePipe): Uint8Array
获取原始的USB描述符。适用于需要获取设备原始描述符数据并自行解析的场景。如果USB服务异常,会返回undefined,注意需要对接口返回值做判空处理。
系统能力: SystemCapability.USB.USBManager
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pipe | USBDevicePipe | 是 | 用于确定总线地址和设备地址,需要调用connectDevice获取。 |
返回值:
| 类型 | 说明 |
|---|---|
| Uint8Array | 返回获取的原始数据;失败返回undefined。 |
错误码:
以下错误码的详细介绍请参见通用错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
| 801 | Capability not supported. 适用版本:18+ |
示例:
async function getRawDescriptor() {
let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
if (!devicesList || devicesList.length == 0) {
console.info(`device list is empty`);
return;
}
try {
let rightResult = await usbManager.requestRight(devicesList?.[0]?.name);
} catch (err) {
console.error(`request right failed. Code: ${err.code}, message: ${err.message}`);
return;
}
let devicePipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList?.[0]);
if (devicePipe == undefined) {
console.error(`connect device failed`);
return;
}
// 获取原始的USB描述符数据,失败时可能返回undefined,需做判空处理
usbManager.getRawDescriptor(devicePipe);
usbManager.closePipe(devicePipe);
} getFileDescriptor(pipe: USBDevicePipe): number
获取文件描述符。该接口适用于需要通过文件描述符访问USB设备的场景,获取后可结合文件读写能力与设备进行数据交互。如果USB服务异常,会返回错误码,注意需要对接口返回值做错误码检查处理。
系统能力: SystemCapability.USB.USBManager
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pipe | USBDevicePipe | 是 | 用于确定总线地址和设备地址,需要调用connectDevice获取。 |
返回值:
| 类型 | 说明 |
|---|---|
| number | 返回设备对应的文件描述符,失败返回其他错误码。 - 88080486:服务初始化中,请稍后重试。 - 88080488:无设备访问权限,请先调用requestRight接口申请授权。 - -1:驱动异常。可能原因:1、设备连接不稳定或已断开;2、USB驱动加载失败;3、内核USB模块异常。 |
错误码:
以下错误码的详细介绍请参见通用错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
| 801 | Capability not supported. 适用版本:18+ |
示例:
async function getFileDescriptor() {
let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
if (!devicesList || devicesList.length == 0) {
console.info(`device list is empty`);
return;
}
let rightResult = await usbManager.requestRight(devicesList?.[0]?.name);
if (!rightResult) {
console.error(`request right failed`);
return;
}
let devicePipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList?.[0]);
if (devicePipe == undefined) {
console.error(`connect device failed`);
return;
}
// 获取设备对应的文件描述符
let ret: number = usbManager.getFileDescriptor(devicePipe);
console.info(`getFileDescriptor = ${ret}`);
let closeRet: number = usbManager.closePipe(devicePipe);
console.info(`closePipe = ${closeRet}`);
} usbControlTransfer(pipe: USBDevicePipe, requestparam: USBDeviceRequestParams, timeout?: number): Promise<number>
控制传输。调用成功后完成控制命令的传输,返回传输或接收到的数据块大小。适用于需要与USB设备进行控制命令交互的场景,如获取设备描述符、设置设备地址、发送厂商自定义命令、配置HID(Human Interface Device,人机接口设备)设备特性等。使用Promise异步回调。
系统能力: SystemCapability.USB.USBManager
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pipe | USBDevicePipe | 是 | 用于确定总线地址和设备地址,需要调用connectDevice获取。 |
| requestparam | USBDeviceRequestParams | 是 | 控制传输参数,包含bmRequestType、bRequest、wValue、wIndex、wLength、data等字段,参数传参类型请参考USB协议规范,根据具体设备和控制请求类型设置。 |
| timeout | number | 否 | 超时时间(单位:ms),可选参数,指定时间内等待控制传输完成,若在指定时间内传输完成则正常返回,否则返回超时;默认值为0,表示无限等待直到传输完成。传入负数时抛出参数错误异常。 |
返回值:
| 类型 | 说明 |
|---|---|
| Promise<number> | Promise对象,获取传输或接收到的数据块大小。失败返回其他错误码。 - -1:驱动异常。可能原因:1、设备连接不稳定或已断开;2、USB驱动加载失败;3、内核USB模块异常。 |
错误码:
以下错误码的详细介绍请参见通用错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
| 801 | Capability not supported. 适用版本:18+ |
示例:
import {BusinessError} from '@kit.BasicServicesKit';
// 控制传输参数:根据USB协议规范、设备描述符或设备规格文档设置各字段值
// bmRequestType:请求控制类型,常见取值示例:0x00(标准请求,主机向设备)、0x20(类请求,主机向设备)、0x40(厂商请求,主机向设备)、0x80(标准请求,设备向主机)
// bRequest:具体控制请求命令(如获取描述符、设置地址等)
// wValue:请求参数内容
// wIndex:请求参数的索引值
// wLength:数据长度
// data:用于写入或读取的缓冲区
let param: usbManager.USBDeviceRequestParams = {
bmRequestType: 0x80,
bRequest: 0x06,
wValue: 0x01 << 8 | 0,
wIndex: 0,
wLength: 18,
data: new Uint8Array(18)
};
async function usbControlTransfer() {
let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
if (!devicesList || devicesList.length == 0) {
console.info(`device list is empty`);
return;
}
let rightResult = await usbManager.requestRight(devicesList?.[0]?.name);
if (!rightResult) {
console.error(`request right failed`);
return;
}
let devicePipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList?.[0]);
if (devicePipe == undefined) {
console.error(`connect device failed`);
return;
}
usbManager.usbControlTransfer(devicePipe, param).then((ret: number) => {
console.info(`usbControlTransfer = ${ret}`);
}).catch((error: BusinessError) => {
console.error(`usbControlTransfer failed: ${error.code}, message: ${error.message}`);
}).finally(() => {
usbManager.closePipe(devicePipe);
});
} bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, timeout?: number): Promise<number>
批量传输。调用成功后完成批量数据传输,返回实际传输或接收到的数据块大小。使用Promise异步回调。与usbSubmitTransfer相比,bulkTransfer适合简单的批量传输场景,通过独立参数直接传递数据和端点,使用Promise异步返回结果。usbSubmitTransfer适合需要更灵活控制的场景,通过UsbDataTransferParams对象封装参数,支持异步回调,并可通过usbCancelTransfer取消传输请求。
单次批量传输的传输数据总量(包括pipe、endpoint、buffer、timeout)请控制在200KB以下,数据总量过大会导致传输失败返回-1;在调用接口前需要通过usbManager.claimInterface claim通信接口。
系统能力: SystemCapability.USB.USBManager
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pipe | USBDevicePipe | 是 | 用于确定总线地址和设备地址,需要调用connectDevice获取。 |
| endpoint | USBEndpoint | 是 | 用于确定传输的端点,需要调用getDevices获取设备信息列表。通过endpoint的address确定端点地址,direction用于确定端点的传输方向(0表示输出,128表示输入),interfaceId用于确定所属接口,当前其他属性不做处理。 |
| buffer | Uint8Array | 是 | 用于写入或读取数据的缓冲区,数组长度即为缓冲区大小。用于批量传输时写入或读取数据。 |
| timeout | number | 否 | 超时时间(单位:ms),可选参数,指定时间内等待批量传输完成,若在指定时间内传输完成则正常返回,否则返回超时;默认值为0,表示无限等待直到传输完成。传入负数时抛出参数错误异常。 |
返回值:
| 类型 | 说明 |
|---|---|
| Promise<number> | Promise对象,获取传输或接收到的数据块大小。失败返回其他错误码如下: - -1:驱动异常。可能原因:1、设备连接不稳定或已断开;2、USB驱动加载失败;3、内核USB模块异常。 |
错误码:
以下错误码的详细介绍请参见通用错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
| 801 | Capability not supported. 适用版本:18+ |
示例:
以下示例代码只是调用bulkTransfer接口的必要流程。实际调用时,设备开发者需要遵循目标USB设备的协议规范进行调用。具体协议要求请参考设备的技术文档,确保数据的正确传输和设备的兼容性。
import {BusinessError} from '@kit.BasicServicesKit';
// usbManager.getDevices 接口返回数据集合,取其中一个设备对象,并获取权限。
// 把获取到的设备对象作为参数传入usbManager.connectDevice;当usbManager.connectDevice接口成功返回之后;
// 才可以调用第三个接口usbManager.claimInterface。当usbManager.claimInterface 调用成功以后,再调用该接口。
async 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];
await usbManager.requestRight(device.name);
if (!usbManager.hasRight(device.name)) {
console.error(`request right fail`);
return;
}
let devicePipe: usbManager.USBDevicePipe = usbManager.connectDevice(device);
if (devicePipe == undefined) {
console.error(`connect device failed`);
return;
}
for (let i = 0; i < device.configs?.[0]?.interfaces?.length; i++) {
// 筛选传输类型为批量传输的端点(attributes为2表示bulk端点)
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);
if (ret !== 0) { console.error(`claimInterface failed, code: ${ret}`); continue; }
let buffer = new Uint8Array(128);
await usbManager.bulkTransfer(devicePipe, endpoint, buffer).then((size: number) => {
console.info(`bulkTransfer = ${size}`);
}).catch((error: BusinessError) => {
console.error(`Failed to transfer. Code: ${error.code}, message: ${error.message}`);
});
usbManager.releaseInterface(devicePipe, interfaces);
}
}
usbManager.closePipe(devicePipe);
} usbSubmitTransfer(transfer: UsbDataTransferParams): void
提交异步传输请求,调用后立即返回,实际读写操作的结果以回调的方式返回。可通过调用usbCancelTransfer接口取消异步传输请求。
系统能力: SystemCapability.USB.USBManager
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| transfer | UsbDataTransferParams | 是 | 该参数对象用于通用USB数据传输,客户端需要填充其中的参数,用以发起传输请求。在调用该接口前需要通过usbManager.claimInterface claim通信接口。 |
错误码:
| 错误码ID | 错误信息 |
|---|---|
| 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. |
示例:
以下示例代码需要放入具体的方法中执行,只是调用usbSubmitTransfer接口的必要流程,实际调用时,设备开发者需要遵循目标USB设备的协议规范进行调用,具体协议要求请参考设备的技术文档,确保数据的正确传输和设备的兼容性。
// usbManager.getDevices 接口返回数据集合,取其中一个设备对象,并获取权限。
// 把获取到的设备对象作为参数传入usbManager.connectDevice;当usbManager.connectDevice接口成功返回之后;
// 才可以调用第三个接口usbManager.claimInterface。当usbManager.claimInterface 调用成功以后,再调用该接口。
async 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];
await usbManager.requestRight(device.name);
if (!usbManager.hasRight(device.name)) {
console.error(`request right fail`);
return;
}
let devicePipe: usbManager.USBDevicePipe = usbManager.connectDevice(device);
if (devicePipe == undefined) {
console.error(`connect device failed`);
return;
}
// 获取endpoint端点地址:筛选方向为输出(direction为0)且传输类型为批量传输(type为2)的端点
let endpoint = device.configs?.[0]?.interfaces?.[0]?.endpoints.find((value) => {
return value.direction === 0 && value.type === 2;
});
// 声明接口控制权,force参数为true表示强制获取
let interfaces: usbManager.USBInterface = device.configs?.[0]?.interfaces?.[0];
let ret: number = usbManager.claimInterface(devicePipe, interfaces, true);
if (ret !== 0) {
console.error(`claim interface failed`);
usbManager.closePipe(devicePipe);
return;
}
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) => {
let relIntfRet: number = usbManager.releaseInterface(devicePipe, interfaces);
console.info(`releaseInterface = ${relIntfRet}`);
usbManager.closePipe(devicePipe);
if (err) {
console.error(`USB transfer failed. Code: ${err.code}, message: ${err.message}`);
return;
}
console.info('callbackData =' + JSON.stringify(callbackData));
};
usbManager.usbSubmitTransfer(transferParams);
console.info('USB transfer request submitted.');
} catch (error) {
console.error(`USB transfer failed. Code: ${error.code}, message: ${error.message}`);
usbManager.releaseInterface(devicePipe, interfaces);
usbManager.closePipe(devicePipe);
}
} usbCancelTransfer(transfer: UsbDataTransferParams): void
取消异步传输请求。适用于需要主动终止未完成USB数据传输的场景,如用户手动取消进行中的数据传输、传输超时后的错误恢复、应用切换时中止当前传输等。
系统能力: SystemCapability.USB.USBManager
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| transfer | UsbDataTransferParams | 是 | 被取消传输的参数,该参数与usbManager.usbSubmitTransfer接口的transfer参数相同。在调用该接口前需要通过usbManager.claimInterface claim通信接口。 |
错误码:
| 错误码ID | 错误信息 |
|---|---|
| 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. |
示例:
以下示例代码需要放入具体的方法中执行,只是调用usbCancelTransfer接口的必要流程。实际调用时,设备开发者需要遵循目标USB设备的协议规范进行调用。具体协议要求请参考设备的技术文档,确保数据的正确传输和设备的兼容性。
// usbManager.getDevices 接口返回数据集合,取其中一个设备对象,并获取权限。
// 把获取到的设备对象作为参数传入usbManager.connectDevice;当usbManager.connectDevice接口成功返回之后;
// 才可以调用第三个接口usbManager.claimInterface.当usbManager.claimInterface 调用成功以后,再调用该接口。
async 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];
let rightResult = await usbManager.requestRight(device.name);
if (!rightResult) {
console.error(`request right failed`);
return;
}
let devicePipe: usbManager.USBDevicePipe = usbManager.connectDevice(device);
if (devicePipe === undefined) {
console.error(`connect device fail`);
return;
}
// 获取endpoint端点地址。
let endpoint = device.configs?.[0]?.interfaces?.[0]?.endpoints.find((value) => {
return value.direction === 0 && value.type === 2;
});
if (endpoint === undefined) {
console.error(`invalid endpoint`);
return;
}
// 声明接口控制权,force参数为true表示强制获取。
let interfaces: usbManager.USBInterface = device.configs?.[0]?.interfaces?.[0];
let ret: number = usbManager.claimInterface(devicePipe, interfaces, true);
if (ret !== 0) {
console.error(`claim interface failed`);
usbManager.closePipe(devicePipe);
return;
}
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. Code: ${error.code}, message: ${error.message}`);
}
ret = usbManager.releaseInterface(devicePipe, interfaces);
console.info(`releaseInterface = ${ret}`);
usbManager.closePipe(devicePipe);
} closePipe(pipe: USBDevicePipe): number
关闭设备连接通道。适用于使用USBDevicePipe完成数据传输和设备控制操作后释放设备连接的场景。
系统能力: SystemCapability.USB.USBManager
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pipe | USBDevicePipe | 是 | 用于确定总线地址和设备地址,需要调用connectDevice获取。 |
返回值:
| 类型 | 说明 |
|---|---|
| number | 关闭设备连接通道成功返回0;关闭设备连接通道失败返回其他错误码。 - 22:服务异常。可能原因:1.USB服务未正常运行;2.设备连接通道状态异常。 |
错误码:
以下错误码的详细介绍请参见通用错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
| 801 | Capability not supported. 适用版本:18+ |
示例:
async function closePipe() {
let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
if (!devicesList || devicesList.length == 0) {
console.info(`device list is empty`);
return;
}
let rightResult = await usbManager.requestRight(devicesList?.[0]?.name);
if (!rightResult) {
console.error(`request right failed`);
return;
}
let devicePipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList?.[0]);
if (devicePipe == undefined) {
console.error(`connect device failed`);
return;
}
let ret: number = usbManager.closePipe(devicePipe);
console.info(`closePipe = ${ret}`);
} hasAccessoryRight(accessory: USBAccessory): boolean
检查应用是否有权访问USB配件。适用于在调用requestAccessoryRight申请权限或openAccessory打开配件前,先确认应用是否已拥有该配件访问权限的场景。
需要调用usbManager.getAccessoryList获取配件列表,得到USBAccessory作为参数。
系统能力: SystemCapability.USB.USBManager
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| accessory | USBAccessory | 是 | USB配件,需要通过getAccessoryList获取。 |
返回值:
| 类型 | 说明 |
|---|---|
| boolean | true表示应用有权访问USB配件,false表示应用无权访问USB配件。 |
错误码:
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
| 801 | Capability not supported. 适用版本:18+ |
| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. |
| 14400005 | Database operation exception. |
| 14401001 | The target USBAccessory not matched. |
示例:
import { BusinessError } from '@kit.BasicServicesKit';
try {
let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList();
let flag = usbManager.hasAccessoryRight(accList?.[0]);
console.info(`Succeeded in hasAccessoryRight, ret:${flag}`);
} catch (error) {
const err: BusinessError = error as BusinessError;
console.error(`hasAccessoryRight error ${err.code}, message is ${err.message}`);
} requestAccessoryRight(accessory: USBAccessory): Promise<boolean>
为当前应用申请访问USB配件的权限。使用Promise异步回调。
需要调用usbManager.getAccessoryList获取配件列表,得到USBAccessory作为参数。
系统能力: SystemCapability.USB.USBManager
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| accessory | USBAccessory | 是 | USB配件,需要通过getAccessoryList获取。 |
返回值:
| 类型 | 说明 |
|---|---|
| Promise<boolean> | Promise对象,返回应用访问配件权限的申请结果。返回true表示权限申请成功;返回false表示权限申请失败。 |
错误码:
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
| 801 | Capability not supported. 适用版本:18+ |
| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. |
| 14400005 | Database operation exception. |
| 14401001 | The target USBAccessory not matched. |
示例:
import { BusinessError } from '@kit.BasicServicesKit';
async function requestAccessoryRight() {
try {
let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList();
let flag = await usbManager.requestAccessoryRight(accList?.[0]);
console.info(`Succeeded in requestAccessoryRight, ret:${flag}`);
} catch (error) {
const err: BusinessError = error as BusinessError;
console.error(`requestAccessoryRight error ${err.code}, message is ${err.message}`);
}
} cancelAccessoryRight(accessory: USBAccessory): void
取消当前应用访问USB配件的权限。与requestAccessoryRight()方法配合使用,用于取消此前通过requestAccessoryRight()申请的配件访问权限。
需要调用usbManager.getAccessoryList获取配件列表,得到USBAccessory作为参数。
系统能力: SystemCapability.USB.USBManager
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| accessory | USBAccessory | 是 | USB配件,需要通过getAccessoryList获取。 |
错误码:
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
| 801 | Capability not supported. 适用版本:18+ |
| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. |
| 14400005 | Database operation exception. |
| 14401001 | The target USBAccessory not matched. |
示例:
import { BusinessError } from '@kit.BasicServicesKit';
async function cancelAccessoryRight() {
try {
let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList();
let flag = await usbManager.requestAccessoryRight(accList?.[0]);
if (!flag) {
return;
}
usbManager.cancelAccessoryRight(accList?.[0]);
console.info(`Succeeded in cancelAccessoryRight`);
} catch (error) {
const err: BusinessError = error as BusinessError;
console.error(`cancelAccessoryRight error ${err.code}, message is ${err.message}`);
}
} getAccessoryList(): Array<Readonly<USBAccessory>>
获取当前已接入主机的USB配件列表。可作为调用requestAccessoryRight申请配件访问权限、openAccessory打开配件等后续操作的前置步骤。
系统能力: SystemCapability.USB.USBManager
返回值:
| 类型 | 说明 |
|---|---|
| Array<Readonly<USBAccessory>> | 只读的USB配件列表。包含所有可用的USB配件信息。 |
错误码:
| 错误码ID | 错误信息 |
|---|---|
| 801 | Capability not supported. 适用版本:18+ |
| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. |
示例:
import { BusinessError } from '@kit.BasicServicesKit';
try {
let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList();
console.info(`Succeeded in getAccessoryList, accList: ${JSON.stringify(accList)}`);
} catch (error) {
const err: BusinessError = error as BusinessError;
console.error(`getAccessoryList error ${err.code}, message is ${err.message}`);
} openAccessory(accessory: USBAccessory): USBAccessoryHandle
获取配件句柄并打开配件文件描述符。之后可以通过CoreFileKit提供的read/write接口和配件进行通信。使用完后需要调用closeAccessory接口关闭文件描述符。
需要调用usbManager.getAccessoryList获取配件列表,得到USBAccessory作为参数。调用前需先调用usbManager.requestAccessoryRight请求访问配件权限,权限申请成功(返回true)后方可调用本接口打开配件。
系统能力: SystemCapability.USB.USBManager
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| accessory | USBAccessory | 是 | USB配件,需要通过getAccessoryList获取。 |
返回值:
| 类型 | 说明 |
|---|---|
| USBAccessoryHandle | USB配件句柄。 |
错误码:
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
| 801 | Capability not supported. 适用版本:18+ |
| 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. |
示例:
import { fileIo } from '@kit.CoreFileKit';
import { BusinessError } from '@kit.BasicServicesKit';
async function openAccessory() {
try {
let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList();
let flag = await usbManager.requestAccessoryRight(accList?.[0]);
if (!flag) {
return;
}
let handle = usbManager.openAccessory(accList?.[0]);
console.info(`Succeeded in openAccessory`);
let arrayBuffer = new ArrayBuffer(4096);
// 通过配件句柄中的文件描述符读取配件发送的数据
let readLength = fileIo.readSync(handle.accessoryFd, arrayBuffer, {offset: 0, length: 4096});
console.info('readSync ret: ' + readLength.toString(10));
// 关闭配件文件描述符,释放句柄资源
usbManager.closeAccessory(handle);
} catch (error) {
const err: BusinessError = error as BusinessError;
console.error(`openAccessory error ${err.code}, message is ${err.message}`);
}
} closeAccessory(accessoryHandle: USBAccessoryHandle): void
关闭配件文件描述符。
需要调用usbManager.getAccessoryList获取配件列表,然后调用usbManager.requestAccessoryRight请求访问配件权限,权限申请成功后调用usbManager.openAccessory获取配件句柄,得到USBAccessoryHandle作为参数。
系统能力: SystemCapability.USB.USBManager
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| accessoryHandle | USBAccessoryHandle | 是 | USB配件句柄。需要通过openAccessory获取。 |
错误码:
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
| 801 | Capability not supported. 适用版本:18+ |
| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. |
示例:
import { BusinessError } from '@kit.BasicServicesKit';
async function closeAccessory() {
try {
let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList();
let flag = await usbManager.requestAccessoryRight(accList?.[0]);
if (!flag) {
return;
}
let handle = usbManager.openAccessory(accList?.[0]);
usbManager.closeAccessory(handle);
console.info(`Succeeded in closeAccessory`);
} catch (error) {
const err: BusinessError = error as BusinessError;
console.error(`closeAccessory error ${err.code}, message is ${err.message}`);
}
} resetUsbDevice(pipe: USBDevicePipe): boolean
重置USB设备。适用于USB设备出现通信异常需要恢复的场景,如设备固件升级后需要重新初始化、设备状态异常需要恢复、调试过程中需要重置设备状态等。调用成功后系统会将设备重置为初始状态,并清除此前设置的配置和接口设置,设备需要重新初始化。
本接口调用后会重置此前设置的配置和接口设置,请在调用之前确认相关业务已结束。
系统能力: SystemCapability.USB.USBManager
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pipe | USBDevicePipe | 是 | 用于确定总线地址和设备地址,需要调用connectDevice获取。 |
返回值:
| 类型 | 说明 |
|---|---|
| boolean | true表示重置设备成功,false表示重置设备失败。 |
错误码:
| 错误码ID | 错误信息 |
|---|---|
| 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. |
示例:
import {BusinessError} from '@kit.BasicServicesKit';
async function resetUsbDevice() {
let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
if (!devicesList || devicesList.length == 0) {
console.info(`device list is empty`);
return;
}
let rightResult = await usbManager.requestRight(devicesList?.[0]?.name);
if (!rightResult) {
console.error(`request right failed`);
return;
}
let devicePipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList?.[0]);
if (devicePipe == undefined) {
console.error(`connect device failed`);
return;
}
try {
// 重置USB设备,重置后此前设置的配置和接口设置将被清除,调用前需确认相关业务已结束
let ret: boolean = usbManager.resetUsbDevice(devicePipe);
console.info(`resetUsbDevice = ${ret}`);
} catch (error) {
const err: BusinessError = error as BusinessError;
console.error(`Failed to reset USB device. Code: ${err.code}, message: ${err.message}`);
}
usbManager.closePipe(devicePipe);
} controlTransfer(pipe: USBDevicePipe, controlparam: USBControlParams, timeout?: number): Promise<number>
控制传输。使用Promise异步回调。
系统能力: SystemCapability.USB.USBManager
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pipe | USBDevicePipe | 是 | USB设备连接通道对象,用于确定设备,需要调用connectDevice获取。 |
| controlparam | USBControlParams | 是 | 控制传输参数,包含request、target、reqType、value、index、data等字段,参数传参类型请参考USB协议规范,根据具体设备和控制请求类型设置。 |
| timeout | number | 否 | 超时时间(单位:ms),可选参数,指定时间内等待控制传输完成,若在指定时间内传输完成则正常返回,否则返回超时;默认值为0,表示无限等待直到传输完成。传入负数时抛出参数错误异常。用户按需选择。 |
返回值:
| 类型 | 说明 |
|---|---|
| Promise<number> | Promise对象,获取传输或接收到的数据块大小。失败返回其他错误码如下: - -1:驱动异常。可能原因:1、设备连接不稳定或已断开;2、USB驱动加载失败;3、内核USB模块异常。 |
错误码:
以下错误码的详细介绍请参见通用错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
示例:
import {BusinessError} from '@kit.BasicServicesKit';
let param: usbManager.USBControlParams = {
request: 0x06,
reqType: usbManager.USBControlRequestType.USB_REQUEST_TYPE_STANDARD,
target: usbManager.USBRequestTargetType.USB_REQUEST_TARGET_DEVICE,
value: 0x01 << 8 | 0,
index: 0,
data: new Uint8Array(18)
};
async function controlTransfer() {
let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices();
if (!devicesList || devicesList.length == 0) {
console.info(`device list is empty`);
return;
}
let rightResult = await usbManager.requestRight(devicesList[0].name);
if (!rightResult) {
console.error(`request right failed`);
return;
}
let devicePipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]);
if (devicePipe == undefined) {
console.error(`connect device failed`);
return;
}
// 发起控制传输,Promise返回传输或接收到的数据块大小,完成后在finally中关闭设备通道
usbManager.controlTransfer(devicePipe, param).then((ret: number) => {
console.info(`controlTransfer = ${ret}`);
}).catch((error: BusinessError) => {
console.error(`Failed to transfer. Code: ${error.code}, message: ${error.message}`);
}).finally(() => {
usbManager.closePipe(devicePipe);
});
} USB端点,用于主机与设备之间数据传输的通信端点。通过USBInterface获取。
主机控制器按照端点类型调度,不同类型的端点采用不同的调度策略:批量端点(bulk)采用带宽共享调度适合大量数据非实时传输;中断端点(interrupt)采用固定轮询调度适合小数据量实时传输;实时端点(isochronous)采用带宽预留调度,适合音视频等实时数据流。
type字段决定协议层打包数据时所采用的传输特性,包括数据包格式、错误处理机制、超时策略等。
图2 USB端点示意图

系统能力: SystemCapability.USB.USBManager
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| address | number | 否 | 否 | 端点地址。 |
| attributes | number | 否 | 否 | 端点属性,表示端点的传输特性,包括传输类型(批量、中断、实时)和同步类型等。取值遵循USB端点描述符规范。 |
| interval | number | 否 | 否 | 端点间隔。中断端点和实时端点为时间间隔(单位:ms);批量端点不使用此字段。 |
| maxPacketSize | number | 否 | 否 | 端点最大数据包大小,(单位:B)。 |
| direction | USBRequestDirection | 否 | 否 | 端点的方向。 |
| number | number | 否 | 否 | 端点号。 |
| type | number | 否 | 否 | 端点类型。取值见UsbEndpointTransferType。 |
| interfaceId | number | 否 | 否 | 端点所属的接口的唯一标识。 |
一个USBConfiguration中可以含有多个USBInterface,每个USBInterface提供一个功能。
系统能力: SystemCapability.USB.USBManager
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| id | number | 否 | 否 | 接口的唯一标识。 |
| protocol | number | 否 | 否 | 接口的协议。 |
| clazz | number | 否 | 否 | 接口类型(接口类代码),表示该接口所属的功能类别,取值遵循USB接口描述符规范。 |
| subClass | number | 否 | 否 | 设备子类。 |
| alternateSetting | number | 否 | 否 | 接口的替代设置索引号,用于在同一个接口的多个可选描述符中进行切换选择。0表示默认设置,其他值表示特定的替代设置。 |
| name | string | 否 | 否 | 接口名称。 |
| endpoints | Array<USBEndpoint> | 否 | 否 | 当前接口所包含的端点。 |
描述当已独占声明的USB接口被其他进程以非独占方式声明时的冲突信息,通过调用usbManager.claimInterfaceExclusive独占声明接口后使用。
起始版本: 26.0.1
系统能力: SystemCapability.USB.USBManager
模型约束: 此接口仅可在Stage模型下使用。
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| busNum | number | 否 | 否 | USB设备的总线地址。取值限定为整数。 |
| devAddr | number | 否 | 否 | USB设备的设备地址。 |
| interfaceId | number | 否 | 否 | 被其他进程声明的USB接口的ID。 |
USB配置,一个USBDevice中可以含有多个配置。
系统能力: SystemCapability.USB.USBManager
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| id | number | 否 | 否 | 配置的唯一标识。 |
| attributes | number | 否 | 否 | 配置的属性,取值遵循USB配置描述符规范,用于表示配置的供电方式、远程唤醒能力等特性。 |
| maxPower | number | 否 | 否 | 最大功耗,(单位:mA)。 |
| name | string | 否 | 否 | 配置的名称,可以为空字符串。 |
| isRemoteWakeup | boolean | 否 | 否 | 检查当前配置是否支持远程唤醒。true表示支持,false表示不支持。 |
| isSelfPowered | boolean | 否 | 否 | 检查当前配置是否支持独立电源。true表示支持,false表示不支持。 |
| interfaces | Array<USBInterface> | 否 | 否 | 配置支持的接口列表。 |
USB设备信息。
系统能力: SystemCapability.USB.USBManager
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| busNum | number | 否 | 否 | 总线地址。 |
| devAddress | number | 否 | 否 | 设备地址。 |
| serial | string | 否 | 否 | 序列号。三方应用无法获取此字段的设备序列号信息(该字段对三方应用不可用),如需获取序列号需在申请设备访问权限后自行发起控制传输。 |
| name | string | 否 | 否 | 设备名称。 |
| manufacturerName | string | 否 | 否 | 设备厂商名称。 |
| productName | string | 否 | 否 | 设备产品名称。 |
| version | string | 否 | 否 | 设备版本号。 |
| vendorId | number | 否 | 否 | 厂商ID。 |
| productId | number | 否 | 否 | 产品ID。 |
| clazz | number | 否 | 否 | 设备类型代码。 |
| subClass | number | 否 | 否 | 设备子类型代码。 |
| protocol | number | 否 | 否 | 设备协议代码。 |
| configs | Array<USBConfiguration> | 否 | 否 | 设备配置描述符信息。 |
USB设备连接通道,用于确定总线地址和设备地址。
系统能力: SystemCapability.USB.USBManager
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| busNum | number | 否 | 否 | 总线地址。 |
| devAddress | number | 否 | 否 | 设备地址。 |
控制传输参数。
系统能力: SystemCapability.USB.USBManager
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| bmRequestType | number | 否 | 否 | 请求控制类型,用于指定控制传输的方向和类型,取值需遵循USB协议规范。常见取值示例:0x00(标准请求,主机向设备)、0x20(类请求,主机向设备)、0x40(厂商请求,主机向设备)、0x80(标准请求,设备向主机)。 |
| bRequest | number | 否 | 否 | 请求类型,用于指定具体的USB控制请求命令(如获取描述符,设置地址等)。 |
| wValue | number | 否 | 否 | 请求参数,用于向USB设备传递控制请求所需的参数内容。 |
| wIndex | number | 否 | 否 | 请求参数wValue对应的索引值,用于指定控制请求的目标接口或端点。 |
| wLength | number | 否 | 否 | 请求数据的长度,用于指定控制传输中期望接收或发送的数据字节数。 |
| data | Uint8Array | 否 | 否 | 用于写入或读取的缓冲区,数组长度对应wLength参数指定的数据字节数。用于控制传输时发送或接收数据。 |
请求目标类型。
系统能力: SystemCapability.USB.USBManager
| 名称 | 值 | 说明 |
|---|---|---|
| USB_REQUEST_TARGET_DEVICE | 0 | 将控制请求的目标设置为USB设备本身,用于对整个设备进行控制操作(如设置设备地址、获取设备描述符等)。 |
| USB_REQUEST_TARGET_INTERFACE | 1 | 将控制请求的目标设置为USB设备的某个接口,用于对接口进行控制操作(如设置接口特性、获取接口描述符等)。 |
| USB_REQUEST_TARGET_ENDPOINT | 2 | 将控制请求的目标设置为USB设备的某个端点,用于对端点进行控制操作(如清除端点停止状态、获取端点状态等)。 |
| USB_REQUEST_TARGET_OTHER | 3 | 将控制请求的目标设置为其他单元,用于对非标设备、接口或端点的单元进行控制操作。 |
控制请求类型,用于指定具体的USB控制请求命令(如获取描述符、设置地址等)。
系统能力: SystemCapability.USB.USBManager
| 名称 | 值 | 说明 |
|---|---|---|
| USB_REQUEST_TYPE_STANDARD | 0 | 标准请求类型,用于发送USB协议定义的标准控制请求(如设备描述符、设置地址、设置配置等)。 |
| USB_REQUEST_TYPE_CLASS | 1 | 类请求类型,用于发送特定设备类定义的控制请求(如HID类、Mass Storage类等特定请求)。 |
| USB_REQUEST_TYPE_VENDOR | 2 | 厂商请求类型,用于发送厂商自定义的控制请求,具体请求内容由设备厂商定义。 |
请求方向。
系统能力: SystemCapability.USB.USBManager
| 名称 | 值 | 说明 |
|---|---|---|
| USB_REQUEST_DIR_TO_DEVICE | 0 | 写数据,主机向设备。 |
| USB_REQUEST_DIR_FROM_DEVICE | 0x80 | 读数据,设备向主机。 |
USB配件信息。
系统能力: SystemCapability.USB.USBManager
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| manufacturer | string | 否 | 否 | 配件的生产厂商。 |
| product | string | 否 | 否 | 配件的产品类型。 |
| description | string | 否 | 否 | 配件的描述信息,由厂商提供,用于说明配件的功能、用途或特性。 |
| version | string | 否 | 否 | 配件的版本。 |
| serialNumber | string | 否 | 否 | 配件的序列号(SN)。 |
USB配件句柄,包含配件文件描述符,用于通过CoreFileKit提供的read/write接口和配件进行通信。
系统能力: SystemCapability.USB.USBManager
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| accessoryFd | number | 否 | 否 | 配件文件描述符。合法的accessoryFd是正整数。 |
USB数据传输参数对象,包含USB数据传输所需的所有参数,用于usbSubmitTransfer和usbCancelTransfer接口发起传输请求。
系统能力: SystemCapability.USB.USBManager
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| devPipe | USBDevicePipe | 否 | 否 | 用于确定总线地址和设备地址,需要调用connectDevice获取。 |
| flags | UsbTransferFlags | 否 | 否 | USB传输标志,用于控制传输行为。可选值包括:0(将短帧报告为错误)、1(自动释放传输缓冲区)、2(完成回调后自动释放传输资源)、3(传输将增加一个额外的零长度数据包)。 |
| endpoint | number | 否 | 否 | 端点地址,取值范围为[1, 255]的正整数。需要调用getDevices获取设备信息,通过endpoint的address属性确定端点信息,通过direction属性确定端点方向。 |
| type | UsbEndpointTransferType | 否 | 否 | 传输类型,指定USB传输的方式。可选值包括:0x1(实时传输,适合音视频等实时数据流)、0x2(批量传输,适合大量数据非实时传输)、0x3(中断传输,适合小数据量实时传输)。 |
| timeout | number | 否 | 否 | 超时时间(单位:ms),指定时间内等待传输完成,若在指定时间内传输完成则正常返回否则返回超时。设置为0时无限等待直到传输完成。传入负数时抛出参数错误异常。 |
| length | number | 否 | 否 | 数据缓冲区的长度,取值范围为[0, INT_MAX]的非负数(期望长度,单位:B)。 |
| callback | AsyncCallback<SubmitTransferCallback> | 否 | 否 | 传输完成时的回调函数,签名:(err: Error, data: SubmitTransferCallback) => void。err为错误对象(成功时为null),data包含传输状态、实际长度等信息。 |
| userData | Uint8Array | 否 | 否 | 用户上下文数据,用于在回调函数中传递自定义的上下文信息。大小和格式由用户定义,在传输请求中指定,回调中原样返回。 |
| buffer | Uint8Array | 否 | 否 | 用于存储读或者写请求时的数据。 |
| isoPacketCount | number | 否 | 否 | 实时传输时数据包的数量,仅用于具有实时传输端点的I/O。取值范围为[0, INT_MAX]的非负数,(单位:个)。 |
USB传输标志。
系统能力: SystemCapability.USB.USBManager
| 名称 | 值 | 说明 |
|---|---|---|
| USB_TRANSFER_SHORT_NOT_OK | 0 | 将短帧报告为错误。短帧指实际传输的数据长度小于端点maxPacketSize的数据包。 |
| USB_TRANSFER_FREE_BUFFER | 1 | 自动释放传输缓冲区。 |
| USB_TRANSFER_FREE_TRANSFER | 2 | 完成回调后自动释放传输资源。 |
| USB_TRANSFER_ADD_ZERO_PACKET | 3 | 传输将增加一个额外的零长度数据包。 |
USB传输类型。
系统能力: SystemCapability.USB.USBManager
| 名称 | 值 | 说明 |
|---|---|---|
| TRANSFER_TYPE_ISOCHRONOUS | 0x1 | 实时传输。 |
| TRANSFER_TYPE_BULK | 0x2 | 批量传输。 |
| TRANSFER_TYPE_INTERRUPT | 0x3 | 中断传输。 |
USB异步传输回调。
系统能力: SystemCapability.USB.USBManager
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| actualLength | number | 否 | 否 | 读写操作的实际长度值,(单位:B)。 |
| status | UsbTransferStatus | 否 | 否 | 读写操作完成的状态。 |
| isoPacketDescs | Array<Readonly<UsbIsoPacketDescriptor>> | 否 | 否 | 实时传输的分包信息。 |
数据处理完成后通过回调返回的状态码。
系统能力: SystemCapability.USB.USBManager
| 名称 | 值 | 说明 |
|---|---|---|
| TRANSFER_COMPLETED | 0 | 传输完成。 |
| TRANSFER_ERROR | 1 | 传输失败。 |
| TRANSFER_TIMED_OUT | 2 | 传输超时。 |
| TRANSFER_CANCELED | 3 | 传输已被取消。 |
| TRANSFER_STALL | 4 | 检测到暂停(批量/中断端点)。 |
| TRANSFER_NO_DEVICE | 5 | 设备已断开。 |
| TRANSFER_OVERFLOW | 6 | 设备发送的数据比请求的多。 |
实时传输模式回调返回的分包信息。
系统能力: SystemCapability.USB.USBManager
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| length | number | 否 | 否 | 读写操作的期望长度值,(单位:B)。 |
| actualLength | number | 否 | 否 | 读写操作的实际长度值,(单位:B)。 |
| status | UsbTransferStatus | 否 | 否 | 实时传输分包的状态码。 |
控制传输参数。
系统能力: SystemCapability.USB.USBManager
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| request | number | 否 | 否 | 请求类型,用于指定具体的USB控制请求命令。 |
| target | USBRequestTargetType | 否 | 否 | 请求目标类型。 |
| reqType | USBControlRequestType | 否 | 否 | 请求控制类型。 |
| value | number | 否 | 否 | 请求参数,用于向USB设备传递控制请求所需的参数内容。 |
| index | number | 否 | 否 | 请求参数value对应的索引值,用于指定控制请求的目标接口或端点。 |
| data | Uint8Array | 否 | 否 | 用于写入或读取的缓冲区。 |