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 port 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 usb from "@ohos.usbManager"; 13``` 14 15## usb.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<usb.USBDevice> = usb.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## usb.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 [usb.getDevices](#usbgetdevices) to obtain the USB device list and device information, and then call [usb.requestRight](#usbrequestright) 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 information.| 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 Error Codes](../errorcodes/errorcode-usb.md). 112 113| ID| Error Message| 114| -------- | -------- | 115| 14400001 |Permission denied. Need call requestRight to get permission. | 116 117**Example** 118 119```ts 120let devicesList: Array<usb.USBDevice> = usb.getDevices(); 121if (devicesList.length == 0) { 122 console.log(`device list is empty`); 123} 124 125let device: usb.USBDevice = devicesList[0]; 126usb.requestRight(device.name); 127let devicepipe: usb.USBDevicePipe = usb.connectDevice(device); 128console.log(`devicepipe = ${devicepipe}`); 129``` 130 131## usb.hasRight 132 133hasRight(deviceName: string): boolean 134 135Checks whether the application has the permission to access the device. 136 137Checks 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. 138 139**System capability**: SystemCapability.USB.USBManager 140 141**Parameters** 142 143| Name| Type| Mandatory| Description| 144| -------- | -------- | -------- | -------- | 145| deviceName | string | Yes| Device name.| 146 147**Return value** 148 149| Type| Description| 150| -------- | -------- | 151| boolean | Returns **true** if the application has the permission to access the device; returns **false** otherwise.| 152 153**Example** 154 155```ts 156let devicesName: string = "1-1"; 157let right: boolean = usb.hasRight(devicesName); 158console.log(`${right}`); 159``` 160 161## usb.requestRight 162 163requestRight(deviceName: string): Promise<boolean> 164 165Requests 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. 166 167**System capability**: SystemCapability.USB.USBManager 168 169**Parameters** 170 171| Name| Type| Mandatory| Description| 172| -------- | -------- | -------- | -------- | 173| deviceName | string | Yes| Device name.| 174 175**Return value** 176 177| Type| Description| 178| -------- | -------- | 179| 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.| 180 181**Example** 182 183```ts 184let devicesName: string = "1-1"; 185usb.requestRight(devicesName).then(ret => { 186 console.log(`requestRight = ${ret}`); 187}); 188``` 189 190## usb.removeRight 191 192removeRight(deviceName: string): boolean 193 194Removes 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. 195 196**System capability**: SystemCapability.USB.USBManager 197 198**Parameters** 199 200| Name| Type| Mandatory| Description| 201| -------- | -------- | -------- | -------- | 202| deviceName | string | Yes| Device name.| 203 204**Return value** 205 206| Type| Description| 207| -------- | -------- | 208| boolean | Permission removal result. The value **true** indicates that the access permission is removed successfully; and the value **false** indicates the opposite.| 209 210**Example** 211 212```ts 213let devicesName: string = "1-1"; 214if (usb.removeRight(devicesName)) { 215 console.log(`Succeed in removing right`); 216} 217``` 218 219## usb.addRight 220 221addRight(bundleName: string, deviceName: string): boolean 222 223Adds 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. 224 225[requestRight](#usbrequestright) triggers a dialog box to request for user authorization, whereas **addRight** adds the access permission directly without displaying a dialog box. 226 227**System API**: This is a system API. 228 229**System capability**: SystemCapability.USB.USBManager 230 231**Parameters** 232 233| Name| Type| Mandatory| Description| 234| -------- | -------- | -------- | -------- | 235| deviceName | string | Yes| Device name.| 236| bundleName | string | Yes| Bundle name of the application.| 237 238**Return value** 239 240| Type| Description| 241| -------- | -------- | 242| boolean | Permission addition result. The value **true** indicates that the access permission is added successfully; and the value **false** indicates the opposite.| 243 244**Example** 245 246```ts 247let devicesName: string = "1-1"; 248let bundleName: string = "com.example.hello"; 249if (usb.addRight(bundleName, devicesName)) { 250 console.log(`Succeed in adding right`); 251} 252``` 253 254## usb.claimInterface 255 256claimInterface(pipe: USBDevicePipe, iface: USBInterface, force ?: boolean): number 257 258Claims a USB interface. 259 260Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list and USB interfaces, call [usb.requestRight](#usbrequestright) to request the device access permission, and call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter. 261 262**System capability**: SystemCapability.USB.USBManager 263 264**Parameters** 265 266| Name| Type| Mandatory| Description| 267| -------- | -------- | -------- | -------- | 268| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address.| 269| iface | [USBInterface](#usbinterface) | Yes| USB interface, which is used to determine the index of the interface to claim.| 270| force | boolean | No| Whether to forcibly claim the USB interface. The default value is **false**, indicating not to forcibly claim the USB interface.| 271 272**Return value** 273 274| Type| Description| 275| -------- | -------- | 276| number | Returns **0** if the USB interface is successfully claimed; returns an error code otherwise.| 277 278**Example** 279 280```ts 281let devicesList: Array<usb.USBDevice> = usb.getDevices(); 282if (devicesList.length == 0) { 283 console.log(`device list is empty`); 284} 285 286let device: usb.USBDevice = devicesList[0]; 287usb.requestRight(device.name); 288let devicepipe: usb.USBDevicePipe = usb.connectDevice(device); 289let interfaces: usb.USBInterface = device.configs[0].interfaces[0]; 290let ret: number= usb.claimInterface(devicepipe, interfaces); 291console.log(`claimInterface = ${ret}`); 292``` 293 294## usb.releaseInterface 295 296releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number 297 298Releases a USB interface. 299 300Before you do this, ensure that you have claimed the interface by calling [usb.claimInterface](#usbclaiminterface). 301 302**System capability**: SystemCapability.USB.USBManager 303 304**Parameters** 305 306| Name| Type| Mandatory| Description| 307| -------- | -------- | -------- | -------- | 308| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address.| 309| iface | [USBInterface](#usbinterface) | Yes| USB interface, which is used to determine the index of the interface to release.| 310 311**Return value** 312 313| Type| Description| 314| -------- | -------- | 315| number | Returns **0** if the USB interface is successfully released; returns an error code otherwise.| 316 317**Example** 318 319```ts 320let devicesList: Array<usb.USBDevice> = usb.getDevices(); 321if (devicesList.length == 0) { 322 console.log(`device list is empty`); 323} 324 325let device: usb.USBDevice = devicesList[0]; 326usb.requestRight(device.name); 327let devicepipe: usb.USBDevicePipe = usb.connectDevice(device); 328let interfaces: usb.USBInterface = device.configs[0].interfaces[0]; 329let ret: number = usb.claimInterface(devicepipe, interfaces); 330ret = usb.releaseInterface(devicepipe, interfaces); 331console.log(`releaseInterface = ${ret}`); 332``` 333 334## usb.setConfiguration 335 336setConfiguration(pipe: USBDevicePipe, config: USBConfiguration): number 337 338Sets the device configuration. 339 340Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list and device configuration, call [usb.requestRight](#usbrequestright) to request the device access permission, and call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter. 341 342**System capability**: SystemCapability.USB.USBManager 343 344**Parameters** 345 346| Name| Type| Mandatory| Description| 347| -------- | -------- | -------- | -------- | 348| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address.| 349| config | [USBConfiguration](#usbconfiguration) | Yes| USB configuration to set.| 350 351**Return value** 352 353| Type| Description| 354| -------- | -------- | 355| number | Returns **0** if the USB configuration is successfully set; returns an error code otherwise.| 356 357**Example** 358 359```ts 360let devicesList: Array<usb.USBDevice> = usb.getDevices(); 361if (devicesList.length == 0) { 362 console.log(`device list is empty`); 363} 364 365let device: usb.USBDevice = devicesList[0]; 366usb.requestRight(device.name); 367let devicepipe: usb.USBDevicePipe = usb.connectDevice(device); 368let config: usb.USBConfiguration = device.configs[0]; 369let ret: number= usb.setConfiguration(devicepipe, config); 370console.log(`setConfiguration = ${ret}`); 371``` 372 373## usb.setInterface 374 375setInterface(pipe: USBDevicePipe, iface: USBInterface): number 376 377Sets a USB interface. 378 379Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list and interfaces, call [usb.requestRight](#usbrequestright) to request the device access permission, call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter, and call [usb.claimInterface](#usbclaiminterface) to claim the USB interface. 380 381**System capability**: SystemCapability.USB.USBManager 382 383**Parameters** 384 385| Name | Type | Mandatory | Description | 386| ----- | ------------------------------- | --- | ------------- | 387| pipe | [USBDevicePipe](#usbdevicepipe) | Yes | Device pipe, which is used to determine the bus number and device address.| 388| iface | [USBInterface](#usbinterface) | Yes | USB interface to set. | 389 390**Return value** 391 392| Type| Description| 393| -------- | -------- | 394| number | Returns **0** if the USB interface is successfully set; returns an error code otherwise.| 395 396**Example** 397 398```ts 399let devicesList: Array<usb.USBDevice> = usb.getDevices(); 400if (devicesList.length == 0) { 401 console.log(`device list is empty`); 402} 403 404let device: usb.USBDevice = devicesList[0]; 405usb.requestRight(device.name); 406let devicepipe: usb.USBDevicePipe = usb.connectDevice(device); 407let interfaces: usb.USBInterface = device.configs[0].interfaces[0]; 408let ret: number = usb.claimInterface(devicepipe, interfaces); 409ret = usb.setInterface(devicepipe, interfaces); 410console.log(`setInterface = ${ret}`); 411``` 412 413## usb.getRawDescriptor 414 415getRawDescriptor(pipe: USBDevicePipe): Uint8Array 416 417Obtains the raw USB descriptor. 418 419Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list, call [usb.requestRight](#usbrequestright) to request the device access permission, and call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter. 420 421**System capability**: SystemCapability.USB.USBManager 422 423**Parameters** 424 425| Name| Type| Mandatory| Description| 426| -------- | -------- | -------- | -------- | 427| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address.| 428 429**Return value** 430 431| Type| Description| 432| -------- | -------- | 433| Uint8Array | Returns the raw USB descriptor if the operation is successful; returns **undefined** otherwise.| 434 435**Example** 436 437```ts 438let devicesList: Array<usb.USBDevice> = usb.getDevices(); 439if (devicesList.length == 0) { 440 console.log(`device list is empty`); 441} 442 443usb.requestRight(devicesList[0].name); 444let devicepipe: usb.USBDevicePipe = usb.connectDevice(devicesList[0]); 445let ret: Uint8Array = usb.getRawDescriptor(devicepipe); 446``` 447 448## usb.getFileDescriptor 449 450getFileDescriptor(pipe: USBDevicePipe): number 451 452Obtains the file descriptor. 453 454Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list, call [usb.requestRight](#usbrequestright) to request the device access permission, and call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter. 455 456**System capability**: SystemCapability.USB.USBManager 457 458**Parameters** 459 460| Name| Type| Mandatory| Description| 461| -------- | -------- | -------- | -------- | 462| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address.| 463 464**Return value** 465 466| Type | Description | 467| ------ | -------------------- | 468| number | Returns the file descriptor of the USB device if the operation is successful; returns **-1** otherwise.| 469 470**Example** 471 472```ts 473let devicesList: Array<usb.USBDevice> = usb.getDevices(); 474if (devicesList.length == 0) { 475 console.log(`device list is empty`); 476} 477 478usb.requestRight(devicesList[0].name); 479let devicepipe: usb.USBDevicePipe = usb.connectDevice(devicesList[0]); 480let ret: number = usb.getFileDescriptor(devicepipe); 481``` 482 483## usb.controlTransfer 484 485controlTransfer(pipe: USBDevicePipe, controlparam: USBControlParams, timeout ?: number): Promise<number> 486 487Performs control transfer. 488 489Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list, call [usb.requestRight](#usbrequestright) to request the device access permission, and call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter. 490 491**System capability**: SystemCapability.USB.USBManager 492 493**Parameters** 494 495| Name| Type| Mandatory| Description| 496| -------- | -------- | -------- | -------- | 497| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe, which is used to determine the USB device.| 498| controlparam | [USBControlParams](#usbcontrolparams) | Yes| Control transfer parameters.| 499| timeout | number | No| Timeout duration in ms. This parameter is optional. The default value is **0**, indicating no timeout.| 500 501**Return value** 502 503| Type| Description| 504| -------- | -------- | 505| 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.| 506 507**Example** 508 509```ts 510let param: usb.USBControlParams = { 511 request: 0, 512 reqType: usb.USBControlRequestType.USB_REQUEST_TYPE_STANDARD, 513 target: usb.USBRequestTargetType.USB_REQUEST_TARGET_DEVICE, 514 value: 0, 515 index: 0, 516 data: new Uint8Array() 517}; 518 519let devicesList: Array<usb.USBDevice> = usb.getDevices(); 520if (devicesList.length == 0) { 521 console.log(`device list is empty`); 522} 523 524usb.requestRight(devicesList[0].name); 525let devicepipe: usb.USBDevicePipe = usb.connectDevice(devicesList[0]); 526usb.controlTransfer(devicepipe, param).then((ret: number) => { 527 console.log(`controlTransfer = ${ret}`); 528}) 529``` 530 531## usb.bulkTransfer 532 533bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, timeout ?: number): Promise<number> 534 535Performs bulk transfer. 536 537Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list and endpoints, call [usb.requestRight](#usbrequestright) to request the device access permission, call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter, and call [usb.claimInterface](#usbclaiminterface) to claim the USB interface. 538 539**System capability**: SystemCapability.USB.USBManager 540 541**Parameters** 542 543| Name| Type| Mandatory| Description| 544| -------- | -------- | -------- | -------- | 545| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe, which is used to determine the USB device.| 546| endpoint | [USBEndpoint](#usbendpoint) | Yes| USB endpoint, which is used to determine the USB port for data transfer.| 547| buffer | Uint8Array | Yes| Buffer used to write or read data.| 548| timeout | number | No| Timeout duration in ms. This parameter is optional. The default value is **0**, indicating no timeout.| 549 550**Return value** 551 552| Type| Description| 553| -------- | -------- | 554| 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.| 555 556**Example** 557 558```ts 559// Call usb.getDevices to obtain a data set. Then, obtain a USB device and its access permission. 560// Pass the obtained USB device as a parameter to usb.connectDevice. Then, call usb.connectDevice to connect the USB device. 561// Call usb.claimInterface to claim the USB interface. After that, call usb.bulkTransfer to start bulk transfer. 562let devicesList: Array<usb.USBDevice> = usb.getDevices(); 563if (devicesList.length == 0) { 564 console.log(`device list is empty`); 565} 566 567let device: usb.USBDevice = devicesList[0]; 568usb.requestRight(device.name); 569 570let devicepipe: usb.USBDevicePipe = usb.connectDevice(device); 571let interfaces: usb.USBInterface = device.configs[0].interfaces[0]; 572let endpoint: usb.USBEndpoint = device.configs[0].interfaces[0].endpoints[0]; 573let ret: number = usb.claimInterface(devicepipe, interfaces); 574let buffer = new Uint8Array(128); 575usb.bulkTransfer(devicepipe, endpoint, buffer).then((ret: number) => { 576 console.log(`bulkTransfer = ${ret}`); 577}); 578``` 579 580## usb.closePipe 581 582closePipe(pipe: USBDevicePipe): number 583 584Closes a USB device pipe. 585 586Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB device list, call [usb.requestRight](#usbrequestright) to request the device access permission, and call [usb.connectDevice](#usbconnectdevice) to obtain **devicepipe** as an input parameter. 587 588**System capability**: SystemCapability.USB.USBManager 589 590**Parameters** 591 592| Name| Type| Mandatory| Description| 593| -------- | -------- | -------- | -------- | 594| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe.| 595 596**Return value** 597 598| Type| Description| 599| -------- | -------- | 600| number | Returns **0** if the USB device pipe is closed successfully; returns an error code otherwise.| 601 602**Example** 603 604```ts 605let devicesList: Array<usb.USBDevice> = usb.getDevices(); 606if (devicesList.length == 0) { 607 console.log(`device list is empty`); 608} 609 610usb.requestRight(devicesList[0].name); 611let devicepipe: usb.USBDevicePipe = usb.connectDevice(devicesList[0]); 612let ret: number = usb.closePipe(devicepipe); 613console.log(`closePipe = ${ret}`); 614``` 615 616## usb.usbFunctionsFromString 617 618usbFunctionsFromString(funcs: string): number 619 620Converts the USB function list in the string format to a numeric mask in Device mode. 621 622**System API**: This is a system API. 623 624**System capability**: SystemCapability.USB.USBManager 625 626**Parameters** 627 628| Name| Type | Mandatory| Description | 629| ------ | ------ | ---- | ---------------------- | 630| funcs | string | Yes | Function list in string format.| 631 632**Return value** 633 634| Type | Description | 635| ------ | ------------------ | 636| number | Function list in numeric mask format.| 637 638**Example** 639 640```ts 641let funcs: string = "acm"; 642let ret: number = usb.usbFunctionsFromString(funcs); 643``` 644 645## usb.usbFunctionsToString 646 647usbFunctionsToString(funcs: FunctionType): string 648 649Converts the USB function list in the numeric mask format to a string in Device mode. 650 651**System API**: This is a system API. 652 653**System capability**: SystemCapability.USB.USBManager 654 655**Parameters** 656 657| Name| Type | Mandatory| Description | 658| ------ | ------------------------------ | ---- | ----------------- | 659| funcs | [FunctionType](#functiontype) | Yes | USB function list in numeric mask format.| 660 661**Return value** 662 663| Type | Description | 664| ------ | ------------------------------ | 665| string | Function list in string format.| 666 667**Example** 668 669```ts 670let funcs: number = usb.FunctionType.ACM | usb.FunctionType.ECM; 671let ret: string = usb.usbFunctionsToString(funcs); 672``` 673 674## usb.setCurrentFunctions 675 676setCurrentFunctions(funcs: FunctionType): Promise\<void\> 677 678Sets the current USB function list in Device mode. 679 680**System API**: This is a system API. 681 682**System capability**: SystemCapability.USB.USBManager 683 684**Parameters** 685 686| Name| Type | Mandatory| Description | 687| ------ | ------------------------------ | ---- | ----------------- | 688| funcs | [FunctionType](#functiontype) | Yes | USB function list in numeric mask format.| 689 690**Error codes** 691 692For details about the error codes, see [USB Error Codes](../errorcodes/errorcode-usb.md). 693 694| ID| Error Message | 695| -------- | ---------------------------------------------------- | 696| 14400002 | Permission denied.The HDC is disabled by the system. | 697 698**Return value** 699 700| Type | Description | 701| --------------- | ------------- | 702| Promise\<void\> | Promise used to return the result.| 703 704**Example** 705 706```ts 707import {BusinessError} from '@ohos.base'; 708let funcs: number = usb.FunctionType.HDC; 709usb.setCurrentFunctions(funcs).then(() => { 710 console.info('usb setCurrentFunctions successfully.'); 711}).catch((err: BusinessError) => { 712 console.error('usb setCurrentFunctions failed: ' + err.code + ' message: ' + err.message); 713}); 714``` 715 716## usb.getCurrentFunctions 717 718getCurrentFunctions(): FunctionType 719 720Obtains the numeric mask combination for the USB function list in Device mode. 721 722**System API**: This is a system API. 723 724**System capability**: SystemCapability.USB.USBManager 725 726**Return value** 727 728| Type | Description | 729| ------------------------------ | --------------------------------- | 730| [FunctionType](#functiontype) | Numeric mask combination for the USB function list.| 731 732**Example** 733 734```ts 735let ret: number = usb.getCurrentFunctions(); 736``` 737 738## usb.getPorts 739 740getPorts(): Array\<USBPort\> 741 742Obtains the list of all physical USB ports. 743 744**System API**: This is a system API. 745 746**System capability**: SystemCapability.USB.USBManager 747 748**Return value** 749 750| Type | Description | 751| ----------------------------- | --------------------- | 752| [Array\<USBPort\>](#usbport) | List of physical USB ports.| 753 754**Example** 755 756```ts 757let ret: Array<usb.USBPort> = usb.getPorts(); 758``` 759 760## usb.getSupportedModes 761 762getSupportedModes(portId: number): PortModeType 763 764Obtains the mask combination for the supported mode list of a given USB port. 765 766**System API**: This is a system API. 767 768**System capability**: SystemCapability.USB.USBManager 769 770**Parameters** 771 772| Name| Type | Mandatory| Description | 773| ------ | ------ | ---- | -------- | 774| portId | number | Yes | Port number.| 775 776**Return value** 777 778| Type | Description | 779| ------------------------------ | -------------------------- | 780| [PortModeType](#portmodetype) | Mask combination for the supported mode list.| 781 782**Example** 783 784```ts 785let ret: number = usb.getSupportedModes(0); 786``` 787 788## usb.setPortRoles 789 790setPortRoles(portId: number, powerRole: PowerRoleType, dataRole: DataRoleType): Promise\<void\> 791 792Sets the role types supported by a specified port, which can be **powerRole** (for charging) and **dataRole** (for data transfer). 793 794**System API**: This is a system API. 795 796**System capability**: SystemCapability.USB.USBManager 797 798**Parameters** 799 800| Name | Type | Mandatory| Description | 801| --------- | -------------------------------- | ---- | ---------------- | 802| portId | number | Yes | Port number. | 803| powerRole | [PowerRoleType](#powerroletype) | Yes | Role for charging. | 804| dataRole | [DataRoleType](#dataroletype) | Yes | Role for data transfer.| 805 806**Return value** 807 808| Type | Description | 809| --------------- | ------------- | 810| Promise\<void\> | Promise used to return the result.| 811 812**Example** 813 814```ts 815import {BusinessError} from '@ohos.base'; 816let portId: number = 1; 817usb.setPortRoles(portId, usb.PowerRoleType.SOURCE, usb.DataRoleType.HOST).then(() => { 818 console.info('usb setPortRoles successfully.'); 819}).catch((err: BusinessError) => { 820 console.error('usb setPortRoles failed: ' + err.code + ' message: ' + err.message); 821}); 822``` 823 824## USBEndpoint 825 826Represents the USB endpoint from which data is sent or received. You can obtain the USB endpoint through [USBInterface](#usbinterface). 827 828**System capability**: SystemCapability.USB.USBManager 829 830| Name | Type | Mandatory |Description | 831| ------------- | ------------------------------------------- | ------------- |------------- | 832| address | number | Yes|Endpoint address. | 833| attributes | number | Yes|Endpoint attributes. | 834| interval | number | Yes|Endpoint interval. | 835| maxPacketSize | number | Yes|Maximum size of data packets on the endpoint. | 836| direction | [USBRequestDirection](#usbrequestdirection) | Yes|Endpoint direction. | 837| number | number | Yes|Endpoint number. | 838| type | number | Yes|Endpoint type. | 839| interfaceId | number | Yes|Unique ID of the interface to which the endpoint belongs.| 840 841## USBInterface 842 843Represents a USB interface. One [USBConfiguration](#usbconfiguration) object can contain multiple **USBInterface** instances, each providing a specific function. 844 845**System capability**: SystemCapability.USB.USBManager 846 847| Name | Type | Mandatory |Description | 848| ---------------- | ---------------------------------------- | ------------- |--------------------- | 849| id | number | Yes|Unique ID of the USB interface. | 850| protocol | number | Yes|Interface protocol. | 851| clazz | number | Yes|Device type. | 852| subClass | number | Yes|Device subclass. | 853| alternateSetting | number | Yes|Settings for alternating between descriptors of the same USB interface.| 854| name | string | Yes|Interface name. | 855| endpoints | Array<[USBEndpoint](#usbendpoint)> | Yes|Endpoints that belong to the USB interface. | 856 857## USBConfiguration 858 859Represents the USB configuration. One [USBDevice](#usbdevice) can contain multiple **USBConfig** instances. 860 861**System capability**: SystemCapability.USB.USBManager 862 863| Name | Type | Mandatory |Description | 864| -------------- | ------------------------------------------------ | --------------- |--------------- | 865| id | number | Yes|Unique ID of the USB configuration. | 866| attributes | number | Yes|Configuration attributes. | 867| maxPower | number | Yes|Maximum power consumption, in mA. | 868| name | string | Yes|Configuration name, which can be left empty. | 869| isRemoteWakeup | boolean | Yes|Support for remote wakeup.| 870| isSelfPowered | boolean | Yes| Support for independent power supplies.| 871| interfaces | Array <[USBInterface](#usbinterface)> | Yes|Supported interface attributes. | 872 873## USBDevice 874 875Represents the USB device information. 876 877**System capability**: SystemCapability.USB.USBManager 878 879| Name | Type | Mandatory |Description | 880| ---------------- | ------------------------------------ | ---------- |---------- | 881| busNum | number | Yes|Bus address. | 882| devAddress | number | Yes|Device address. | 883| serial | string | Yes|Sequence number. | 884| name | string | Yes|Device name. | 885| manufacturerName | string | Yes| Device manufacturer. | 886| productName | string | Yes|Product name. | 887| version | string | Yes|Version number. | 888| vendorId | number | Yes|Vendor ID. | 889| productId | number | Yes|Product ID. | 890| clazz | number | Yes|Device class. | 891| subClass | number | Yes|Device subclass. | 892| protocol | number | Yes|Device protocol code. | 893| configs | Array<[USBConfiguration](#usbconfiguration)> | Yes|Device configuration descriptor information.| 894 895## USBDevicePipe 896 897Represents a USB device pipe, which is used to determine a USB device. 898 899**System capability**: SystemCapability.USB.USBManager 900 901| Name | Type | Mandatory |Description | 902| ---------- | ------ | ----- |----- | 903| busNum | number |Yes| Bus address.| 904| devAddress | number |Yes| Device address.| 905 906## USBControlParams 907 908Represents control transfer parameters. 909 910**System capability**: SystemCapability.USB.USBManager 911 912| Name | Type | Mandatory |Description | 913| ------- | ----------------------------------------------- | ---------------- |---------------- | 914| request | number | Yes |Request type. | 915| target | [USBRequestTargetType](#usbrequesttargettype) | Yes |Request target type. | 916| reqType | [USBControlRequestType](#usbcontrolrequesttype) | Yes |Control request type. | 917| value | number | Yes |Request parameter value. | 918| index | number | Yes |Index of the request parameter value.| 919| data | Uint8Array | Yes |Buffer for writing or reading data. | 920 921## USBPort 922 923Represents a USB port. 924 925**System API**: This is a system API. 926 927**System capability**: SystemCapability.USB.USBManager 928 929| Name | Type | Mandatory |Description | 930| -------------- | ------------------------------- | ------------------- |------------------------ | 931| id | number | Yes |Unique identifier of a USB port. | 932| supportedModes | [PortModeType](#portmodetype) | Yes |Numeric mask combination for the supported mode list.| 933| status | [USBPortStatus](#usbportstatus) | Yes |USB port role. | 934 935## USBPortStatus 936 937Enumerates USB port roles. 938 939**System API**: This is a system API. 940 941**System capability**: SystemCapability.USB.USBManager 942 943| Name | Type| Mandatory |Description | 944| ---------------- | -------- | ---------------- |---------------------- | 945| currentMode | number | Yes|Current USB mode. | 946| currentPowerRole | number | Yes |Current power role. | 947| currentDataRole | number | Yes |Current data role.| 948 949## USBRequestTargetType 950 951Enumerates request target types. 952 953**System capability**: SystemCapability.USB.USBManager 954 955| Name | Value | Description | 956| ---------------------------- | ---- | ------ | 957| USB_REQUEST_TARGET_DEVICE | 0 | Device.| 958| USB_REQUEST_TARGET_INTERFACE | 1 | Interface.| 959| USB_REQUEST_TARGET_ENDPOINT | 2 | Endpoint.| 960| USB_REQUEST_TARGET_OTHER | 3 | Other.| 961 962## USBControlRequestType 963 964Enumerates control request types. 965 966**System capability**: SystemCapability.USB.USBManager 967 968| Name | Value | Description | 969| ------------------------- | ---- | ------ | 970| USB_REQUEST_TYPE_STANDARD | 0 | Standard.| 971| USB_REQUEST_TYPE_CLASS | 1 | Class. | 972| USB_REQUEST_TYPE_VENDOR | 2 | Vendor.| 973 974## USBRequestDirection 975 976Enumerates request directions. 977 978**System capability**: SystemCapability.USB.USBManager 979 980| Name | Value | Description | 981| --------------------------- | ---- | ------------------------ | 982| USB_REQUEST_DIR_TO_DEVICE | 0 | Request for writing data from the host to the device.| 983| USB_REQUEST_DIR_FROM_DEVICE | 0x80 | Request for reading data from the device to the host.| 984 985## FunctionType 986 987Enumerates USB device function types. 988 989**System API**: This is a system API. 990 991**System capability**: SystemCapability.USB.USBManager 992 993| Name | Value | Description | 994| ------------ | ---- | ---------- | 995| NONE | 0 | No function.| 996| ACM | 1 | ACM function. | 997| ECM | 2 | ECM function. | 998| HDC | 4 | HDC function. | 999| MTP | 8 | Not supported currently.| 1000| PTP | 16 | Not supported currently.| 1001| RNDIS | 32 | Not supported currently.| 1002| MIDI | 64 | Not supported currently.| 1003| AUDIO_SOURCE | 128 | Not supported currently.| 1004| NCM | 256 | Not supported currently.| 1005 1006## PortModeType 1007 1008Enumerates USB port mode types. 1009 1010**System API**: This is a system API. 1011 1012**System capability**: SystemCapability.USB.USBManager 1013 1014| Name | Value | Description | 1015| --------- | ---- | ---------------------------------------------------- | 1016| NONE | 0 | None | 1017| UFP | 1 | Upstream facing port, which functions as the sink of power supply. | 1018| DFP | 2 | Downstream facing port, which functions as the source of power supply. | 1019| DRP | 3 | Dynamic reconfiguration port (DRP), which can function as the DFP (host) or UFP (device). It is not supported currently.| 1020| NUM_MODES | 4 | Not supported currently. | 1021 1022## PowerRoleType 1023 1024Enumerates power role types. 1025 1026**System API**: This is a system API. 1027 1028**System capability**: SystemCapability.USB.USBManager 1029 1030| Name | Value | Description | 1031| ------ | ---- | ---------- | 1032| NONE | 0 | None | 1033| SOURCE | 1 | External power supply.| 1034| SINK | 2 | Internal power supply.| 1035 1036## DataRoleType 1037 1038Enumerates data role types. 1039 1040**System API**: This is a system API. 1041 1042**System capability**: SystemCapability.USB.USBManager 1043 1044| Name | Value | Description | 1045| ------ | ---- | ------------ | 1046| NONE | 0 | None | 1047| HOST | 1 | USB host.| 1048| DEVICE | 2 | USB device.| 1049