1# @ohos.usbManager (USB管理) 2 3本模块主要提供管理USB设备的相关功能,包括主设备上查询USB设备列表、批量数据传输、控制命令传输、权限控制等;从设备上端口管理、功能切换及查询等。 4 5> **说明:** 6> 7> 本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```ts 12import { usbManager } from '@kit.BasicServicesKit'; 13``` 14 15## usbManager.getDevices 16 17getDevices(): Array<Readonly<USBDevice>> 18 19获取接入主设备的USB设备列表。如果没有设备接入,那么将会返回一个空的列表。 20 21**系统能力:** SystemCapability.USB.USBManager 22 23**返回值:** 24 25| 类型 | 说明 | 26| ---------------------------------------------------- | ------- | 27| Array<Readonly<[USBDevice](#usbdevice)>> | 设备信息列表。 | 28 29**示例:** 30 31```ts 32let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 33console.log(`devicesList = ${devicesList}`); 34/* 35devicesList 返回的数据结构,此处提供一个简单的示例,如下 36[ 37 { 38 name: "1-1", 39 serial: "", 40 manufacturerName: "", 41 productName: "", 42 version: "", 43 vendorId: 7531, 44 productId: 2, 45 clazz: 9, 46 subClass: 0, 47 protocol: 1, 48 devAddress: 1, 49 busNum: 1, 50 configs: [ 51 { 52 id: 1, 53 attributes: 224, 54 isRemoteWakeup: true, 55 isSelfPowered: true, 56 maxPower: 0, 57 name: "1-1", 58 interfaces: [ 59 { 60 id: 0, 61 protocol: 0, 62 clazz: 9, 63 subClass: 0, 64 alternateSetting: 0, 65 name: "1-1", 66 endpoints: [ 67 { 68 address: 129, 69 attributes: 3, 70 interval: 12, 71 maxPacketSize: 4, 72 direction: 128, 73 number: 1, 74 type: 3, 75 interfaceId: 0, 76 }, 77 ], 78 }, 79 ], 80 }, 81 ], 82 }, 83] 84*/ 85``` 86 87## usbManager.connectDevice 88 89connectDevice(device: USBDevice): Readonly<USBDevicePipe> 90 91根据getDevices()返回的设备信息打开USB设备。 92 93需要调用[usbManager.getDevices](#usbmanagergetdevices)获取设备信息以及device,再调用[usbManager.requestRight](#usbmanagerrequestright)请求使用该设备的权限。 94 95> **说明:** 96> 97> 单次批量传输的传输数据总量(包括pipe、endpoint、buffer、timeout)请控制在200KB以下。 98 99**系统能力:** SystemCapability.USB.USBManager 100 101**参数:** 102 103| 参数名 | 类型 | 必填 | 说明 | 104| -------- | -------- | -------- | ---------------- | 105| device | [USBDevice](#usbdevice) | 是 | USB设备信息,用getDevices获取的busNum和devAddress确定设备,当前其他属性不做处理。 | 106 107**返回值:** 108 109| 类型 | 说明 | 110| -------- | -------- | 111| Readonly<[USBDevicePipe](#usbdevicepipe)> | 指定的传输通道对象。 | 112 113**错误码:** 114 115以下错误码的详细介绍参见[USB服务错误码](errorcode-usb.md)。 116 117| 错误码ID | 错误信息 | 118| -------- | ------------------------------------------------------------ | 119| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 120| 14400001 | Permission denied. Call requestRight to get the permission first. | 121 122**示例:** 123 124```ts 125let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 126if (devicesList.length == 0) { 127 console.log(`device list is empty`); 128} 129 130let device: usbManager.USBDevice = devicesList[0]; 131usbManager.requestRight(device.name); 132let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 133console.log(`devicepipe = ${devicepipe}`); 134``` 135 136## usbManager.hasRight 137 138hasRight(deviceName: string): boolean 139 140判断是否有权访问该设备。 141 142如果“使用者”(如各种App或系统)有权访问设备则返回true;无权访问设备则返回false。 143 144**系统能力:** SystemCapability.USB.USBManager 145 146**参数:** 147 148| 参数名 | 类型 | 必填 | 说明 | 149| -------- | -------- | -------- | -------- | 150| deviceName | string | 是 | 设备名称,来自getDevices获取的设备列表。 | 151 152**错误码:** 153 154以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 155 156| 错误码ID | 错误信息 | 157| -------- | ------------------------------------------------------------ | 158| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 159 160**返回值:** 161 162| 类型 | 说明 | 163| -------- | -------- | 164| boolean | true表示有访问设备的权限,false表示没有访问设备的权限。 | 165 166**示例:** 167 168```ts 169let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 170if (devicesList.length == 0) { 171 console.log(`device list is empty`); 172} 173 174let device: usbManager.USBDevice = devicesList[0]; 175usbManager.requestRight(device.name); 176let right: boolean = usbManager.hasRight(device.name); 177console.log(`${right}`); 178``` 179 180## usbManager.requestRight 181 182requestRight(deviceName: string): Promise<boolean> 183 184请求软件包的临时权限以访问设备。使用Promise异步回调。系统应用默认拥有访问设备权限,无需调用此接口申请。 185 186**系统能力:** SystemCapability.USB.USBManager 187 188**参数:** 189 190| 参数名 | 类型 | 必填 | 说明 | 191| -------- | -------- | -------- | -------- | 192| deviceName | string | 是 | 设备名称,来自getDevices获取的设备列表。| 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 202**返回值:** 203 204| 类型 | 说明 | 205| -------- | -------- | 206| Promise<boolean> | Promise对象,返回临时权限的申请结果。返回true表示临时权限申请成功;返回false则表示临时权限申请失败。 | 207 208**示例:** 209 210```ts 211let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 212if (devicesList.length == 0) { 213 console.log(`device list is empty`); 214} 215 216let device: usbManager.USBDevice = devicesList[0]; 217usbManager.requestRight(device.name).then(ret => { 218 console.log(`requestRight = ${ret}`); 219}); 220``` 221 222## usbManager.removeRight 223 224removeRight(deviceName: string): boolean 225 226移除软件包访问设备的权限。系统应用默认拥有访问设备权限,调用此接口不会产生影响。 227 228**系统能力:** SystemCapability.USB.USBManager 229 230**参数:** 231 232| 参数名 | 类型 | 必填 | 说明 | 233| -------- | -------- | -------- | -------- | 234| deviceName | string | 是 | 设备名称,来自getDevices获取的设备列表。| 235 236**错误码:** 237 238以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 239 240| 错误码ID | 错误信息 | 241| -------- | ------------------------------------------------------------ | 242| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 243 244**返回值:** 245 246| 类型 | 说明 | 247| -------- | -------- | 248| boolean | 返回权限移除结果。返回true表示权限移除成功;返回false则表示权限移除失败。 | 249 250**示例:** 251 252```ts 253let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 254if (devicesList.length == 0) { 255 console.log(`device list is empty`); 256} 257 258let device: usbManager.USBDevice = devicesList[0]; 259if (usbManager.removeRight(device.name)) { 260 console.log(`Succeed in removing right`); 261} 262``` 263 264## usbManager.claimInterface 265 266claimInterface(pipe: USBDevicePipe, iface: USBInterface, force ?: boolean): number 267 268注册通信接口。 269 270需要调用[usbManager.getDevices](#usbmanagergetdevices)获取设备信息以及interfaces;调用[usbManager.requestRight](#usbmanagerrequestright)获取设备请求权限;调用[usbManager.connectDevice](#usbmanagerconnectdevice)接口得到devicepipe作为参数。 271 272**系统能力:** SystemCapability.USB.USBManager 273 274**参数:** 275 276| 参数名 | 类型 | 必填 | 说明 | 277| -------- | -------- | -------- | -------- | 278| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址,需要调用connectDevice获取。| 279| iface | [USBInterface](#usbinterface) | 是 | 用于确定需要获取接口的索引,需要调用getDevices获取设备信息并通过id确定唯一接口。| 280| force | boolean | 否 | 可选参数,是否强制获取。默认值为false ,表示不强制获取,用户按需选择。| 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 290**返回值:** 291 292| 类型 | 说明 | 293| -------- | -------- | 294| number | 注册通信接口成功返回0;注册通信接口失败返回其他错误码。 | 295 296**示例:** 297 298```ts 299let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 300if (devicesList.length == 0) { 301 console.log(`device list is empty`); 302} 303 304let device: usbManager.USBDevice = devicesList[0]; 305usbManager.requestRight(device.name); 306let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 307let interfaces: usbManager.USBInterface = device.configs[0].interfaces[0]; 308let ret: number= usbManager.claimInterface(devicepipe, interfaces); 309console.log(`claimInterface = ${ret}`); 310``` 311 312## usbManager.releaseInterface 313 314releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number 315 316释放注册过的通信接口。 317 318需要调用[usbManager.claimInterface](#usbmanagerclaiminterface)先获取接口,才能使用此方法释放接口。 319 320**系统能力:** SystemCapability.USB.USBManager 321 322**参数:** 323 324| 参数名 | 类型 | 必填 | 说明 | 325| -------- | -------- | -------- | -------- | 326| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址,需要调用connectDevice获取。| 327| iface | [USBInterface](#usbinterface) | 是 | 用于确定需要释放接口的索引,需要调用getDevices获取设备信息并通过id确定唯一接口。| 328 329**错误码:** 330 331以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 332 333| 错误码ID | 错误信息 | 334| -------- | ------------------------------------------------------------ | 335| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified.2.Incorrect parameter types. | 336 337**返回值:** 338 339| 类型 | 说明 | 340| -------- | -------- | 341| number | 释放接口成功返回0;释放接口失败返回其他错误码。 | 342 343**示例:** 344 345```ts 346let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 347if (devicesList.length == 0) { 348 console.log(`device list is empty`); 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); 356ret = usbManager.releaseInterface(devicepipe, interfaces); 357console.log(`releaseInterface = ${ret}`); 358``` 359 360## usbManager.setConfiguration 361 362setConfiguration(pipe: USBDevicePipe, config: USBConfiguration): number 363 364设置设备配置。 365 366需要调用[usbManager.getDevices](#usbmanagergetdevices)获取设备信息以及config;调用[usbManager.requestRight](#usbmanagerrequestright)获取设备请求权限;调用[usbManager.connectDevice](#usbmanagerconnectdevice)得到devicepipe作为参数。 367 368**系统能力:** SystemCapability.USB.USBManager 369 370**参数:** 371 372| 参数名 | 类型 | 必填 | 说明 | 373| -------- | -------- | -------- | -------- | 374| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址,需要调用connectDevice获取。| 375| config | [USBConfiguration](#usbconfiguration) | 是 | 用于确定需要设置的配置,需要调用getDevices获取设备信息并通过id用于确定唯一设置。| 376 377**错误码:** 378 379以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 380 381| 错误码ID | 错误信息 | 382| -------- | ------------------------------------------------------------ | 383| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 384 385**返回值:** 386 387| 类型 | 说明 | 388| -------- | -------- | 389| number | 设置设备配置成功返回0;设置设备配置失败返回其他错误码。 | 390 391**示例:** 392 393```ts 394let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 395if (devicesList.length == 0) { 396 console.log(`device list is empty`); 397} 398 399let device: usbManager.USBDevice = devicesList[0]; 400usbManager.requestRight(device.name); 401let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 402let config: usbManager.USBConfiguration = device.configs[0]; 403let ret: number= usbManager.setConfiguration(devicepipe, config); 404console.log(`setConfiguration = ${ret}`); 405``` 406 407## usbManager.setInterface 408 409setInterface(pipe: USBDevicePipe, iface: USBInterface): number 410 411设置设备接口。 412 413需要调用[usbManager.getDevices](#usbmanagergetdevices)获取设备列表以及interfaces;调用[usbManager.requestRight](#usbmanagerrequestright)获取设备请求权限;调用[usbManager.connectDevice](#usbmanagerconnectdevice)得到devicepipe作为参数;调用[usbManager.claimInterface](#usbmanagerclaiminterface)注册通信接口。 414 415**系统能力:** SystemCapability.USB.USBManager 416 417**参数:** 418 419| 参数名 | 类型 | 必填 | 说明 | 420| -------- | -------- | -------- | -------- | 421| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址,需要调用connectDevice获取。| 422| iface | [USBInterface](#usbinterface) | 是 | 用于确定需要设置的接口,需要调用getDevices获取设备信息并通过id和alternateSetting确定唯一接口。| 423 424**错误码:** 425 426以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 427 428| 错误码ID | 错误信息 | 429| -------- | ------------------------------------------------------------ | 430| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 431 432**返回值:** 433 434| 类型 | 说明 | 435| -------- | -------- | 436| number | 设置设备接口成功返回0;设置设备接口失败返回其他错误码。 | 437 438**示例:** 439 440```ts 441let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 442if (devicesList.length == 0) { 443 console.log(`device list is empty`); 444} 445 446let device: usbManager.USBDevice = devicesList[0]; 447usbManager.requestRight(device.name); 448let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 449let interfaces: usbManager.USBInterface = device.configs[0].interfaces[0]; 450let ret: number = usbManager.claimInterface(devicepipe, interfaces); 451ret = usbManager.setInterface(devicepipe, interfaces); 452console.log(`setInterface = ${ret}`); 453``` 454 455## usbManager.getRawDescriptor 456 457getRawDescriptor(pipe: USBDevicePipe): Uint8Array 458 459获取原始的USB描述符。 460 461需要调用[usbManager.getDevices](#usbmanagergetdevices)获取设备列表;调用[usbManager.requestRight](#usbmanagerrequestright)获取设备请求权限;调用[usbManager.connectDevice](#usbmanagerconnectdevice)接口得到devicepipe作为参数。 462 463**系统能力:** SystemCapability.USB.USBManager 464 465**参数:** 466 467| 参数名 | 类型 | 必填 | 说明 | 468| -------- | -------- | -------- | -------- | 469| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址,需要调用connectDevice获取。| 470 471**错误码:** 472 473以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 474 475| 错误码ID | 错误信息 | 476| -------- | ------------------------------------------------------------ | 477| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 478 479**返回值:** 480 481| 类型 | 说明 | 482| -------- | -------- | 483| Uint8Array | 返回获取的原始数据;失败返回undefined。 | 484 485**示例:** 486 487```ts 488let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 489if (devicesList.length == 0) { 490 console.log(`device list is empty`); 491} 492 493usbManager.requestRight(devicesList[0].name); 494let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 495let ret: Uint8Array = usbManager.getRawDescriptor(devicepipe); 496``` 497 498## usbManager.getFileDescriptor 499 500getFileDescriptor(pipe: USBDevicePipe): number 501 502获取文件描述符。 503 504需要调用[usbManager.getDevices](#usbmanagergetdevices)获取设备列表;调用[usbManager.requestRight](#usbmanagerrequestright)获取设备请求权限;调用[usbManager.connectDevice](#usbmanagerconnectdevice)接口得到devicepipe作为参数。 505 506**系统能力:** SystemCapability.USB.USBManager 507 508**参数:** 509 510| 参数名 | 类型 | 必填 | 说明 | 511| -------- | -------- | -------- | -------- | 512| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址,需要调用connectDevice获取。| 513 514**错误码:** 515 516以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 517 518| 错误码ID | 错误信息 | 519| -------- | ------------------------------------------------------------ | 520| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 521 522**返回值:** 523 524| 类型 | 说明 | 525| ------ | -------------------- | 526| number | 返回设备对应的文件描述符;失败返回-1。 | 527 528**示例:** 529 530```ts 531let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 532if (devicesList.length == 0) { 533 console.log(`device list is empty`); 534} 535 536usbManager.requestRight(devicesList[0].name); 537let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 538let ret: number = usbManager.getFileDescriptor(devicepipe); 539``` 540 541## usbManager.controlTransfer<sup>(deprecated)</sup> 542 543controlTransfer(pipe: USBDevicePipe, controlparam: USBControlParams, timeout ?: number): Promise<number> 544 545控制传输。 546 547需要调用[usbManager.getDevices](#usbmanagergetdevices)获取设备列表;调用[usbManager.requestRight](#usbmanagerrequestright)获取设备请求权限;调用[usbManager.connectDevice](#usbmanagerconnectdevice)接口得到devicepipe作为参数。 548 549**说明:** 550 551> 从 API version 9开始支持,从API version 12开始废弃。建议使用 [usbControlTransfer](#usbmanagerusbcontroltransfer12) 替代。 552 553**系统能力:** SystemCapability.USB.USBManager 554 555**参数:** 556 557| 参数名 | 类型 | 必填 | 说明 | 558| -------- | -------- | -------- | -------- | 559| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定设备,需要调用connectDevice获取。| 560| controlparam | [USBControlParams](#usbcontrolparams) | 是 | 控制传输参数,按需设置参数,参数传参类型请参考USB协议。| 561| timeout | number | 否 | 超时时间(单位:ms),可选参数,默认为0不超时,用户按需选择 。 | 562 563**错误码:** 564 565以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 566 567| 错误码ID | 错误信息 | 568| -------- | ------------------------------------------------------------ | 569| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 570 571**返回值:** 572 573| 类型 | 说明 | 574| -------- | -------- | 575| Promise<number> | Promise对象,获取传输或接收到的数据块大小。失败返回-1。 | 576 577**示例:** 578 579```ts 580class PARA { 581 request: number = 0 582 reqType: usbManager.USBControlRequestType = 0 583 target: usbManager.USBRequestTargetType = 0 584 value: number = 0 585 index: number = 0 586 data: Uint8Array = new Uint8Array() 587} 588 589let param: PARA = { 590 request: 0x06, 591 reqType: 0x80, 592 target:0, 593 value: 0x01 << 8 | 0, 594 index: 0, 595 data: new Uint8Array(18) 596}; 597 598let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 599if (devicesList.length == 0) { 600 console.log(`device list is empty`); 601} 602 603usbManager.requestRight(devicesList[0].name); 604let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 605usbManager.controlTransfer(devicepipe, param).then((ret: number) => { 606console.log(`controlTransfer = ${ret}`); 607}) 608``` 609 610## usbManager.usbControlTransfer<sup>12+</sup> 611 612usbControlTransfer(pipe: USBDevicePipe, requestparam: USBDeviceRequestParams, timeout ?: number): Promise<number> 613 614控制传输。 615 616需要调用[usbManager.getDevices](#usbmanagergetdevices)获取设备列表;调用[usbManager.requestRight](#usbmanagerrequestright)获取设备请求权限;调用[usbManager.connectDevice](#usbmanagerconnectdevice)接口得到devicepipe作为参数。 617 618**系统能力:** SystemCapability.USB.USBManager 619 620**参数:** 621 622| 参数名 | 类型 | 必填 | 说明 | 623| -------- | -------- | -------- | -------- | 624| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定设备。 | 625| requestparam | [USBDeviceRequestParams](#usbdevicerequestparams12) | 是 | 控制传输参数,按需设置参数,参数传参类型请参考USB协议。 | 626| timeout | number | 否 | 超时时间(单位:ms),可选参数,默认为0不超时。 | 627 628**错误码:** 629 630以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 631 632| 错误码ID | 错误信息 | 633| -------- | ------------------------------------------------------------ | 634| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified.2.Incorrect parameter types | 635 636**返回值:** 637 638| 类型 | 说明 | 639| -------- | -------- | 640| Promise<number> | Promise对象,获取传输或接收到的数据块大小。失败返回-1。 | 641 642**示例:** 643 644```ts 645class PARA { 646 bmRequestType: number = 0 647 bRequest: number = 0 648 wValue: number = 0 649 wIndex: number = 0 650 wLength: number = 0 651 data: Uint8Array = new Uint8Array() 652} 653 654let param: PARA = { 655 bmRequestType: 0x80, 656 bRequest: 0x06, 657 658 wValue:0x01 << 8 | 0, 659 wIndex: 0, 660 wLength: 18, 661 data: new Uint8Array(18) 662}; 663 664let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 665if (devicesList.length == 0) { 666 console.log(`device list is empty`); 667} 668 669usbManager.requestRight(devicesList[0].name); 670let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 671usbManager.usbControlTransfer(devicepipe, param).then((ret: number) => { 672console.log(`usbControlTransfer = ${ret}`); 673}) 674``` 675 676## usbManager.bulkTransfer 677 678bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, timeout ?: number): Promise<number> 679 680批量传输。 681 682需要调用[usbManager.getDevices](#usbmanagergetdevices)获取设备信息列表以及endpoint;再调用[usbManager.requestRight](#usbmanagerrequestright)获取设备请求权限;然后调用[usbManager.connectDevice](#usbmanagerconnectdevice)接口得到返回数据devicepipe之后,再次获取接口[usbManager.claimInterface](#usbmanagerclaiminterface);再调用usb.bulkTransfer接口。 683 684**系统能力:** SystemCapability.USB.USBManager 685 686**参数:** 687 688| 参数名 | 类型 | 必填 | 说明 | 689| -------- | -------- | -------- | -------- | 690| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定设备,需要调用connectDevice获取。| 691| endpoint | [USBEndpoint](#usbendpoint) | 是 | 用于确定传输的端口,需要调用getDevices获取设备信息列表以及endpoint,address用于确定端点地址,direction用于确定端点的方向,interfaceId用于确定所属接口,当前其他属性不做处理。| 692| buffer | Uint8Array | 是 | 用于写入或读取数据的缓冲区。 | 693| timeout | number | 否 | 超时时间(单位:ms),可选参数,默认为0不超时,用户按需选择 。 | 694 695**错误码:** 696 697以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 698 699| 错误码ID | 错误信息 | 700| -------- | ------------------------------------------------------------ | 701| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 702 703**返回值:** 704 705| 类型 | 说明 | 706| -------- | -------- | 707| Promise<number> | Promise对象,获取传输或接收到的数据块大小。失败返回-1。 | 708 709**示例:** 710 711> **说明:** 712> 713> 以下示例代码只是调用bulkTransfer接口的必要流程,实际调用时,设备开发者需要遵循设备相关协议进行调用,确保数据的正确传输和设备的兼容性。 714 715```ts 716//usbManager.getDevices 接口返回数据集合,取其中一个设备对象,并获取权限 。 717//把获取到的设备对象作为参数传入usbManager.connectDevice;当usbManager.connectDevice接口成功返回之后; 718//才可以调用第三个接口usbManager.claimInterface.当usbManager.claimInterface 调用成功以后,再调用该接口。 719let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 720if (devicesList.length == 0) { 721 console.log(`device list is empty`); 722} 723 724let device: usbManager.USBDevice = devicesList[0]; 725usbManager.requestRight(device.name); 726 727let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 728for (let i = 0; i < device.configs[0].interfaces.length; i++) { 729 if (device.configs[0].interfaces[i].endpoints[0].attributes == 2) { 730 let endpoint: usbManager.USBEndpoint = device.configs[0].interfaces[i].endpoints[0]; 731 let interfaces: usbManager.USBInterface = device.configs[0].interfaces[i]; 732 let ret: number = usbManager.claimInterface(devicepipe, interfaces); 733 let buffer = new Uint8Array(128); 734 usbManager.bulkTransfer(devicepipe, endpoint, buffer).then((ret: number) => { 735 console.log(`bulkTransfer = ${ret}`); 736 }); 737 } 738} 739``` 740 741## usbManager.closePipe 742 743closePipe(pipe: USBDevicePipe): number 744 745关闭设备消息控制通道。 746 747需要调用[usbManager.getDevices](#usbmanagergetdevices)获取设备列表;调用[usbManager.requestRight](#usbmanagerrequestright)获取设备请求权限;调用[usbManager.connectDevice](#usbmanagerconnectdevice)得到devicepipe作为参数。 748 749**系统能力:** SystemCapability.USB.USBManager 750 751**参数:** 752 753| 参数名 | 类型 | 必填 | 说明 | 754| -------- | -------- | -------- | -------- | 755| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定USB设备消息控制通道,需要调用connectDevice获取。| 756 757**错误码:** 758 759以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 760 761| 错误码ID | 错误信息 | 762| -------- | ------------------------------------------------------------ | 763| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 764 765**返回值:** 766 767| 类型 | 说明 | 768| -------- | -------- | 769| number | 关闭设备消息控制通道成功返回0;关闭设备消息控制通道失败返回其他错误码。 | 770 771**示例:** 772 773```ts 774let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 775if (devicesList.length == 0) { 776 console.log(`device list is empty`); 777} 778 779usbManager.requestRight(devicesList[0].name); 780let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 781let ret: number = usbManager.closePipe(devicepipe); 782console.log(`closePipe = ${ret}`); 783``` 784 785## usbManager.hasAccessoryRight<sup>14+</sup> 786 787hasAccessoryRight(accessory: USBAccessory): boolean 788 789检查应用程序是否有权访问USB配件。 790 791需要调用[usbManager.getAccessoryList](#usbmanagergetaccessorylist14)获取配件列表,得到[USBAccessory](#usbaccessory14)作为参数。 792 793**系统能力:** SystemCapability.USB.USBManager 794 795**参数:** 796 797| 参数名 | 类型 | 必填 | 说明 | 798| --------- | ------------ | ---- | ------------------------------------- | 799| accessory | [USBAccessory](#usbaccessory14) | 是 | USB配件,需要通过[getAccessoryList](#usbmanagergetaccessorylist14)获取。 | 800 801**错误码:** 802 803以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 804 805| 错误码ID | 错误信息 | 806| -------- | ------------------------------------------------------------ | 807| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 808| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. | 809| 14400005 | Database operation exception. | 810| 14401001 | The target USBAccessory not matched. | 811 812**返回值:** 813 814| 类型 | 说明 | 815| ------- | ----------------------------- | 816| boolean | true表示应用程序有权访问USB配件,false表示应用程序无权访问USB配件。 | 817 818**示例:** 819 820```ts 821import { hilog } from '@kit.PerformanceAnalysisKit'; 822try { 823 let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList() 824 let flag = usbManager.hasAccessoryRight(accList[0]) 825 hilog.info(0, 'testTag ui', `hasAccessoryRight success, ret:${flag}`) 826} catch (error) { 827 hilog.info(0, 'testTag ui', `hasAccessoryRight error ${error.code}, message is ${error.message}`) 828} 829``` 830 831## usbManager.requestAccessoryRight<sup>14+</sup> 832 833requestAccessoryRight(accessory: USBAccessory): Promise<boolean> 834 835为指定应用程序申请访问USB配件的访问权限。 836 837需要调用[usbManager.getAccessoryList](#usbmanagergetaccessorylist14)获取配件列表,得到[USBAccessory](#usbaccessory14)作为参数。 838 839**系统能力** SystemCapability.USB.USBManager 840 841**参数:** 842 843| 参数名 | 类型 | 必填 | 说明 | 844| --------- | ------------ | ---- | ------------------------------------- | 845| accessory | [USBAccessory](#usbaccessory14) | 是 | USB配件,需要通过[getAccessoryList](#usbmanagergetaccessorylist14)获取。 | 846 847**错误码:** 848 849以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 850 851| 错误码ID | 错误信息 | 852| -------- | ------------------------------------------------------------ | 853| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 854| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. | 855| 14400005 | Database operation exception. | 856| 14401001 | The target USBAccessory not matched. | 857 858**返回值:** 859 860| 类型 | 说明 | 861| ---------------- | ----------------------------- | 862| Promise<boolean> | Promise对象,返回应用程序访问配件权限的申请结果。返回true表示权限申请成功;返回false表示权限申请失败。 | 863 864**示例:** 865 866```ts 867import { hilog } from '@kit.PerformanceAnalysisKit'; 868try { 869 let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList() 870 let flag = usbManager.requestAccessoryRight(accList[0]) 871 hilog.info(0, 'testTag ui', `requestAccessoryRight success, ret:${flag}`) 872} catch (error) { 873 hilog.info(0, 'testTag ui', `requestAccessoryRight error ${error.code}, message is ${error.message}`) 874} 875``` 876 877## usbManager.cancelAccessoryRight<sup>14+</sup> 878 879cancelAccessoryRight(accessory: USBAccessory): void; 880 881取消当前应用程序访问USB配件的权限。 882 883需要调用[usbManager.getAccessoryList](#usbmanagergetaccessorylist14)获取配件列表,得到[USBAccessory](#usbaccessory14)作为参数。 884 885**系统能力** SystemCapability.USB.USBManager 886 887**参数:** 888 889| 参数名 | 类型 | 必填 | 说明 | 890| --------- | ------------ | ---- | ------------------------------------- | 891| accessory | [USBAccessory](#usbaccessory14) | 是 | USB配件,需要通过[getAccessoryList](#usbmanagergetaccessorylist14)获取。 | 892 893**错误码:** 894 895以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 896 897| 错误码ID | 错误信息 | 898| -------- | ------------------------------------------------------------ | 899| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 900| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. | 901| 14400005 | Database operation exception. | 902| 14401001 | The target USBAccessory not matched. | 903 904**示例:** 905 906```ts 907import { hilog } from '@kit.PerformanceAnalysisKit'; 908try { 909 let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList() 910 let flag = usbManager.requestAccessoryRight(accList[0]) 911 usbManager.cancelAccessoryRight(accList[0]) 912 hilog.info(0, 'testTag ui', `cancelAccessoryRight success`) 913} catch (error) { 914 hilog.info(0, 'testTag ui', `cancelAccessoryRight error ${error.code}, message is ${error.message}`) 915} 916``` 917 918## usbManager.getAccessoryList<sup>14+</sup> 919 920getAccessoryList(): Array<Readonly<USBAccessory>> 921 922获取当前已接入主机的USB配件列表。 923 924**系统能力** SystemCapability.USB.USBManager 925 926**错误码:** 927 928以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 929 930| 错误码ID | 错误信息 | 931| -------- | ------------------------------------------------------------ | 932| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. | 933 934**返回值:** 935 936| 类型 | 说明 | 937| ----------------------------- | -------------------------------------------------- | 938| Array<Readonly<USBAccessory>> | 只读的USB配件列表。当前仅支持列表中包含1个USB配件。 | 939 940**示例:** 941 942```ts 943import { hilog } from '@kit.PerformanceAnalysisKit'; 944try { 945 let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList() 946 hilog.info(0, 'testTag ui', `getAccessoryList success, accList: ${JSON.stringify(accList)}`) 947} catch (error) { 948 hilog.info(0, 'testTag ui', `getAccessoryList error ${error.code}, message is ${error.message}`) 949} 950``` 951 952## usbManager.openAccessory<sup>14+</sup> 953 954openAccessory(accessory: USBAccessory): USBAccessoryHandle; 955 956获取配件句柄并打开配件文件描述符。 957 958需要调用[usbManager.getAccessoryList](#usbmanagergetaccessorylist14)获取配件列表,得到[USBAccessory](#usbaccessory14)作为参数。 959 960**系统能力** SystemCapability.USB.USBManager 961 962**参数:** 963 964| 参数名 | 类型 | 必填 | 说明 | 965| --------- | ------------ | ---- | ------------------------------------- | 966| accessory | [USBAccessory](#usbaccessory14) | 是 | USB配件,需要通过[getAccessoryList](#usbmanagergetaccessorylist14)获取。 | 967 968**错误码:** 969 970以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 971 972| 错误码ID | 错误信息 | 973| -------- | ------------------------------------------------------------ | 974| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 975| 14400001 | Permission denied. Call requestAccessoryRight to get the right first. | 976| 14400004 | Service exception. Possible causes: No accessory is plugged in. | 977| 14401001 | The target USBAccessory not matched. | 978| 14401002 | Failed to open the native accessory node. | 979| 14401003 | Cannot reopen the accessory. | 980 981**返回值:** 982 983| 类型 | 说明 | 984| ------------------ | ----------- | 985| [USBAccessoryHandle](#usbaccessoryhandle14) | USB配件句柄。 | 986 987**示例:** 988 989```ts 990import { hilog } from '@kit.PerformanceAnalysisKit'; 991try { 992 let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList() 993 let flag = usbManager.requestAccessoryRight(accList[0]) 994 let handle = usbManager.openAccessory(accList[0]) 995 hilog.info(0, 'testTag ui', `openAccessory success`) 996} catch (error) { 997 hilog.info(0, 'testTag ui', `openAccessory error ${error.code}, message is ${error.message}`) 998} 999``` 1000 1001## usbManager.closeAccessory<sup>14+</sup> 1002 1003closeAccessory(accessoryHandle: USBAccessoryHandle): void; 1004 1005关闭配件文件描述符。 1006 1007需要调用[usbManager.openAccessory](#usbmanageropenaccessory14)获取配件列表,得到[USBAccessoryHandle](#usbaccessoryhandle14)作为参数。 1008 1009**系统能力** SystemCapability.USB.USBManager 1010 1011**参数:** 1012 1013| 参数名 | 类型 | 必填 | 说明 | 1014| --------------- | ------------------ | ---- | -------------------------------------- | 1015| accessoryHandle | [USBAccessoryHandle](#usbaccessoryhandle14) | 是 | USB配件句柄。需要通过[openAccessory](#usbmanageropenaccessory14)获取。 | 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| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. | 1025 1026**示例:** 1027 1028```ts 1029import { hilog } from '@kit.PerformanceAnalysisKit'; 1030try { 1031 let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList() 1032 let flag = usbManager.requestAccessoryRight(accList[0]) 1033 let handle = usbManager.openAccessory(accList[0]) 1034 usbManager.closeAccessory(handle) 1035 hilog.info(0, 'testTag ui', `closeAccessory success`) 1036} catch (error) { 1037 hilog.info(0, 'testTag ui', `closeAccessory error ${error.code}, message is ${error.message}`) 1038} 1039``` 1040 1041## USBEndpoint 1042 1043通过USB发送和接收数据的端口。通过[USBInterface](#usbinterface)获取。 1044 1045**系统能力:** SystemCapability.USB.USBManager 1046 1047| 名称 | 类型 | 必填 |说明 | 1048| ------------- | ------------------------------------------- | ------------- |------------- | 1049| address | number | 是 |端点地址。 | 1050| attributes | number | 是 |端点属性。 | 1051| interval | number | 是 |端点间隔。 | 1052| maxPacketSize | number | 是 |端点最大数据包大小。 | 1053| direction | [USBRequestDirection](#usbrequestdirection) | 是 |端点的方向。 | 1054| number | number | 是 |端点号。 | 1055| type | number | 是 |端点类型。 | 1056| interfaceId | number | 是 |端点所属的接口的唯一标识。 | 1057 1058## USBInterface 1059 1060一个[USBConfiguration](#usbconfiguration)中可以含有多个USBInterface,每个USBInterface提供一个功能。 1061 1062**系统能力:** SystemCapability.USB.USBManager 1063 1064| 名称 | 类型 | 必填 |说明 | 1065| ---------------- | ---------------------------------------- | ------------- |--------------------- | 1066| id | number | 是 |接口的唯一标识。 | 1067| protocol | number | 是 |接口的协议。 | 1068| clazz | number | 是 |设备类型。 | 1069| subClass | number | 是 |设备子类。 | 1070| alternateSetting | number | 是 |在同一个接口中的多个描述符中进行切换设置。 | 1071| name | string | 是 |接口名称。 | 1072| endpoints | Array<[USBEndpoint](#usbendpoint)> | 是 |当前接口所包含的端点。 | 1073 1074## USBConfiguration 1075 1076USB配置,一个[USBDevice](#usbdevice)中可以含有多个配置。 1077 1078**系统能力:** SystemCapability.USB.USBManager 1079 1080| 名称 | 类型 | 必填 |说明 | 1081| -------------- | ------------------------------------------------ | --------------- |--------------- | 1082| id | number | 是 |配置的唯一标识。 | 1083| attributes | number | 是 |配置的属性。 | 1084| maxPower | number | 是 |最大功耗,以毫安为单位。 | 1085| name | string | 是 |配置的名称,可以为空。 | 1086| isRemoteWakeup | boolean | 是 |检查当前配置是否支持远程唤醒。 | 1087| isSelfPowered | boolean | 是 | 检查当前配置是否支持独立电源。 | 1088| interfaces | Array <[USBInterface](#usbinterface)> | 是 |配置支持的接口属性。 | 1089 1090## USBDevice 1091 1092USB设备信息。 1093 1094**系统能力:** SystemCapability.USB.USBManager 1095 1096| 名称 | 类型 | 必填 |说明 | 1097| ---------------- | ------------------------------------ | ---------- |---------- | 1098| busNum | number | 是 |总线地址。 | 1099| devAddress | number | 是 |设备地址。 | 1100| serial | string | 是 |序列号。 | 1101| name | string | 是 |设备名字。 | 1102| manufacturerName | string | 是 | 产商信息。 | 1103| productName | string | 是 |产品信息。 | 1104| version | string | 是 |版本。 | 1105| vendorId | number | 是 |厂商ID。 | 1106| productId | number | 是 |产品ID。 | 1107| clazz | number | 是 |设备类。 | 1108| subClass | number | 是 |设备子类。 | 1109| protocol | number | 是 |设备协议码。 | 1110| configs | Array<[USBConfiguration](#usbconfiguration)> | 是 |设备配置描述符信息。 | 1111 1112## USBDevicePipe 1113 1114USB设备消息传输通道,用于确定设备。 1115 1116**系统能力:** SystemCapability.USB.USBManager 1117 1118| 名称 | 类型 | 必填 |说明 | 1119| ---------- | ------ | ----- |----- | 1120| busNum | number |是 | 总线地址。 | 1121| devAddress | number |是 | 设备地址。 | 1122 1123## USBControlParams 1124 1125控制传输参数。 1126 1127**系统能力:** SystemCapability.USB.USBManager 1128 1129| 名称 | 类型 | 必填 |说明 | 1130| ------- | ----------------------------------------------- | ---------------- |---------------- | 1131| request | number | 是 |请求类型。 | 1132| target | [USBRequestTargetType](#usbrequesttargettype) | 是 |请求目标类型。 | 1133| reqType | [USBControlRequestType](#usbcontrolrequesttype) | 是 |请求控制类型。 | 1134| value | number | 是 |请求参数。 | 1135| index | number | 是 |请求参数value对应的索引值。 | 1136| data | Uint8Array | 是 |用于写入或读取的缓冲区。 | 1137 1138## USBDeviceRequestParams<sup>12+</sup> 1139 1140控制传输参数。 1141 1142**系统能力:** SystemCapability.USB.USBManager 1143 1144| 名称 | 类型 | 必填 |说明 | 1145| ------- | ----------------------------------------------- | ---------------- |---------------- | 1146| bmRequestType | number | 是 |请求控制类型。 | 1147| bRequest | number | 是 |请求类型。 | 1148| wValue | number | 是 |请求参数。 | 1149| wIndex | number | 是 |请求参数value对应的索引值。 | 1150| wLength | number | 是 |请求数据的长度 | 1151| data | Uint8Array | 是 |用于写入或读取的缓冲区。 | 1152 1153## USBRequestTargetType 1154 1155请求目标类型。 1156 1157**系统能力:** SystemCapability.USB.USBManager 1158 1159| 名称 | 值 | 说明 | 1160| ---------------------------- | ---- | ------ | 1161| USB_REQUEST_TARGET_DEVICE | 0 | 设备。 | 1162| USB_REQUEST_TARGET_INTERFACE | 1 | 接口。 | 1163| USB_REQUEST_TARGET_ENDPOINT | 2 | 端点。 | 1164| USB_REQUEST_TARGET_OTHER | 3 | 其他。 | 1165 1166## USBControlRequestType 1167 1168控制请求类型。 1169 1170**系统能力:** SystemCapability.USB.USBManager 1171 1172| 名称 | 值 | 说明 | 1173| ------------------------- | ---- | ------ | 1174| USB_REQUEST_TYPE_STANDARD | 0 | 标准。 | 1175| USB_REQUEST_TYPE_CLASS | 1 | 类。 | 1176| USB_REQUEST_TYPE_VENDOR | 2 | 厂商。 | 1177 1178## USBRequestDirection 1179 1180请求方向。 1181 1182**系统能力:** SystemCapability.USB.USBManager 1183 1184| 名称 | 值 | 说明 | 1185| --------------------------- | ---- | ------------------------ | 1186| USB_REQUEST_DIR_TO_DEVICE | 0 | 写数据,主设备往从设备。 | 1187| USB_REQUEST_DIR_FROM_DEVICE | 0x80 | 读数据,从设备往主设备。 | 1188 1189## USBAccessory<sup>14+</sup> 1190 1191USB配件信息。 1192 1193**系统能力:** SystemCapability.USB.USBManager 1194 1195| 名称 | 类型 | 必填 | 说明 | 1196| ------------ | ------ | ---- | ---------------- | 1197| manufacturer | string | 是 | 配件的生产厂商。 | 1198| product | string | 是 | 配件的产品类型。 | 1199| description | string | 是 | 配件的描述。 | 1200| version | string | 是 | 配件的版本。 | 1201| serialNumber | string | 是 | 配件的SN号。 | 1202 1203## USBAccessoryHandle<sup>14+</sup> 1204 1205USB配件句柄。 1206 1207**系统能力:** SystemCapability.USB.USBManager 1208 1209| 名称 | 类型 | 必填 | 说明 | 1210| ----------- | ------ | ---- | ----------------------------------------- | 1211| accessoryFd | number | 是 | 配件文件描述符。合法的accessoryFd是正整数。 | 1212