1# @ohos.usbManager (USB Manager) 2 3<!--Kit: Basic Services Kit--> 4<!--Subsystem: USB--> 5<!--Owner: @hwymlgitcode--> 6<!--Designer: @w00373942--> 7<!--Tester: @dong-dongzhen--> 8<!--Adviser: @w_Machine_cc--> 9 10The **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. 11 12> **NOTE** 13> 14> 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. 15 16## Modules to Import 17 18```ts 19import { usbManager } from '@kit.BasicServicesKit'; 20``` 21 22## How to Use 23 24Perform the following steps when using the APIs with the [USBDevicePipe](#usbdevicepipe) parameter: 25 26**Before use:** 27 281. Call [usbManager.getDevices](#usbmanagergetdevices) to obtain the list of USB devices. 29 302. Call [usbManager.requestRight](#usbmanagerrequestright) to request the temporary device access permission. 31 323. Call [usbManager.connectDevice](#usbmanagerconnectdevice) to obtain **USBDevicePipe** as an input parameter. 33 34**After use:** 35 36Call [usbManager.closePipe](#usbmanagerclosepipe) to close a USB device pipe. 37 38## usbManager.getDevices 39 40getDevices(): Array<Readonly<USBDevice>> 41 42Obtains the list of USB devices connected to the host. 43 44> **NOTE** 45> 46> If the USB service is running properly but no device is connected, an empty list is returned, which indicates that the call is successful but no USB device is connected. 47> 48> This API returns **undefined** in the following scenarios: the USB host mode is not enabled, the USB service is not correctly initialized, the USB service fails to be connected (for example, the developer mode is disabled), the permission is insufficient, or other system errors occur. Note that you should perform an empty check for the return value. 49 50**System capability**: SystemCapability.USB.USBManager 51 52**Return value** 53 54| Type | Description | 55| ---------------------------------------------------- | ------- | 56| Array<Readonly<[USBDevice](#usbdevice)>> | USB device list.| 57 58**Error codes** 59 60For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 61 62| ID| Error Message | 63| -------- | ------------------------- | 64| 801 | Capability not supported. | 65 66**Example** 67 68```ts 69let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 70console.log(`devicesList = ${devicesList}`); 71/* 72The following is a simple example of the data structure for devicesList: 73[ 74 { 75 name: "1-1", 76 serial: "", 77 manufacturerName: "", 78 productName: "", 79 version: "", 80 vendorId: 7531, 81 productId: 2, 82 clazz: 9, 83 subClass: 0, 84 protocol: 1, 85 devAddress: 1, 86 busNum: 1, 87 configs: [ 88 { 89 id: 1, 90 attributes: 224, 91 isRemoteWakeup: true, 92 isSelfPowered: true, 93 maxPower: 0, 94 name: "1-1", 95 interfaces: [ 96 { 97 id: 0, 98 protocol: 0, 99 clazz: 9, 100 subClass: 0, 101 alternateSetting: 0, 102 name: "1-1", 103 endpoints: [ 104 { 105 address: 129, 106 attributes: 3, 107 interval: 12, 108 maxPacketSize: 4, 109 direction: 128, 110 number: 1, 111 type: 3, 112 interfaceId: 0, 113 }, 114 ], 115 }, 116 ], 117 }, 118 ], 119 }, 120] 121*/ 122``` 123 124## usbManager.connectDevice 125 126connectDevice(device: USBDevice): Readonly<USBDevicePipe> 127 128Connects to the USB device based on the device information returned by **getDevices()**. If the USB service is abnormal, **undefined** may be returned. Check whether the return value of the API is empty. 129 1301. Call [usbManager.getDevices](#usbmanagergetdevices) to obtain the USB device list. 1312. Call [usbManager.requestRight](#usbmanagerrequestright) to request the permission to use the device. 132 133**System capability**: SystemCapability.USB.USBManager 134 135**Parameters** 136 137| Name| Type| Mandatory| Description| 138| -------- | -------- | -------- | ---------------- | 139| 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.| 140 141**Return value** 142 143| Type| Description| 144| -------- | -------- | 145| Readonly<[USBDevicePipe](#usbdevicepipe)> | USB device pipe for data transfer.| 146 147**Error codes** 148 149For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 150 151| ID| Error Message | 152| -------- | ------------------------------------------------------------ | 153| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 154| 801 | Capability not supported. | 155| 14400001 | Access right denied. Call requestRight to get the USBDevicePipe access right first.| 156 157**Example** 158 159```ts 160let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 161if (devicesList.length == 0) { 162 console.log(`device list is empty`); 163} 164 165let device: usbManager.USBDevice = devicesList[0]; 166usbManager.requestRight(device.name); 167let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 168console.log(`devicepipe = ${devicepipe}`); 169``` 170 171## usbManager.hasRight 172 173hasRight(deviceName: string): boolean 174 175Checks whether the application has the permission to access the device. 176 177Checks 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. 178 179**System capability**: SystemCapability.USB.USBManager 180 181**Parameters** 182 183| Name| Type| Mandatory| Description| 184| -------- | -------- | -------- | -------- | 185| deviceName | string | Yes| Device name, which can be obtained from the device list returned by **getDevices**.| 186 187**Return value** 188 189| Type| Description| 190| -------- | -------- | 191| boolean | Returns **true** if the application has the permission to access the device; returns **false** otherwise. If this API fails to be called, the following error codes are returned:<br>- 88080385: This API is not initialized.<br>- 88080492: An error occurs when the service data packet is written.<br>- 88080493: An error occurs when the service data packet is read.| 192 193**Error codes** 194 195For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 196 197| ID| Error Message | 198| -------- | ------------------------------------------------------------ | 199| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 200| 801 | Capability not supported. | 201 202**Example** 203 204```ts 205let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 206if (devicesList.length == 0) { 207 console.log(`device list is empty`); 208} 209 210let device: usbManager.USBDevice = devicesList[0]; 211usbManager.requestRight(device.name); 212let right: boolean = usbManager.hasRight(device.name); 213console.log(`${right}`); 214``` 215 216## usbManager.requestRight 217 218requestRight(deviceName: string): Promise<boolean> 219 220Requests 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. 221 222**System capability**: SystemCapability.USB.USBManager 223 224**Parameters** 225 226| Name| Type| Mandatory| Description| 227| -------- | -------- | -------- | -------- | 228| deviceName | string | Yes| Device name, which can be obtained from the device list returned by **getDevices**.| 229 230**Return value** 231 232| Type| Description| 233| -------- | -------- | 234| 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. If this API fails to be called, the following error codes are returned:<br>- 88080385: This API is not initialized.<br>- 88080392: An error occurs when the API data packet is written.<br>- 88080393: An error occurs when the API data packet is read.<br>- 88080492: An error occurs when the service data packet is written.<br>- 88080493: An error occurs when the service data packet is read.<br>- 88080497: An error occurs when the internal logic of the service is executed.| 235 236**Error codes** 237 238For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 239 240| ID| Error Message | 241| -------- | ------------------------------------------------------------ | 242| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 243| 801 | Capability not supported. | 244 245**Example** 246 247```ts 248let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 249if (devicesList.length == 0) { 250 console.log(`device list is empty`); 251} 252 253let device: usbManager.USBDevice = devicesList[0]; 254usbManager.requestRight(device.name).then(ret => { 255 console.log(`requestRight = ${ret}`); 256}); 257``` 258 259## usbManager.removeRight 260 261removeRight(deviceName: string): boolean 262 263Removes 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. 264 265**System capability**: SystemCapability.USB.USBManager 266 267**Parameters** 268 269| Name| Type| Mandatory| Description| 270| -------- | -------- | -------- | -------- | 271| deviceName | string | Yes| Device name, which can be obtained from the device list returned by **getDevices**.| 272 273**Return value** 274 275| Type| Description| 276| -------- | -------- | 277| boolean | Permission removal result. The value **true** indicates that the access permission is removed successfully; and the value **false** indicates the opposite. If this API fails to be called, the following error codes are returned:<br>- 88080382: An invalid value or parameter occurs during the API operation.<br>- 88080385: This API is not initialized.<br>- 88080392: An error occurs when the API data packet is written.<br>- 88080393: An error occurs when the API data packet is read.<br>- 88080492: An error occurs when the service data packet is written.<br>- 88080493: An error occurs when the service data packet is read.<br>- 88080497: An error occurs when the internal logic of the service is executed.| 278 279**Error codes** 280 281For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 282 283| ID| Error Message | 284| -------- | ------------------------------------------------------------ | 285| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 286| 801 | Capability not supported. | 287 288**Example** 289 290```ts 291let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 292if (devicesList.length == 0) { 293 console.log(`device list is empty`); 294} 295 296let device: usbManager.USBDevice = devicesList[0]; 297if (usbManager.removeRight(device.name)) { 298 console.log(`Succeed in removing right`); 299} 300``` 301 302## usbManager.claimInterface 303 304claimInterface(pipe: USBDevicePipe, iface: USBInterface, force ?: boolean): number 305 306Claims a USB device interface. 307 308> **NOTE** 309> 310> In USB programming, **claimInterface** is a common operation, which indicates that an application requests the operating system to release a USB interface from the kernel driver and hand over the USB interface to a user space program for control.<br> 311> All the **claim** communication interfaces used below refer to the claim interface operations. 312 313**System capability**: SystemCapability.USB.USBManager 314 315**Parameters** 316 317| Name| Type| Mandatory| Description| 318| -------- | -------- | -------- | -------- | 319| 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.| 320| iface | [USBInterface](#usbinterface) | Yes| USB interface. You can use **getDevices** to obtain device information and identify the USB interface based on its ID.| 321| force | boolean | No| 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.| 322 323**Return value** 324 325| Type| Description| 326| -------- | -------- | 327| number | Returns **0** if the **claim** interface is called successfully; returns an error code otherwise. The error codes are as follows:<br>- 63: The data exceeds the expected maximum volume.<br>- 88080385: This API is not initialized.<br>- 88080482: An invalid value or parameter occurs during the service.<br>- 88080484: No permission.<br>- 88080492: An error occurs when the service data packet is written.<br>- 88080493: An error occurs when the service data packet is read.<br>- 88080497: An error occurs when the internal logic of the service is executed.<br>- -1: The underlying interface fails to be called.| 328 329**Error codes** 330 331For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 332 333| ID| Error Message | 334| -------- | ------------------------------------------------------------ | 335| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 336| 801 | Capability not supported. | 337 338**Example** 339 340```ts 341let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 342if (devicesList.length == 0) { 343 console.log(`device list is empty`); 344} 345 346let device: usbManager.USBDevice = devicesList[0]; 347usbManager.requestRight(device.name); 348let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 349let interfaces: usbManager.USBInterface = device.configs[0].interfaces[0]; 350let ret: number= usbManager.claimInterface(devicepipe, interfaces); 351console.log(`claimInterface = ${ret}`); 352``` 353 354## usbManager.releaseInterface 355 356releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number 357 358Releases the claimed communication interface. 359 360> **NOTE** 361> 362> Before calling this API, call the [usbManager.claimInterface](#usbmanagerclaiminterface) API to claim a communication interface. 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| iface | [USBInterface](#usbinterface) | Yes| USB interface. You can use **getDevices** to obtain device information and identify the USB interface based on its ID.| 372 373**Return value** 374 375| Type| Description| 376| -------- | -------- | 377| number | Returns **0** if the USB interface is successfully released; returns an error code otherwise. The error codes are as follows:<br>- 63: The data exceeds the expected maximum volume.<br>- 88080381: Invalid interface operation.<br>- 88080385: This API is not initialized.<br>- 88080482: An invalid value or parameter occurs during the service.<br>- 88080484: No permission.<br>- 88080492: An error occurs when the service data packet is written.<br>- 88080493: An error occurs when the service data packet is read.<br>- 88080497: An error occurs when the internal logic of the service is executed.<br>- -1: The underlying interface fails to be called.| 378 379**Error codes** 380 381For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 382 383| ID| Error Message | 384| -------- | ------------------------------------------------------------ | 385| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified.2.Incorrect parameter types. | 386| 801 | Capability not supported. | 387 388**Example** 389 390```ts 391let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 392if (devicesList.length == 0) { 393 console.log(`device list is empty`); 394} 395 396let device: usbManager.USBDevice = devicesList[0]; 397usbManager.requestRight(device.name); 398let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 399let interfaces: usbManager.USBInterface = device.configs[0].interfaces[0]; 400let ret: number = usbManager.claimInterface(devicepipe, interfaces); 401ret = usbManager.releaseInterface(devicepipe, interfaces); 402console.log(`releaseInterface = ${ret}`); 403``` 404 405## usbManager.setConfiguration 406 407setConfiguration(pipe: USBDevicePipe, config: USBConfiguration): number 408 409Sets the device configuration. 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| config | [USBConfiguration](#usbconfiguration) | Yes| USB configuration. You can use **getDevices** to obtain device information and identify the USB configuration based on the ID.| 419 420**Return value** 421 422| Type| Description| 423| -------- | -------- | 424| number | Returns **0** if the USB configuration is successfully set; returns an error code otherwise. The error codes are as follows:<br>- 63: The data exceeds the expected maximum volume.<br>- 88080385: This API is not initialized.<br>- 88080482: An invalid value or parameter occurs during the service.<br>- 88080484: No permission.<br>- 88080492: An error occurs when the service data packet is written.<br>- 88080493: An error occurs when the service data packet is read.<br>- 88080497: An error occurs when the internal logic of the service is executed.<br>- -1: The underlying interface fails to be called.<br>- -17: I/O failure.| 425 426**Error codes** 427 428For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 429 430| ID| Error Message | 431| -------- | ------------------------------------------------------------ | 432| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 433| 801 | Capability not supported. | 434 435**Example** 436 437```ts 438let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 439if (devicesList.length == 0) { 440 console.log(`device list is empty`); 441} 442 443let device: usbManager.USBDevice = devicesList[0]; 444usbManager.requestRight(device.name); 445let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 446let config: usbManager.USBConfiguration = device.configs[0]; 447let ret: number= usbManager.setConfiguration(devicepipe, config); 448console.log(`setConfiguration = ${ret}`); 449``` 450 451## usbManager.setInterface 452 453setInterface(pipe: USBDevicePipe, iface: USBInterface): number 454 455Sets a USB interface. 456 457> **NOTE** 458> 459> A USB interface may have multiple selection modes and supports dynamic switching. It is used to reset the endpoint to match the transmission type during data transmission. 460> 461> Before calling this API, call the [usbManager.claimInterface](#usbmanagerclaiminterface) API to claim a communication interface. 462 463**System capability**: SystemCapability.USB.USBManager 464 465**Parameters** 466 467| Name| Type| Mandatory| Description| 468| -------- | -------- | -------- | -------- | 469| 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.| 470| 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**.| 471 472**Return value** 473 474| Type| Description| 475| -------- | -------- | 476| number | Returns **0** if the USB interface is successfully set; returns an error code otherwise. The error codes are as follows:<br>- 63: The data exceeds the expected maximum volume.<br>- 88080385: This API is not initialized.<br>- 88080482: An invalid value or parameter occurs during the service.<br>- 88080484: No permission.<br>- 88080492: An error occurs when the service data packet is written.<br>- 88080493: An error occurs when the service data packet is read.<br>- 88080497: An error occurs when the internal logic of the service is executed.<br>- -1: The underlying interface fails to be called.| 477 478**Error codes** 479 480For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 481 482| ID| Error Message | 483| -------- | ------------------------------------------------------------ | 484| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 485| 801 | Capability not supported. | 486 487**Example** 488 489```ts 490let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 491if (devicesList.length == 0) { 492 console.log(`device list is empty`); 493} 494 495let device: usbManager.USBDevice = devicesList[0]; 496usbManager.requestRight(device.name); 497let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 498let interfaces: usbManager.USBInterface = device.configs[0].interfaces[0]; 499let ret: number = usbManager.claimInterface(devicepipe, interfaces); 500ret = usbManager.setInterface(devicepipe, interfaces); 501console.log(`setInterface = ${ret}`); 502``` 503 504## usbManager.getRawDescriptor 505 506getRawDescriptor(pipe: USBDevicePipe): Uint8Array 507 508Obtains the raw USB descriptor. If the USB service is abnormal, **undefined** may be returned. Check whether the return value of the API is empty. 509 510**System capability**: SystemCapability.USB.USBManager 511 512**Parameters** 513 514| Name| Type| Mandatory| Description| 515| -------- | -------- | -------- | -------- | 516| 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.| 517 518**Return value** 519 520| Type| Description| 521| -------- | -------- | 522| Uint8Array | Returns the raw USB descriptor if the operation is successful; returns **undefined** otherwise.| 523 524**Error codes** 525 526For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 527 528| ID| Error Message | 529| -------- | ------------------------------------------------------------ | 530| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 531| 801 | Capability not supported. | 532 533**Example** 534 535```ts 536let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 537if (devicesList.length == 0) { 538 console.log(`device list is empty`); 539} 540 541usbManager.requestRight(devicesList[0].name); 542let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 543let ret: Uint8Array = usbManager.getRawDescriptor(devicepipe); 544``` 545 546## usbManager.getFileDescriptor 547 548getFileDescriptor(pipe: USBDevicePipe): number 549 550Obtains the file descriptor. 551 552**System capability**: SystemCapability.USB.USBManager 553 554**Parameters** 555 556| Name| Type| Mandatory| Description| 557| -------- | -------- | -------- | -------- | 558| 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.| 559 560**Return value** 561 562| Type | Description | 563| ------ | -------------------- | 564| number | Returns the file descriptor corresponding to the device if this API is successfully called; returns an error code otherwise. The error codes are as follows:<br>- 63: The data exceeds the expected maximum volume.<br>- 88080385: This API is not initialized.<br>- 88080482: An invalid value or parameter occurs during the service.<br>- 88080484: No permission.<br>- 88080492: An error occurs when the service data packet is written.<br>- 88080493: An error occurs when the service data packet is read.<br>- 88080497: An error occurs when the internal logic of the service is executed.<br>- -1: The underlying interface fails to be called.| 565 566**Error codes** 567 568For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 569 570| ID| Error Message | 571| -------- | ------------------------------------------------------------ | 572| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 573| 801 | Capability not supported. | 574 575**Example** 576 577```ts 578let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 579if (devicesList.length == 0) { 580 console.log(`device list is empty`); 581} 582 583usbManager.requestRight(devicesList[0].name); 584let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 585let ret: number = usbManager.getFileDescriptor(devicepipe); 586console.log(`getFileDescriptor = ${ret}`); 587let closeRet: number = usbManager.closePipe(devicepipe); 588console.log(`closePipe = ${closeRet}`); 589``` 590 591## usbManager.controlTransfer<sup>(deprecated)</sup> 592 593controlTransfer(pipe: USBDevicePipe, controlparam: USBControlParams, timeout ?: number): Promise<number> 594 595Performs control transfer. 596 597> **NOTE** 598> 599> This API is supported since API version 9 and deprecated since API version 12. You are advised to use [usbControlTransfer](#usbmanagerusbcontroltransfer12). 600 601**System capability**: SystemCapability.USB.USBManager 602 603**Parameters** 604 605| Name| Type| Mandatory| Description| 606| -------- | -------- | -------- | -------- | 607| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe. You need to call **connectDevice** to obtain its value.| 608| controlparam | [USBControlParams](#usbcontrolparamsdeprecated) | Yes| Control transfer parameters. Set the parameters as required. For details, see the USB protocol.| 609| timeout | number | No| (Optional) Timeout duration, in ms. The default value is **0**. You can set this parameter as required.| 610 611**Return value** 612 613| Type| Description| 614| -------- | -------- | 615| Promise<number> | Promise used to return the result, which is the size of the transferred or received data block if the transfer is successful. If the API call fails, the following error codes are returned:<br>- 88080385: This API is not initialized.<br>- 88080482: An invalid value or parameter occurs during the service.<br>- 88080484: No permission.<br>- 88080492: An error occurs when the service data packet is written.<br>- 88080493: An error occurs when the service data packet is read.<br>- 88080497: An error occurs when the internal logic of the service is executed.<br>- -1: The underlying interface fails to be called.| 616 617**Error codes** 618 619For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 620 621| ID| Error Message | 622| -------- | ------------------------------------------------------------ | 623| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 624 625**Example** 626 627```ts 628class PARA { 629 request: number = 0 630 reqType: usbManager.USBControlRequestType = 0 631 target: usbManager.USBRequestTargetType = 0 632 value: number = 0 633 index: number = 0 634 data: Uint8Array = new Uint8Array() 635} 636 637let param: PARA = { 638 request: 0x06, 639 reqType: 0x80, 640 target:0, 641 value: 0x01 << 8 | 0, 642 index: 0, 643 data: new Uint8Array(18) 644}; 645 646let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 647if (devicesList.length == 0) { 648 console.log(`device list is empty`); 649} 650 651usbManager.requestRight(devicesList[0].name); 652let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 653usbManager.controlTransfer(devicepipe, param).then((ret: number) => { 654console.log(`controlTransfer = ${ret}`); 655}) 656``` 657 658## usbManager.usbControlTransfer<sup>12+</sup> 659 660usbControlTransfer(pipe: USBDevicePipe, requestparam: USBDeviceRequestParams, timeout ?: number): Promise<number> 661 662Performs control transfer. 663 664**System capability**: SystemCapability.USB.USBManager 665 666**Parameters** 667 668| Name| Type| Mandatory| Description| 669| -------- | -------- | -------- | -------- | 670| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe, which is used to determine the USB device.| 671| requestparam | [USBDeviceRequestParams](#usbdevicerequestparams12) | Yes| Control transfer parameters. Set the parameters as required. For details, see the USB protocol.| 672| timeout | number | No| (Optional) Timeout duration, in ms. The default value is **0**, indicating no timeout.| 673 674**Return value** 675 676| Type| Description| 677| -------- | -------- | 678| Promise<number> | Promise used to return the result, which is the size of the transferred or received data block if the transfer is successful. If the API call fails, the following error codes are returned:<br>- 88080385: This API is not initialized.<br>- 88080482: An invalid value or parameter occurs during the service.<br>- 88080484: No permission.<br>- 88080492: An error occurs when the service data packet is written.<br>- 88080493: An error occurs when the service data packet is read.<br>- 88080497: An error occurs when the internal logic of the service is executed.<br>- -1: The underlying interface fails to be called.| 679 680**Error codes** 681 682For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 683 684| ID| Error Message | 685| -------- | ------------------------------------------------------------ | 686| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified.2.Incorrect parameter types. | 687| 801 | Capability not supported. | 688 689**Example** 690 691```ts 692class PARA { 693 bmRequestType: number = 0 694 bRequest: number = 0 695 wValue: number = 0 696 wIndex: number = 0 697 wLength: number = 0 698 data: Uint8Array = new Uint8Array() 699} 700 701let param: PARA = { 702 bmRequestType: 0x80, 703 bRequest: 0x06, 704 705 wValue:0x01 << 8 | 0, 706 wIndex: 0, 707 wLength: 18, 708 data: new Uint8Array(18) 709}; 710 711let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 712if (devicesList.length == 0) { 713 console.log(`device list is empty`); 714} 715 716usbManager.requestRight(devicesList[0].name); 717let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 718usbManager.usbControlTransfer(devicepipe, param).then((ret: number) => { 719console.log(`usbControlTransfer = ${ret}`); 720}) 721``` 722 723## usbManager.bulkTransfer 724 725bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, timeout ?: number): Promise<number> 726 727Performs bulk transfer. 728 729> **NOTE** 730> 731> The total amount of data (including **pipe**, **endpoint**, **buffer**, and **timeout**) transferred in bulk must be less than 200 KB. 732> 733> Before calling this API, the call the [usbManager.claimInterface](#usbmanagerclaiminterface) API to claim a communication interface. 734 735**System capability**: SystemCapability.USB.USBManager 736 737**Parameters** 738 739| Name| Type| Mandatory| Description| 740| -------- | -------- | -------- | -------- | 741| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe. You need to call **connectDevice** to obtain its value.| 742| 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.| 743| buffer | Uint8Array | Yes| Buffer used to write or read data.| 744| timeout | number | No| (Optional) Timeout duration, in ms. The default value is **0**. You can set this parameter as required.| 745 746**Return value** 747 748| Type| Description| 749| -------- | -------- | 750| Promise<number> | Promise used to return the result, which is the size of the transferred or received data block if the transfer is successful. If the API call fails, the following error codes are returned:<br>- 63: The data exceeds the expected maximum volume.<br>- 88080385: This API is not initialized.<br>- 88080482: An invalid value or parameter occurs during the service.<br>- 88080484: No permission.<br>- 88080492: An error occurs when the service data packet is written.<br>- 88080493: An error occurs when the service data packet is read.<br>- 88080497: An error occurs when the internal logic of the service is executed.<br>- -1: The underlying interface fails to be called.<br>- -3: The parameter is invalid.<br>- -202: The device is not found.| 751 752**Error codes** 753 754For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 755 756| ID| Error Message | 757| -------- | ------------------------------------------------------------ | 758| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 759| 801 | Capability not supported. | 760 761**Example** 762 763> **NOTE** 764> 765> The following sample code is only a basic process for calling the **bulkTransfer** API. In actual calling, you must comply with the device-related protocols to ensure correct data transfer and device compatibility. 766 767```ts 768// Call usbManager.getDevices to obtain a data set. Then, obtain a USB device and its access permission. 769// Pass the obtained USB device as a parameter to usbManager.connectDevice. Then, call usbManager.connectDevice to connect the USB device. 770// Call usbManager.claimInterface to claim a USB interface. After that, call usbManager.bulkTransfer to start bulk transfer. 771let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 772if (devicesList.length == 0) { 773 console.log(`device list is empty`); 774} 775 776let device: usbManager.USBDevice = devicesList[0]; 777usbManager.requestRight(device.name); 778 779let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 780for (let i = 0; i < device.configs[0].interfaces.length; i++) { 781 if (device.configs[0].interfaces[i].endpoints[0].attributes == 2) { 782 let endpoint: usbManager.USBEndpoint = device.configs[0].interfaces[i].endpoints[0]; 783 let interfaces: usbManager.USBInterface = device.configs[0].interfaces[i]; 784 let ret: number = usbManager.claimInterface(devicepipe, interfaces); 785 let buffer = new Uint8Array(128); 786 usbManager.bulkTransfer(devicepipe, endpoint, buffer).then((ret: number) => { 787 console.log(`bulkTransfer = ${ret}`); 788 }); 789 } 790} 791``` 792 793## usbManager.usbSubmitTransfer<sup>18+</sup> 794 795usbSubmitTransfer(transfer: UsbDataTransferParams): void 796 797Requests a USB data transfer. 798 799> **NOTE** 800> 801> This API uses an asynchronous callback to return the result. 802> 803> Before calling this API, call the [usbManager.claimInterface](#usbmanagerclaiminterface) API to claim a communication interface. 804 805**System capability**: SystemCapability.USB.USBManager 806 807**Parameters** 808 809| Name| Type| Mandatory| Description| 810| -------- | -------- | -------- | -------- | 811| transfer | [UsbDataTransferParams](#usbdatatransferparams18) | Yes| As a USB data transfer interface, it is required for a client to initiate a transfer request.| 812 813**Error codes** 814 815For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 816 817| ID| Error Message | 818| -------- | ------------------------------------------------------------ | 819| 801 | Capability not supported. | 820| 14400001 | Access right denied. Call requestRight to get the USBDevicePipe access right first. | 821| 14400007 | Resource busy. Possible causes: 1. The transfer has already been submitted. 2. The interface is claimed by another program or driver.| 822| 14400008 | No such device (it may have been disconnected). | 823| 14400009 | Insufficient memory. Possible causes: 1. Memory allocation failed. | 824| 14400012 | Transmission I/O error. | 825 826**Example** 827 828> **NOTE** 829> 830> The following sample code shows the basic process for calling the **usbSubmitTransfer** API and it needs to be executed in a specific method. In actual calling, you must comply with the device-related protocols to ensure correct data transfer and device compatibility. 831 832<!--code_no_check--> 833```ts 834// Call usbManager.getDevices to obtain a data set. Then, obtain a USB device and its access permission. 835// Pass the obtained USB device as a parameter to usbManager.connectDevice. Then, call usbManager.connectDevice to connect the USB device. 836// Call usbManager.claimInterface to claim a USB interface. After that, call usbManager.bulkTransfer to start bulk transfer. 837let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 838if (devicesList.length == 0) { 839 console.log(`device list is empty`); 840 return; 841} 842let device: usbManager.USBDevice = devicesList[0]; 843usbManager.requestRight(device.name); 844let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 845// Obtain the endpoint address. 846let endpoint = device.configs[0].interfaces[0]?.endpoints.find((value) => { 847 return value.direction === 0 && value.type === 2 848}) 849// Obtain the first ID of the device. 850let ret: number = usbManager.claimInterface(devicepipe, device.configs[0].interfaces[0], true); 851 852let transferParams: usbManager.UsbDataTransferParams = { 853 devPipe: devicepipe, 854 flags: usbManager.UsbTransferFlags.USB_TRANSFER_SHORT_NOT_OK, 855 endpoint: 1, 856 type: usbManager.UsbEndpointTransferType.TRANSFER_TYPE_BULK, 857 timeout: 2000, 858 length: 10, 859 callback: () => {}, 860 userData: new Uint8Array(10), 861 buffer: new Uint8Array(10), 862 isoPacketCount: 0, 863}; 864try { 865 transferParams.endpoint=endpoint?.address as number; 866 transferParams.callback=(err, callBackData: usbManager.SubmitTransferCallback)=>{ 867 console.info('callBackData =' +JSON.stringify(callBackData)); 868 } 869 usbManager.usbSubmitTransfer(transferParams); 870 console.info('USB transfer request submitted.'); 871} catch (error) { 872 console.error('USB transfer failed:', error); 873} 874``` 875 876## usbManager.usbCancelTransfer<sup>18+</sup> 877 878usbCancelTransfer(transfer: UsbDataTransferParams): void 879 880Cancels an asynchronous USB data transfer request. 881 882> **NOTE** 883> 884> This API is used to proactively cancel an unfinished USB data transfer request (for example, the one submitted by **usbSubmitTransfer**).<br> 885> Before calling this API, call the [usbManager.claimInterface](#usbmanagerclaiminterface) API to claim a communication interface. 886 887**System capability**: SystemCapability.USB.USBManager 888 889**Parameters** 890 891| Name| Type| Mandatory| Description| 892| -------- | -------- | -------- | -------- | 893| transfer | [UsbDataTransferParams](#usbdatatransferparams18) | Yes| Only **USBDevicePipe** and **endpoint** are required for canceling the transfer.| 894 895**Return value** 896 897| Type| Description| 898| -------- | -------- | 899| <void> | None.| 900 901**Error codes** 902 903For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 904 905| ID| Error Message | 906| -------- | ------------------------------------------------------------ | 907| 801 | Capability not supported. | 908| 14400001 | Access right denied. Call requestRight to get the USBDevicePipe access right first. | 909| 14400008 | No such device (it may have been disconnected). | 910| 14400010 | Other USB error. Possible causes:<br>1.Unrecognized discard error code. | 911| 14400011 | The transfer is not in progress, or is already complete or cancelled.| 912 913**Example** 914 915> **NOTE** 916> 917> The following sample code shows the basic process for calling the **usbCancelTransfer** API and it needs to be executed in a specific method. In actual calling, you must comply with the device-related protocols to ensure correct data transfer and device compatibility. 918 919<!--code_no_check--> 920```ts 921// Call usbManager.getDevices to obtain a data set. Then, obtain a USB device and its access permission. 922// Pass the obtained USB device as a parameter to usbManager.connectDevice. Then, call usbManager.connectDevice to connect the USB device. 923// Call usbManager.claimInterface to claim a USB interface. After that, call usbManager.bulkTransfer to start bulk transfer. 924let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 925if (devicesList.length == 0) { 926 console.log(`device list is empty`); 927 return; 928} 929let device: usbManager.USBDevice = devicesList[0]; 930usbManager.requestRight(device.name); 931let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(device); 932// Obtain the endpoint address. 933let endpoint = device.configs[0].interfaces[0]?.endpoints.find((value) => { 934 return value.direction === 0 && value.type === 2 935}) 936// Obtain the first ID of the device. 937let ret: number = usbManager.claimInterface(devicepipe, device.configs[0].interfaces[0], true); 938let transferParams: usbManager.UsbDataTransferParams = { 939 devPipe: devicepipe, 940 flags: usbManager.UsbTransferFlags.USB_TRANSFER_SHORT_NOT_OK, 941 endpoint: 1, 942 type: usbManager.UsbEndpointTransferType.TRANSFER_TYPE_BULK, 943 timeout: 2000, 944 length: 10, 945 callback: () => {}, 946 userData: new Uint8Array(10), 947 buffer: new Uint8Array(10), 948 isoPacketCount: 0, 949}; 950try { 951 transferParams.endpoint=endpoint?.address as number; 952 transferParams.callback=(err, callBackData: usbManager.SubmitTransferCallback)=>{ 953 console.info('callBackData =' +JSON.stringify(callBackData)); 954 } 955 usbManager.usbSubmitTransfer(transferParams); 956 usbManager.usbCancelTransfer(transferParams); 957 console.info('USB transfer request submitted.'); 958} catch (error) { 959 console.error('USB transfer failed:', error); 960} 961``` 962 963## usbManager.closePipe 964 965closePipe(pipe: USBDevicePipe): number 966 967Closes a USB device pipe. 968 9691. Call [usbManager.getDevices](#usbmanagergetdevices) to obtain the USB device list. 9702. Call [usbManager.requestRight](#usbmanagerrequestright) to request the device access permission. 9713. Call [usbManager.connectDevice](#usbmanagerconnectdevice) to obtain **devicepipe** as an input parameter. 972 973**System capability**: SystemCapability.USB.USBManager 974 975**Parameters** 976 977| Name| Type| Mandatory| Description| 978| -------- | -------- | -------- | -------- | 979| 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.| 980 981**Return value** 982 983| Type| Description| 984| -------- | -------- | 985| number | Returns **0** if the USB device pipe is closed successfully; returns an error code otherwise. The error codes are as follows:<br>- 63: The data exceeds the expected maximum volume.<br>- 88080393: An error occurs when the API data packet is read.<br>- 88080482: An invalid value or parameter occurs during the service.<br>- 88080484: No permission.<br>- 88080493: An error occurs when the service data packet is read.<br>- 88080497: An error occurs when the internal logic of the service is executed.<br>- -1: The underlying interface fails to be called.| 986 987**Error codes** 988 989For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 990 991| ID| Error Message | 992| -------- | ------------------------------------------------------------ | 993| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 994| 801 | Capability not supported. | 995 996**Example** 997 998```ts 999let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 1000if (devicesList.length == 0) { 1001 console.log(`device list is empty`); 1002} 1003 1004usbManager.requestRight(devicesList[0].name); 1005let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 1006let ret: number = usbManager.closePipe(devicepipe); 1007console.log(`closePipe = ${ret}`); 1008``` 1009 1010## usbManager.hasAccessoryRight<sup>14+</sup> 1011 1012hasAccessoryRight(accessory: USBAccessory): boolean 1013 1014Checks whether the application has the permission to access the USB accessory. 1015 1016You need to call [usbManager.getAccessoryList](#usbmanagergetaccessorylist14) to obtain the accessory list and use [USBAccessory](#usbaccessory14) as a parameter. 1017 1018**System capability**: SystemCapability.USB.USBManager 1019 1020**Parameters** 1021 1022| Name | Type | Mandatory| Description | 1023| --------- | ------------ | ---- | ------------------------------------- | 1024| accessory | [USBAccessory](#usbaccessory14) | Yes | USB accessory.| 1025 1026**Return value** 1027 1028| Type | Description | 1029| ------- | ----------------------------- | 1030| boolean | The value **true** indicates that the application has the permission to access the USB accessory; **false** indicates the opposite.| 1031 1032**Error codes** 1033 1034For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 1035 1036| ID| Error Message | 1037| -------- | ------------------------------------------------------------ | 1038| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 1039| 801 | Capability not supported. | 1040| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. | 1041| 14400005 | Database operation exception. | 1042| 14401001 | The target USBAccessory not matched. | 1043 1044**Example** 1045 1046```ts 1047import { hilog } from '@kit.PerformanceAnalysisKit'; 1048try { 1049 let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList() 1050 let flag = usbManager.hasAccessoryRight(accList[0]) 1051 hilog.info(0, 'testTag ui', `hasAccessoryRight success, ret:${flag}`) 1052} catch (error) { 1053 hilog.info(0, 'testTag ui', `hasAccessoryRight error ${error.code}, message is ${error.message}`) 1054} 1055``` 1056 1057## usbManager.requestAccessoryRight<sup>14+</sup> 1058 1059requestAccessoryRight(accessory: USBAccessory): Promise<boolean> 1060 1061Requests the permission to access a USB accessory for a specified application. 1062 1063You need to call [usbManager.getAccessoryList](#usbmanagergetaccessorylist14) to obtain the accessory list and use [USBAccessory](#usbaccessory14) as a parameter. 1064 1065**System capability**: SystemCapability.USB.USBManager 1066 1067**Parameters** 1068 1069| Name | Type | Mandatory| Description | 1070| --------- | ------------ | ---- | ------------------------------------- | 1071| accessory | [USBAccessory](#usbaccessory14) | Yes | USB accessory.| 1072 1073**Return value** 1074 1075| Type | Description | 1076| ---------------- | ----------------------------- | 1077| Promise<boolean> | Promise used to return the application result. The value **true** indicates that the device access permissions are granted; **false** indicates the opposite.| 1078 1079**Error codes** 1080 1081For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 1082 1083| ID| Error Message | 1084| -------- | ------------------------------------------------------------ | 1085| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 1086| 801 | Capability not supported. | 1087| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. | 1088| 14400005 | Database operation exception. | 1089| 14401001 | The target USBAccessory not matched. | 1090 1091**Example** 1092 1093```ts 1094import { hilog } from '@kit.PerformanceAnalysisKit'; 1095try { 1096 let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList() 1097 let flag = usbManager.requestAccessoryRight(accList[0]) 1098 hilog.info(0, 'testTag ui', `requestAccessoryRight success, ret:${flag}`) 1099} catch (error) { 1100 hilog.info(0, 'testTag ui', `requestAccessoryRight error ${error.code}, message is ${error.message}`) 1101} 1102``` 1103 1104## usbManager.cancelAccessoryRight<sup>14+</sup> 1105 1106cancelAccessoryRight(accessory: USBAccessory): void 1107 1108Cancels the permission of the current application to access USB accessories. 1109 1110You need to call [usbManager.getAccessoryList](#usbmanagergetaccessorylist14) to obtain the accessory list and use [USBAccessory](#usbaccessory14) as a parameter. 1111 1112**System capability**: SystemCapability.USB.USBManager 1113 1114**Parameters** 1115 1116| Name | Type | Mandatory| Description | 1117| --------- | ------------ | ---- | ------------------------------------- | 1118| accessory | [USBAccessory](#usbaccessory14) | Yes | USB accessory.| 1119 1120**Error codes** 1121 1122For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 1123 1124| ID| Error Message | 1125| -------- | ------------------------------------------------------------ | 1126| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 1127| 801 | Capability not supported. | 1128| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. | 1129| 14400005 | Database operation exception. | 1130| 14401001 | The target USBAccessory not matched. | 1131 1132**Example** 1133 1134```ts 1135import { hilog } from '@kit.PerformanceAnalysisKit'; 1136try { 1137 let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList() 1138 let flag = usbManager.requestAccessoryRight(accList[0]) 1139 usbManager.cancelAccessoryRight(accList[0]) 1140 hilog.info(0, 'testTag ui', `cancelAccessoryRight success`) 1141} catch (error) { 1142 hilog.info(0, 'testTag ui', `cancelAccessoryRight error ${error.code}, message is ${error.message}`) 1143} 1144``` 1145 1146## usbManager.getAccessoryList<sup>14+</sup> 1147 1148getAccessoryList(): Array<Readonly<USBAccessory>> 1149 1150Obtains the list of USB accessories connected to the host. 1151 1152**System capability**: SystemCapability.USB.USBManager 1153 1154**Return value** 1155 1156| Type | Description | 1157| ----------------------------- | -------------------------------------------------- | 1158| Array<Readonly<USBAccessory>> | List of USB accessories (read-only). Currently, only one USB accessory is contained in the list.| 1159 1160**Error codes** 1161 1162For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 1163 1164| ID| Error Message | 1165| -------- | ------------------------------------------------------------ | 1166| 801 | Capability not supported. | 1167| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. | 1168 1169**Example** 1170 1171```ts 1172import { hilog } from '@kit.PerformanceAnalysisKit'; 1173try { 1174 let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList() 1175 hilog.info(0, 'testTag ui', `getAccessoryList success, accList: ${JSON.stringify(accList)}`) 1176} catch (error) { 1177 hilog.info(0, 'testTag ui', `getAccessoryList error ${error.code}, message is ${error.message}`) 1178} 1179``` 1180 1181## usbManager.openAccessory<sup>14+</sup> 1182 1183openAccessory(accessory: USBAccessory): USBAccessoryHandle 1184 1185Obtains the accessory handle and opens the accessory file descriptor. Then, the host can communicate with the accessory through the **read** and **write** APIs provided by Core File Kit. 1186 1187You need to call [usbManager.getAccessoryList](#usbmanagergetaccessorylist14) to obtain the accessory list and use [USBAccessory](#usbaccessory14) as a parameter. 1188 1189**System capability**: SystemCapability.USB.USBManager 1190 1191**Parameters** 1192 1193| Name | Type | Mandatory| Description | 1194| --------- | ------------ | ---- | ------------------------------------- | 1195| accessory | [USBAccessory](#usbaccessory14) | Yes | USB accessory.| 1196 1197**Return value** 1198 1199| Type | Description | 1200| ------------------ | ----------- | 1201| [USBAccessoryHandle](#usbaccessoryhandle14) | USB accessory handle.| 1202 1203**Error codes** 1204 1205For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 1206 1207| ID| Error Message | 1208| -------- | ------------------------------------------------------------ | 1209| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 1210| 801 | Capability not supported. | 1211| 14400001 | Access right denied. Call requestRight to get the USBDevicePipe access right first. | 1212| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. | 1213| 14401001 | The target USBAccessory not matched. | 1214| 14401002 | Failed to open the native accessory node. | 1215| 14401003 | Cannot reopen the accessory. | 1216 1217**Example** 1218 1219```ts 1220import { hilog } from '@kit.PerformanceAnalysisKit'; 1221import { fileIo as fs } from '@kit.CoreFileKit'; 1222try { 1223 let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList() 1224 let flag = usbManager.requestAccessoryRight(accList[0]) 1225 let handle = usbManager.openAccessory(accList[0]) 1226 hilog.info(0, 'testTag ui', `openAccessory success`) 1227 let arrayBuffer = new ArrayBuffer(4096); 1228 let readLength = fs.readSync(handle.accessoryFd, arrayBuffer, {offset: 0, length: 4096}); 1229 hilog.info(0, 'testTag ui', 'readSync ret: ' + readLength.toString(10)); 1230} catch (error) { 1231 hilog.info(0, 'testTag ui', `openAccessory error ${error.code}, message is ${error.message}`) 1232} 1233``` 1234 1235## usbManager.closeAccessory<sup>14+</sup> 1236 1237closeAccessory(accessoryHandle: USBAccessoryHandle): void 1238 1239Closes the accessory file descriptor. 1240 1241You need to call [usbManager.openAccessory](#usbmanageropenaccessory14) to obtain the accessory list and use [USBAccessoryHandle](#usbaccessoryhandle14) as a parameter. 1242 1243**System capability**: SystemCapability.USB.USBManager 1244 1245**Parameters** 1246 1247| Name | Type | Mandatory| Description | 1248| --------------- | ------------------ | ---- | -------------------------------------- | 1249| accessoryHandle | [USBAccessoryHandle](#usbaccessoryhandle14) | Yes | USB accessory handle. | 1250 1251**Error codes** 1252 1253For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 1254 1255| ID| Error Message | 1256| -------- | ------------------------------------------------------------ | 1257| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 1258| 801 | Capability not supported. | 1259| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. | 1260 1261**Example** 1262 1263```ts 1264import { hilog } from '@kit.PerformanceAnalysisKit'; 1265try { 1266 let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList() 1267 let flag = usbManager.requestAccessoryRight(accList[0]) 1268 let handle = usbManager.openAccessory(accList[0]) 1269 usbManager.closeAccessory(handle) 1270 hilog.info(0, 'testTag ui', `closeAccessory success`) 1271} catch (error) { 1272 hilog.info(0, 'testTag ui', `closeAccessory error ${error.code}, message is ${error.message}`) 1273} 1274``` 1275 1276## usbManager.resetUsbDevice<sup>20+</sup> 1277 1278resetUsbDevice(pipe: USBDevicePipe): boolean 1279 1280Resets a USB peripheral. 1281 1282> **NOTE** 1283> 1284> Previous configurations and APIs will be reset. Ensure that the related services have been completed before calling this API. 1285 1286**System capability**: SystemCapability.USB.USBManager 1287 1288**Parameters** 1289 1290| Name| Type| Mandatory| Description| 1291| -------- | -------- | -------- | -------- | 1292| 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.| 1293 1294**Return value** 1295 1296| Type| Description| 1297| -------- | -------- | 1298| boolean | Returns **true** if the device is reset successfully; returns **false** otherwise.| 1299 1300**Error codes** 1301 1302For details about the error codes, see [USB Service Error Codes](errorcode-usb.md). 1303 1304| ID| Error Message | 1305| -------- | ------------------------------------------------------------ | 1306| 801 | Capability not supported. | 1307| 14400001 | Access right denied. Call requestRight to get the USBDevicePipe access right first.| 1308| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. | 1309| 14400008 | No such device (it may have been disconnected). | 1310| 14400010 | Other USB error. Possible causes:<br>1.Unrecognized discard error code. | 1311| 14400013 | The USBDevicePipe validity check failed. Possible causes:<br>1. The input parameters fail the validation check.<br>2. The call chain used to obtain the input parameters is not reasonable. | 1312 1313**Example** 1314 1315```ts 1316let devicesList: Array<usbManager.USBDevice> = usbManager.getDevices(); 1317if (devicesList.length == 0) { 1318 console.error(`device list is empty`); 1319} 1320 1321usbManager.requestRight(devicesList[0].name); 1322let devicepipe: usbManager.USBDevicePipe = usbManager.connectDevice(devicesList[0]); 1323try { 1324 let ret: boolean = usbManager.resetUsbDevice(devicepipe); 1325 console.info(`resetUsbDevice = ${ret}`); 1326} catch (err) { 1327 console.error(`resetUsbDevice failed: ` + err); 1328} 1329``` 1330 1331## USBEndpoint 1332 1333Represents the USB endpoint from which data is sent or received. You can obtain the USB endpoint through [USBInterface](#usbinterface). 1334 1335>**NOTE** 1336> 1337> The host controller schedules the endpoint based on the endpoint type. 1338> 1339> The transmission characteristics are determined by the type during protocol layer packaging. 1340 1341**System capability**: SystemCapability.USB.USBManager 1342 1343| Name | Type | Mandatory |Description | 1344| ------------- | ------------------------------------------- | ------------- |------------- | 1345| address | number | Yes|Endpoint address. | 1346| attributes | number | Yes|Endpoint attributes. | 1347| interval | number | Yes|Endpoint interval. | 1348| maxPacketSize | number | Yes|Maximum size of data packets on the endpoint. | 1349| direction | [USBRequestDirection](#usbrequestdirection) | Yes|Endpoint direction. | 1350| number | number | Yes|Endpoint number. | 1351| type | number | Yes|Endpoint type. For details, see [UsbEndpointTransferType](#usbendpointtransfertype18). | 1352| interfaceId | number | Yes|Unique ID of the interface to which the endpoint belongs.| 1353 1354## USBInterface 1355 1356Represents a USB interface. One [USBConfiguration](#usbconfiguration) object can contain multiple **USBInterface** instances, each providing a specific function. 1357 1358**System capability**: SystemCapability.USB.USBManager 1359 1360| Name | Type | Mandatory |Description | 1361| ---------------- | ---------------------------------------- | ------------- |--------------------- | 1362| id | number | Yes|Unique ID of the USB interface. | 1363| protocol | number | Yes|Interface protocol. | 1364| clazz | number | Yes|Device type. | 1365| subClass | number | Yes|Device subclass. | 1366| alternateSetting | number | Yes|Settings for alternating between descriptors of the same USB interface. The value size indicates the number of optional modes. The value 0 indicates that no optional mode is supported.| 1367| name | string | Yes|Interface name. | 1368| endpoints | Array<[USBEndpoint](#usbendpoint)> | Yes|Endpoints that belong to the USB interface. | 1369 1370## USBConfiguration 1371 1372Represents the USB configuration. One [USBDevice](#usbdevice) can contain multiple **USBConfig** instances. 1373 1374**System capability**: SystemCapability.USB.USBManager 1375 1376| Name | Type | Mandatory |Description | 1377| -------------- | ------------------------------------------------ | --------------- |--------------- | 1378| id | number | Yes|Unique ID of the USB configuration. | 1379| attributes | number | Yes|Configuration attributes. | 1380| maxPower | number | Yes|Maximum power consumption, in mA. | 1381| name | string | Yes|Configuration name, which can be left empty. | 1382| isRemoteWakeup | boolean | Yes|Support for remote wakeup.| 1383| isSelfPowered | boolean | Yes| Support for independent power supplies.| 1384| interfaces | Array <[USBInterface](#usbinterface)> | Yes|Supported interface attributes. | 1385 1386## USBDevice 1387 1388Represents the USB device information. 1389 1390**System capability**: SystemCapability.USB.USBManager 1391 1392| Name | Type | Mandatory |Description | 1393| ---------------- | ------------------------------------ | ---------- |---------- | 1394| busNum | number | Yes|Bus address. | 1395| devAddress | number | Yes|Device address. | 1396| serial | string | Yes|Sequence number. | 1397| name | string | Yes|Device name. | 1398| manufacturerName | string | Yes| Device manufacturer. | 1399| productName | string | Yes|Product name. | 1400| version | string | Yes|Version number. | 1401| vendorId | number | Yes|Vendor ID. | 1402| productId | number | Yes|Product ID. | 1403| clazz | number | Yes|Device class. | 1404| subClass | number | Yes|Device subclass. | 1405| protocol | number | Yes|Device protocol code. | 1406| configs | Array<[USBConfiguration](#usbconfiguration)> | Yes|Device configuration descriptor information.| 1407 1408## USBDevicePipe 1409 1410Represents a USB device pipe, which is used to determine a USB device. 1411 1412**System capability**: SystemCapability.USB.USBManager 1413 1414| Name | Type | Mandatory |Description | 1415| ---------- | ------ | ----- |----- | 1416| busNum | number |Yes| Bus address.| 1417| devAddress | number |Yes| Device address.| 1418 1419## USBControlParams<sup>(deprecated)</sup> 1420 1421Represents control transfer parameters. 1422 1423>**NOTE** 1424> 1425> This API is supported since API version 9 and deprecated since API version 18. You are advised to use [USBDeviceRequestParams](#usbdevicerequestparams12) instead. 1426 1427**System capability**: SystemCapability.USB.USBManager 1428 1429| Name | Type | Mandatory |Description | 1430| ------- | ----------------------------------------------- | ---------------- |---------------- | 1431| request | number | Yes |Request type. | 1432| target | [USBRequestTargetType](#usbrequesttargettype) | Yes |Request target type. | 1433| reqType | [USBControlRequestType](#usbcontrolrequesttype) | Yes |Control request type. | 1434| value | number | Yes |Request parameter. | 1435| index | number | Yes |Index of the request parameter.| 1436| data | Uint8Array | Yes |Buffer for writing or reading data. | 1437 1438## USBDeviceRequestParams<sup>12+</sup> 1439 1440Represents control transfer parameters. 1441 1442**System capability**: SystemCapability.USB.USBManager 1443 1444| Name | Type | Mandatory |Description | 1445| ------- | ----------------------------------------------- | ---------------- |---------------- | 1446| bmRequestType | number | Yes |Control request type. | 1447| bRequest | number | Yes |Request type. | 1448| wValue | number | Yes |Request parameter. | 1449| wIndex | number | Yes |Index of the request parameter. | 1450| wLength | number | Yes |Length of the requested data.| 1451| data | Uint8Array | Yes |Buffer for writing or reading data. | 1452 1453## USBRequestTargetType 1454 1455Enumerates request target types. 1456 1457**System capability**: SystemCapability.USB.USBManager 1458 1459| Name | Value | Description | 1460| ---------------------------- | ---- | ------ | 1461| USB_REQUEST_TARGET_DEVICE | 0 | Device.| 1462| USB_REQUEST_TARGET_INTERFACE | 1 | Interface.| 1463| USB_REQUEST_TARGET_ENDPOINT | 2 | Endpoint.| 1464| USB_REQUEST_TARGET_OTHER | 3 | Other.| 1465 1466## USBControlRequestType 1467 1468Enumerates control request types. 1469 1470**System capability**: SystemCapability.USB.USBManager 1471 1472| Name | Value | Description | 1473| ------------------------- | ---- | ------ | 1474| USB_REQUEST_TYPE_STANDARD | 0 | Standard.| 1475| USB_REQUEST_TYPE_CLASS | 1 | Class. | 1476| USB_REQUEST_TYPE_VENDOR | 2 | Vendor.| 1477 1478## USBRequestDirection 1479 1480Enumerates request directions. 1481 1482**System capability**: SystemCapability.USB.USBManager 1483 1484| Name | Value | Description | 1485| --------------------------- | ---- | ------------------------ | 1486| USB_REQUEST_DIR_TO_DEVICE | 0 | Request for writing data from the host to the device.| 1487| USB_REQUEST_DIR_FROM_DEVICE | 0x80 | Request for reading data from the device to the host.| 1488 1489## USBAccessory<sup>14+</sup> 1490 1491Describes the USB accessory information. 1492 1493**System capability**: SystemCapability.USB.USBManager 1494 1495| Name | Type | Mandatory| Description | 1496| ------------ | ------ | ---- | ---------------- | 1497| manufacturer | string | Yes | Manufacturer of an accessory.| 1498| product | string | Yes | Product type of an accessory.| 1499| description | string | Yes | Description of an accessory. | 1500| version | string | Yes | Version of an accessory. | 1501| serialNumber | string | Yes | SN of an accessory. | 1502 1503## USBAccessoryHandle<sup>14+</sup> 1504 1505Describes the USB accessory handle. 1506 1507**System capability**: SystemCapability.USB.USBManager 1508 1509| Name | Type | Mandatory| Description | 1510| ----------- | ------ | ---- | ----------------------------------------- | 1511| accessoryFd | number | Yes | Accessory file descriptor. A valid **accessoryFd** is a positive integer.| 1512 1513## UsbDataTransferParams<sup>18+</sup> 1514 1515As a USB data transfer interface, it is required for a client to initiate a transfer request. 1516 1517**System capability**: SystemCapability.USB.USBManager 1518 1519| Name | Type | Mandatory |Description | 1520| ---------- | ------ | ----- |----- | 1521| devPipe | [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.| 1522| flags | [UsbTransferFlags](#usbtransferflags18) |Yes| USB transfer flag.| 1523| endpoint | number | Yes| Endpoint address, which is a positive integer.| 1524| type | [UsbEndpointTransferType](#usbendpointtransfertype18) |Yes| Transfer type.| 1525| timeout | number | Yes| Timeout duration, in ms.| 1526| length | number |Yes| Length of the data buffer, in bytes. The value must be a non-negative number (expected length).| 1527| callback | AsyncCallback<[SubmitTransferCallback](#submittransfercallback18)> |Yes| Information returned by the callback.| 1528| userData | Uint8Array | Yes| User data.| 1529| buffer | Uint8Array | Yes| Buffer, which is used to store data for read or write requests.| 1530| isoPacketCount | number | Yes| Number of data packets during real-time transfer, used only for I/Os with real-time transfer endpoints. The value must be a non-negative number.| 1531 1532## UsbTransferFlags<sup>18+</sup> 1533 1534Enumerates USB transfer flags. 1535 1536**System capability**: SystemCapability.USB.USBManager 1537 1538| Name | Value | Description | 1539| ---------------------------- | ---- | ------ | 1540| USB_TRANSFER_SHORT_NOT_OK | 0 | Reports short frames as errors.| 1541| USB_TRANSFER_FREE_BUFFER | 1 | Automatically releases the transfer buffer.| 1542| USB_TRANSFER_FREE_TRANSFER | 2 | Automatically transfers after the callback is complete.| 1543| USB_TRANSFER_ADD_ZERO_PACKET | 3 | Adds an additional data packet to the transfer.| 1544 1545## UsbEndpointTransferType<sup>18+</sup> 1546 1547Enumerates USB transfer types. 1548 1549**System capability**: SystemCapability.USB.USBManager 1550 1551| Name | Value | Description | 1552| ---------------------------- | ---- | ------ | 1553| TRANSFER_TYPE_ISOCHRONOUS | 0x1 | Real-time transfer.| 1554| TRANSFER_TYPE_BULK | 0x2 | Performs bulk transfer.| 1555| TRANSFER_TYPE_INTERRUPT | 0x3 | Interrupt transfer.| 1556 1557## SubmitTransferCallback<sup>18+</sup> 1558 1559Transfers USB data packets in an asynchronous manner. 1560 1561**System capability**: SystemCapability.USB.USBManager 1562 1563| Name | Type| Mandatory | Description | 1564| ---------- | ------ | ----- | ------ | 1565| actualLength | number | Yes|Actual length of the read or written data, in bytes.| 1566| status | [UsbTransferStatus](#usbtransferstatus18) | Yes|Status after reading or writing is complete.| 1567| isoPacketDescs | Array<Readonly<[UsbIsoPacketDescriptor](#usbisopacketdescriptor18)>> | Yes|Packet information transferred in real time.| 1568 1569## UsbTransferStatus<sup>18+</sup> 1570 1571Enumerates the status code returned after data processing is complete. 1572 1573**System capability**: SystemCapability.USB.USBManager 1574 1575| Name | Value | Description | 1576| ---------------------------- | ---- | ------ | 1577| TRANSFER_COMPLETED | 0 | Transfer completed.| 1578| TRANSFER_ERROR | 1 | Transfer failed.| 1579| TRANSFER_TIMED_OUT | 2 | Transfer timeout.| 1580| TRANSFER_CANCELED | 3 |Transfer canceled.| 1581| TRANSFER_STALL | 4 | Transfer stalled (at bulk/interrupt endpoint).| 1582| TRANSFER_NO_DEVICE | 5 | Device disconnected.| 1583| TRANSFER_OVERFLOW | 6 | Data overflow.| 1584 1585## UsbIsoPacketDescriptor<sup>18+</sup> 1586 1587Describes packet information returned in real time by the transfer callback. 1588 1589**System capability**: SystemCapability.USB.USBManager 1590 1591| Name | Type| Mandatory| Description | 1592| ---------- | ------ | ----- | ------ | 1593| length | number | Yes|Expected length of the read or written data, in bytes.| 1594| actualLength | number| Yes|Actual length of the read or written data, in bytes.| 1595| status | [UsbTransferStatus](#usbtransferstatus18) | Yes|Status returned by callback.| 1596