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 Service 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[usb.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 510class PARA { 511 request: number = 0 512 reqType: usb.USBControlRequestType = 0 513 target: usb.USBRequestTargetType = 0 514 value: number = 0 515 index: number = 0 516 data: Uint8Array = new Uint8Array() 517} 518 519let param: PARA = { 520 request: 0, 521 reqType: 0, 522 target:0, 523 value: 0, 524 index: 0, 525 data: new Uint8Array() 526}; 527 528let devicesList: Array<usb.USBDevice> = usb.getDevices(); 529if (devicesList.length == 0) { 530 console.log(`device list is empty`); 531} 532 533usb.requestRight(devicesList[0].name); 534let devicepipe: usb.USBDevicePipe = usb.connectDevice(devicesList[0]); 535usb.controlTransfer(devicepipe, param).then((ret: number) => { 536 console.log(`controlTransfer = ${ret}`); 537}) 538``` 539 540## usb.bulkTransfer 541 542bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, timeout ?: number): Promise<number> 543 544Performs bulk transfer. 545 546Before 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. 547 548**System capability**: SystemCapability.USB.USBManager 549 550**Parameters** 551 552| Name| Type| Mandatory| Description| 553| -------- | -------- | -------- | -------- | 554| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe, which is used to determine the USB device.| 555| endpoint | [USBEndpoint](#usbendpoint) | Yes| USB endpoint, which is used to determine the USB port for data transfer.| 556| buffer | Uint8Array | Yes| Buffer used to write or read data.| 557| timeout | number | No| Timeout duration in ms. This parameter is optional. The default value is **0**, indicating no timeout.| 558 559**Return value** 560 561| Type| Description| 562| -------- | -------- | 563| 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.| 564 565**Example** 566 567```ts 568// Call usb.getDevices to obtain a data set. Then, obtain a USB device and its access permission. 569// Pass the obtained USB device as a parameter to usb.connectDevice. Then, call usb.connectDevice to connect the USB device. 570// Call usb.claimInterface to claim the USB interface. After that, call usb.bulkTransfer to start bulk transfer. 571let devicesList: Array<usb.USBDevice> = usb.getDevices(); 572if (devicesList.length == 0) { 573 console.log(`device list is empty`); 574} 575 576let device: usb.USBDevice = devicesList[0]; 577usb.requestRight(device.name); 578 579let devicepipe: usb.USBDevicePipe = usb.connectDevice(device); 580let interfaces: usb.USBInterface = device.configs[0].interfaces[0]; 581let endpoint: usb.USBEndpoint = device.configs[0].interfaces[0].endpoints[0]; 582let ret: number = usb.claimInterface(devicepipe, interfaces); 583let buffer = new Uint8Array(128); 584usb.bulkTransfer(devicepipe, endpoint, buffer).then((ret: number) => { 585 console.log(`bulkTransfer = ${ret}`); 586}); 587``` 588 589## usb.closePipe 590 591closePipe(pipe: USBDevicePipe): number 592 593Closes a USB device pipe. 594 595Before 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. 596 597**System capability**: SystemCapability.USB.USBManager 598 599**Parameters** 600 601| Name| Type| Mandatory| Description| 602| -------- | -------- | -------- | -------- | 603| pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe.| 604 605**Return value** 606 607| Type| Description| 608| -------- | -------- | 609| number | Returns **0** if the USB device pipe is closed successfully; returns an error code otherwise.| 610 611**Example** 612 613```ts 614let devicesList: Array<usb.USBDevice> = usb.getDevices(); 615if (devicesList.length == 0) { 616 console.log(`device list is empty`); 617} 618 619usb.requestRight(devicesList[0].name); 620let devicepipe: usb.USBDevicePipe = usb.connectDevice(devicesList[0]); 621let ret: number = usb.closePipe(devicepipe); 622console.log(`closePipe = ${ret}`); 623``` 624 625## usb.usbFunctionsFromString 626 627usbFunctionsFromString(funcs: string): number 628 629Converts the USB function list in the string format to a numeric mask in Device mode. 630 631**System API**: This is a system API. 632 633**System capability**: SystemCapability.USB.USBManager 634 635**Parameters** 636 637| Name| Type | Mandatory| Description | 638| ------ | ------ | ---- | ---------------------- | 639| funcs | string | Yes | Function list in string format.| 640 641**Return value** 642 643| Type | Description | 644| ------ | ------------------ | 645| number | Function list in numeric mask format.| 646 647**Example** 648 649```ts 650let funcs: string = "acm"; 651let ret: number = usb.usbFunctionsFromString(funcs); 652``` 653 654## usb.usbFunctionsToString 655 656usbFunctionsToString(funcs: FunctionType): string 657 658Converts the USB function list in the numeric mask format to a string in Device mode. 659 660**System API**: This is a system API. 661 662**System capability**: SystemCapability.USB.USBManager 663 664**Parameters** 665 666| Name| Type | Mandatory| Description | 667| ------ | ------------------------------ | ---- | ----------------- | 668| funcs | [FunctionType](#functiontype) | Yes | USB function list in numeric mask format.| 669 670**Return value** 671 672| Type | Description | 673| ------ | ------------------------------ | 674| string | Function list in string format.| 675 676**Example** 677 678```ts 679let funcs: number = usb.FunctionType.ACM | usb.FunctionType.ECM; 680let ret: string = usb.usbFunctionsToString(funcs); 681``` 682 683## usb.setCurrentFunctions 684 685setCurrentFunctions(funcs: FunctionType): Promise\<void\> 686 687Sets the current USB function list in Device mode. 688 689**System API**: This is a system API. 690 691**System capability**: SystemCapability.USB.USBManager 692 693**Parameters** 694 695| Name| Type | Mandatory| Description | 696| ------ | ------------------------------ | ---- | ----------------- | 697| funcs | [FunctionType](#functiontype) | Yes | USB function list in numeric mask format.| 698 699**Error codes** 700 701For details about the error codes, see [USB Service Error Codes](../errorcodes/errorcode-usb.md). 702 703| ID| Error Message | 704| -------- | ---------------------------------------------------- | 705| 14400002 | Permission denied.The HDC is disabled by the system. | 706 707**Return value** 708 709| Type | Description | 710| --------------- | ------------- | 711| Promise\<void\> | Promise used to return the result.| 712 713**Example** 714 715```ts 716import {BusinessError} from '@ohos.base'; 717let funcs: number = usb.FunctionType.HDC; 718usb.setCurrentFunctions(funcs).then(() => { 719 console.info('usb setCurrentFunctions successfully.'); 720}).catch((err: BusinessError) => { 721 console.error('usb setCurrentFunctions failed: ' + err.code + ' message: ' + err.message); 722}); 723``` 724 725## usb.getCurrentFunctions 726 727getCurrentFunctions(): FunctionType 728 729Obtains the numeric mask combination for the USB function list in Device mode. 730 731**System API**: This is a system API. 732 733**System capability**: SystemCapability.USB.USBManager 734 735**Return value** 736 737| Type | Description | 738| ------------------------------ | --------------------------------- | 739| [FunctionType](#functiontype) | Numeric mask combination for the USB function list.| 740 741**Example** 742 743```ts 744let ret: number = usb.getCurrentFunctions(); 745``` 746 747## usb.getPorts 748 749getPorts(): Array\<USBPort\> 750 751Obtains the list of all physical USB ports. 752 753**System API**: This is a system API. 754 755**System capability**: SystemCapability.USB.USBManager 756 757**Return value** 758 759| Type | Description | 760| ----------------------------- | --------------------- | 761| Array<[USBPort](#usbport)> | List of physical USB ports.| 762 763**Example** 764 765```ts 766let ret: Array<usb.USBPort> = usb.getPorts(); 767``` 768 769## usb.getSupportedModes 770 771getSupportedModes(portId: number): PortModeType 772 773Obtains the mask combination for the supported mode list of a given USB port. 774 775**System API**: This is a system API. 776 777**System capability**: SystemCapability.USB.USBManager 778 779**Parameters** 780 781| Name| Type | Mandatory| Description | 782| ------ | ------ | ---- | -------- | 783| portId | number | Yes | Port number.| 784 785**Return value** 786 787| Type | Description | 788| ------------------------------ | -------------------------- | 789| [PortModeType](#portmodetype) | Mask combination for the supported mode list.| 790 791**Example** 792 793```ts 794let ret: number = usb.getSupportedModes(0); 795``` 796 797## usb.setPortRoles 798 799setPortRoles(portId: number, powerRole: PowerRoleType, dataRole: DataRoleType): Promise\<void\> 800 801Sets the role types supported by a specified port, which can be **powerRole** (for charging) and **dataRole** (for data transfer). 802 803**System API**: This is a system API. 804 805**System capability**: SystemCapability.USB.USBManager 806 807**Parameters** 808 809| Name | Type | Mandatory| Description | 810| --------- | -------------------------------- | ---- | ---------------- | 811| portId | number | Yes | Port number. | 812| powerRole | [PowerRoleType](#powerroletype) | Yes | Role for charging. | 813| dataRole | [DataRoleType](#dataroletype) | Yes | Role for data transfer.| 814 815**Return value** 816 817| Type | Description | 818| --------------- | ------------- | 819| Promise\<void\> | Promise used to return the result.| 820 821**Example** 822 823```ts 824import {BusinessError} from '@ohos.base'; 825let portId: number = 1; 826usb.setPortRoles(portId, usb.PowerRoleType.SOURCE, usb.DataRoleType.HOST).then(() => { 827 console.info('usb setPortRoles successfully.'); 828}).catch((err: BusinessError) => { 829 console.error('usb setPortRoles failed: ' + err.code + ' message: ' + err.message); 830}); 831``` 832 833## USBEndpoint 834 835Represents the USB endpoint from which data is sent or received. You can obtain the USB endpoint through [USBInterface](#usbinterface). 836 837**System capability**: SystemCapability.USB.USBManager 838 839| Name | Type | Mandatory |Description | 840| ------------- | ------------------------------------------- | ------------- |------------- | 841| address | number | Yes|Endpoint address. | 842| attributes | number | Yes|Endpoint attributes. | 843| interval | number | Yes|Endpoint interval. | 844| maxPacketSize | number | Yes|Maximum size of data packets on the endpoint. | 845| direction | [USBRequestDirection](#usbrequestdirection) | Yes|Endpoint direction. | 846| number | number | Yes|Endpoint number. | 847| type | number | Yes|Endpoint type. | 848| interfaceId | number | Yes|Unique ID of the interface to which the endpoint belongs.| 849 850## USBInterface 851 852Represents a USB interface. One [USBConfiguration](#usbconfiguration) object can contain multiple **USBInterface** instances, each providing a specific function. 853 854**System capability**: SystemCapability.USB.USBManager 855 856| Name | Type | Mandatory |Description | 857| ---------------- | ---------------------------------------- | ------------- |--------------------- | 858| id | number | Yes|Unique ID of the USB interface. | 859| protocol | number | Yes|Interface protocol. | 860| clazz | number | Yes|Device type. | 861| subClass | number | Yes|Device subclass. | 862| alternateSetting | number | Yes|Settings for alternating between descriptors of the same USB interface.| 863| name | string | Yes|Interface name. | 864| endpoints | Array<[USBEndpoint](#usbendpoint)> | Yes|Endpoints that belong to the USB interface. | 865 866## USBConfiguration 867 868Represents the USB configuration. One [USBDevice](#usbdevice) can contain multiple **USBConfig** instances. 869 870**System capability**: SystemCapability.USB.USBManager 871 872| Name | Type | Mandatory |Description | 873| -------------- | ------------------------------------------------ | --------------- |--------------- | 874| id | number | Yes|Unique ID of the USB configuration. | 875| attributes | number | Yes|Configuration attributes. | 876| maxPower | number | Yes|Maximum power consumption, in mA. | 877| name | string | Yes|Configuration name, which can be left empty. | 878| isRemoteWakeup | boolean | Yes|Support for remote wakeup.| 879| isSelfPowered | boolean | Yes| Support for independent power supplies.| 880| interfaces | Array <[USBInterface](#usbinterface)> | Yes|Supported interface attributes. | 881 882## USBDevice 883 884Represents the USB device information. 885 886**System capability**: SystemCapability.USB.USBManager 887 888| Name | Type | Mandatory |Description | 889| ---------------- | ------------------------------------ | ---------- |---------- | 890| busNum | number | Yes|Bus address. | 891| devAddress | number | Yes|Device address. | 892| serial | string | Yes|Sequence number. | 893| name | string | Yes|Device name. | 894| manufacturerName | string | Yes| Device manufacturer. | 895| productName | string | Yes|Product name. | 896| version | string | Yes|Version number. | 897| vendorId | number | Yes|Vendor ID. | 898| productId | number | Yes|Product ID. | 899| clazz | number | Yes|Device class. | 900| subClass | number | Yes|Device subclass. | 901| protocol | number | Yes|Device protocol code. | 902| configs | Array<[USBConfiguration](#usbconfiguration)> | Yes|Device configuration descriptor information.| 903 904## USBDevicePipe 905 906Represents a USB device pipe, which is used to determine a USB device. 907 908**System capability**: SystemCapability.USB.USBManager 909 910| Name | Type | Mandatory |Description | 911| ---------- | ------ | ----- |----- | 912| busNum | number |Yes| Bus address.| 913| devAddress | number |Yes| Device address.| 914 915## USBControlParams 916 917Represents control transfer parameters. 918 919**System capability**: SystemCapability.USB.USBManager 920 921| Name | Type | Mandatory |Description | 922| ------- | ----------------------------------------------- | ---------------- |---------------- | 923| request | number | Yes |Request type. | 924| target | [USBRequestTargetType](#usbrequesttargettype) | Yes |Request target type. | 925| reqType | [USBControlRequestType](#usbcontrolrequesttype) | Yes |Control request type. | 926| value | number | Yes |Request parameter value. | 927| index | number | Yes |Index of the request parameter value.| 928| data | Uint8Array | Yes |Buffer for writing or reading data. | 929 930## USBPort 931 932Represents a USB port. 933 934**System API**: This is a system API. 935 936**System capability**: SystemCapability.USB.USBManager 937 938| Name | Type | Mandatory |Description | 939| -------------- | ------------------------------- | ------------------- |------------------------ | 940| id | number | Yes |Unique identifier of a USB port. | 941| supportedModes | [PortModeType](#portmodetype) | Yes |Numeric mask combination for the supported mode list.| 942| status | [USBPortStatus](#usbportstatus) | Yes |USB port role. | 943 944## USBPortStatus 945 946Enumerates USB port roles. 947 948**System API**: This is a system API. 949 950**System capability**: SystemCapability.USB.USBManager 951 952| Name | Type| Mandatory |Description | 953| ---------------- | -------- | ---------------- |---------------------- | 954| currentMode | number | Yes|Current USB mode. | 955| currentPowerRole | number | Yes |Current power role. | 956| currentDataRole | number | Yes |Current data role.| 957 958## USBRequestTargetType 959 960Enumerates request target types. 961 962**System capability**: SystemCapability.USB.USBManager 963 964| Name | Value | Description | 965| ---------------------------- | ---- | ------ | 966| USB_REQUEST_TARGET_DEVICE | 0 | Device.| 967| USB_REQUEST_TARGET_INTERFACE | 1 | Interface.| 968| USB_REQUEST_TARGET_ENDPOINT | 2 | Endpoint.| 969| USB_REQUEST_TARGET_OTHER | 3 | Other.| 970 971## USBControlRequestType 972 973Enumerates control request types. 974 975**System capability**: SystemCapability.USB.USBManager 976 977| Name | Value | Description | 978| ------------------------- | ---- | ------ | 979| USB_REQUEST_TYPE_STANDARD | 0 | Standard.| 980| USB_REQUEST_TYPE_CLASS | 1 | Class. | 981| USB_REQUEST_TYPE_VENDOR | 2 | Vendor.| 982 983## USBRequestDirection 984 985Enumerates request directions. 986 987**System capability**: SystemCapability.USB.USBManager 988 989| Name | Value | Description | 990| --------------------------- | ---- | ------------------------ | 991| USB_REQUEST_DIR_TO_DEVICE | 0 | Request for writing data from the host to the device.| 992| USB_REQUEST_DIR_FROM_DEVICE | 0x80 | Request for reading data from the device to the host.| 993 994## FunctionType 995 996Enumerates USB device function types. 997 998**System API**: This is a system API. 999 1000**System capability**: SystemCapability.USB.USBManager 1001 1002| Name | Value | Description | 1003| ------------ | ---- | ---------- | 1004| NONE | 0 | No function.| 1005| ACM | 1 | ACM function. | 1006| ECM | 2 | ECM function. | 1007| HDC | 4 | HDC function. | 1008| MTP | 8 | Not supported currently.| 1009| PTP | 16 | Not supported currently.| 1010| RNDIS | 32 | Not supported currently.| 1011| MIDI | 64 | Not supported currently.| 1012| AUDIO_SOURCE | 128 | Not supported currently.| 1013| NCM | 256 | Not supported currently.| 1014 1015## PortModeType 1016 1017Enumerates USB port mode types. 1018 1019**System API**: This is a system API. 1020 1021**System capability**: SystemCapability.USB.USBManager 1022 1023| Name | Value | Description | 1024| --------- | ---- | ---------------------------------------------------- | 1025| NONE | 0 | None | 1026| UFP | 1 | Upstream facing port, which functions as the sink of power supply. | 1027| DFP | 2 | Downstream facing port, which functions as the source of power supply. | 1028| DRP | 3 | Dynamic reconfiguration port (DRP), which can function as the DFP (host) or UFP (device). It is not supported currently.| 1029| NUM_MODES | 4 | Not supported currently. | 1030 1031## PowerRoleType 1032 1033Enumerates power role types. 1034 1035**System API**: This is a system API. 1036 1037**System capability**: SystemCapability.USB.USBManager 1038 1039| Name | Value | Description | 1040| ------ | ---- | ---------- | 1041| NONE | 0 | None | 1042| SOURCE | 1 | External power supply.| 1043| SINK | 2 | Internal power supply.| 1044 1045## DataRoleType 1046 1047Enumerates data role types. 1048 1049**System API**: This is a system API. 1050 1051**System capability**: SystemCapability.USB.USBManager 1052 1053| Name | Value | Description | 1054| ------ | ---- | ------------ | 1055| NONE | 0 | None | 1056| HOST | 1 | USB host.| 1057| DEVICE | 2 | USB device.| 1058