目录

@ohos.usbManager (USB管理)

本模块主要提供管理USB设备的相关功能,包括主机端的查询USB设备列表、批量数据传输、控制命令传输、权限控制等;设备端的端口管理、功能切换及查询等。适用于需要与USB设备进行数据交互、管理USB设备权限、动态切换USB设备模式等场景。

本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

导入模块

import { usbManager } from '@kit.BasicServicesKit';

使用说明

凡是参数类型为USBDevicePipe的接口,都需要执行如下操作:

在使用接口前:

  1. 调用usbManager.getDevices获取设备列表。

  2. 调用usbManager.requestRight获取请求权限。

  3. 调用usbManager.connectDevice得到USBDevicePipe作为参数。

在使用接口后:

调用usbManager.closePipe关闭设备连接通道。

图1 usbManager接口使用流程图

usbManager.getDevices

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,
                },
              ],
            },
          ],
        },
      ],
    },
  ]
 */

usbManager.connectDevice

connectDevice(device: USBDevice): Readonly<USBDevicePipe>

根据getDevices()返回的设备信息打开USB设备,调用成功后建立设备连接通道,可以进行后续的数据传输和设备控制操作。使用完后需要调用usbManager.closePipe关闭设备连接通道。如果USB服务异常,会返回undefined,注意需要对接口返回值做判空处理。

  1. 调用usbManager.getDevices获取设备列表。
  2. 调用usbManager.requestRight获取设备访问权限。

系统能力: SystemCapability.USB.USBManager

参数:

参数名 类型 必填 说明
device USBDevice 是 USB设备信息,用getDevices获取的busNum和devAddress确定设备,当前其他属性(如name、vendorId等)不参与设备匹配。

返回值:

类型 说明
Readonly<USBDevicePipe> USB设备连接通道对象,用于后续的数据传输和设备控制操作。

错误码:

以下错误码的详细介绍请参见通用错误码和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);
}

usbManager.hasRight

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

usbManager.requestRight

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}`);
  });
}

usbManager.removeRight

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

usbManager.claimInterface

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);
}

usbManager.claimInterfaceExclusive

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接口时的冲突信息。如果不指定此参数,则发生此类冲突时不发送通知。

错误码:

以下错误码的详细介绍请参见通用错误码和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)}`);
  }
}

usbManager.releaseInterface

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

释放claim过的通信接口。

在调用该接口前需要通过usbManager.claimInterface 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);
}

usbManager.setConfiguration

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

设置设备配置。适用于多功能USB设备需要切换工作模式的场景,如打印机+扫描仪组合设备切换为打印模式或扫描模式、设备从低功耗配置切换到高功耗配置以启用全部功能等。调用成功后系统会将设备配置切换为指定的配置,后续的数据传输和设备操作将基于新配置进行。

在调用该接口前需要通过usbManager.claimInterface claim通信接口。

系统能力: 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);
}

usbManager.setInterface

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);
}

usbManager.getRawDescriptor

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);
}

usbManager.getFileDescriptor

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}`);
}

usbManager.usbControlTransfer12+

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);
  });
}

usbManager.bulkTransfer

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);
}

usbManager.usbSubmitTransfer18+

usbSubmitTransfer(transfer: UsbDataTransferParams): void

提交异步传输请求,调用后立即返回,实际读写操作的结果以回调的方式返回。可通过调用usbCancelTransfer接口取消异步传输请求。

本接口为异步接口,调用后立刻返回,实际读写操作的结果以回调的方式返回;在调用该接口前需要通过usbManager.claimInterface claim通信接口。

系统能力: SystemCapability.USB.USBManager

参数:

参数名 类型 必填 说明
transfer UsbDataTransferParams 是 该参数对象用于通用USB数据传输,客户端需要填充其中的参数,用以发起传输请求。在调用该接口前需要通过usbManager.claimInterface claim通信接口。

错误码:

以下错误码的详细介绍请参见通用错误码和USB服务错误码。

错误码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);
  }
}

usbManager.usbCancelTransfer18+

usbCancelTransfer(transfer: UsbDataTransferParams): void

取消异步传输请求。适用于需要主动终止未完成USB数据传输的场景,如用户手动取消进行中的数据传输、传输超时后的错误恢复、应用切换时中止当前传输等。

主动取消尚未完成的USB数据传输请求(如usbSubmitTransfer提交的传输)。

在调用该接口前需要通过usbManager.claimInterface claim通信接口。

系统能力: SystemCapability.USB.USBManager

参数:

参数名 类型 必填 说明
transfer UsbDataTransferParams 是 被取消传输的参数,该参数与usbManager.usbSubmitTransfer接口的transfer参数相同。在调用该接口前需要通过usbManager.claimInterface claim通信接口。

错误码:

以下错误码的详细介绍请参见通用错误码和USB服务错误码。

错误码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);
}

usbManager.closePipe

closePipe(pipe: USBDevicePipe): number

关闭设备连接通道。适用于使用USBDevicePipe完成数据传输和设备控制操作后释放设备连接的场景。

  1. 调用usbManager.getDevices获取设备列表。
  2. 调用usbManager.requestRight获取设备访问权限。
  3. 调用usbManager.connectDevice得到devicepipe作为参数。

系统能力: 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}`);
}

usbManager.hasAccessoryRight14+

hasAccessoryRight(accessory: USBAccessory): boolean

检查应用是否有权访问USB配件。适用于在调用requestAccessoryRight申请权限或openAccessory打开配件前,先确认应用是否已拥有该配件访问权限的场景。

需要调用usbManager.getAccessoryList获取配件列表,得到USBAccessory作为参数。

系统能力: SystemCapability.USB.USBManager

参数:

参数名 类型 必填 说明
accessory USBAccessory 是 USB配件,需要通过getAccessoryList获取。

返回值:

类型 说明
boolean true表示应用有权访问USB配件,false表示应用无权访问USB配件。

错误码:

以下错误码的详细介绍请参见通用错误码和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}`);
}

usbManager.requestAccessoryRight14+

requestAccessoryRight(accessory: USBAccessory): Promise<boolean>

为当前应用申请访问USB配件的权限。使用Promise异步回调。

需要调用usbManager.getAccessoryList获取配件列表,得到USBAccessory作为参数。

系统能力: SystemCapability.USB.USBManager

参数:

参数名 类型 必填 说明
accessory USBAccessory 是 USB配件,需要通过getAccessoryList获取。

返回值:

类型 说明
Promise<boolean> Promise对象,返回应用访问配件权限的申请结果。返回true表示权限申请成功;返回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';
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}`);
  }
}

usbManager.cancelAccessoryRight14+

cancelAccessoryRight(accessory: USBAccessory): void

取消当前应用访问USB配件的权限。与requestAccessoryRight()方法配合使用,用于取消此前通过requestAccessoryRight()申请的配件访问权限。

需要调用usbManager.getAccessoryList获取配件列表,得到USBAccessory作为参数。

系统能力: SystemCapability.USB.USBManager

参数:

参数名 类型 必填 说明
accessory USBAccessory 是 USB配件,需要通过getAccessoryList获取。

错误码:

以下错误码的详细介绍请参见通用错误码和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';
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}`);
  }
}

usbManager.getAccessoryList14+

getAccessoryList(): Array<Readonly<USBAccessory>>

获取当前已接入主机的USB配件列表。可作为调用requestAccessoryRight申请配件访问权限、openAccessory打开配件等后续操作的前置步骤。

系统能力: SystemCapability.USB.USBManager

返回值:

类型 说明
Array<Readonly<USBAccessory>> 只读的USB配件列表。包含所有可用的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}`);
}

usbManager.openAccessory14+

openAccessory(accessory: USBAccessory): USBAccessoryHandle

获取配件句柄并打开配件文件描述符。之后可以通过CoreFileKit提供的read/write接口和配件进行通信。使用完后需要调用closeAccessory接口关闭文件描述符。

需要调用usbManager.getAccessoryList获取配件列表,得到USBAccessory作为参数。调用前需先调用usbManager.requestAccessoryRight请求访问配件权限,权限申请成功(返回true)后方可调用本接口打开配件。

系统能力: SystemCapability.USB.USBManager

参数:

参数名 类型 必填 说明
accessory USBAccessory 是 USB配件,需要通过getAccessoryList获取。

返回值:

类型 说明
USBAccessoryHandle USB配件句柄。

错误码:

以下错误码的详细介绍请参见通用错误码和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}`);
  }
}

usbManager.closeAccessory14+

closeAccessory(accessoryHandle: USBAccessoryHandle): void

关闭配件文件描述符。

需要调用usbManager.getAccessoryList获取配件列表,然后调用usbManager.requestAccessoryRight请求访问配件权限,权限申请成功后调用usbManager.openAccessory获取配件句柄,得到USBAccessoryHandle作为参数。

系统能力: SystemCapability.USB.USBManager

参数:

参数名 类型 必填 说明
accessoryHandle USBAccessoryHandle 是 USB配件句柄。需要通过openAccessory获取。

错误码:

以下错误码的详细介绍请参见通用错误码和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.

示例:

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}`);
  }
}

usbManager.resetUsbDevice20+

resetUsbDevice(pipe: USBDevicePipe): boolean

重置USB设备。适用于USB设备出现通信异常需要恢复的场景,如设备固件升级后需要重新初始化、设备状态异常需要恢复、调试过程中需要重置设备状态等。调用成功后系统会将设备重置为初始状态,并清除此前设置的配置和接口设置,设备需要重新初始化。

本接口调用后会重置此前设置的配置和接口设置,请在调用之前确认相关业务已结束。

  1. 调用usbManager.getDevices获取设备列表。
  2. 调用usbManager.requestRight获取设备访问权限。
  3. 调用usbManager.connectDevice得到devicepipe作为参数。

系统能力: SystemCapability.USB.USBManager

参数:

参数名 类型 必填 说明
pipe USBDevicePipe 是 用于确定总线地址和设备地址,需要调用connectDevice获取。

返回值:

类型 说明
boolean true表示重置设备成功,false表示重置设备失败。

错误码:

以下错误码的详细介绍请参见通用错误码和USB服务错误码。

错误码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);
}

usbManager.controlTransfer(deprecated)

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

控制传输。使用Promise异步回调。

从API version 9开始支持,从API version 12开始废弃。建议使用usbControlTransfer替代。

系统能力: 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);
  });
}

USBEndpoint

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 否 否 端点所属的接口的唯一标识。

USBInterface

一个USBConfiguration中可以含有多个USBInterface,每个USBInterface提供一个功能。

系统能力: SystemCapability.USB.USBManager

名称 类型 只读 可选 说明
id number 否 否 接口的唯一标识。
protocol number 否 否 接口的协议。
clazz number 否 否 接口类型(接口类代码),表示该接口所属的功能类别,取值遵循USB接口描述符规范。
subClass number 否 否 设备子类。
alternateSetting number 否 否 接口的替代设置索引号,用于在同一个接口的多个可选描述符中进行切换选择。0表示默认设置,其他值表示特定的替代设置。
name string 否 否 接口名称。
endpoints Array<USBEndpoint> 否 否 当前接口所包含的端点。

InterfaceConflictInfo

描述当已独占声明的USB接口被其他进程以非独占方式声明时的冲突信息,通过调用usbManager.claimInterfaceExclusive独占声明接口后使用。

此回调在其他进程调用非独占的usbManager.claimInterface接口声明同一USB接口时触发。独占持有方可通过此回调获知潜在的访问冲突。

起始版本: 26.0.1

系统能力: SystemCapability.USB.USBManager

模型约束: 此接口仅可在Stage模型下使用。

名称 类型 只读 可选 说明
busNum number 否 否 USB设备的总线地址。取值限定为整数。
devAddr number 否 否 USB设备的设备地址。
interfaceId number 否 否 被其他进程声明的USB接口的ID。

USBConfiguration

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> 否 否 配置支持的接口列表。

USBDevice

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> 否 否 设备配置描述符信息。

USBDevicePipe

USB设备连接通道,用于确定总线地址和设备地址。

系统能力: SystemCapability.USB.USBManager

名称 类型 只读 可选 说明
busNum number 否 否 总线地址。
devAddress number 否 否 设备地址。

USBDeviceRequestParams12+

控制传输参数。

系统能力: SystemCapability.USB.USBManager

名称 类型 只读 可选 说明
bmRequestType number 否 否 请求控制类型,用于指定控制传输的方向和类型,取值需遵循USB协议规范。常见取值示例:0x00(标准请求,主机向设备)、0x20(类请求,主机向设备)、0x40(厂商请求,主机向设备)、0x80(标准请求,设备向主机)。
bRequest number 否 否 请求类型,用于指定具体的USB控制请求命令(如获取描述符,设置地址等)。
wValue number 否 否 请求参数,用于向USB设备传递控制请求所需的参数内容。
wIndex number 否 否 请求参数wValue对应的索引值,用于指定控制请求的目标接口或端点。
wLength number 否 否 请求数据的长度,用于指定控制传输中期望接收或发送的数据字节数。
data Uint8Array 否 否 用于写入或读取的缓冲区,数组长度对应wLength参数指定的数据字节数。用于控制传输时发送或接收数据。

USBRequestTargetType

请求目标类型。

系统能力: 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 将控制请求的目标设置为其他单元,用于对非标设备、接口或端点的单元进行控制操作。

USBControlRequestType

控制请求类型,用于指定具体的USB控制请求命令(如获取描述符、设置地址等)。

系统能力: SystemCapability.USB.USBManager

名称 值 说明
USB_REQUEST_TYPE_STANDARD 0 标准请求类型,用于发送USB协议定义的标准控制请求(如设备描述符、设置地址、设置配置等)。
USB_REQUEST_TYPE_CLASS 1 类请求类型,用于发送特定设备类定义的控制请求(如HID类、Mass Storage类等特定请求)。
USB_REQUEST_TYPE_VENDOR 2 厂商请求类型,用于发送厂商自定义的控制请求,具体请求内容由设备厂商定义。

USBRequestDirection

请求方向。

系统能力: SystemCapability.USB.USBManager

名称 值 说明
USB_REQUEST_DIR_TO_DEVICE 0 写数据,主机向设备。
USB_REQUEST_DIR_FROM_DEVICE 0x80 读数据,设备向主机。

USBAccessory14+

USB配件信息。

系统能力: SystemCapability.USB.USBManager

名称 类型 只读 可选 说明
manufacturer string 否 否 配件的生产厂商。
product string 否 否 配件的产品类型。
description string 否 否 配件的描述信息,由厂商提供,用于说明配件的功能、用途或特性。
version string 否 否 配件的版本。
serialNumber string 否 否 配件的序列号(SN)。

USBAccessoryHandle14+

USB配件句柄,包含配件文件描述符,用于通过CoreFileKit提供的read/write接口和配件进行通信。

系统能力: SystemCapability.USB.USBManager

名称 类型 只读 可选 说明
accessoryFd number 否 否 配件文件描述符。合法的accessoryFd是正整数。

UsbDataTransferParams18+

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]的非负数,(单位:个)。

UsbTransferFlags18+

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 传输将增加一个额外的零长度数据包。

UsbEndpointTransferType18+

USB传输类型。

系统能力: SystemCapability.USB.USBManager

名称 值 说明
TRANSFER_TYPE_ISOCHRONOUS 0x1 实时传输。
TRANSFER_TYPE_BULK 0x2 批量传输。
TRANSFER_TYPE_INTERRUPT 0x3 中断传输。

SubmitTransferCallback18+

USB异步传输回调。

系统能力: SystemCapability.USB.USBManager

名称 类型 只读 可选 说明
actualLength number 否 否 读写操作的实际长度值,(单位:B)。
status UsbTransferStatus 否 否 读写操作完成的状态。
isoPacketDescs Array<Readonly<UsbIsoPacketDescriptor>> 否 否 实时传输的分包信息。

UsbTransferStatus18+

数据处理完成后通过回调返回的状态码。

系统能力: 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 设备发送的数据比请求的多。

UsbIsoPacketDescriptor18+

实时传输模式回调返回的分包信息。

系统能力: SystemCapability.USB.USBManager

名称 类型 只读 可选 说明
length number 否 否 读写操作的期望长度值,(单位:B)。
actualLength number 否 否 读写操作的实际长度值,(单位:B)。
status UsbTransferStatus 否 否 实时传输分包的状态码。

USBControlParams(deprecated)

控制传输参数。

从API version 9开始支持,从API version 18开始废弃。建议使用USBDeviceRequestParams替代。

系统能力: SystemCapability.USB.USBManager

名称 类型 只读 可选 说明
request number 否 否 请求类型,用于指定具体的USB控制请求命令。
target USBRequestTargetType 否 否 请求目标类型。
reqType USBControlRequestType 否 否 请求控制类型。
value number 否 否 请求参数,用于向USB设备传递控制请求所需的参数内容。
index number 否 否 请求参数value对应的索引值,用于指定控制请求的目标接口或端点。
data Uint8Array 否 否 用于写入或读取的缓冲区。