1# @ohos.usbManager (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 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15 16## 导入模块 17 18```ts 19import { usbManager } from '@kit.BasicServicesKit'; 20``` 21 22## 使用说明 23 24凡是参数类型为[USBDevicePipe](#usbdevicepipe)的接口,都需要执行如下操作： 25 26**在使用接口前：** 27 281. 调用[usbManager.getDevices](#usbmanagergetdevices)获取设备列表。 29 302. 调用[usbManager.requestRight](#usbmanagerrequestright)获取请求权限。 31 323. 调用[usbManager.connectDevice](#usbmanagerconnectdevice)得到USBDevicePipe作为参数。 33 34**在使用接口后：** 35 36调用[usbManager.closePipe](#usbmanagerclosepipe)关闭设备消息控制通道。 37 38## usbManager.getDevices 39 40getDevices(): Array<Readonly<USBDevice>> 41 42获取接入主设备的USB设备列表。 43 44> **说明：** 45> 46> 当USB服务正常运行但无设备接入时，那么将会返回一个空的列表，这是正常情况，表示调用成功但当前没有连接的USB设备。 47> 48> 在USB主机模式未开启、USB服务未正确初始化、USB服务连接失败（如开发者模式关闭）、权限不足或其他系统错误时，接口会返回`undefined`，注意需要对接口返回值做判空处理。 49 50**系统能力：** SystemCapability.USB.USBManager 51 52**返回值：** 53 54| 类型 | 说明 | 55| ---------------------------------------------------- | ------- | 56| Array<Readonly<[USBDevice](#usbdevice)>> | 设备信息列表。 | 57 58**错误码：** 59 60以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 61 62| 错误码ID | 错误信息 | 63| -------- | ------------------------- | 64| 801 | Capability not supported. | 65 66**示例：** 67 68```ts 69let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 70console.log(`devicesList = ${devicesList}`); 71/* 72devicesList 返回的数据结构,此处提供一个简单的示例，如下 73[ 74 { 75 name: "1-1", 76 serial: "", 77 manufacturerName: "", 78 productName: "", 79 version: "", 80 vendorId: 7531, 81 productId: 2, 82 clazz: 9, 83 subClass: 0, 84 protocol: 1, 85 devAddress: 1, 86 busNum: 1, 87 configs: [ 88 { 89 id: 1, 90 attributes: 224, 91 isRemoteWakeup: true, 92 isSelfPowered: true, 93 maxPower: 0, 94 name: "1-1", 95 interfaces: [ 96 { 97 id: 0, 98 protocol: 0, 99 clazz: 9, 100 subClass: 0, 101 alternateSetting: 0, 102 name: "1-1", 103 endpoints: [ 104 { 105 address: 129, 106 attributes: 3, 107 interval: 12, 108 maxPacketSize: 4, 109 direction: 128, 110 number: 1, 111 type: 3, 112 interfaceId: 0, 113 }, 114 ], 115 }, 116 ], 117 }, 118 ], 119 }, 120] 121*/ 122``` 123 124## usbManager.connectDevice 125 126connectDevice(device: USBDevice): Readonly<USBDevicePipe> 127 128根据getDevices()返回的设备信息打开USB设备。如果USB服务异常，可能返回`undefined`，注意需要对接口返回值做判空处理。 129 1301. 需要调用[usbManager.getDevices](#usbmanagergetdevices)获取设备信息以及device; 1312. 调用[usbManager.requestRight](#usbmanagerrequestright)请求使用该设备的权限。 132 133**系统能力：** SystemCapability.USB.USBManager 134 135**参数：** 136 137| 参数名 | 类型 | 必填 | 说明 | 138| -------- | -------- | -------- | ---------------- | 139| device | [USBDevice](#usbdevice) | 是 | USB设备信息，用getDevices获取的busNum和devAddress确定设备，当前其他属性不做处理。 | 140 141**返回值：** 142 143| 类型 | 说明 | 144| -------- | -------- | 145| Readonly<[USBDevicePipe](#usbdevicepipe)> | 指定的传输通道对象。 | 146 147**错误码：** 148 149以下错误码的详细介绍参见[USB服务错误码](errorcode-usb.md)。 150 151| 错误码ID | 错误信息 | 152| -------- | ------------------------------------------------------------ | 153| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 154| 801 | Capability not supported. | 155| 14400001 | Access right denied. Call requestRight to get the USBDevicePipe access right first.| 156 157**示例：** 158 159```ts 160let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 161if (!devicesList || devicesList.length == 0) { 162 console.log(`device list is empty`); 163 return; 164} 165 166let device: usbManager.USBDevice = devicesList[0]; 167usbManager.requestRight(device.name); 168let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 169console.log(`devicepipe = ${devicepipe}`); 170``` 171 172## usbManager.hasRight 173 174hasRight(deviceName: string): boolean 175 176判断是否有权访问该设备。 177 178如果“使用者”（如各种App或系统）有权访问设备则返回true；无权访问设备则返回false。 179 180**系统能力：** SystemCapability.USB.USBManager 181 182**参数：** 183 184| 参数名 | 类型 | 必填 | 说明 | 185| -------- | -------- | -------- | -------- | 186| deviceName | string | 是 | 设备名称，来自getDevices获取的设备列表。 | 187 188**返回值：** 189 190| 类型 | 说明 | 191| -------- | -------- | 192| boolean | true表示有访问设备的权限，false表示没有访问设备的权限。调用失败返回其他错误码如下：<br>- 88080385：接口未初始化。<br>- 88080492：写入服务数据包过程发生错误。<br>- 88080493：读取服务数据包过程发送错误。| 193 194**错误码：** 195 196以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 197 198| 错误码ID | 错误信息 | 199| -------- | ------------------------------------------------------------ | 200| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 201| 801 | Capability not supported. | 202 203**示例：** 204 205```ts 206let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 207if (!devicesList || devicesList.length == 0) { 208 console.log(`device list is empty`); 209 return; 210} 211 212let device: usbManager.USBDevice = devicesList[0]; 213usbManager.requestRight(device.name); 214let right: boolean = usbManager.hasRight(device.name); 215console.log(`${right}`); 216``` 217 218## usbManager.requestRight 219 220requestRight(deviceName: string): Promise<boolean> 221 222请求软件包的临时权限以访问设备。使用Promise异步回调。系统应用默认拥有访问设备权限，无需调用此接口申请。 223 224**系统能力：** SystemCapability.USB.USBManager 225 226**参数：** 227 228| 参数名 | 类型 | 必填 | 说明 | 229| -------- | -------- | -------- | -------- | 230| deviceName | string | 是 | 设备名称，来自getDevices获取的设备列表。| 231 232**返回值：** 233 234| 类型 | 说明 | 235| -------- | -------- | 236| Promise<boolean> | Promise对象，返回临时权限的申请结果。返回true表示临时权限申请成功；返回false则表示临时权限申请失败。| 237 238**错误码：** 239 240以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 241 242| 错误码ID | 错误信息 | 243| -------- | ------------------------------------------------------------ | 244| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 245| 801 | Capability not supported. | 246 247**示例：** 248 249```ts 250let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 251if (!devicesList || devicesList.length == 0) { 252 console.log(`device list is empty`); 253 return; 254} 255 256let device: usbManager.USBDevice = devicesList[0]; 257usbManager.requestRight(device.name).then(ret => { 258 console.log(`requestRight = ${ret}`); 259}); 260``` 261 262## usbManager.removeRight 263 264removeRight(deviceName: string): boolean 265 266移除软件包访问设备的权限。系统应用默认拥有访问设备权限，调用此接口不会产生影响。 267 268**系统能力：** SystemCapability.USB.USBManager 269 270**参数：** 271 272| 参数名 | 类型 | 必填 | 说明 | 273| -------- | -------- | -------- | -------- | 274| deviceName | string | 是 | 设备名称，来自getDevices获取的设备列表。| 275 276**返回值：** 277 278| 类型 | 说明 | 279| -------- | -------- | 280| boolean | 返回权限移除结果。返回true表示权限移除成功；返回false则表示权限移除失败。调用失败返回其他错误码如下：<br>- 88080382：接口操作过程中遇到无效值或参数。<br>- 88080385：接口未初始化。<br>- 88080392：写入接口数据包过程发生错误。<br>- 88080393：读取接口数据包过程发送错误。<br>- 88080492：写入服务数据包过程发生错误。<br>- 88080493：读取服务数据包过程发生错误。<br>- 88080497：服务内部逻辑执行发生错误。| 281 282**错误码：** 283 284以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 285 286| 错误码ID | 错误信息 | 287| -------- | ------------------------------------------------------------ | 288| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 289| 801 | Capability not supported. | 290 291**示例：** 292 293```ts 294let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 295if (!devicesList || devicesList.length == 0) { 296 console.log(`device list is empty`); 297 return; 298} 299 300let device: usbManager.USBDevice = devicesList[0]; 301if (usbManager.removeRight(device.name)) { 302 console.log(`Succeed in removing right`); 303} 304``` 305 306## usbManager.claimInterface 307 308claimInterface(pipe: USBDevicePipe, iface: USBInterface, force ?: boolean): number 309 310声明对USB设备某个接口的控制权。 311 312> **说明：** 313> 314> 在USB编程中，claim interface是一个常见操作，指的是应用程序请求操作系统将某个USB接口从内核驱动中释放并交由用户空间程序控制。<br> 315> 下面用到的claim通信接口都表示claim interface操作。 316 317**系统能力：** SystemCapability.USB.USBManager 318 319**参数：** 320 321| 参数名 | 类型 | 必填 | 说明 | 322| -------- | -------- | -------- | -------- | 323| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址，需要调用connectDevice获取。| 324| iface | [USBInterface](#usbinterface) | 是 | 用于确定需要获取接口的索引，需要调用getDevices获取设备信息并通过id确定唯一接口。| 325| force | boolean | 否 | 可选参数，是否强制获取。默认值为false ，表示不强制获取，用户按需选择。| 326 327**返回值：** 328 329| 类型 | 说明 | 330| -------- | -------- | 331| number | claim通信接口成功返回0；claim通信接口失败返回其他错误码如下：<br>- 63：数据量超过预期的最大值。<br>- 88080385：接口未初始化。<br>- 88080482：服务过程中遇到无效值或参数。<br>- 88080484：没有权限。<br>- 88080492：写入服务数据包过程发生错误。<br>- 88080493：读取服务数据包过程发生错误。<br>- 88080497：服务内部逻辑执行发生错误。<br>- -1：调用底层接口失败。| 332 333**错误码：** 334 335以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 336 337| 错误码ID | 错误信息 | 338| -------- | ------------------------------------------------------------ | 339| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 340| 801 | Capability not supported. | 341 342**示例：** 343 344```ts 345let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 346if (!devicesList || devicesList.length == 0) { 347 console.log(`device list is empty`); 348 return; 349} 350 351let device: usbManager.USBDevice = devicesList[0]; 352usbManager.requestRight(device.name); 353let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 354let interfaces: usbManager.USBInterface = device.configs[0].interfaces[0]; 355let ret: number= usbManager.claimInterface(devicepipe, interfaces); 356console.log(`claimInterface = ${ret}`); 357``` 358 359## usbManager.releaseInterface 360 361releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number 362 363释放claim过的通信接口。 364 365> **说明：** 366> 367> 在调用该接口前需要通过[usbManager.claimInterface](#usbmanagerclaiminterface)claim通信接口。 368 369**系统能力：** SystemCapability.USB.USBManager 370 371**参数：** 372 373| 参数名 | 类型 | 必填 | 说明 | 374| -------- | -------- | -------- | -------- | 375| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址，需要调用connectDevice获取。| 376| iface | [USBInterface](#usbinterface) | 是 | 用于确定需要释放接口的索引，需要调用getDevices获取设备信息并通过id确定唯一接口。| 377 378**返回值：** 379 380| 类型 | 说明 | 381| -------- | -------- | 382| number | 释放接口成功返回0；释放接口失败返回其他错误码如下：<br>- 63：数据量超过预期的最大值。<br>- 88080381：无效的接口操作。<br>- 88080385：接口未初始化。<br>- 88080482：服务过程中遇到无效值或参数。<br>- 88080484：没有权限。<br>- 88080492：写入服务数据包过程发生错误。<br>- 88080493：读取服务数据包过程发生错误。<br>- 88080497：服务内部逻辑执行发生错误。<br>- -1：调用底层接口失败。| 383 384**错误码：** 385 386以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 387 388| 错误码ID | 错误信息 | 389| -------- | ------------------------------------------------------------ | 390| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified.2.Incorrect parameter types. | 391| 801 | Capability not supported. | 392 393**示例：** 394 395```ts 396let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 397if (!devicesList || devicesList.length == 0) { 398 console.log(`device list is empty`); 399 return; 400} 401 402let device: usbManager.USBDevice = devicesList[0]; 403usbManager.requestRight(device.name); 404let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 405let interfaces: usbManager.USBInterface = device.configs[0].interfaces[0]; 406let ret: number = usbManager.claimInterface(devicepipe, interfaces); 407ret = usbManager.releaseInterface(devicepipe, interfaces); 408console.log(`releaseInterface = ${ret}`); 409``` 410 411## usbManager.setConfiguration 412 413setConfiguration(pipe: USBDevicePipe, config: USBConfiguration): number 414 415设置设备配置。 416 417**系统能力：** SystemCapability.USB.USBManager 418 419**参数：** 420 421| 参数名 | 类型 | 必填 | 说明 | 422| -------- | -------- | -------- | -------- | 423| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址，需要调用connectDevice获取。| 424| config | [USBConfiguration](#usbconfiguration) | 是 | 用于确定需要设置的配置，需要调用getDevices获取设备信息并通过id用于确定唯一设置。| 425 426**返回值：** 427 428| 类型 | 说明 | 429| -------- | -------- | 430| number | 设置设备配置成功返回0；设置设备配置失败返回其他错误码如下：<br>- 63：数据量超过预期的最大值。<br>- 88080385：接口未初始化。<br>- 88080482：服务过程中遇到无效值或参数。<br>- 88080484：没有权限。<br>- 88080492：写入服务数据包过程发生错误。<br>- 88080493：读取服务数据包过程发生错误。<br>- 88080497：服务内部逻辑执行发生错误。<br>- -1：调用底层接口失败。<br>- -17：I/O失败。| 431 432**错误码：** 433 434以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 435 436| 错误码ID | 错误信息 | 437| -------- | ------------------------------------------------------------ | 438| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 439| 801 | Capability not supported. | 440 441**示例：** 442 443```ts 444let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 445if (!devicesList || devicesList.length == 0) { 446 console.log(`device list is empty`); 447 return; 448} 449 450let device: usbManager.USBDevice = devicesList[0]; 451usbManager.requestRight(device.name); 452let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 453let config: usbManager.USBConfiguration = device.configs[0]; 454let ret: number= usbManager.setConfiguration(devicepipe, config); 455console.log(`setConfiguration = ${ret}`); 456``` 457 458## usbManager.setInterface 459 460setInterface(pipe: USBDevicePipe, iface: USBInterface): number 461 462设置设备接口。 463 464> **说明：** 465> 466> 一个USB接口可能存在多重选择模式，支持动态切换。使用的场景：数据传输时，通过该接口可重新设置端点，使端点与传输类型匹配。 467> 468> 在调用该接口前需要通过[usbManager.claimInterface](#usbmanagerclaiminterface)claim通信接口。 469 470**系统能力：** SystemCapability.USB.USBManager 471 472**参数：** 473 474| 参数名 | 类型 | 必填 | 说明 | 475| -------- | -------- | -------- | -------- | 476| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址，需要调用connectDevice获取。| 477| iface | [USBInterface](#usbinterface) | 是 | 用于确定需要设置的接口，需要调用getDevices获取设备信息并通过id和alternateSetting确定唯一接口。| 478 479**返回值：** 480 481| 类型 | 说明 | 482| -------- | -------- | 483| number | 设置设备接口成功返回0；设置设备接口失败返回其他错误码如下：<br>- 63：数据量超过预期的最大值。<br>- 88080385：接口未初始化。<br>- 88080482：服务过程中遇到无效值或参数。<br>- 88080484：没有权限。<br>- 88080492：写入服务数据包过程发生错误。<br>- 88080493：读取服务数据包过程发生错误。<br>- 88080497：服务内部逻辑执行发生错误。<br>- -1：调用底层接口失败。| 484 485**错误码：** 486 487以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 488 489| 错误码ID | 错误信息 | 490| -------- | ------------------------------------------------------------ | 491| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 492| 801 | Capability not supported. | 493 494**示例：** 495 496```ts 497let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 498if (!devicesList || devicesList.length == 0) { 499 console.log(`device list is empty`); 500 return; 501} 502 503let device: usbManager.USBDevice = devicesList[0]; 504usbManager.requestRight(device.name); 505let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 506let interfaces: usbManager.USBInterface = device.configs[0].interfaces[0]; 507let ret: number = usbManager.claimInterface(devicepipe, interfaces); 508ret = usbManager.setInterface(devicepipe, interfaces); 509console.log(`setInterface = ${ret}`); 510``` 511 512## usbManager.getRawDescriptor 513 514getRawDescriptor(pipe: USBDevicePipe): Uint8Array 515 516获取原始的USB描述符。如果USB服务异常，可能返回`undefined`，注意需要对接口返回值做判空处理。 517 518**系统能力：** SystemCapability.USB.USBManager 519 520**参数：** 521 522| 参数名 | 类型 | 必填 | 说明 | 523| -------- | -------- | -------- | -------- | 524| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址，需要调用connectDevice获取。| 525 526**返回值：** 527 528| 类型 | 说明 | 529| -------- | -------- | 530| Uint8Array | 返回获取的原始数据；失败返回undefined。 | 531 532**错误码：** 533 534以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 535 536| 错误码ID | 错误信息 | 537| -------- | ------------------------------------------------------------ | 538| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 539| 801 | Capability not supported. | 540 541**示例：** 542 543```ts 544let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 545if (!devicesList || devicesList.length == 0) { 546 console.log(`device list is empty`); 547 return; 548} 549 550usbManager.requestRight(devicesList[0].name); 551let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 552let ret: Uint8Array = usbManager.getRawDescriptor(devicepipe); 553``` 554 555## usbManager.getFileDescriptor 556 557getFileDescriptor(pipe: USBDevicePipe): number 558 559获取文件描述符。 560 561**系统能力：** SystemCapability.USB.USBManager 562 563**参数：** 564 565| 参数名 | 类型 | 必填 | 说明 | 566| -------- | -------- | -------- | -------- | 567| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址，需要调用connectDevice获取。| 568 569**返回值：** 570 571| 类型 | 说明 | 572| ------ | -------------------- | 573| number | 返回设备对应的文件描述符；失败返回其他错误码如下：<br>- 63：数据量超过预期的最大值。<br>- 88080385：接口未初始化。<br>- 88080482：服务过程中遇到无效值或参数。<br>- 88080484：没有权限。<br>- 88080492：写入服务数据包过程发生错误。<br>- 88080493：读取服务数据包过程发生错误。<br>- 88080497：服务内部逻辑执行发生错误。<br>- -1：调用底层接口失败。| 574 575**错误码：** 576 577以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 578 579| 错误码ID | 错误信息 | 580| -------- | ------------------------------------------------------------ | 581| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 582| 801 | Capability not supported. | 583 584**示例：** 585 586```ts 587let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 588if (!devicesList || devicesList.length == 0) { 589 console.log(`device list is empty`); 590 return; 591} 592 593usbManager.requestRight(devicesList[0].name); 594let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 595let ret: number = usbManager.getFileDescriptor(devicepipe); 596console.log(`getFileDescriptor = ${ret}`); 597let closeRet: number = usbManager.closePipe(devicepipe); 598console.log(`closePipe = ${closeRet}`); 599``` 600 601## usbManager.controlTransfer<sup>(deprecated)</sup> 602 603controlTransfer(pipe: USBDevicePipe, controlparam: USBControlParams, timeout ?: number): Promise<number> 604 605控制传输。 606 607> **说明：** 608> 609> 从 API version 9开始支持，从API version 12开始废弃。建议使用 [usbControlTransfer](#usbmanagerusbcontroltransfer12) 替代。 610 611**系统能力：** SystemCapability.USB.USBManager 612 613**参数：** 614 615| 参数名 | 类型 | 必填 | 说明 | 616| -------- | -------- | -------- | -------- | 617| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定设备，需要调用connectDevice获取。| 618| controlparam | [USBControlParams](#usbcontrolparamsdeprecated) | 是 | 控制传输参数，按需设置参数，参数传参类型请参考USB协议。| 619| timeout | number | 否 | 超时时间（单位：ms），可选参数，默认为0不超时，用户按需选择。 | 620 621**返回值：** 622 623| 类型 | 说明 | 624| -------- | -------- | 625| Promise<number> | Promise对象，获取传输或接收到的数据块大小。失败返回其他错误码如下：<br>- 88080385：接口未初始化。<br>- 88080482：服务过程中遇到无效值或参数。<br>- 88080484：没有权限。<br>- 88080492：写入服务数据包过程发生错误。<br>- 88080493：读取服务数据包过程发生错误。<br>- 88080497：服务内部逻辑执行发生错误。<br>- -1：调用底层接口失败。| 626 627**错误码：** 628 629以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 630 631| 错误码ID | 错误信息 | 632| -------- | ------------------------------------------------------------ | 633| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 634 635**示例：** 636 637```ts 638class PARA { 639 request: number = 0 640 reqType: usbManager.USBControlRequestType = 0 641 target: usbManager.USBRequestTargetType = 0 642 value: number = 0 643 index: number = 0 644 data: Uint8Array = new Uint8Array() 645} 646 647let param: PARA = { 648 request: 0x06, 649 reqType: 0x80, 650 target:0, 651 value: 0x01 << 8 | 0, 652 index: 0, 653 data: new Uint8Array(18) 654}; 655 656let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 657if (!devicesList || devicesList.length == 0) { 658 console.log(`device list is empty`); 659 return; 660} 661 662usbManager.requestRight(devicesList[0].name); 663let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 664usbManager.controlTransfer(devicepipe, param).then((ret: number) => { 665console.log(`controlTransfer = ${ret}`); 666}) 667``` 668 669## usbManager.usbControlTransfer<sup>12+</sup> 670 671usbControlTransfer(pipe: USBDevicePipe, requestparam: USBDeviceRequestParams, timeout ?: number): Promise<number> 672 673控制传输。 674 675**系统能力：** SystemCapability.USB.USBManager 676 677**参数：** 678 679| 参数名 | 类型 | 必填 | 说明 | 680| -------- | -------- | -------- | -------- | 681| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定设备。 | 682| requestparam | [USBDeviceRequestParams](#usbdevicerequestparams12) | 是 | 控制传输参数，按需设置参数，参数传参类型请参考USB协议。 | 683| timeout | number | 否 | 超时时间（单位：ms），可选参数，默认为0不超时。 | 684 685**返回值：** 686 687| 类型 | 说明 | 688| -------- | -------- | 689| Promise<number> | Promise对象，获取传输或接收到的数据块大小。失败返回其他错误码如下：<br>- 88080385：接口未初始化。<br>- 88080482：服务过程中遇到无效值或参数。<br>- 88080484：没有权限。<br>- 88080492：写入服务数据包过程发生错误。<br>- 88080493：读取服务数据包过程发生错误。<br>- 88080497：服务内部逻辑执行发生错误。<br>- -1：调用底层接口失败。| 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| 801 | Capability not supported. | 699 700**示例：** 701 702```ts 703class PARA { 704 bmRequestType: number = 0 705 bRequest: number = 0 706 wValue: number = 0 707 wIndex: number = 0 708 wLength: number = 0 709 data: Uint8Array = new Uint8Array() 710} 711 712let param: PARA = { 713 bmRequestType: 0x80, 714 bRequest: 0x06, 715 716 wValue:0x01 << 8 | 0, 717 wIndex: 0, 718 wLength: 18, 719 data: new Uint8Array(18) 720}; 721 722let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 723if (!devicesList || devicesList.length == 0) { 724 console.log(`device list is empty`); 725 return; 726} 727 728usbManager.requestRight(devicesList[0].name); 729let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 730usbManager.usbControlTransfer(devicepipe, param).then((ret: number) => { 731console.log(`usbControlTransfer = ${ret}`); 732}) 733``` 734 735## usbManager.bulkTransfer 736 737bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, timeout ?: number): Promise<number> 738 739批量传输。 740 741> **说明：** 742> 743> 单次批量传输的传输数据总量（包括pipe、endpoint、buffer、timeout）请控制在200KB以下。 744> 745> 在调用接口前需要通过[usbManager.claimInterface](#usbmanagerclaiminterface)claim通信接口。 746 747**系统能力：** SystemCapability.USB.USBManager 748 749**参数：** 750 751| 参数名 | 类型 | 必填 | 说明 | 752| -------- | -------- | -------- | -------- | 753| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定设备，需要调用connectDevice获取。| 754| endpoint | [USBEndpoint](#usbendpoint) | 是 | 用于确定传输的端口，需要调用getDevices获取设备信息列表以及endpoint，address用于确定端点地址，direction用于确定端点的方向，interfaceId用于确定所属接口，当前其他属性不做处理。| 755| buffer | Uint8Array | 是 | 用于写入或读取数据的缓冲区。 | 756| timeout | number | 否 | 超时时间（单位：ms），可选参数，默认为0不超时，用户按需选择。 | 757 758**返回值：** 759 760| 类型 | 说明 | 761| -------- | -------- | 762| Promise<number> | Promise对象，获取传输或接收到的数据块大小。失败返回其他错误码如下：<br>- 63：数据量超过预期的最大值。<br>- 88080385：接口未初始化。<br>- 88080482：服务过程中遇到无效值或参数。<br>- 88080484：没有权限。<br>- 88080492：写入服务数据包过程发生错误。<br>- 88080493：读取服务数据包过程发生错误。<br>- 88080497：服务内部逻辑执行发生错误。<br>- -1：调用底层接口失败。<br>- -3：参数无效。<br>- -202：设备未找到。| 763 764**错误码：** 765 766以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 767 768| 错误码ID | 错误信息 | 769| -------- | ------------------------------------------------------------ | 770| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 771| 801 | Capability not supported. | 772 773**示例：** 774 775> **说明：** 776> 777> 以下示例代码只是调用bulkTransfer接口的必要流程，实际调用时，设备开发者需要遵循设备相关协议进行调用，确保数据的正确传输和设备的兼容性。 778 779```ts 780//usbManager.getDevices 接口返回数据集合，取其中一个设备对象，并获取权限。 781//把获取到的设备对象作为参数传入usbManager.connectDevice;当usbManager.connectDevice接口成功返回之后； 782//才可以调用第三个接口usbManager.claimInterface.当usbManager.claimInterface 调用成功以后,再调用该接口。 783let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 784if (!devicesList || devicesList.length == 0) { 785 console.log(`device list is empty`); 786 return; 787} 788 789let device: usbManager.USBDevice = devicesList[0]; 790usbManager.requestRight(device.name); 791 792let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 793for (let i = 0; i < device.configs[0].interfaces.length; i++) { 794 if (device.configs[0].interfaces[i].endpoints[0].attributes == 2) { 795 let endpoint: usbManager.USBEndpoint = device.configs[0].interfaces[i].endpoints[0]; 796 let interfaces: usbManager.USBInterface = device.configs[0].interfaces[i]; 797 let ret: number = usbManager.claimInterface(devicepipe, interfaces); 798 let buffer = new Uint8Array(128); 799 usbManager.bulkTransfer(devicepipe, endpoint, buffer).then((ret: number) => { 800 console.log(`bulkTransfer = ${ret}`); 801 }); 802 } 803} 804``` 805 806## usbManager.usbSubmitTransfer<sup>18+</sup> 807 808usbSubmitTransfer(transfer: UsbDataTransferParams): void 809 810提交异步传输请求。 811 812> **说明：** 813> 814> 本接口为异步接口，调用后立刻返回，实际读写操作的结果以回调的方式返回。 815> 816> 在调用该接口前需要通过[usbManager.claimInterface](#usbmanagerclaiminterface)claim通信接口。 817 818**系统能力：** SystemCapability.USB.USBManager 819 820**参数：** 821 822| 参数名 | 类型 | 必填 | 说明 | 823| -------- | -------- | -------- | -------- | 824| transfer | [UsbDataTransferParams](#usbdatatransferparams18) | 是 | 作为通用USB数据传输接口，客户端需要填充这个对象中的参数，用以发起传输请求。| 825 826**错误码：** 827 828以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 829 830| 错误码ID | 错误信息 | 831| -------- | ------------------------------------------------------------ | 832| 801 | Capability not supported. | 833| 14400001 | Access right denied. Call requestRight to get the USBDevicePipe access right first. | 834| 14400007 | Resource busy. Possible causes: 1. The transfer has already been submitted. 2. The interface is claimed by another program or driver.| 835| 14400008 | No such device (it may have been disconnected). | 836| 14400009 | Insufficient memory. Possible causes: 1. Memory allocation failed. | 837| 14400012 | Transmission I/O error. | 838 839**示例：** 840 841> **说明：** 842> 843> 以下示例代码需要放入具体的方法中执行，只是调用usbSubmitTransfer接口的必要流程，实际调用时，设备开发者需要遵循设备相关协议进行调用，确保数据的正确传输和设备的兼容性。 844 845<!--code_no_check--> 846```ts 847//usbManager.getDevices 接口返回数据集合，取其中一个设备对象，并获取权限。 848//把获取到的设备对象作为参数传入usbManager.connectDevice;当usbManager.connectDevice接口成功返回之后； 849//才可以调用第三个接口usbManager.claimInterface.当usbManager.claimInterface 调用成功以后,再调用该接口。 850let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 851if (!devicesList || devicesList.length == 0) { 852 console.log(`device list is empty`); 853 return; 854} 855let device: usbManager.USBDevice = devicesList[0]; 856usbManager.requestRight(device.name); 857let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 858//获取endpoint端点地址。 859let endpoint = device.configs[0].interfaces[0]?.endpoints.find((value) => { 860 return value.direction === 0 && value.type === 2 861}) 862//获取设备的第一个id。 863let ret: number = usbManager.claimInterface(devicepipe, device.configs[0].interfaces[0], true); 864 865let transferParams: usbManager.UsbDataTransferParams = { 866 devPipe: devicepipe, 867 flags: usbManager.UsbTransferFlags.USB_TRANSFER_SHORT_NOT_OK, 868 endpoint: 1, 869 type: usbManager.UsbEndpointTransferType.TRANSFER_TYPE_BULK, 870 timeout: 2000, 871 length: 10, 872 callback: () => {}, 873 userData: new Uint8Array(10), 874 buffer: new Uint8Array(10), 875 isoPacketCount: 0, 876}; 877try { 878 transferParams.endpoint=endpoint?.address as number; 879 transferParams.callback=(err, callBackData: usbManager.SubmitTransferCallback)=>{ 880 console.info('callBackData =' +JSON.stringify(callBackData)); 881 } 882 usbManager.usbSubmitTransfer(transferParams); 883 console.info('USB transfer request submitted.'); 884} catch (error) { 885 console.error('USB transfer failed:', error); 886} 887``` 888 889## usbManager.usbCancelTransfer<sup>18+</sup> 890 891usbCancelTransfer(transfer: UsbDataTransferParams): void 892 893取消异步传输请求。 894 895> **说明：** 896> 897> 该接口的主要作用是主动取消尚未完成的USB数据传输请求（如usbSubmitTransfer提交的传输）。<br> 898> 在调用该接口前需要通过[usbManager.claimInterface](#usbmanagerclaiminterface)claim通信接口。 899 900**系统能力：** SystemCapability.USB.USBManager 901 902**参数：** 903 904| 参数名 | 类型 | 必填 | 说明 | 905| -------- | -------- | -------- | -------- | 906| transfer | [UsbDataTransferParams](#usbdatatransferparams18) | 是 | 在取消传输的接口中，只需要填充USBDevicePipe和endpoint即可。| 907 908**错误码：** 909 910以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 911 912| 错误码ID | 错误信息 | 913| -------- | ------------------------------------------------------------ | 914| 801 | Capability not supported. | 915| 14400001 | Access right denied. Call requestRight to get the USBDevicePipe access right first. | 916| 14400008 | No such device (it may have been disconnected). | 917| 14400010 | Other USB error. Possible causes:<br>1.Unrecognized discard error code. | 918| 14400011 | The transfer is not in progress, or is already complete or cancelled.| 919 920**示例：** 921 922> **说明：** 923> 924> 以下示例代码需要放入具体的方法中执行，只是调用usbCancelTransfer接口的必要流程，实际调用时，设备开发者需要遵循设备相关协议进行调用，确保数据的正确传输和设备的兼容性。 925 926<!--code_no_check--> 927```ts 928//usbManager.getDevices 接口返回数据集合，取其中一个设备对象，并获取权限。 929//把获取到的设备对象作为参数传入usbManager.connectDevice;当usbManager.connectDevice接口成功返回之后； 930//才可以调用第三个接口usbManager.claimInterface.当usbManager.claimInterface 调用成功以后,再调用该接口。 931let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 932if (!devicesList || devicesList.length == 0) { 933 console.log(`device list is empty`); 934 return; 935} 936let device: usbManager.USBDevice = devicesList[0]; 937usbManager.requestRight(device.name); 938let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 939//获取endpoint端点地址。 940let endpoint = device.configs[0].interfaces[0]?.endpoints.find((value) => { 941 return value.direction === 0 && value.type === 2 942}) 943//获取设备的第一个id。 944let ret: number = usbManager.claimInterface(devicepipe, device.configs[0].interfaces[0], true); 945let transferParams: usbManager.UsbDataTransferParams = { 946 devPipe: devicepipe, 947 flags: usbManager.UsbTransferFlags.USB_TRANSFER_SHORT_NOT_OK, 948 endpoint: 1, 949 type: usbManager.UsbEndpointTransferType.TRANSFER_TYPE_BULK, 950 timeout: 2000, 951 length: 10, 952 callback: () => {}, 953 userData: new Uint8Array(10), 954 buffer: new Uint8Array(10), 955 isoPacketCount: 0, 956}; 957try { 958 transferParams.endpoint=endpoint?.address as number; 959 transferParams.callback=(err, callBackData: usbManager.SubmitTransferCallback)=>{ 960 console.info('callBackData =' +JSON.stringify(callBackData)); 961 } 962 usbManager.usbSubmitTransfer(transferParams); 963 usbManager.usbCancelTransfer(transferParams); 964 console.info('USB transfer request submitted.'); 965} catch (error) { 966 console.error('USB transfer failed:', error); 967} 968``` 969 970## usbManager.closePipe 971 972closePipe(pipe: USBDevicePipe): number 973 974关闭设备消息控制通道。 975 9761. 需要调用[usbManager.getDevices](#usbmanagergetdevices)获取设备列表； 9772. 调用[usbManager.requestRight](#usbmanagerrequestright)获取设备请求权限； 9783. 调用[usbManager.connectDevice](#usbmanagerconnectdevice)得到devicepipe作为参数。 979 980**系统能力：** SystemCapability.USB.USBManager 981 982**参数：** 983 984| 参数名 | 类型 | 必填 | 说明 | 985| -------- | -------- | -------- | -------- | 986| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定USB设备消息控制通道，需要调用connectDevice获取。| 987 988**返回值：** 989 990| 类型 | 说明 | 991| -------- | -------- | 992| number | 关闭设备消息控制通道成功返回0；关闭设备消息控制通道失败返回其他错误码如下：<br>- 63：数据量超过预期的最大值。<br>- 88080393：读取接口数据包过程发生错误。<br>- 88080482：服务过程中遇到无效值或参数。<br>- 88080484：没有权限。<br>- 88080493：读取服务数据包过程发生错误。<br>- 88080497：服务内部逻辑执行发生错误。<br>- -1：调用底层接口失败。 | 993 994**错误码：** 995 996以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 997 998| 错误码ID | 错误信息 | 999| -------- | ------------------------------------------------------------ | 1000| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 1001| 801 | Capability not supported. | 1002 1003**示例：** 1004 1005```ts 1006let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 1007if (!devicesList || devicesList.length == 0) { 1008 console.log(`device list is empty`); 1009 return; 1010} 1011 1012usbManager.requestRight(devicesList[0].name); 1013let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 1014let ret: number = usbManager.closePipe(devicepipe); 1015console.log(`closePipe = ${ret}`); 1016``` 1017 1018## usbManager.hasAccessoryRight<sup>14+</sup> 1019 1020hasAccessoryRight(accessory: USBAccessory): boolean 1021 1022检查应用程序是否有权访问USB配件。 1023 1024需要调用[usbManager.getAccessoryList](#usbmanagergetaccessorylist14)获取配件列表，得到[USBAccessory](#usbaccessory14)作为参数。 1025 1026**系统能力：** SystemCapability.USB.USBManager 1027 1028**参数：** 1029 1030| 参数名 | 类型 | 必填 | 说明 | 1031| --------- | ------------ | ---- | ------------------------------------- | 1032| accessory | [USBAccessory](#usbaccessory14) | 是 | USB配件，需要通过[getAccessoryList](#usbmanagergetaccessorylist14)获取。 | 1033 1034**返回值：** 1035 1036| 类型 | 说明 | 1037| ------- | ----------------------------- | 1038| boolean | true表示应用程序有权访问USB配件，false表示应用程序无权访问USB配件。 | 1039 1040**错误码：** 1041 1042以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 1043 1044| 错误码ID | 错误信息 | 1045| -------- | ------------------------------------------------------------ | 1046| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 1047| 801 | Capability not supported. | 1048| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. | 1049| 14400005 | Database operation exception. | 1050| 14401001 | The target USBAccessory not matched. | 1051 1052**示例：** 1053 1054```ts 1055import { hilog } from '@kit.PerformanceAnalysisKit'; 1056try { 1057 let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList() 1058 let flag = usbManager.hasAccessoryRight(accList[0]) 1059 hilog.info(0, 'testTag ui', `hasAccessoryRight success, ret:${flag}`) 1060} catch (error) { 1061 hilog.info(0, 'testTag ui', `hasAccessoryRight error ${error.code}, message is ${error.message}`) 1062} 1063``` 1064 1065## usbManager.requestAccessoryRight<sup>14+</sup> 1066 1067requestAccessoryRight(accessory: USBAccessory): Promise<boolean> 1068 1069为指定应用程序申请访问USB配件的访问权限。 1070 1071需要调用[usbManager.getAccessoryList](#usbmanagergetaccessorylist14)获取配件列表，得到[USBAccessory](#usbaccessory14)作为参数。 1072 1073**系统能力：** SystemCapability.USB.USBManager 1074 1075**参数：** 1076 1077| 参数名 | 类型 | 必填 | 说明 | 1078| --------- | ------------ | ---- | ------------------------------------- | 1079| accessory | [USBAccessory](#usbaccessory14) | 是 | USB配件，需要通过[getAccessoryList](#usbmanagergetaccessorylist14)获取。 | 1080 1081**返回值：** 1082 1083| 类型 | 说明 | 1084| ---------------- | ----------------------------- | 1085| Promise<boolean> | Promise对象，返回应用程序访问配件权限的申请结果。返回true表示权限申请成功；返回false表示权限申请失败。 | 1086 1087**错误码：** 1088 1089以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 1090 1091| 错误码ID | 错误信息 | 1092| -------- | ------------------------------------------------------------ | 1093| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 1094| 801 | Capability not supported. | 1095| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. | 1096| 14400005 | Database operation exception. | 1097| 14401001 | The target USBAccessory not matched. | 1098 1099**示例：** 1100 1101```ts 1102import { hilog } from '@kit.PerformanceAnalysisKit'; 1103try { 1104 let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList() 1105 let flag = usbManager.requestAccessoryRight(accList[0]) 1106 hilog.info(0, 'testTag ui', `requestAccessoryRight success, ret:${flag}`) 1107} catch (error) { 1108 hilog.info(0, 'testTag ui', `requestAccessoryRight error ${error.code}, message is ${error.message}`) 1109} 1110``` 1111 1112## usbManager.cancelAccessoryRight<sup>14+</sup> 1113 1114cancelAccessoryRight(accessory: USBAccessory): void 1115 1116取消当前应用程序访问USB配件的权限。 1117 1118需要调用[usbManager.getAccessoryList](#usbmanagergetaccessorylist14)获取配件列表，得到[USBAccessory](#usbaccessory14)作为参数。 1119 1120**系统能力：** SystemCapability.USB.USBManager 1121 1122**参数：** 1123 1124| 参数名 | 类型 | 必填 | 说明 | 1125| --------- | ------------ | ---- | ------------------------------------- | 1126| accessory | [USBAccessory](#usbaccessory14) | 是 | USB配件，需要通过[getAccessoryList](#usbmanagergetaccessorylist14)获取。 | 1127 1128**错误码：** 1129 1130以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 1131 1132| 错误码ID | 错误信息 | 1133| -------- | ------------------------------------------------------------ | 1134| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 1135| 801 | Capability not supported. | 1136| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. | 1137| 14400005 | Database operation exception. | 1138| 14401001 | The target USBAccessory not matched. | 1139 1140**示例：** 1141 1142```ts 1143import { hilog } from '@kit.PerformanceAnalysisKit'; 1144try { 1145 let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList() 1146 let flag = usbManager.requestAccessoryRight(accList[0]) 1147 usbManager.cancelAccessoryRight(accList[0]) 1148 hilog.info(0, 'testTag ui', `cancelAccessoryRight success`) 1149} catch (error) { 1150 hilog.info(0, 'testTag ui', `cancelAccessoryRight error ${error.code}, message is ${error.message}`) 1151} 1152``` 1153 1154## usbManager.getAccessoryList<sup>14+</sup> 1155 1156getAccessoryList(): Array<Readonly<USBAccessory>> 1157 1158获取当前已接入主机的USB配件列表。 1159 1160**系统能力：** SystemCapability.USB.USBManager 1161 1162**返回值：** 1163 1164| 类型 | 说明 | 1165| ----------------------------- | -------------------------------------------------- | 1166| Array<Readonly<USBAccessory>> | 只读的USB配件列表。当前仅支持列表中包含1个USB配件。 | 1167 1168**错误码：** 1169 1170以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 1171 1172| 错误码ID | 错误信息 | 1173| -------- | ------------------------------------------------------------ | 1174| 801 | Capability not supported. | 1175| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. | 1176 1177**示例：** 1178 1179```ts 1180import { hilog } from '@kit.PerformanceAnalysisKit'; 1181try { 1182 let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList() 1183 hilog.info(0, 'testTag ui', `getAccessoryList success, accList: ${JSON.stringify(accList)}`) 1184} catch (error) { 1185 hilog.info(0, 'testTag ui', `getAccessoryList error ${error.code}, message is ${error.message}`) 1186} 1187``` 1188 1189## usbManager.openAccessory<sup>14+</sup> 1190 1191openAccessory(accessory: USBAccessory): USBAccessoryHandle 1192 1193获取配件句柄并打开配件文件描述符。之后可以通过CoreFileKit提供的read/write接口和配件进行通信。 1194 1195需要调用[usbManager.getAccessoryList](#usbmanagergetaccessorylist14)获取配件列表，得到[USBAccessory](#usbaccessory14)作为参数。 1196 1197**系统能力：** SystemCapability.USB.USBManager 1198 1199**参数：** 1200 1201| 参数名 | 类型 | 必填 | 说明 | 1202| --------- | ------------ | ---- | ------------------------------------- | 1203| accessory | [USBAccessory](#usbaccessory14) | 是 | USB配件，需要通过[getAccessoryList](#usbmanagergetaccessorylist14)获取。 | 1204 1205**返回值：** 1206 1207| 类型 | 说明 | 1208| ------------------ | ----------- | 1209| [USBAccessoryHandle](#usbaccessoryhandle14) | USB配件句柄。 | 1210 1211**错误码：** 1212 1213以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 1214 1215| 错误码ID | 错误信息 | 1216| -------- | ------------------------------------------------------------ | 1217| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 1218| 801 | Capability not supported. | 1219| 14400001 | Access right denied. Call requestRight to get the USBDevicePipe access right first. | 1220| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. | 1221| 14401001 | The target USBAccessory not matched. | 1222| 14401002 | Failed to open the native accessory node. | 1223| 14401003 | Cannot reopen the accessory. | 1224 1225**示例：** 1226 1227```ts 1228import { hilog } from '@kit.PerformanceAnalysisKit'; 1229import { fileIo as fs } from '@kit.CoreFileKit'; 1230try { 1231 let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList() 1232 let flag = usbManager.requestAccessoryRight(accList[0]) 1233 let handle = usbManager.openAccessory(accList[0]) 1234 hilog.info(0, 'testTag ui', `openAccessory success`) 1235 let arrayBuffer = new ArrayBuffer(4096); 1236 let readLength = fs.readSync(handle.accessoryFd, arrayBuffer, {offset: 0, length: 4096}); 1237 hilog.info(0, 'testTag ui', 'readSync ret: ' + readLength.toString(10)); 1238} catch (error) { 1239 hilog.info(0, 'testTag ui', `openAccessory error ${error.code}, message is ${error.message}`) 1240} 1241``` 1242 1243## usbManager.closeAccessory<sup>14+</sup> 1244 1245closeAccessory(accessoryHandle: USBAccessoryHandle): void 1246 1247关闭配件文件描述符。 1248 1249需要调用[usbManager.openAccessory](#usbmanageropenaccessory14)获取配件列表，得到[USBAccessoryHandle](#usbaccessoryhandle14)作为参数。 1250 1251**系统能力：** SystemCapability.USB.USBManager 1252 1253**参数：** 1254 1255| 参数名 | 类型 | 必填 | 说明 | 1256| --------------- | ------------------ | ---- | -------------------------------------- | 1257| accessoryHandle | [USBAccessoryHandle](#usbaccessoryhandle14) | 是 | USB配件句柄。需要通过[openAccessory](#usbmanageropenaccessory14)获取。 | 1258 1259**错误码：** 1260 1261以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 1262 1263| 错误码ID | 错误信息 | 1264| -------- | ------------------------------------------------------------ | 1265| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 1266| 801 | Capability not supported. | 1267| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. | 1268 1269**示例：** 1270 1271```ts 1272import { hilog } from '@kit.PerformanceAnalysisKit'; 1273try { 1274 let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList() 1275 let flag = usbManager.requestAccessoryRight(accList[0]) 1276 let handle = usbManager.openAccessory(accList[0]) 1277 usbManager.closeAccessory(handle) 1278 hilog.info(0, 'testTag ui', `closeAccessory success`) 1279} catch (error) { 1280 hilog.info(0, 'testTag ui', `closeAccessory error ${error.code}, message is ${error.message}`) 1281} 1282``` 1283 1284## usbManager.resetUsbDevice<sup>20+</sup> 1285 1286resetUsbDevice(pipe: USBDevicePipe): boolean 1287 1288重置USB外设。 1289 1290> **说明：** 1291> 1292> 本接口调用后会重置此前设置的配置和替换接口，请在调用之前确认相关业务已结束。 1293 1294**系统能力：** SystemCapability.USB.USBManager 1295 1296**参数：** 1297 1298| 参数名 | 类型 | 必填 | 说明 | 1299| -------- | -------- | -------- | -------- | 1300| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址，需要调用connectDevice获取。| 1301 1302**返回值：** 1303 1304| 类型 | 说明 | 1305| -------- | -------- | 1306| boolean | true表示重置设备成功，false表示重置设备失败。 | 1307 1308**错误码：** 1309 1310以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 1311 1312| 错误码ID | 错误信息 | 1313| -------- | ------------------------------------------------------------ | 1314| 801 | Capability not supported. | 1315| 14400001 | Access right denied. Call requestRight to get the USBDevicePipe access right first.| 1316| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. | 1317| 14400008 | No such device (it may have been disconnected). | 1318| 14400010 | Other USB error. Possible causes:<br>1.Unrecognized discard error code. | 1319| 14400013 | The USBDevicePipe validity check failed. Possible causes:<br>1. The input parameters fail the validation check.<br>2. The call chain used to obtain the input parameters is not reasonable. | 1320 1321**示例：** 1322 1323```ts 1324let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 1325if (!devicesList || devicesList.length == 0) { 1326 console.error(`device list is empty`); 1327 return; 1328} 1329 1330usbManager.requestRight(devicesList[0].name); 1331let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 1332try { 1333 let ret: boolean = usbManager.resetUsbDevice(devicepipe); 1334 console.info(`resetUsbDevice = ${ret}`); 1335} catch (err) { 1336 console.error(`resetUsbDevice failed: ` + err); 1337} 1338``` 1339 1340## USBEndpoint 1341 1342通过USB发送和接收数据的端口。通过[USBInterface](#usbinterface)获取。 1343 1344>**说明：** 1345> 1346> 主机控制器按照Endpoint类型调度。 1347> 1348> 协议层打包时依赖type决定传输特性。 1349 1350**系统能力：** SystemCapability.USB.USBManager 1351 1352| 名称 | 类型 | 必填 |说明 | 1353| ------------- | ------------------------------------------- | ------------- |------------- | 1354| address | number | 是 |端点地址。 | 1355| attributes | number | 是 |端点属性。 | 1356| interval | number | 是 |端点间隔。 | 1357| maxPacketSize | number | 是 |端点最大数据包大小。 | 1358| direction | [USBRequestDirection](#usbrequestdirection) | 是 |端点的方向。 | 1359| number | number | 是 |端点号。 | 1360| type | number | 是 |端点类型。取值见[UsbEndpointTransferType](#usbendpointtransfertype18) | 1361| interfaceId | number | 是 |端点所属的接口的唯一标识。 | 1362 1363## USBInterface 1364 1365一个[USBConfiguration](#usbconfiguration)中可以含有多个USBInterface，每个USBInterface提供一个功能。 1366 1367**系统能力：** SystemCapability.USB.USBManager 1368 1369| 名称 | 类型 | 必填 |说明 | 1370| ---------------- | ---------------------------------------- | ------------- |--------------------- | 1371| id | number | 是 |接口的唯一标识。 | 1372| protocol | number | 是 |接口的协议。 | 1373| clazz | number | 是 |设备类型。 | 1374| subClass | number | 是 |设备子类。 | 1375| alternateSetting | number | 是 |在同一个接口中的多个描述符中进行切换设置。值的大小表示支持可选模式个数，其中0表示不支持可选模式。 | 1376| name | string | 是 |接口名称。 | 1377| endpoints | Array<[USBEndpoint](#usbendpoint)> | 是 |当前接口所包含的端点。 | 1378 1379## USBConfiguration 1380 1381USB配置，一个[USBDevice](#usbdevice)中可以含有多个配置。 1382 1383**系统能力：** SystemCapability.USB.USBManager 1384 1385| 名称 | 类型 | 必填 |说明 | 1386| -------------- | ------------------------------------------------ | --------------- |--------------- | 1387| id | number | 是 |配置的唯一标识。 | 1388| attributes | number | 是 |配置的属性。 | 1389| maxPower | number | 是 |最大功耗，以毫安为单位。 | 1390| name | string | 是 |配置的名称，可以为空。 | 1391| isRemoteWakeup | boolean | 是 |检查当前配置是否支持远程唤醒。 | 1392| isSelfPowered | boolean | 是 | 检查当前配置是否支持独立电源。 | 1393| interfaces | Array <[USBInterface](#usbinterface)> | 是 |配置支持的接口属性。 | 1394 1395## USBDevice 1396 1397USB设备信息。 1398 1399**系统能力：** SystemCapability.USB.USBManager 1400 1401| 名称 | 类型 | 必填 |说明 | 1402| ---------------- | ------------------------------------ | ---------- |---------- | 1403| busNum | number | 是 |总线地址。 | 1404| devAddress | number | 是 |设备地址。 | 1405| serial | string | 是 |序列号。 | 1406| name | string | 是 |设备名字。 | 1407| manufacturerName | string | 是 | 产商信息。 | 1408| productName | string | 是 |产品信息。 | 1409| version | string | 是 |版本。 | 1410| vendorId | number | 是 |厂商ID。 | 1411| productId | number | 是 |产品ID。 | 1412| clazz | number | 是 |设备类。 | 1413| subClass | number | 是 |设备子类。 | 1414| protocol | number | 是 |设备协议码。 | 1415| configs | Array<[USBConfiguration](#usbconfiguration)> | 是 |设备配置描述符信息。 | 1416 1417## USBDevicePipe 1418 1419USB设备消息传输通道，用于确定设备。 1420 1421**系统能力：** SystemCapability.USB.USBManager 1422 1423| 名称 | 类型 | 必填 |说明 | 1424| ---------- | ------ | ----- |----- | 1425| busNum | number |是 | 总线地址。 | 1426| devAddress | number |是 | 设备地址。 | 1427 1428## USBControlParams<sup>(deprecated)</sup> 1429 1430控制传输参数。 1431 1432>**说明：** 1433> 1434> 从 API version 9开始支持，从API version 18开始废弃。建议使用 [USBDeviceRequestParams](#usbdevicerequestparams12) 替代。 1435 1436**系统能力：** SystemCapability.USB.USBManager 1437 1438| 名称 | 类型 | 必填 |说明 | 1439| ------- | ----------------------------------------------- | ---------------- |---------------- | 1440| request | number | 是 |请求类型。 | 1441| target | [USBRequestTargetType](#usbrequesttargettype) | 是 |请求目标类型。 | 1442| reqType | [USBControlRequestType](#usbcontrolrequesttype) | 是 |请求控制类型。 | 1443| value | number | 是 |请求参数。 | 1444| index | number | 是 |请求参数value对应的索引值。 | 1445| data | Uint8Array | 是 |用于写入或读取的缓冲区。 | 1446 1447## USBDeviceRequestParams<sup>12+</sup> 1448 1449控制传输参数。 1450 1451**系统能力：** SystemCapability.USB.USBManager 1452 1453| 名称 | 类型 | 必填 |说明 | 1454| ------- | ----------------------------------------------- | ---------------- |---------------- | 1455| bmRequestType | number | 是 |请求控制类型。 | 1456| bRequest | number | 是 |请求类型。 | 1457| wValue | number | 是 |请求参数。 | 1458| wIndex | number | 是 |请求参数value对应的索引值。 | 1459| wLength | number | 是 |请求数据的长度。 | 1460| data | Uint8Array | 是 |用于写入或读取的缓冲区。 | 1461 1462## USBRequestTargetType 1463 1464请求目标类型。 1465 1466**系统能力：** SystemCapability.USB.USBManager 1467 1468| 名称 | 值 | 说明 | 1469| ---------------------------- | ---- | ------ | 1470| USB_REQUEST_TARGET_DEVICE | 0 | 设备。 | 1471| USB_REQUEST_TARGET_INTERFACE | 1 | 接口。 | 1472| USB_REQUEST_TARGET_ENDPOINT | 2 | 端点。 | 1473| USB_REQUEST_TARGET_OTHER | 3 | 其他。 | 1474 1475## USBControlRequestType 1476 1477控制请求类型。 1478 1479**系统能力：** SystemCapability.USB.USBManager 1480 1481| 名称 | 值 | 说明 | 1482| ------------------------- | ---- | ------ | 1483| USB_REQUEST_TYPE_STANDARD | 0 | 标准。 | 1484| USB_REQUEST_TYPE_CLASS | 1 | 类。 | 1485| USB_REQUEST_TYPE_VENDOR | 2 | 厂商。 | 1486 1487## USBRequestDirection 1488 1489请求方向。 1490 1491**系统能力：** SystemCapability.USB.USBManager 1492 1493| 名称 | 值 | 说明 | 1494| --------------------------- | ---- | ------------------------ | 1495| USB_REQUEST_DIR_TO_DEVICE | 0 | 写数据，主设备往从设备。 | 1496| USB_REQUEST_DIR_FROM_DEVICE | 0x80 | 读数据，从设备往主设备。 | 1497 1498## USBAccessory<sup>14+</sup> 1499 1500USB配件信息。 1501 1502**系统能力：** SystemCapability.USB.USBManager 1503 1504| 名称 | 类型 | 必填 | 说明 | 1505| ------------ | ------ | ---- | ---------------- | 1506| manufacturer | string | 是 | 配件的生产厂商。 | 1507| product | string | 是 | 配件的产品类型。 | 1508| description | string | 是 | 配件的描述。 | 1509| version | string | 是 | 配件的版本。 | 1510| serialNumber | string | 是 | 配件的SN号。 | 1511 1512## USBAccessoryHandle<sup>14+</sup> 1513 1514USB配件句柄。 1515 1516**系统能力：** SystemCapability.USB.USBManager 1517 1518| 名称 | 类型 | 必填 | 说明 | 1519| ----------- | ------ | ---- | ----------------------------------------- | 1520| accessoryFd | number | 是 | 配件文件描述符。合法的accessoryFd是正整数。 | 1521 1522## UsbDataTransferParams<sup>18+</sup> 1523 1524作为通用USB数据传输接口，客户端需要填充这个对象中的参数，用以发起传输请求。 1525 1526**系统能力：** SystemCapability.USB.USBManager 1527 1528| 名称 | 类型 | 必填 |说明 | 1529| ---------- | ------ | ----- |----- | 1530| devPipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址，需要调用connectDevice获取。 | 1531| flags | [UsbTransferFlags](#usbtransferflags18) |是 | USB传输标志。 | 1532| endpoint | number | 是 | 端点地址，正整数。 | 1533| type | [UsbEndpointTransferType](#usbendpointtransfertype18) |是 | 传输类型。 | 1534| timeout | number | 是 | 超时时间，单位为毫秒。 | 1535| length | number |是 | 数据缓冲区的长度，必须是非负数（期望长度），单位为字节。 | 1536| callback | AsyncCallback<[SubmitTransferCallback](#submittransfercallback18)> |是 | 传输完成时的回调信息。| 1537| userData | Uint8Array | 是 | 用户上下文数据。 | 1538| buffer | Uint8Array | 是 | 用于存储读或者写请求时的数据。 | 1539| isoPacketCount | number | 是 | 实时传输时数据包的数量，仅用于具有实时传输端点的I/O。必须是非负数，单位为个数。 | 1540 1541## UsbTransferFlags<sup>18+</sup> 1542 1543USB传输标志。 1544 1545**系统能力：** SystemCapability.USB.USBManager 1546 1547| 名称 | 值 | 说明 | 1548| ---------------------------- | ---- | ------ | 1549| USB_TRANSFER_SHORT_NOT_OK | 0 | 将短帧报告为错误。 | 1550| USB_TRANSFER_FREE_BUFFER | 1 | 自动释放传输缓冲区。 | 1551| USB_TRANSFER_FREE_TRANSFER | 2 | 完成回调后自动传输。 | 1552| USB_TRANSFER_ADD_ZERO_PACKET | 3 | 传输将增加一个额外的数据包。 | 1553 1554## UsbEndpointTransferType<sup>18+</sup> 1555 1556Usb传输类型。 1557 1558**系统能力：** SystemCapability.USB.USBManager 1559 1560| 名称 | 值 | 说明 | 1561| ---------------------------- | ---- | ------ | 1562| TRANSFER_TYPE_ISOCHRONOUS | 0x1 | 实时传输。 | 1563| TRANSFER_TYPE_BULK | 0x2 | 批量传输。 | 1564| TRANSFER_TYPE_INTERRUPT | 0x3 | 中断传输。| 1565 1566## SubmitTransferCallback<sup>18+</sup> 1567 1568Usb异步传输回调。 1569 1570**系统能力：** SystemCapability.USB.USBManager 1571 1572| 名称 | 类型 | 必填 | 说明 | 1573| ---------- | ------ | ----- | ------ | 1574| actualLength | number | 是 |读写操作的实际长度值，单位为字节。 | 1575| status | [UsbTransferStatus](#usbtransferstatus18) | 是 |读写操作完成的状态。 | 1576| isoPacketDescs | Array<Readonly<[UsbIsoPacketDescriptor](#usbisopacketdescriptor18)>> | 是 |实时传输的分包信息。 | 1577 1578## UsbTransferStatus<sup>18+</sup> 1579 1580数据处理完成后通过回调返回的状态码。 1581 1582**系统能力：** SystemCapability.USB.USBManager 1583 1584| 名称 | 值 | 说明 | 1585| ---------------------------- | ---- | ------ | 1586| TRANSFER_COMPLETED | 0 | 传输完成。| 1587| TRANSFER_ERROR | 1 | 传输失败。 | 1588| TRANSFER_TIMED_OUT | 2 | 传输超时。 | 1589| TRANSFER_CANCELED | 3 |传输已被取消。 | 1590| TRANSFER_STALL | 4 | 检测到暂停（批量/中断端点）。| 1591| TRANSFER_NO_DEVICE | 5 | 设备已断开。| 1592| TRANSFER_OVERFLOW | 6 | 设备发送的数据比请求的多。| 1593 1594## UsbIsoPacketDescriptor<sup>18+</sup> 1595 1596实时传输模式回调返回的分包信息。 1597 1598**系统能力：** SystemCapability.USB.USBManager 1599 1600| 名称 | 类型 | 必填 | 说明 | 1601| ---------- | ------ | ----- | ------ | 1602| length | number | 是 |读写操作的期望长度值，单位为字节。 | 1603| actualLength | number| 是 |读写操作的实际长度值，单位为字节。 | 1604| status | [UsbTransferStatus](#usbtransferstatus18) | 是 |实时传输分包的状态码。 | 1605