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