HarmonyOS API：@ohos.usbV9 (USB管理)

版本：v3.1 Beta

@ohos.usbV9 (USB管理)

更新时间: 2023-03-17 18:27

本模块主要提供管理USB设备的相关功能，包括主设备上查询USB设备列表、批量数据传输、控制命令传输、权限控制等；从设备上端口管理、功能切换及查询等。

说明

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

导入模块

import usb from "@ohos.usbV9";

usb.getDevices

getDevices(): Array<Readonly<USBDevice>>

获取接入主设备的USB设备列表。如果没有设备接入，那么将会返回一个空的列表。

系统能力： SystemCapability.USB.USBManager

返回值：

示例：

let devicesList = usb.getDevices();
console.log(`devicesList = ${devicesList}`);
//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,
              },
            ],
          },
        ],
      },
    ],
  },
]

usb.connectDevice

connectDevice(device: USBDevice): Readonly<USBDevicePipe>

打开USB设备。

需要调用​​usb.getDevices​​​获取设备信息以及device，再调用​​usb.requestRight​​请求使用该设备的权限。

系统能力： SystemCapability.USB.USBManager

参数：

返回值：

错误码：

以下错误码的详细介绍参见​​USB错误码​​。

示例：

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

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

usb.hasRight

hasRight(deviceName: string): boolean

判断是否有权访问该设备。

系统能力： SystemCapability.USB.USBManager

参数：

返回值：

示例：

let devicesName="1-1";
let bool = usb.hasRight(devicesName);
console.log(`${bool}`);

usb.requestRight

requestRight(deviceName: string): Promise<boolean>

请求软件包的临时权限以访问设备。使用Promise异步回调。

系统能力： SystemCapability.USB.USBManager

参数：

返回值：

示例：

let devicesName="1-1";
usb.requestRight(devicesName).then((ret) => {
  console.log(`requestRight = ${ret}`);
});

usb.claimInterface

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

注册通信接口。

需要调用​​usb.getDevices​​​获取设备信息以及interfaces；调用​​usb.requestRight​​​获取设备请求权限；调用​​usb.connectDevice​​接口得到devicepipe作为参数。

系统能力： SystemCapability.USB.USBManager

参数：

返回值：

示例：

let ret = usb.claimInterface(devicepipe, interfaces);
console.log(`claimInterface = ${ret}`);

usb.releaseInterface

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

释放注册过的通信接口。

需要调用​​usb.claimInterface​​先获取接口，才能使用此方法释放接口。

系统能力： SystemCapability.USB.USBManager

参数：

返回值：

示例：

let ret = usb.releaseInterface(devicepipe, interfaces);
console.log(`releaseInterface = ${ret}`);

usb.setConfiguration

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

设置设备配置。

需要调用​​usb.getDevices​​​获取设备信息以及config；调用​​usb.requestRight​​​获取设备请求权限；调用​​usb.connectDevice​​得到devicepipe作为参数。

系统能力： SystemCapability.USB.USBManager

参数：

返回值：

示例：

let ret = usb.setConfiguration(devicepipe, config);
console.log(`setConfiguration = ${ret}`);

usb.setInterface

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

设置设备接口。

需要调用​​usb.getDevices​​​获取设备列表以及interfaces；调用​​usb.requestRight​​​获取设备请求权限；调用​​usb.connectDevice​​​得到devicepipe作为参数；调用​​usb.claimInterface​​注册通信接口。

系统能力： SystemCapability.USB.USBManager

参数：

返回值：

示例：

let ret = usb.setInterface(devicepipe, interfaces);
console.log(`setInterface = ${ret}`);

usb.getRawDescriptor

getRawDescriptor(pipe: USBDevicePipe): Uint8Array

获取原始的USB描述符。

需要调用​​usb.getDevices​​​获取设备列表；调用​​usb.requestRight​​​获取设备请求权限；调用​​usb.connectDevice​​接口得到devicepipe作为参数。

系统能力： SystemCapability.USB.USBManager

参数：

返回值：

示例：

let ret = usb.getRawDescriptor(devicepipe);

usb.getFileDescriptor

getFileDescriptor(pipe: USBDevicePipe): number

获取文件描述符。

需要调用​​usb.getDevices​​​获取设备列表；调用​​usb.requestRight​​​获取设备请求权限；调用​​usb.connectDevice​​接口得到devicepipe作为参数。

系统能力： SystemCapability.USB.USBManager

参数：

返回值：

示例：

let ret = usb.getFileDescriptor(devicepipe);

usb.controlTransfer

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

控制传输。

需要调用​​usb.getDevices​​​获取设备列表；调用​​usb.requestRight​​​获取设备请求权限；调用​​usb.connectDevice​​接口得到devicepipe作为参数。

系统能力： SystemCapability.USB.USBManager

参数：

返回值：

示例：

let param = new usb.USBControlParams();
usb.controlTransfer(devicepipe, param).then((ret) => {
 console.log(`controlTransfer = ${ret}`);
})

usb.bulkTransfer

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

批量传输。

需要调用​​usb.getDevices​​​获取设备信息列表以及endpoint；再调用​​usb.requestRight​​​获取设备请求权限；然后调用​​usb.connectDevice​​​接口得到返回数据devicepipe之后，再次获取接口​​usb.claimInterface​​；再调用usb.bulkTransfer接口。

系统能力： SystemCapability.USB.USBManager

参数：

返回值：

示例：

//usb.getDevices 接口返回数据集合，取其中一个设备对象，并获取权限 。
//把获取到的设备对象作为参数传入usb.connectDevice;当usb.connectDevice接口成功返回之后；
//才可以调用第三个接口usb.claimInterface.当usb.claimInterface 调用成功以后,再调用该接口。
usb.bulkTransfer(devicepipe, endpoint, buffer).then((ret) => {
 console.log(`bulkTransfer = ${ret}`);
});

usb.closePipe

closePipe(pipe: USBDevicePipe): number

关闭设备消息控制通道。

需要调用​​usb.getDevices​​​获取设备列表；调用​​usb.requestRight​​​获取设备请求权限；调用​​usb.connectDevice​​得到devicepipe作为参数。

系统能力： SystemCapability.USB.USBManager

参数：

返回值：

示例：

let ret = usb.closePipe(devicepipe);
console.log(`closePipe = ${ret}`);

USBEndpoint

通过USB发送和接收数据的端口。通过​​USBInterface​​获取。

系统能力： SystemCapability.USB.USBManager

USBInterface

一个​​USBConfig​​中可以含有多个USBInterface，每个USBInterface提供一个功能。

系统能力： SystemCapability.USB.USBManager

USBConfig

USB配置，一个​​USBDevice​​中可以含有多个配置。

系统能力： SystemCapability.USB.USBManager

USBDevice

USB设备信息。

系统能力： SystemCapability.USB.USBManager

USBDevicePipe

USB设备消息传输通道，用于确定设备。

系统能力： SystemCapability.USB.USBManager

USBControlParams

控制传输参数。

系统能力： SystemCapability.USB.USBManager

USBRequestTargetType

请求目标类型。

系统能力： SystemCapability.USB.USBManager

USBControlRequestType

控制请求类型。

系统能力： SystemCapability.USB.USBManager

USBRequestDirection

请求方向。

系统能力： SystemCapability.USB.USBManager

文章转载自：​​https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/js-apis-usb-0000001427902736-V3?catalogVersion=V3#ZH-CN_TOPIC_0000001427902736__导入模块​​