1# @ohos.usbManager (USB Manager) 2 3The **usbManager** module provides USB device management functions, including USB device list query, bulk data transfer, control transfer, and permission control on the host side as well as USB interface management, and function switch and query on the device side. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9## Modules to Import 10 11```ts 12import { usbManager } from '@kit.BasicServicesKit'; 13``` 14 15## usbManager.getDevices 16 17getDevices(): Array<Readonly<USBDevice>> 18 19Obtains the list of USB devices connected to the host. If no device is connected, an empty list is returned. 20 21**System capability**: SystemCapability.USB.USBManager 22 23**Return value** 24 25| Type | Description | 26| ---------------------------------------------------- | ------- | 27| Array<Readonly<[USBDevice](#usbdevice)>> | USB device list.| 28 29**Example** 30 31```ts 32let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 33console.log(`devicesList = ${devicesList}`); 34/* 35The following is a simple example of the data structure for devicesList: 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 91Connects to the USB device based on the device information returned by **getDevices()**. 92 93Before you do this, call [usbManager.getDevices](#usbmanagergetdevices) to obtain the USB device list and device information, and then call [usbManager.getDevices](#usbmanagergetdevices) to request the device access permission. 94 95**System capability**: SystemCapability.USB.USBManager 96 97**Parameters** 98 99| Name| Type| Mandatory| Description| 100| -------- | -------- | -------- | ---------------- | 101| device | [USBDevice](#usbdevice) | Yes| USB device. The **busNum** and **devAddress** parameters obtained by **getDevices** are used to determine a USB device. Other parameters are passed transparently.| 102 103**Return value** 104 105| Type| Description| 106| -------- | -------- | 107| Readonly<[USBDevicePipe](#usbdevicepipe)> | USB device pipe for data transfer.| 108 109**Error codes** 110 111For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 112 113| ID| Error Message | 114| -------- | ------------------------------------------------------------ | 115| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 116| 14400001 | Permission denied. Call requestRight to get the permission first. | 117 118**Example** 119 120```ts 121let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 122if (devicesList.length == 0) { 123 console.log(`device list is empty`); 124} 125 126let device: usbManager.USBDevice = devicesList[0]; 127usbManager.requestRight(device.name); 128let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 129console.log(`devicepipe = ${devicepipe}`); 130``` 131 132## usbManager.hasRight 133 134hasRight(deviceName: string): boolean 135 136Checks whether the application has the permission to access the device. 137 138Checks whether the user, for example, the application or system, has the device access permissions. The value **true** is returned if the user has the device access permissions; the value **false** is returned otherwise. 139 140**System capability**: SystemCapability.USB.USBManager 141 142**Parameters** 143 144| Name| Type| Mandatory| Description| 145| -------- | -------- | -------- | -------- | 146| deviceName | string | Yes| Device name, which can be obtained from the device list returned by **getDevices**.| 147 148**Error codes** 149 150For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 151 152| ID| Error Message | 153| -------- | ------------------------------------------------------------ | 154| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 155 156**Return value** 157 158| Type| Description| 159| -------- | -------- | 160| boolean | Returns **true** if the application has the permission to access the device; returns **false** otherwise.| 161 162**Example** 163 164```ts 165let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 166if (devicesList.length == 0) { 167 console.log(`device list is empty`); 168} 169 170let device: usbManager.USBDevice = devicesList[0]; 171usbManager.requestRight(device.name); 172let right: boolean = usbManager.hasRight(device.name); 173console.log(`${right}`); 174``` 175 176## usbManager.requestRight 177 178requestRight(deviceName: string): Promise<boolean> 179 180Requests the temporary device access permission for the application. This API uses a promise to return the result. System applications are granted the device access permission by default, and you do not need to apply for the permission separately. 181 182**System capability**: SystemCapability.USB.USBManager 183 184**Parameters** 185 186| Name| Type| Mandatory| Description| 187| -------- | -------- | -------- | -------- | 188| deviceName | string | Yes| Device name, which can be obtained from the device list returned by **getDevices**.| 189 190**Error codes** 191 192For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 193 194| ID| Error Message | 195| -------- | ------------------------------------------------------------ | 196| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 197 198**Return value** 199 200| Type| Description| 201| -------- | -------- | 202| Promise<boolean> | Promise used to return the result. The value **true** indicates that the temporary device access permissions are granted; and the value **false** indicates the opposite.| 203 204**Example** 205 206```ts 207let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 208if (devicesList.length == 0) { 209 console.log(`device list is empty`); 210} 211 212let device: usbManager.USBDevice = devicesList[0]; 213usbManager.requestRight(device.name).then(ret => { 214 console.log(`requestRight = ${ret}`); 215}); 216``` 217 218## usbManager.removeRight 219 220removeRight(deviceName: string): boolean 221 222Removes the device access permission for the application. System applications are granted the device access permission by default, and calling this API will not revoke the permission. 223 224**System capability**: SystemCapability.USB.USBManager 225 226**Parameters** 227 228| Name| Type| Mandatory| Description| 229| -------- | -------- | -------- | -------- | 230| deviceName | string | Yes| Device name, which can be obtained from the device list returned by **getDevices**.| 231 232**Error codes** 233 234For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 235 236| ID| Error Message | 237| -------- | ------------------------------------------------------------ | 238| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 239 240**Return value** 241 242| Type| Description| 243| -------- | -------- | 244| boolean | Permission removal result. The value **true** indicates that the access permission is removed successfully; and the value **false** indicates the opposite.| 245 246**Example** 247 248```ts 249let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 250if (devicesList.length == 0) { 251 console.log(`device list is empty`); 252} 253 254let device: usbManager.USBDevice = devicesList[0]; 255if (usbManager.removeRight(device.name)) { 256 console.log(`Succeed in removing right`); 257} 258``` 259 260## usbManager.claimInterface 261 262claimInterface(pipe: USBDevicePipe, iface: USBInterface, force ?: boolean): number 263 264Claims a USB interface. 265 266Before you do this, call [usbManager.getDevices](#usbmanagergetdevices) to obtain the USB device list and USB interfaces, call [usbManager.requestRight](#usbmanagerrequestright) to request the device access permission, and call [usbManager.connectDevice](#usbmanagerconnectdevice) to obtain **devicepipe** as an input parameter. 267 268**System capability**: SystemCapability.USB.USBManager 269 270**Parameters** 271 272| Name| Type| Mandatory| Description| 273| -------- | -------- | -------- | -------- | 274| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe, which is used to determine the bus number and device address. You need to call **connectDevice** to obtain its value.| 275| iface | [USBInterface](#usbinterface) | Yes| USB interface. You can use **getDevices** to obtain device information and identify the USB interface based on its ID.| 276| force | boolean | No| Whether to forcibly claim the USB interface. Whether to forcibly claim a USB interface. The default value is **false**, which means not to forcibly claim a USB interface. You can set the value as required.| 277 278**Error codes** 279 280For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 281 282| ID| Error Message | 283| -------- | ------------------------------------------------------------ | 284| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 285 286**Return value** 287 288| Type| Description| 289| -------- | -------- | 290| number | Returns **0** if the USB interface is successfully claimed; returns an error code otherwise.| 291 292**Example** 293 294```ts 295let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 296if (devicesList.length == 0) { 297 console.log(`device list is empty`); 298} 299 300let device: usbManager.USBDevice = devicesList[0]; 301usbManager.requestRight(device.name); 302let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 303let interfaces: usbManager.USBInterface = device.configs[0].interfaces[0]; 304let ret: number= usbManager.claimInterface(devicepipe, interfaces); 305console.log(`claimInterface = ${ret}`); 306``` 307 308## usbManager.releaseInterface 309 310releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number 311 312Releases a USB interface. 313 314Before you do this, ensure that you have claimed the interface by calling [usbManager.claimInterface](#usbmanagerclaiminterface). 315 316**System capability**: SystemCapability.USB.USBManager 317 318**Parameters** 319 320| Name| Type| Mandatory| Description| 321| -------- | -------- | -------- | -------- | 322| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe, which is used to determine the bus number and device address. You need to call **connectDevice** to obtain its value.| 323| iface | [USBInterface](#usbinterface) | Yes| USB interface. You can use **getDevices** to obtain device information and identify the USB interface based on its ID.| 324 325**Error codes** 326 327For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 328 329| ID| Error Message | 330| -------- | ------------------------------------------------------------ | 331| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified.2.Incorrect parameter types. | 332 333**Return value** 334 335| Type| Description| 336| -------- | -------- | 337| number | Returns **0** if the USB interface is successfully released; returns an error code otherwise.| 338 339**Example** 340 341```ts 342let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 343if (devicesList.length == 0) { 344 console.log(`device list is empty`); 345} 346 347let device: usbManager.USBDevice = devicesList[0]; 348usbManager.requestRight(device.name); 349let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 350let interfaces: usbManager.USBInterface = device.configs[0].interfaces[0]; 351let ret: number = usbManager.claimInterface(devicepipe, interfaces); 352ret = usbManager.releaseInterface(devicepipe, interfaces); 353console.log(`releaseInterface = ${ret}`); 354``` 355 356## usbManager.setConfiguration 357 358setConfiguration(pipe: USBDevicePipe, config: USBConfiguration): number 359 360Sets the device configuration. 361 362Before you do this, call [usbManager.getDevices](#usbmanagergetdevices) to obtain the USB device list and device configuration, call [usbManager.requestRight](#usbmanagerrequestright) to request the device access permission, and call [usbManager.connectDevice](#usbmanagerconnectdevice) to obtain **devicepipe** as an input parameter. 363 364**System capability**: SystemCapability.USB.USBManager 365 366**Parameters** 367 368| Name| Type| Mandatory| Description| 369| -------- | -------- | -------- | -------- | 370| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe, which is used to determine the bus number and device address. You need to call **connectDevice** to obtain its value.| 371| config | [USBConfiguration](#usbconfiguration) | Yes| USB configuration. You can use **getDevices** to obtain device information and identify the USB configuration based on the ID.| 372 373**Error codes** 374 375For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 376 377| ID| Error Message | 378| -------- | ------------------------------------------------------------ | 379| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 380 381**Return value** 382 383| Type| Description| 384| -------- | -------- | 385| number | Returns **0** if the USB configuration is successfully set; returns an error code otherwise.| 386 387**Example** 388 389```ts 390let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 391if (devicesList.length == 0) { 392 console.log(`device list is empty`); 393} 394 395let device: usbManager.USBDevice = devicesList[0]; 396usbManager.requestRight(device.name); 397let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 398let config: usbManager.USBConfiguration = device.configs[0]; 399let ret: number= usbManager.setConfiguration(devicepipe, config); 400console.log(`setConfiguration = ${ret}`); 401``` 402 403## usbManager.setInterface 404 405setInterface(pipe: USBDevicePipe, iface: USBInterface): number 406 407Sets a USB interface. 408 409Before you do this, call [usbManager.getDevices](#usbmanagergetdevices) to obtain the USB device list and interfaces, call [usbManager.requestRight](#usbmanagerrequestright) to request the device access permission, call [usbManager.connectDevice](#usbmanagerconnectdevice) to obtain **devicepipe** as an input parameter, and call [usbManager.connectDevice](#usbmanagerconnectdevice) to claim a USB interface. 410 411**System capability**: SystemCapability.USB.USBManager 412 413**Parameters** 414 415| Name| Type| Mandatory| Description| 416| -------- | -------- | -------- | -------- | 417| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe, which is used to determine the bus number and device address. You need to call **connectDevice** to obtain its value.| 418| iface | [USBInterface](#usbinterface) | Yes| USB interface. You can use **getDevices** to obtain device information and identify the USB interface based on its **id** and **alternateSetting**.| 419 420**Error codes** 421 422For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 423 424| ID| Error Message | 425| -------- | ------------------------------------------------------------ | 426| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 427 428**Return value** 429 430| Type| Description| 431| -------- | -------- | 432| number | Returns **0** if the USB interface is successfully set; returns an error code otherwise.| 433 434**Example** 435 436```ts 437let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 438if (devicesList.length == 0) { 439 console.log(`device list is empty`); 440} 441 442let device: usbManager.USBDevice = devicesList[0]; 443usbManager.requestRight(device.name); 444let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 445let interfaces: usbManager.USBInterface = device.configs[0].interfaces[0]; 446let ret: number = usbManager.claimInterface(devicepipe, interfaces); 447ret = usbManager.setInterface(devicepipe, interfaces); 448console.log(`setInterface = ${ret}`); 449``` 450 451## usbManager.getRawDescriptor 452 453getRawDescriptor(pipe: USBDevicePipe): Uint8Array 454 455Obtains the raw USB descriptor. 456 457Before you do this, call [usbManager.getDevices](#usbmanagergetdevices) to obtain the USB device list, call [usbManager.requestRight](#usbmanagerrequestright) to request the device access permission, and call [usbManager.connectDevice](#usbmanagerconnectdevice) to obtain **devicepipe** as an input parameter. 458 459**System capability**: SystemCapability.USB.USBManager 460 461**Parameters** 462 463| Name| Type| Mandatory| Description| 464| -------- | -------- | -------- | -------- | 465| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe, which is used to determine the bus number and device address. You need to call **connectDevice** to obtain its value.| 466 467**Error codes** 468 469For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 470 471| ID| Error Message | 472| -------- | ------------------------------------------------------------ | 473| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 474 475**Return value** 476 477| Type| Description| 478| -------- | -------- | 479| Uint8Array | Returns the raw USB descriptor if the operation is successful; returns **undefined** otherwise.| 480 481**Example** 482 483```ts 484let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 485if (devicesList.length == 0) { 486 console.log(`device list is empty`); 487} 488 489usbManager.requestRight(devicesList[0].name); 490let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 491let ret: Uint8Array = usbManager.getRawDescriptor(devicepipe); 492``` 493 494## usbManager.getFileDescriptor 495 496getFileDescriptor(pipe: USBDevicePipe): number 497 498Obtains the file descriptor. 499 500Before you do this, call [usbManager.getDevices](#usbmanagergetdevices) to obtain the USB device list, call [usbManager.requestRight](#usbmanagerrequestright) to request the device access permission, and call [usbManager.connectDevice](#usbmanagerconnectdevice) to obtain **devicepipe** as an input parameter. 501 502**System capability**: SystemCapability.USB.USBManager 503 504**Parameters** 505 506| Name| Type| Mandatory| Description| 507| -------- | -------- | -------- | -------- | 508| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe, which is used to determine the bus number and device address. You need to call **connectDevice** to obtain its value.| 509 510**Error codes** 511 512For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 513 514| ID| Error Message | 515| -------- | ------------------------------------------------------------ | 516| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 517 518**Return value** 519 520| Type | Description | 521| ------ | -------------------- | 522| number | Returns the file descriptor of the USB device if the operation is successful; returns **-1** otherwise.| 523 524**Example** 525 526```ts 527let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 528if (devicesList.length == 0) { 529 console.log(`device list is empty`); 530} 531 532usbManager.requestRight(devicesList[0].name); 533let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 534let ret: number = usbManager.getFileDescriptor(devicepipe); 535``` 536 537## usbManager.controlTransfer<sup>(deprecated)</sup> 538 539controlTransfer(pipe: USBDevicePipe, controlparam: USBControlParams, timeout ?: number): Promise<number> 540 541Performs control transfer. 542 543Before you do this, call [usbManager.getDevices](#usbmanagergetdevices) to obtain the USB device list, call [usbManager.requestRight](#usbmanagerrequestright) to request the device access permission, and call [usbManager.connectDevice](#usbmanagerconnectdevice) to obtain **devicepipe** as an input parameter. 544 545**NOTE** 546 547> This API is supported since API version 9 and deprecated since API version 12. You are advised to use [usbControlTransfer](#usbmanagerusbcontroltransfer12). 548 549**System capability**: SystemCapability.USB.USBManager 550 551**Parameters** 552 553| Name| Type| Mandatory| Description| 554| -------- | -------- | -------- | -------- | 555| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe. You need to call **connectDevice** to obtain its value.| 556| controlparam | [USBControlParams](#usbcontrolparams) | Yes| Control transfer parameters. Set the parameters as required. For details, see the USB protocol.| 557| timeout | number | No| Timeout period, in ms. This parameter is optional. The default value is **0**. You can set this parameter as required.| 558 559**Error codes** 560 561For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 562 563| ID| Error Message | 564| -------- | ------------------------------------------------------------ | 565| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 566 567**Return value** 568 569| Type| Description| 570| -------- | -------- | 571| Promise<number> | Promise used to return the result, which is the size of the transmitted or received data block if the transfer is successful, or **-1** if an exception has occurred.| 572 573**Example** 574 575```ts 576class PARA { 577 request: number = 0 578 reqType: usbManager.USBControlRequestType = 0 579 target: usbManager.USBRequestTargetType = 0 580 value: number = 0 581 index: number = 0 582 data: Uint8Array = new Uint8Array() 583} 584 585let param: PARA = { 586 request: 0x06, 587 reqType: 0x80, 588 target:0, 589 value: 0x01 << 8 | 0, 590 index: 0, 591 data: new Uint8Array(18) 592}; 593 594let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 595if (devicesList.length == 0) { 596 console.log(`device list is empty`); 597} 598 599usbManager.requestRight(devicesList[0].name); 600let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 601usbManager.controlTransfer(devicepipe, param).then((ret: number) => { 602console.log(`controlTransfer = ${ret}`); 603}) 604``` 605 606## usbManager.usbControlTransfer<sup>12+</sup> 607 608usbControlTransfer(pipe: USBDevicePipe, requestparam: USBDeviceRequestParams, timeout ?: number): Promise<number> 609 610Performs control transfer. 611 612Before you do this, call [usbManager.getDevices](#usbmanagergetdevices) to obtain the USB device list, call [usbManager.requestRight](#usbmanagerrequestright) to request the device access permission, and call [usbManager.connectDevice](#usbmanagerconnectdevice) to obtain **devicepipe** as an input parameter. 613 614**System capability**: SystemCapability.USB.USBManager 615 616**Parameters** 617 618| Name| Type| Mandatory| Description| 619| -------- | -------- | -------- | -------- | 620| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe, which is used to determine the USB device.| 621| requestparam | [USBDeviceRequestParams](#usbdevicerequestparams12) | Yes| Control transfer parameters. Set the parameters as required. For details, see the USB protocol.| 622| timeout | number | No| Timeout duration in ms. This parameter is optional. The default value is **0**, indicating no timeout.| 623 624**Error codes** 625 626For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 627 628| ID| Error Message | 629| -------- | ------------------------------------------------------------ | 630| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified.2.Incorrect parameter types | 631 632**Return value** 633 634| Type| Description| 635| -------- | -------- | 636| Promise<number> | Promise used to return the result, which is the size of the transmitted or received data block if the transfer is successful, or **-1** if an exception has occurred.| 637 638**Example** 639 640```ts 641class PARA { 642 bmRequestType: number = 0 643 bRequest: number = 0 644 wValue: number = 0 645 wIndex: number = 0 646 wLength: number = 0 647 data: Uint8Array = new Uint8Array() 648} 649 650let param: PARA = { 651 bmRequestType: 0x80, 652 bRequest: 0x06, 653 654 wValue:0x01 << 8 | 0, 655 wIndex: 0, 656 wLength: 18, 657 data: new Uint8Array(18) 658}; 659 660let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 661if (devicesList.length == 0) { 662 console.log(`device list is empty`); 663} 664 665usbManager.requestRight(devicesList[0].name); 666let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 667usbManager.usbControlTransfer(devicepipe, param).then((ret: number) => { 668console.log(`usbControlTransfer = ${ret}`); 669}) 670``` 671 672## usbManager.bulkTransfer 673 674bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, timeout ?: number): Promise<number> 675 676Performs bulk transfer. 677 678Before you do this, call [usbManager.getDevices](#usbmanagergetdevices) to obtain the USB device list and endpoints, call [usbManager.requestRight](#usbmanagerrequestright) to request the device access permission, call [usbManager.connectDevice](#usbmanagerconnectdevice) to obtain **devicepipe** as an input parameter, and call [usbManager.claimInterface](#usbmanagerclaiminterface) to claim a USB interface. 679 680**System capability**: SystemCapability.USB.USBManager 681 682**Parameters** 683 684| Name| Type| Mandatory| Description| 685| -------- | -------- | -------- | -------- | 686| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe. You need to call **connectDevice** to obtain its value.| 687| endpoint | [USBEndpoint](#usbendpoint) | Yes| USB endpoint, which is used to determine the USB interface for data transfer. You need to call **getDevices** to obtain the device information list and endpoint. Wherein, **address** is used to determine the endpoint address, **direction** is used to determine the endpoint direction, and **interfaceId** is used to determine the USB interface to which the endpoint belongs. Other parameters are passed transparently.| 688| buffer | Uint8Array | Yes| Buffer used to write or read data.| 689| timeout | number | No| Timeout period, in ms. This parameter is optional. The default value is **0**. You can set this parameter as required.| 690 691**Error codes** 692 693For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 694 695| ID| Error Message | 696| -------- | ------------------------------------------------------------ | 697| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 698 699**Return value** 700 701| Type| Description| 702| -------- | -------- | 703| Promise<number> | Promise used to return the result, which is the size of the transmitted or received data block if the transfer is successful, or **-1** if an exception has occurred.| 704 705**Example** 706 707```ts 708// Call usbManager.getDevices to obtain a data set. Then, obtain a USB device and its access permission. 709// Pass the obtained USB device as a parameter to usbManager.connectDevice. Then, call usbManager.connectDevice to connect the USB device. 710// Call usbManager.claimInterface to claim a USB interface. After that, call usbManager.bulkTransfer to start bulk transfer. 711let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 712if (devicesList.length == 0) { 713 console.log(`device list is empty`); 714} 715 716let device: usbManager.USBDevice = devicesList[0]; 717usbManager.requestRight(device.name); 718 719let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 720for (let i = 0; i < device.configs[0].interfaces.length; i++) { 721 if (device.configs[0].interfaces[i].endpoints[0].attributes == 2) { 722 let endpoint: usbManager.USBEndpoint = device.configs[0].interfaces[i].endpoints[0]; 723 let interfaces: usbManager.USBInterface = device.configs[0].interfaces[i]; 724 let ret: number = usbManager.claimInterface(devicepipe, interfaces); 725 let buffer = new Uint8Array(128); 726 usbManager.bulkTransfer(devicepipe, endpoint, buffer).then((ret: number) => { 727 console.log(`bulkTransfer = ${ret}`); 728 }); 729 } 730} 731``` 732 733## usbManager.closePipe 734 735closePipe(pipe: USBDevicePipe): number 736 737Closes a USB device pipe. 738 739Before you do this, call [usbManager.getDevices](#usbmanagergetdevices) to obtain the USB device list, call [usbManager.requestRight](#usbmanagerrequestright) to request the device access permission, and call [usbManager.connectDevice](#usbmanagerconnectdevice) to obtain **devicepipe** as an input parameter. 740 741**System capability**: SystemCapability.USB.USBManager 742 743**Parameters** 744 745| Name| Type| Mandatory| Description| 746| -------- | -------- | -------- | -------- | 747| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe, which is used to determine the message control channel. You need to call **connectDevice** to obtain its value.| 748 749**Error codes** 750 751For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 752 753| ID| Error Message | 754| -------- | ------------------------------------------------------------ | 755| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 756 757**Return value** 758 759| Type| Description| 760| -------- | -------- | 761| number | Returns **0** if the USB device pipe is closed successfully; returns an error code otherwise.| 762 763**Example** 764 765```ts 766let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 767if (devicesList.length == 0) { 768 console.log(`device list is empty`); 769} 770 771usbManager.requestRight(devicesList[0].name); 772let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 773let ret: number = usbManager.closePipe(devicepipe); 774console.log(`closePipe = ${ret}`); 775``` 776 777## USBEndpoint 778 779Represents the USB endpoint from which data is sent or received. You can obtain the USB endpoint through [USBInterface](#usbinterface). 780 781**System capability**: SystemCapability.USB.USBManager 782 783| Name | Type | Mandatory |Description | 784| ------------- | ------------------------------------------- | ------------- |------------- | 785| address | number | Yes|Endpoint address. | 786| attributes | number | Yes|Endpoint attributes. | 787| interval | number | Yes|Endpoint interval. | 788| maxPacketSize | number | Yes|Maximum size of data packets on the endpoint. | 789| direction | [USBRequestDirection](#usbrequestdirection) | Yes|Endpoint direction. | 790| number | number | Yes|Endpoint number. | 791| type | number | Yes|Endpoint type. | 792| interfaceId | number | Yes|Unique ID of the interface to which the endpoint belongs.| 793 794## USBInterface 795 796Represents a USB interface. One [USBConfiguration](#usbconfiguration) object can contain multiple **USBInterface** instances, each providing a specific function. 797 798**System capability**: SystemCapability.USB.USBManager 799 800| Name | Type | Mandatory |Description | 801| ---------------- | ---------------------------------------- | ------------- |--------------------- | 802| id | number | Yes|Unique ID of the USB interface. | 803| protocol | number | Yes|Interface protocol. | 804| clazz | number | Yes|Device type. | 805| subClass | number | Yes|Device subclass. | 806| alternateSetting | number | Yes|Settings for alternating between descriptors of the same USB interface.| 807| name | string | Yes|Interface name. | 808| endpoints | Array<[USBEndpoint](#usbendpoint)> | Yes|Endpoints that belong to the USB interface. | 809 810## USBConfiguration 811 812Represents the USB configuration. One [USBDevice](#usbdevice) can contain multiple **USBConfig** instances. 813 814**System capability**: SystemCapability.USB.USBManager 815 816| Name | Type | Mandatory |Description | 817| -------------- | ------------------------------------------------ | --------------- |--------------- | 818| id | number | Yes|Unique ID of the USB configuration. | 819| attributes | number | Yes|Configuration attributes. | 820| maxPower | number | Yes|Maximum power consumption, in mA. | 821| name | string | Yes|Configuration name, which can be left empty. | 822| isRemoteWakeup | boolean | Yes|Support for remote wakeup.| 823| isSelfPowered | boolean | Yes| Support for independent power supplies.| 824| interfaces | Array <[USBInterface](#usbinterface)> | Yes|Supported interface attributes. | 825 826## USBDevice 827 828Represents the USB device information. 829 830**System capability**: SystemCapability.USB.USBManager 831 832| Name | Type | Mandatory |Description | 833| ---------------- | ------------------------------------ | ---------- |---------- | 834| busNum | number | Yes|Bus address. | 835| devAddress | number | Yes|Device address. | 836| serial | string | Yes|Sequence number. | 837| name | string | Yes|Device name. | 838| manufacturerName | string | Yes| Device manufacturer. | 839| productName | string | Yes|Product name. | 840| version | string | Yes|Version number. | 841| vendorId | number | Yes|Vendor ID. | 842| productId | number | Yes|Product ID. | 843| clazz | number | Yes|Device class. | 844| subClass | number | Yes|Device subclass. | 845| protocol | number | Yes|Device protocol code. | 846| configs | Array<[USBConfiguration](#usbconfiguration)> | Yes|Device configuration descriptor information.| 847 848## USBDevicePipe 849 850Represents a USB device pipe, which is used to determine a USB device. 851 852**System capability**: SystemCapability.USB.USBManager 853 854| Name | Type | Mandatory |Description | 855| ---------- | ------ | ----- |----- | 856| busNum | number |Yes| Bus address.| 857| devAddress | number |Yes| Device address.| 858 859## USBControlParams 860 861Represents control transfer parameters. 862 863**System capability**: SystemCapability.USB.USBManager 864 865| Name | Type | Mandatory |Description | 866| ------- | ----------------------------------------------- | ---------------- |---------------- | 867| request | number | Yes |Request type. | 868| target | [USBRequestTargetType](#usbrequesttargettype) | Yes |Request target type. | 869| reqType | [USBControlRequestType](#usbcontrolrequesttype) | Yes |Control request type. | 870| value | number | Yes |Request parameter value. | 871| index | number | Yes |Index of the request parameter value.| 872| data | Uint8Array | Yes |Buffer for writing or reading data. | 873 874## USBDeviceRequestParams<sup>12+</sup> 875 876Represents control transfer parameters. 877 878**System capability**: SystemCapability.USB.USBManager 879 880| Name | Type | Mandatory |Description | 881| ------- | ----------------------------------------------- | ---------------- |---------------- | 882| bmRequestType | number | Yes |Control request type. | 883| bRequest | number | Yes |Request type. | 884| wValue | number | Yes |Request parameter value. | 885| wIndex | number | Yes |Index of the request parameter value. | 886| wLength | number | Yes |Length of the requested data.| 887| data | Uint8Array | Yes |Buffer for writing or reading data. | 888 889## USBRequestTargetType 890 891Enumerates request target types. 892 893**System capability**: SystemCapability.USB.USBManager 894 895| Name | Value | Description | 896| ---------------------------- | ---- | ------ | 897| USB_REQUEST_TARGET_DEVICE | 0 | Device.| 898| USB_REQUEST_TARGET_INTERFACE | 1 | Interface.| 899| USB_REQUEST_TARGET_ENDPOINT | 2 | Endpoint.| 900| USB_REQUEST_TARGET_OTHER | 3 | Other.| 901 902## USBControlRequestType 903 904Enumerates control request types. 905 906**System capability**: SystemCapability.USB.USBManager 907 908| Name | Value | Description | 909| ------------------------- | ---- | ------ | 910| USB_REQUEST_TYPE_STANDARD | 0 | Standard.| 911| USB_REQUEST_TYPE_CLASS | 1 | Class. | 912| USB_REQUEST_TYPE_VENDOR | 2 | Vendor.| 913 914## USBRequestDirection 915 916Enumerates request directions. 917 918**System capability**: SystemCapability.USB.USBManager 919 920| Name | Value | Description | 921| --------------------------- | ---- | ------------------------ | 922| USB_REQUEST_DIR_TO_DEVICE | 0 | Request for writing data from the host to the device.| 923| USB_REQUEST_DIR_FROM_DEVICE | 0x80 | Request for reading data from the device to the host.| 924