1# @ohos.usb (USB管理)(已停止维护) 2 3<!--Kit: Basic Services Kit--> 4<!--Subsystem: USB--> 5<!--Owner: @hwymlgitcode--> 6<!--Designer: @w00373942--> 7<!--Tester: @dong-dongzhen--> 8<!--Adviser: @w_Machine_cc--> 9 10本模块主要提供管理USB设备的相关功能，包括查询USB设备列表、批量数据传输、控制命令传输、权限控制等。 11 12> **说明：** 13> 14> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15> 16> 从API version 9开始，该接口不再维护，推荐使用新接口[@ohos.usbManager](js-apis-usbManager.md)。 17 18## 导入模块 19 20```js 21import usb from "@ohos.usb"; 22``` 23 24## usb.getDevices 25 26getDevices(): Array<Readonly<USBDevice>> 27 28获取USB设备列表。 29 30**系统能力：** SystemCapability.USB.USBManager 31 32**返回值：** 33 34| 类型 | 说明 | 35| ---------------------------------------------------- | ------- | 36| Array<Readonly<[USBDevice](#usbdevice)>> | 设备信息列表。 | 37 38**示例：** 39 40```js 41let devicesList = usb.getDevices(); 42console.log(`devicesList = ${devicesList}`); 43//devicesList 返回的数据结构 44//此处提供一个简单的示例，如下 45/*[ 46 { 47 name: "1-1", 48 serial: "", 49 manufacturerName: "", 50 productName: "", 51 version: "", 52 vendorId: 7531, 53 productId: 2, 54 clazz: 9, 55 subClass: 0, 56 protocol: 1, 57 devAddress: 1, 58 busNum: 1, 59 configs: [ 60 { 61 id: 1, 62 attributes: 224, 63 isRemoteWakeup: true, 64 isSelfPowered: true, 65 maxPower: 0, 66 name: "1-1", 67 interfaces: [ 68 { 69 id: 0, 70 protocol: 0, 71 clazz: 9, 72 subClass: 0, 73 alternateSetting: 0, 74 name: "1-1", 75 endpoints: [ 76 { 77 address: 129, 78 attributes: 3, 79 interval: 12, 80 maxPacketSize: 4, 81 direction: 128, 82 number: 1, 83 type: 3, 84 interfaceId: 0, 85 }, 86 ], 87 }, 88 ], 89 }, 90 ], 91 }, 92]*/ 93``` 94 95## usb.connectDevice 96 97connectDevice(device: USBDevice): Readonly<USBDevicePipe> 98 99打开USB设备。 100 101需要调用[usb.getDevices](#usbgetdevices)获取设备信息以及device，再调用[usb.requestRight](#usbrequestright)获取设备请求权限。 102 103**系统能力：** SystemCapability.USB.USBManager 104 105**参数：** 106 107| 参数名 | 类型 | 必填 | 说明 | 108| -------- | -------- | -------- | -------- | 109| device | [USBDevice](#usbdevice) | 是 | USB设备信息。 | 110 111**返回值：** 112 113| 类型 | 说明 | 114| -------- | -------- | 115| Readonly<[USBDevicePipe](#usbdevicepipe)> | 指定的传输通道对象。 | 116 117**示例：** 118 119```js 120let devicepipe= usb.connectDevice(device); 121console.log(`devicepipe = ${devicepipe}`); 122``` 123 124## usb.hasRight 125 126hasRight(deviceName: string): boolean 127 128判断是否有权访问该设备。 129 130**系统能力：** SystemCapability.USB.USBManager 131 132**参数：** 133 134| 参数名 | 类型 | 必填 | 说明 | 135| -------- | -------- | -------- | -------- | 136| deviceName | string | 是 | 设备名称。 | 137 138**返回值：** 139 140| 类型 | 说明 | 141| -------- | -------- | 142| boolean | true表示有访问设备的权限，false表示没有访问设备的权限。 | 143 144**示例：** 145 146```js 147let devicesName= "1-1"; 148let bool = usb.hasRight(devicesName); 149console.log(`hasRight = ${bool}`); 150``` 151 152## usb.requestRight 153 154requestRight(deviceName: string): Promise<boolean> 155 156请求软件包的临时权限以访问设备。使用Promise异步回调。系统应用默认拥有访问设备权限，无需调用此接口申请。 157 158**系统能力：** SystemCapability.USB.USBManager 159 160**参数：** 161 162| 参数名 | 类型 | 必填 | 说明 | 163| -------- | -------- | -------- | -------- | 164| deviceName | string | 是 | 设备名称。 | 165 166**返回值：** 167 168| 类型 | 说明 | 169| -------- | -------- | 170| Promise<boolean> | Promise对象，返回临时权限的申请结果。返回true表示临时权限申请成功；返回false则表示临时权限申请失败。 | 171 172**示例：** 173 174```js 175let devicesName= "1-1"; 176usb.requestRight(devicesName).then((ret) => { 177 console.log(`requestRight = ${ret}`); 178}); 179``` 180 181## usb.claimInterface 182 183claimInterface(pipe: USBDevicePipe, iface: USBInterface, force ?: boolean): number 184 185注册通信接口。 186 187需要调用[usb.getDevices](#usbgetdevices)获取设备信息以及interfaces；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)接口得到devicepipe作为参数。 188 189**系统能力：** SystemCapability.USB.USBManager 190 191**参数：** 192 193| 参数名 | 类型 | 必填 | 说明 | 194| -------- | -------- | -------- | -------- | 195| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 | 196| iface | [USBInterface](#usbinterface) | 是 | 用于确定需要获取接口的索引。 | 197| force | boolean | 否 | 可选参数，是否强制获取。默认值为false ，表示不强制获取。 | 198 199**返回值：** 200 201| 类型 | 说明 | 202| -------- | -------- | 203| number | 注册通信接口成功返回0；注册通信接口失败返回其他错误码。 | 204 205**示例：** 206 207```js 208let ret = usb.claimInterface(devicepipe, interfaces); 209console.log(`claimInterface = ${ret}`); 210``` 211 212## usb.releaseInterface 213 214releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number 215 216释放注册过的通信接口。 217 218需要调用[usb.claimInterface](#usbclaiminterface)先获取接口，才能使用此方法释放接口。 219 220**系统能力：** SystemCapability.USB.USBManager 221 222**参数：** 223 224| 参数名 | 类型 | 必填 | 说明 | 225| -------- | -------- | -------- | -------- | 226| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 | 227| iface | [USBInterface](#usbinterface) | 是 | 用于确定需要释放接口的索引。 | 228 229**返回值：** 230 231| 类型 | 说明 | 232| -------- | -------- | 233| number | 释放接口成功返回0；释放接口失败返回其他错误码。 | 234 235**示例：** 236 237```js 238let ret = usb.releaseInterface(devicepipe, interfaces); 239console.log(`releaseInterface = ${ret}`); 240``` 241 242## usb.setConfiguration 243 244setConfiguration(pipe: USBDevicePipe, config: USBConfig): number 245 246设置设备配置。 247 248需要调用[usb.getDevices](#usbgetdevices)获取设备信息以及config；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)得到devicepipe作为参数。 249 250**系统能力：** SystemCapability.USB.USBManager 251 252**参数：** 253 254| 参数名 | 类型 | 必填 | 说明 | 255| -------- | -------- | -------- | -------- | 256| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 | 257| config | [USBConfig](#usbconfig) | 是 | 用于确定需要设置的配置。 | 258 259**返回值：** 260 261| 类型 | 说明 | 262| -------- | -------- | 263| number | 设置设备配置成功返回0；设置设备配置失败返回其他错误码。 | 264 265**示例：** 266 267```js 268let ret = usb.setConfiguration(devicepipe, config); 269console.log(`setConfiguration = ${ret}`); 270``` 271 272## usb.setInterface 273 274setInterface(pipe: USBDevicePipe, iface: USBInterface): number 275 276设置设备接口。 277 278需要调用[usb.getDevices](#usbgetdevices)获取设备列表以及interfaces；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)得到devicepipe作为参数；调用[usb.claimInterface](#usbclaiminterface)注册通信接口。 279 280**系统能力：** SystemCapability.USB.USBManager 281 282**参数：** 283 284| 参数名 | 类型 | 必填 | 说明 | 285| ----- | ------------------------------- | --- | ------------- | 286| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 | 287| iface | [USBInterface](#usbinterface) | 是 | 用于确定需要设置的接口。 | 288 289**返回值：** 290 291| 类型 | 说明 | 292| -------- | -------- | 293| number | 设置设备接口成功返回0；设置设备接口失败返回其他错误码。 | 294 295**示例：** 296 297```js 298let ret = usb.setInterface(devicepipe, interfaces); 299console.log(`setInterface = ${ret}`); 300``` 301 302## usb.getRawDescriptor 303 304getRawDescriptor(pipe: USBDevicePipe): Uint8Array 305 306获取原始的USB描述符。 307 308需要调用[usb.getDevices](#usbgetdevices)获取设备列表；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)接口得到devicepipe作为参数。 309 310**系统能力：** SystemCapability.USB.USBManager 311 312**参数：** 313 314| 参数名 | 类型 | 必填 | 说明 | 315| -------- | -------- | -------- | -------- | 316| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 | 317 318**返回值：** 319 320| 类型 | 说明 | 321| -------- | -------- | 322| Uint8Array | 返回获取的原始数据；失败返回undefined。 | 323 324**示例：** 325 326```js 327let ret = usb.getRawDescriptor(devicepipe); 328``` 329 330## usb.getFileDescriptor 331 332getFileDescriptor(pipe: USBDevicePipe): number 333 334获取文件描述符。 335 336需要调用[usb.getDevices](#usbgetdevices)获取设备列表；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)接口得到devicepipe作为参数。 337 338**系统能力：** SystemCapability.USB.USBManager 339 340**参数：** 341 342| 参数名 | 类型 | 必填 | 说明 | 343| -------- | -------- | -------- | -------- | 344| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 | 345 346**返回值：** 347 348| 类型 | 说明 | 349| ------ | -------------------- | 350| number | 返回设备对应的文件描述符；失败返回-1。 | 351 352**示例：** 353 354```js 355let ret = usb.getFileDescriptor(devicepipe); 356``` 357 358## usb.controlTransfer 359 360controlTransfer(pipe: USBDevicePipe, controlparam: USBControlParams, timeout ?: number): Promise<number> 361 362控制传输。 363 364需要调用[usb.getDevices](#usbgetdevices)获取设备列表；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)接口得到devicepipe作为参数。 365 366**系统能力：** SystemCapability.USB.USBManager 367 368**参数：** 369 370| 参数名 | 类型 | 必填 | 说明 | 371| -------- | -------- | -------- | -------- | 372| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定设备。 | 373| controlparam | [USBControlParams](#usbcontrolparams) | 是 | 控制传输参数。 | 374| timeout | number | 否 | 超时时间（单位：ms），可选参数，默认为0不超时。 | 375 376**返回值：** 377 378| 类型 | 说明 | 379| -------- | -------- | 380| Promise<number> | Promise对象，获取传输或接收到的数据块大小。失败返回-1。 | 381 382**示例：** 383 384```js 385let param = { 386 request: 0, 387 reqType: 0, 388 target:0, 389 value: 0, 390 index: 0, 391 data: null 392}; 393usb.controlTransfer(devicepipe, param).then((ret) => { 394 console.log(`controlTransfer = ${ret}`); 395}) 396``` 397 398## usb.bulkTransfer 399 400bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, timeout ?: number): Promise<number> 401 402批量传输。 403 404需要调用[usb.getDevices](#usbgetdevices)获取设备信息列表以及endpoint；再调用[usb.requestRight](#usbrequestright)获取设备请求权限；然后调用[usb.connectDevice](#usbconnectdevice)接口得到返回数据devicepipe之后，再次获取接口[usb.claimInterface](#usbclaiminterface)；再调用usb.bulkTransfer接口。 405 406**系统能力：** SystemCapability.USB.USBManager 407 408**参数：** 409 410| 参数名 | 类型 | 必填 | 说明 | 411| -------- | -------- | -------- | -------- | 412| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定设备。 | 413| endpoint | [USBEndpoint](#usbendpoint) | 是 | 用于确定传输的端口。 | 414| buffer | Uint8Array | 是 | 用于写入或读取的缓冲区。 | 415| timeout | number | 否 | 超时时间（单位：ms），可选参数，默认为0不超时。| 416 417**返回值：** 418 419| 类型 | 说明 | 420| -------- | -------- | 421| Promise<number> | Promise对象，获取传输或接收到的数据块大小。失败返回-1。 | 422 423**示例：** 424 425```js 426//usb.getDevices 接口返回数据集合，取其中一个设备对象，并获取权限 。 427//把获取到的设备对象作为参数传入usb.connectDevice;当usb.connectDevice接口成功返回之后； 428//才可以调用第三个接口usb.claimInterface.当usb.claimInterface 调用成功以后,再调用该接口。 429usb.bulkTransfer(devicepipe, endpoint, buffer).then((ret) => { 430 console.log(`bulkTransfer = ${ret}`); 431}); 432``` 433 434## usb.closePipe 435 436closePipe(pipe: USBDevicePipe): number 437 438关闭设备消息控制通道。 439 440需要调用[usb.getDevices](#usbgetdevices)获取设备列表；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)得到devicepipe作为参数。 441 442**系统能力：** SystemCapability.USB.USBManager 443 444**参数：** 445 446| 参数名 | 类型 | 必填 | 说明 | 447| -------- | -------- | -------- | -------- | 448| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定USB设备消息控制通道。 | 449 450**返回值：** 451 452| 类型 | 说明 | 453| -------- | -------- | 454| number | 关闭设备消息控制通道成功返回0；关闭设备消息控制通道失败返回其他错误码。 | 455 456**示例：** 457 458```js 459let ret = usb.closePipe(devicepipe); 460console.log(`closePipe = ${ret}`); 461``` 462 463## USBEndpoint 464 465通过USB发送和接收数据的端口。通过[USBInterface](#usbinterface)获取。 466 467**系统能力：** SystemCapability.USB.USBManager 468 469| 名称 | 类型 | 必填 | 说明 | 470| ------------- | ------------------------------------------- | ------------- |------------ | 471| address | number | 是 |端点地址。 | 472| attributes | number | 是 |端点属性。 | 473| interval | number | 是 |端点间隔。 | 474| maxPacketSize | number | 是 |端点最大数据包大小。 | 475| direction | [USBRequestDirection](#usbrequestdirection) | 是 |端点的方向。 | 476| number | number | 是 |端点号。 | 477| type | number | 是 |端点类型。 | 478| interfaceId | number | 是 |端点所属的接口的唯一标识。 | 479 480## USBInterface 481 482一个[USBConfig](#usbconfig)中可以含有多个USBInterface，每个USBInterface提供一个功能。 483 484**系统能力：** SystemCapability.USB.USBManager 485 486| 名称 | 类型 | 必填 |说明 | 487| ---------------- | ---------------------------------------- | ------------- |--------------------- | 488| id | number | 是 |接口的唯一标识。 | 489| protocol | number | 是 |接口的协议。 | 490| clazz | number | 是 |设备类型。 | 491| subClass | number | 是 |设备子类。 | 492| alternateSetting | number | 是 |在同一个接口中的多个描述符中进行切换设置。 | 493| name | string | 是 |接口名称。 | 494| endpoints | Array<[USBEndpoint](#usbendpoint)> | 是 |当前接口所包含的端点。 | 495 496## USBConfig 497 498USB配置，一个[USBDevice](#usbdevice)中可以含有多个配置。 499 500**系统能力：** SystemCapability.USB.USBManager 501 502| 名称 | 类型 | 必填 |说明 | 503| -------------- | ------------------------------------------------ | --------------- |----------- | 504| id | number | 是 |配置的唯一标识。 | 505| attributes | number | 是 |配置的属性。 | 506| maxPower | number | 是 |最大功耗，以毫安为单位。 | 507| name | string | 是 |配置的名称，可以为空。 | 508| isRemoteWakeup | boolean | 是 |检查当前配置是否支持远程唤醒。 | 509| isSelfPowered | boolean | 是 |检查当前配置是否支持独立电源。 | 510| interfaces | Array <[USBInterface](#usbinterface)> | 是 |配置支持的接口属性。 | 511 512## USBDevice 513 514USB设备信息。 515 516**系统能力：** SystemCapability.USB.USBManager 517 518| 名称 | 类型 | 必填 |说明 | 519| ---------------- | ------------------------------------ | ---------- |---------- | 520| busNum | number | 是 |总线地址。 | 521| devAddress | number | 是 |设备地址。 | 522| serial | string | 是 |序列号。 | 523| name | string | 是 |设备名字。 | 524| manufacturerName | string | 是 |产商信息。 | 525| productName | string | 是 |产品信息。 | 526| version | string | 是 |版本。 | 527| vendorId | number | 是 |厂商ID。 | 528| productId | number | 是 |产品ID。 | 529| clazz | number | 是 |设备类。 | 530| subClass | number | 是 |设备子类。 | 531| protocol | number | 是 |设备协议码。 | 532| configs | Array<[USBConfig](#usbconfig)> | 是 |设备配置描述符信息。 | 533 534## USBDevicePipe 535 536USB设备消息传输通道，用于确定设备。 537 538**系统能力：** SystemCapability.USB.USBManager 539 540| 名称 | 类型 | 必填 |说明 | 541| ---------- | ------ | ----- |----- | 542| busNum | number | 是 |总线地址。 | 543| devAddress | number | 是 |设备地址。 | 544 545## USBControlParams 546 547控制传输参数。 548 549**系统能力：** SystemCapability.USB.USBManager 550 551| 名称 | 类型 | 必填 |说明 | 552| ------- | ----------------------------------------------- | ---------------- |---------------- | 553| request | number | 是 |请求类型。 | 554| target | [USBRequestTargetType](#usbrequesttargettype) | 是 |请求目标类型。 | 555| reqType | [USBControlRequestType](#usbcontrolrequesttype) | 是 |请求控制类型。 | 556| value | number | 是 |请求参数。 | 557| index | number | 是 |请求参数value对应的索引值。 | 558| data | Uint8Array | 是 |用于写入或读取的缓冲区。 | 559 560 561## USBRequestTargetType 562 563请求目标类型。 564 565**系统能力：** SystemCapability.USB.USBManager 566 567| 名称 | 值 | 说明 | 568| ---------------------------- | ---- | ------ | 569| USB_REQUEST_TARGET_DEVICE | 0 | 设备。 | 570| USB_REQUEST_TARGET_INTERFACE | 1 | 接口。 | 571| USB_REQUEST_TARGET_ENDPOINT | 2 | 端点。 | 572| USB_REQUEST_TARGET_OTHER | 3 | 其他。 | 573 574## USBControlRequestType 575 576控制请求类型。 577 578**系统能力：** SystemCapability.USB.USBManager 579 580| 名称 | 值 | 说明 | 581| ------------------------- | ---- | ------ | 582| USB_REQUEST_TYPE_STANDARD | 0 | 标准。 | 583| USB_REQUEST_TYPE_CLASS | 1 | 类。 | 584| USB_REQUEST_TYPE_VENDOR | 2 | 厂商。 | 585 586## USBRequestDirection 587 588请求方向。 589 590**系统能力：** SystemCapability.USB.USBManager 591 592| 名称 | 值 | 说明 | 593| --------------------------- | ---- | ------------------------ | 594| USB_REQUEST_DIR_TO_DEVICE | 0 | 写数据，主设备往从设备。 | 595| USB_REQUEST_DIR_FROM_DEVICE | 0x80 | 读数据，从设备往主设备。 | 596 597