1# @ohos.usbManager (USB管理) 2 3本模块主要提供管理USB设备的相关功能，包括主设备上查询USB设备列表、批量数据传输、控制命令传输、权限控制等；从设备上端口管理、功能切换及查询等。 4 5> **说明：** 6> 7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```ts 12import { usbManager } from '@kit.BasicServicesKit'; 13``` 14 15## usbManager.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 31```ts 32let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 33console.log(`devicesList = ${devicesList}`); 34/* 35devicesList 返回的数据结构,此处提供一个简单的示例，如下 36[ 37 { 38 name: "1-1", 39 serial: "", 40 manufacturerName: "", 41 productName: "", 42 version: "", 43 vendorId: 7531, 44 productId: 2, 45 clazz: 9, 46 subClass: 0, 47 protocol: 1, 48 devAddress: 1, 49 busNum: 1, 50 configs: [ 51 { 52 id: 1, 53 attributes: 224, 54 isRemoteWakeup: true, 55 isSelfPowered: true, 56 maxPower: 0, 57 name: "1-1", 58 interfaces: [ 59 { 60 id: 0, 61 protocol: 0, 62 clazz: 9, 63 subClass: 0, 64 alternateSetting: 0, 65 name: "1-1", 66 endpoints: [ 67 { 68 address: 129, 69 attributes: 3, 70 interval: 12, 71 maxPacketSize: 4, 72 direction: 128, 73 number: 1, 74 type: 3, 75 interfaceId: 0, 76 }, 77 ], 78 }, 79 ], 80 }, 81 ], 82 }, 83] 84*/ 85``` 86 87## usbManager.connectDevice 88 89connectDevice(device: USBDevice): Readonly<USBDevicePipe> 90 91根据getDevices()返回的设备信息打开USB设备。 92 93需要调用[usbManager.getDevices](#usbmanagergetdevices)获取设备信息以及device，再调用[usbManager.requestRight](#usbmanagerrequestright)请求使用该设备的权限。 94 95**系统能力：** SystemCapability.USB.USBManager 96 97**参数：** 98 99| 参数名 | 类型 | 必填 | 说明 | 100| -------- | -------- | -------- | ---------------- | 101| device | [USBDevice](#usbdevice) | 是 | USB设备信息，用getDevices获取的busNum和devAddress确定设备，当前其他属性不做处理。 | 102 103**返回值：** 104 105| 类型 | 说明 | 106| -------- | -------- | 107| Readonly<[USBDevicePipe](#usbdevicepipe)> | 指定的传输通道对象。 | 108 109**错误码：** 110 111以下错误码的详细介绍参见[USB服务错误码](errorcode-usb.md)。 112 113| 错误码ID | 错误信息 | 114| -------- | ------------------------------------------------------------ | 115| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 116| 14400001 | Permission denied. Call requestRight to get the permission first. | 117 118**示例：** 119 120```ts 121let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 122if (devicesList.length == 0) { 123 console.log(`device list is empty`); 124} 125 126let device: usbManager.USBDevice = devicesList[0]; 127usbManager.requestRight(device.name); 128let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 129console.log(`devicepipe = ${devicepipe}`); 130``` 131 132## usbManager.hasRight 133 134hasRight(deviceName: string): boolean 135 136判断是否有权访问该设备。 137 138如果“使用者”（如各种App或系统）有权访问设备则返回true；无权访问设备则返回false。 139 140**系统能力：** SystemCapability.USB.USBManager 141 142**参数：** 143 144| 参数名 | 类型 | 必填 | 说明 | 145| -------- | -------- | -------- | -------- | 146| deviceName | string | 是 | 设备名称，来自getDevices获取的设备列表。 | 147 148**错误码：** 149 150以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 151 152| 错误码ID | 错误信息 | 153| -------- | ------------------------------------------------------------ | 154| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 155 156**返回值：** 157 158| 类型 | 说明 | 159| -------- | -------- | 160| boolean | true表示有访问设备的权限，false表示没有访问设备的权限。 | 161 162**示例：** 163 164```ts 165let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 166if (devicesList.length == 0) { 167 console.log(`device list is empty`); 168} 169 170let device: usbManager.USBDevice = devicesList[0]; 171usbManager.requestRight(device.name); 172let right: boolean = usbManager.hasRight(device.name); 173console.log(`${right}`); 174``` 175 176## usbManager.requestRight 177 178requestRight(deviceName: string): Promise<boolean> 179 180请求软件包的临时权限以访问设备。使用Promise异步回调。系统应用默认拥有访问设备权限，无需调用此接口申请。 181 182**系统能力：** SystemCapability.USB.USBManager 183 184**参数：** 185 186| 参数名 | 类型 | 必填 | 说明 | 187| -------- | -------- | -------- | -------- | 188| deviceName | string | 是 | 设备名称，来自getDevices获取的设备列表。| 189 190**错误码：** 191 192以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 193 194| 错误码ID | 错误信息 | 195| -------- | ------------------------------------------------------------ | 196| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 197 198**返回值：** 199 200| 类型 | 说明 | 201| -------- | -------- | 202| Promise<boolean> | Promise对象，返回临时权限的申请结果。返回true表示临时权限申请成功；返回false则表示临时权限申请失败。 | 203 204**示例：** 205 206```ts 207let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 208if (devicesList.length == 0) { 209 console.log(`device list is empty`); 210} 211 212let device: usbManager.USBDevice = devicesList[0]; 213usbManager.requestRight(device.name).then(ret => { 214 console.log(`requestRight = ${ret}`); 215}); 216``` 217 218## usbManager.removeRight 219 220removeRight(deviceName: string): boolean 221 222移除软件包访问设备的权限。系统应用默认拥有访问设备权限，调用此接口不会产生影响。 223 224**系统能力：** SystemCapability.USB.USBManager 225 226**参数：** 227 228| 参数名 | 类型 | 必填 | 说明 | 229| -------- | -------- | -------- | -------- | 230| deviceName | string | 是 | 设备名称，来自getDevices获取的设备列表。| 231 232**错误码：** 233 234以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 235 236| 错误码ID | 错误信息 | 237| -------- | ------------------------------------------------------------ | 238| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 239 240**返回值：** 241 242| 类型 | 说明 | 243| -------- | -------- | 244| boolean | 返回权限移除结果。返回true表示权限移除成功；返回false则表示权限移除失败。 | 245 246**示例：** 247 248```ts 249let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 250if (devicesList.length == 0) { 251 console.log(`device list is empty`); 252} 253 254let device: usbManager.USBDevice = devicesList[0]; 255if (usbManager.removeRight(device.name)) { 256 console.log(`Succeed in removing right`); 257} 258``` 259 260## usbManager.claimInterface 261 262claimInterface(pipe: USBDevicePipe, iface: USBInterface, force ?: boolean): number 263 264注册通信接口。 265 266需要调用[usbManager.getDevices](#usbmanagergetdevices)获取设备信息以及interfaces；调用[usbManager.requestRight](#usbmanagerrequestright)获取设备请求权限；调用[usbManager.connectDevice](#usbmanagerconnectdevice)接口得到devicepipe作为参数。 267 268**系统能力：** SystemCapability.USB.USBManager 269 270**参数：** 271 272| 参数名 | 类型 | 必填 | 说明 | 273| -------- | -------- | -------- | -------- | 274| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址，需要调用connectDevice获取。| 275| iface | [USBInterface](#usbinterface) | 是 | 用于确定需要获取接口的索引，需要调用getDevices获取设备信息并通过id确定唯一接口。| 276| force | boolean | 否 | 可选参数，是否强制获取。默认值为false ，表示不强制获取，用户按需选择。| 277 278**错误码：** 279 280以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 281 282| 错误码ID | 错误信息 | 283| -------- | ------------------------------------------------------------ | 284| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 285 286**返回值：** 287 288| 类型 | 说明 | 289| -------- | -------- | 290| number | 注册通信接口成功返回0；注册通信接口失败返回其他错误码。 | 291 292**示例：** 293 294```ts 295let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 296if (devicesList.length == 0) { 297 console.log(`device list is empty`); 298} 299 300let device: usbManager.USBDevice = devicesList[0]; 301usbManager.requestRight(device.name); 302let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 303let interfaces: usbManager.USBInterface = device.configs[0].interfaces[0]; 304let ret: number= usbManager.claimInterface(devicepipe, interfaces); 305console.log(`claimInterface = ${ret}`); 306``` 307 308## usbManager.releaseInterface 309 310releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number 311 312释放注册过的通信接口。 313 314需要调用[usbManager.claimInterface](#usbmanagerclaiminterface)先获取接口，才能使用此方法释放接口。 315 316**系统能力：** SystemCapability.USB.USBManager 317 318**参数：** 319 320| 参数名 | 类型 | 必填 | 说明 | 321| -------- | -------- | -------- | -------- | 322| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址，需要调用connectDevice获取。| 323| iface | [USBInterface](#usbinterface) | 是 | 用于确定需要释放接口的索引，需要调用getDevices获取设备信息并通过id确定唯一接口。| 324 325**错误码：** 326 327以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 328 329| 错误码ID | 错误信息 | 330| -------- | ------------------------------------------------------------ | 331| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified.2.Incorrect parameter types. | 332 333**返回值：** 334 335| 类型 | 说明 | 336| -------- | -------- | 337| number | 释放接口成功返回0；释放接口失败返回其他错误码。 | 338 339**示例：** 340 341```ts 342let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 343if (devicesList.length == 0) { 344 console.log(`device list is empty`); 345} 346 347let device: usbManager.USBDevice = devicesList[0]; 348usbManager.requestRight(device.name); 349let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 350let interfaces: usbManager.USBInterface = device.configs[0].interfaces[0]; 351let ret: number = usbManager.claimInterface(devicepipe, interfaces); 352ret = usbManager.releaseInterface(devicepipe, interfaces); 353console.log(`releaseInterface = ${ret}`); 354``` 355 356## usbManager.setConfiguration 357 358setConfiguration(pipe: USBDevicePipe, config: USBConfiguration): number 359 360设置设备配置。 361 362需要调用[usbManager.getDevices](#usbmanagergetdevices)获取设备信息以及config；调用[usbManager.requestRight](#usbmanagerrequestright)获取设备请求权限；调用[usbManager.connectDevice](#usbmanagerconnectdevice)得到devicepipe作为参数。 363 364**系统能力：** SystemCapability.USB.USBManager 365 366**参数：** 367 368| 参数名 | 类型 | 必填 | 说明 | 369| -------- | -------- | -------- | -------- | 370| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址，需要调用connectDevice获取。| 371| config | [USBConfiguration](#usbconfiguration) | 是 | 用于确定需要设置的配置，需要调用getDevices获取设备信息并通过id用于确定唯一设置。| 372 373**错误码：** 374 375以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 376 377| 错误码ID | 错误信息 | 378| -------- | ------------------------------------------------------------ | 379| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 380 381**返回值：** 382 383| 类型 | 说明 | 384| -------- | -------- | 385| number | 设置设备配置成功返回0；设置设备配置失败返回其他错误码。 | 386 387**示例：** 388 389```ts 390let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 391if (devicesList.length == 0) { 392 console.log(`device list is empty`); 393} 394 395let device: usbManager.USBDevice = devicesList[0]; 396usbManager.requestRight(device.name); 397let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 398let config: usbManager.USBConfiguration = device.configs[0]; 399let ret: number= usbManager.setConfiguration(devicepipe, config); 400console.log(`setConfiguration = ${ret}`); 401``` 402 403## usbManager.setInterface 404 405setInterface(pipe: USBDevicePipe, iface: USBInterface): number 406 407设置设备接口。 408 409需要调用[usbManager.getDevices](#usbmanagergetdevices)获取设备列表以及interfaces；调用[usbManager.requestRight](#usbmanagerrequestright)获取设备请求权限；调用[usbManager.connectDevice](#usbmanagerconnectdevice)得到devicepipe作为参数；调用[usbManager.claimInterface](#usbmanagerclaiminterface)注册通信接口。 410 411**系统能力：** SystemCapability.USB.USBManager 412 413**参数：** 414 415| 参数名 | 类型 | 必填 | 说明 | 416| -------- | -------- | -------- | -------- | 417| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址，需要调用connectDevice获取。| 418| iface | [USBInterface](#usbinterface) | 是 | 用于确定需要设置的接口，需要调用getDevices获取设备信息并通过id和alternateSetting确定唯一接口。| 419 420**错误码：** 421 422以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 423 424| 错误码ID | 错误信息 | 425| -------- | ------------------------------------------------------------ | 426| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 427 428**返回值：** 429 430| 类型 | 说明 | 431| -------- | -------- | 432| number | 设置设备接口成功返回0；设置设备接口失败返回其他错误码。 | 433 434**示例：** 435 436```ts 437let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 438if (devicesList.length == 0) { 439 console.log(`device list is empty`); 440} 441 442let device: usbManager.USBDevice = devicesList[0]; 443usbManager.requestRight(device.name); 444let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 445let interfaces: usbManager.USBInterface = device.configs[0].interfaces[0]; 446let ret: number = usbManager.claimInterface(devicepipe, interfaces); 447ret = usbManager.setInterface(devicepipe, interfaces); 448console.log(`setInterface = ${ret}`); 449``` 450 451## usbManager.getRawDescriptor 452 453getRawDescriptor(pipe: USBDevicePipe): Uint8Array 454 455获取原始的USB描述符。 456 457需要调用[usbManager.getDevices](#usbmanagergetdevices)获取设备列表；调用[usbManager.requestRight](#usbmanagerrequestright)获取设备请求权限；调用[usbManager.connectDevice](#usbmanagerconnectdevice)接口得到devicepipe作为参数。 458 459**系统能力：** SystemCapability.USB.USBManager 460 461**参数：** 462 463| 参数名 | 类型 | 必填 | 说明 | 464| -------- | -------- | -------- | -------- | 465| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址，需要调用connectDevice获取。| 466 467**错误码：** 468 469以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 470 471| 错误码ID | 错误信息 | 472| -------- | ------------------------------------------------------------ | 473| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 474 475**返回值：** 476 477| 类型 | 说明 | 478| -------- | -------- | 479| Uint8Array | 返回获取的原始数据；失败返回undefined。 | 480 481**示例：** 482 483```ts 484let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 485if (devicesList.length == 0) { 486 console.log(`device list is empty`); 487} 488 489usbManager.requestRight(devicesList[0].name); 490let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 491let ret: Uint8Array = usbManager.getRawDescriptor(devicepipe); 492``` 493 494## usbManager.getFileDescriptor 495 496getFileDescriptor(pipe: USBDevicePipe): number 497 498获取文件描述符。 499 500需要调用[usbManager.getDevices](#usbmanagergetdevices)获取设备列表；调用[usbManager.requestRight](#usbmanagerrequestright)获取设备请求权限；调用[usbManager.connectDevice](#usbmanagerconnectdevice)接口得到devicepipe作为参数。 501 502**系统能力：** SystemCapability.USB.USBManager 503 504**参数：** 505 506| 参数名 | 类型 | 必填 | 说明 | 507| -------- | -------- | -------- | -------- | 508| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址，需要调用connectDevice获取。| 509 510**错误码：** 511 512以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 513 514| 错误码ID | 错误信息 | 515| -------- | ------------------------------------------------------------ | 516| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 517 518**返回值：** 519 520| 类型 | 说明 | 521| ------ | -------------------- | 522| number | 返回设备对应的文件描述符；失败返回-1。 | 523 524**示例：** 525 526```ts 527let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 528if (devicesList.length == 0) { 529 console.log(`device list is empty`); 530} 531 532usbManager.requestRight(devicesList[0].name); 533let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 534let ret: number = usbManager.getFileDescriptor(devicepipe); 535``` 536 537## usbManager.controlTransfer<sup>(deprecated)</sup> 538 539controlTransfer(pipe: USBDevicePipe, controlparam: USBControlParams, timeout ?: number): Promise<number> 540 541控制传输。 542 543需要调用[usbManager.getDevices](#usbmanagergetdevices)获取设备列表；调用[usbManager.requestRight](#usbmanagerrequestright)获取设备请求权限；调用[usbManager.connectDevice](#usbmanagerconnectdevice)接口得到devicepipe作为参数。 544 545**说明：** 546 547> 从 API version 9开始支持，从API version 12开始废弃。建议使用 [usbControlTransfer](#usbmanagerusbcontroltransfer12) 替代。 548 549**系统能力：** SystemCapability.USB.USBManager 550 551**参数：** 552 553| 参数名 | 类型 | 必填 | 说明 | 554| -------- | -------- | -------- | -------- | 555| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定设备，需要调用connectDevice获取。| 556| controlparam | [USBControlParams](#usbcontrolparams) | 是 | 控制传输参数，按需设置参数，参数传参类型请参考USB协议。| 557| timeout | number | 否 | 超时时间（单位：ms），可选参数，默认为0不超时，用户按需选择 。 | 558 559**错误码：** 560 561以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 562 563| 错误码ID | 错误信息 | 564| -------- | ------------------------------------------------------------ | 565| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 566 567**返回值：** 568 569| 类型 | 说明 | 570| -------- | -------- | 571| Promise<number> | Promise对象，获取传输或接收到的数据块大小。失败返回-1。 | 572 573**示例：** 574 575```ts 576class PARA { 577 request: number = 0 578 reqType: usbManager.USBControlRequestType = 0 579 target: usbManager.USBRequestTargetType = 0 580 value: number = 0 581 index: number = 0 582 data: Uint8Array = new Uint8Array() 583} 584 585let param: PARA = { 586 request: 0x06, 587 reqType: 0x80, 588 target:0, 589 value: 0x01 << 8 | 0, 590 index: 0, 591 data: new Uint8Array(18) 592}; 593 594let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 595if (devicesList.length == 0) { 596 console.log(`device list is empty`); 597} 598 599usbManager.requestRight(devicesList[0].name); 600let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 601usbManager.controlTransfer(devicepipe, param).then((ret: number) => { 602console.log(`controlTransfer = ${ret}`); 603}) 604``` 605 606## usbManager.usbControlTransfer<sup>12+</sup> 607 608usbControlTransfer(pipe: USBDevicePipe, requestparam: USBDeviceRequestParams, timeout ?: number): Promise<number> 609 610控制传输。 611 612需要调用[usbManager.getDevices](#usbmanagergetdevices)获取设备列表；调用[usbManager.requestRight](#usbmanagerrequestright)获取设备请求权限；调用[usbManager.connectDevice](#usbmanagerconnectdevice)接口得到devicepipe作为参数。 613 614**系统能力：** SystemCapability.USB.USBManager 615 616**参数：** 617 618| 参数名 | 类型 | 必填 | 说明 | 619| -------- | -------- | -------- | -------- | 620| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定设备。 | 621| requestparam | [USBDeviceRequestParams](#usbdevicerequestparams12) | 是 | 控制传输参数，按需设置参数，参数传参类型请参考USB协议。 | 622| timeout | number | 否 | 超时时间（单位：ms），可选参数，默认为0不超时。 | 623 624**错误码：** 625 626以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 627 628| 错误码ID | 错误信息 | 629| -------- | ------------------------------------------------------------ | 630| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified.2.Incorrect parameter types | 631 632**返回值：** 633 634| 类型 | 说明 | 635| -------- | -------- | 636| Promise<number> | Promise对象，获取传输或接收到的数据块大小。失败返回-1。 | 637 638**示例：** 639 640```ts 641class PARA { 642 bmRequestType: number = 0 643 bRequest: number = 0 644 wValue: number = 0 645 wIndex: number = 0 646 wLength: number = 0 647 data: Uint8Array = new Uint8Array() 648} 649 650let param: PARA = { 651 bmRequestType: 0x80, 652 bRequest: 0x06, 653 654 wValue:0x01 << 8 | 0, 655 wIndex: 0, 656 wLength: 18, 657 data: new Uint8Array(18) 658}; 659 660let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 661if (devicesList.length == 0) { 662 console.log(`device list is empty`); 663} 664 665usbManager.requestRight(devicesList[0].name); 666let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 667usbManager.usbControlTransfer(devicepipe, param).then((ret: number) => { 668console.log(`usbControlTransfer = ${ret}`); 669}) 670``` 671 672## usbManager.bulkTransfer 673 674bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, timeout ?: number): Promise<number> 675 676批量传输。 677 678需要调用[usbManager.getDevices](#usbmanagergetdevices)获取设备信息列表以及endpoint；再调用[usbManager.requestRight](#usbmanagerrequestright)获取设备请求权限；然后调用[usbManager.connectDevice](#usbmanagerconnectdevice)接口得到返回数据devicepipe之后，再次获取接口[usbManager.claimInterface](#usbmanagerclaiminterface)；再调用usb.bulkTransfer接口。 679 680**系统能力：** SystemCapability.USB.USBManager 681 682**参数：** 683 684| 参数名 | 类型 | 必填 | 说明 | 685| -------- | -------- | -------- | -------- | 686| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定设备，需要调用connectDevice获取。| 687| endpoint | [USBEndpoint](#usbendpoint) | 是 | 用于确定传输的端口，需要调用getDevices获取设备信息列表以及endpoint，address用于确定端点地址，direction用于确定端点的方向，interfaceId用于确定所属接口，当前其他属性不做处理。| 688| buffer | Uint8Array | 是 | 用于写入或读取数据的缓冲区。 | 689| timeout | number | 否 | 超时时间（单位：ms），可选参数，默认为0不超时，用户按需选择 。 | 690 691**错误码：** 692 693以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 694 695| 错误码ID | 错误信息 | 696| -------- | ------------------------------------------------------------ | 697| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 698 699**返回值：** 700 701| 类型 | 说明 | 702| -------- | -------- | 703| Promise<number> | Promise对象，获取传输或接收到的数据块大小。失败返回-1。 | 704 705**示例：** 706 707```ts 708//usbManager.getDevices 接口返回数据集合，取其中一个设备对象，并获取权限 。 709//把获取到的设备对象作为参数传入usbManager.connectDevice;当usbManager.connectDevice接口成功返回之后； 710//才可以调用第三个接口usbManager.claimInterface.当usbManager.claimInterface 调用成功以后,再调用该接口。 711let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 712if (devicesList.length == 0) { 713 console.log(`device list is empty`); 714} 715 716let device: usbManager.USBDevice = devicesList[0]; 717usbManager.requestRight(device.name); 718 719let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 720for (let i = 0; i < device.configs[0].interfaces.length; i++) { 721 if (device.configs[0].interfaces[i].endpoints[0].attributes == 2) { 722 let endpoint: usbManager.USBEndpoint = device.configs[0].interfaces[i].endpoints[0]; 723 let interfaces: usbManager.USBInterface = device.configs[0].interfaces[i]; 724 let ret: number = usbManager.claimInterface(devicepipe, interfaces); 725 let buffer = new Uint8Array(128); 726 usbManager.bulkTransfer(devicepipe, endpoint, buffer).then((ret: number) => { 727 console.log(`bulkTransfer = ${ret}`); 728 }); 729 } 730} 731``` 732 733## usbManager.closePipe 734 735closePipe(pipe: USBDevicePipe): number 736 737关闭设备消息控制通道。 738 739需要调用[usbManager.getDevices](#usbmanagergetdevices)获取设备列表；调用[usbManager.requestRight](#usbmanagerrequestright)获取设备请求权限；调用[usbManager.connectDevice](#usbmanagerconnectdevice)得到devicepipe作为参数。 740 741**系统能力：** SystemCapability.USB.USBManager 742 743**参数：** 744 745| 参数名 | 类型 | 必填 | 说明 | 746| -------- | -------- | -------- | -------- | 747| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定USB设备消息控制通道，需要调用connectDevice获取。| 748 749**错误码：** 750 751以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 752 753| 错误码ID | 错误信息 | 754| -------- | ------------------------------------------------------------ | 755| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 756 757**返回值：** 758 759| 类型 | 说明 | 760| -------- | -------- | 761| number | 关闭设备消息控制通道成功返回0；关闭设备消息控制通道失败返回其他错误码。 | 762 763**示例：** 764 765```ts 766let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 767if (devicesList.length == 0) { 768 console.log(`device list is empty`); 769} 770 771usbManager.requestRight(devicesList[0].name); 772let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 773let ret: number = usbManager.closePipe(devicepipe); 774console.log(`closePipe = ${ret}`); 775``` 776 777## USBEndpoint 778 779通过USB发送和接收数据的端口。通过[USBInterface](#usbinterface)获取。 780 781**系统能力：** SystemCapability.USB.USBManager 782 783| 名称 | 类型 | 必填 |说明 | 784| ------------- | ------------------------------------------- | ------------- |------------- | 785| address | number | 是 |端点地址。 | 786| attributes | number | 是 |端点属性。 | 787| interval | number | 是 |端点间隔。 | 788| maxPacketSize | number | 是 |端点最大数据包大小。 | 789| direction | [USBRequestDirection](#usbrequestdirection) | 是 |端点的方向。 | 790| number | number | 是 |端点号。 | 791| type | number | 是 |端点类型。 | 792| interfaceId | number | 是 |端点所属的接口的唯一标识。 | 793 794## USBInterface 795 796一个[USBConfiguration](#usbconfiguration)中可以含有多个USBInterface，每个USBInterface提供一个功能。 797 798**系统能力：** SystemCapability.USB.USBManager 799 800| 名称 | 类型 | 必填 |说明 | 801| ---------------- | ---------------------------------------- | ------------- |--------------------- | 802| id | number | 是 |接口的唯一标识。 | 803| protocol | number | 是 |接口的协议。 | 804| clazz | number | 是 |设备类型。 | 805| subClass | number | 是 |设备子类。 | 806| alternateSetting | number | 是 |在同一个接口中的多个描述符中进行切换设置。 | 807| name | string | 是 |接口名称。 | 808| endpoints | Array<[USBEndpoint](#usbendpoint)> | 是 |当前接口所包含的端点。 | 809 810## USBConfiguration 811 812USB配置，一个[USBDevice](#usbdevice)中可以含有多个配置。 813 814**系统能力：** SystemCapability.USB.USBManager 815 816| 名称 | 类型 | 必填 |说明 | 817| -------------- | ------------------------------------------------ | --------------- |--------------- | 818| id | number | 是 |配置的唯一标识。 | 819| attributes | number | 是 |配置的属性。 | 820| maxPower | number | 是 |最大功耗，以毫安为单位。 | 821| name | string | 是 |配置的名称，可以为空。 | 822| isRemoteWakeup | boolean | 是 |检查当前配置是否支持远程唤醒。 | 823| isSelfPowered | boolean | 是 | 检查当前配置是否支持独立电源。 | 824| interfaces | Array <[USBInterface](#usbinterface)> | 是 |配置支持的接口属性。 | 825 826## USBDevice 827 828USB设备信息。 829 830**系统能力：** SystemCapability.USB.USBManager 831 832| 名称 | 类型 | 必填 |说明 | 833| ---------------- | ------------------------------------ | ---------- |---------- | 834| busNum | number | 是 |总线地址。 | 835| devAddress | number | 是 |设备地址。 | 836| serial | string | 是 |序列号。 | 837| name | string | 是 |设备名字。 | 838| manufacturerName | string | 是 | 产商信息。 | 839| productName | string | 是 |产品信息。 | 840| version | string | 是 |版本。 | 841| vendorId | number | 是 |厂商ID。 | 842| productId | number | 是 |产品ID。 | 843| clazz | number | 是 |设备类。 | 844| subClass | number | 是 |设备子类。 | 845| protocol | number | 是 |设备协议码。 | 846| configs | Array<[USBConfiguration](#usbconfiguration)> | 是 |设备配置描述符信息。 | 847 848## USBDevicePipe 849 850USB设备消息传输通道，用于确定设备。 851 852**系统能力：** SystemCapability.USB.USBManager 853 854| 名称 | 类型 | 必填 |说明 | 855| ---------- | ------ | ----- |----- | 856| busNum | number |是 | 总线地址。 | 857| devAddress | number |是 | 设备地址。 | 858 859## USBControlParams 860 861控制传输参数。 862 863**系统能力：** SystemCapability.USB.USBManager 864 865| 名称 | 类型 | 必填 |说明 | 866| ------- | ----------------------------------------------- | ---------------- |---------------- | 867| request | number | 是 |请求类型。 | 868| target | [USBRequestTargetType](#usbrequesttargettype) | 是 |请求目标类型。 | 869| reqType | [USBControlRequestType](#usbcontrolrequesttype) | 是 |请求控制类型。 | 870| value | number | 是 |请求参数。 | 871| index | number | 是 |请求参数value对应的索引值。 | 872| data | Uint8Array | 是 |用于写入或读取的缓冲区。 | 873 874## USBDeviceRequestParams<sup>12+</sup> 875 876控制传输参数。 877 878**系统能力：** SystemCapability.USB.USBManager 879 880| 名称 | 类型 | 必填 |说明 | 881| ------- | ----------------------------------------------- | ---------------- |---------------- | 882| bmRequestType | number | 是 |请求控制类型。 | 883| bRequest | number | 是 |请求类型。 | 884| wValue | number | 是 |请求参数。 | 885| wIndex | number | 是 |请求参数value对应的索引值。 | 886| wLength | number | 是 |请求数据的长度 | 887| data | Uint8Array | 是 |用于写入或读取的缓冲区。 | 888 889## USBRequestTargetType 890 891请求目标类型。 892 893**系统能力：** SystemCapability.USB.USBManager 894 895| 名称 | 值 | 说明 | 896| ---------------------------- | ---- | ------ | 897| USB_REQUEST_TARGET_DEVICE | 0 | 设备。 | 898| USB_REQUEST_TARGET_INTERFACE | 1 | 接口。 | 899| USB_REQUEST_TARGET_ENDPOINT | 2 | 端点。 | 900| USB_REQUEST_TARGET_OTHER | 3 | 其他。 | 901 902## USBControlRequestType 903 904控制请求类型。 905 906**系统能力：** SystemCapability.USB.USBManager 907 908| 名称 | 值 | 说明 | 909| ------------------------- | ---- | ------ | 910| USB_REQUEST_TYPE_STANDARD | 0 | 标准。 | 911| USB_REQUEST_TYPE_CLASS | 1 | 类。 | 912| USB_REQUEST_TYPE_VENDOR | 2 | 厂商。 | 913 914## USBRequestDirection 915 916请求方向。 917 918**系统能力：** SystemCapability.USB.USBManager 919 920| 名称 | 值 | 说明 | 921| --------------------------- | ---- | ------------------------ | 922| USB_REQUEST_DIR_TO_DEVICE | 0 | 写数据，主设备往从设备。 | 923| USB_REQUEST_DIR_FROM_DEVICE | 0x80 | 读数据，从设备往主设备。 | 924 925