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