1 # @ohos.usbManager (USB Manager) 2 3 The **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 12 import usb from "@ohos.usbManager"; 13 ``` 14 15 ## usb.getDevices 16 17 getDevices(): Array<Readonly<USBDevice>> 18 19 Obtains 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 32 let devicesList: Array<usb.USBDevice> = usb.getDevices(); 33 console.log(`devicesList = ${devicesList}`); 34 /* 35 The 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 89 connectDevice(device: USBDevice): Readonly<USBDevicePipe> 90 91 Connects to the USB device based on the device information returned by **getDevices()**. 92 93 Before 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 111 For 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 120 let devicesList: Array<usb.USBDevice> = usb.getDevices(); 121 if (devicesList.length == 0) { 122 console.log(`device list is empty`); 123 } 124 125 let device: usb.USBDevice = devicesList[0]; 126 usb.requestRight(device.name); 127 let devicepipe: usb.USBDevicePipe = usb.connectDevice(device); 128 console.log(`devicepipe = ${devicepipe}`); 129 ``` 130 131 ## usb.hasRight 132 133 hasRight(deviceName: string): boolean 134 135 Checks whether the application has the permission to access the device. 136 137 Checks 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 156 let devicesName: string = "1-1"; 157 let right: boolean = usb.hasRight(devicesName); 158 console.log(`${right}`); 159 ``` 160 161 ## usb.requestRight 162 163 requestRight(deviceName: string): Promise<boolean> 164 165 Requests 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 184 let devicesName: string = "1-1"; 185 usb.requestRight(devicesName).then(ret => { 186 console.log(`requestRight = ${ret}`); 187 }); 188 ``` 189 190 ## usb.removeRight 191 192 removeRight(deviceName: string): boolean 193 194 Removes 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 213 let devicesName: string = "1-1"; 214 if (usb.removeRight(devicesName)) { 215 console.log(`Succeed in removing right`); 216 } 217 ``` 218 219 ## usb.addRight 220 221 addRight(bundleName: string, deviceName: string): boolean 222 223 Adds 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 247 let devicesName: string = "1-1"; 248 let bundleName: string = "com.example.hello"; 249 if (usb.addRight(bundleName, devicesName)) { 250 console.log(`Succeed in adding right`); 251 } 252 ``` 253 254 ## usb.claimInterface 255 256 claimInterface(pipe: USBDevicePipe, iface: USBInterface, force ?: boolean): number 257 258 Claims a USB interface. 259 260 Before 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 281 let devicesList: Array<usb.USBDevice> = usb.getDevices(); 282 if (devicesList.length == 0) { 283 console.log(`device list is empty`); 284 } 285 286 let device: usb.USBDevice = devicesList[0]; 287 usb.requestRight(device.name); 288 let devicepipe: usb.USBDevicePipe = usb.connectDevice(device); 289 let interfaces: usb.USBInterface = device.configs[0].interfaces[0]; 290 let ret: number= usb.claimInterface(devicepipe, interfaces); 291 console.log(`claimInterface = ${ret}`); 292 ``` 293 294 ## usb.releaseInterface 295 296 releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number 297 298 Releases a USB interface. 299 300 Before 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 320 let devicesList: Array<usb.USBDevice> = usb.getDevices(); 321 if (devicesList.length == 0) { 322 console.log(`device list is empty`); 323 } 324 325 let device: usb.USBDevice = devicesList[0]; 326 usb.requestRight(device.name); 327 let devicepipe: usb.USBDevicePipe = usb.connectDevice(device); 328 let interfaces: usb.USBInterface = device.configs[0].interfaces[0]; 329 let ret: number = usb.claimInterface(devicepipe, interfaces); 330 ret = usb.releaseInterface(devicepipe, interfaces); 331 console.log(`releaseInterface = ${ret}`); 332 ``` 333 334 ## usb.setConfiguration 335 336 setConfiguration(pipe: USBDevicePipe, config: USBConfiguration): number 337 338 Sets the device configuration. 339 340 Before 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 360 let devicesList: Array<usb.USBDevice> = usb.getDevices(); 361 if (devicesList.length == 0) { 362 console.log(`device list is empty`); 363 } 364 365 let device: usb.USBDevice = devicesList[0]; 366 usb.requestRight(device.name); 367 let devicepipe: usb.USBDevicePipe = usb.connectDevice(device); 368 let config: usb.USBConfiguration = device.configs[0]; 369 let ret: number= usb.setConfiguration(devicepipe, config); 370 console.log(`setConfiguration = ${ret}`); 371 ``` 372 373 ## usb.setInterface 374 375 setInterface(pipe: USBDevicePipe, iface: USBInterface): number 376 377 Sets a USB interface. 378 379 Before 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 399 let devicesList: Array<usb.USBDevice> = usb.getDevices(); 400 if (devicesList.length == 0) { 401 console.log(`device list is empty`); 402 } 403 404 let device: usb.USBDevice = devicesList[0]; 405 usb.requestRight(device.name); 406 let devicepipe: usb.USBDevicePipe = usb.connectDevice(device); 407 let interfaces: usb.USBInterface = device.configs[0].interfaces[0]; 408 let ret: number = usb.claimInterface(devicepipe, interfaces); 409 ret = usb.setInterface(devicepipe, interfaces); 410 console.log(`setInterface = ${ret}`); 411 ``` 412 413 ## usb.getRawDescriptor 414 415 getRawDescriptor(pipe: USBDevicePipe): Uint8Array 416 417 Obtains the raw USB descriptor. 418 419 Before 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 438 let devicesList: Array<usb.USBDevice> = usb.getDevices(); 439 if (devicesList.length == 0) { 440 console.log(`device list is empty`); 441 } 442 443 usb.requestRight(devicesList[0].name); 444 let devicepipe: usb.USBDevicePipe = usb.connectDevice(devicesList[0]); 445 let ret: Uint8Array = usb.getRawDescriptor(devicepipe); 446 ``` 447 448 ## usb.getFileDescriptor 449 450 getFileDescriptor(pipe: USBDevicePipe): number 451 452 Obtains the file descriptor. 453 454 Before 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 473 let devicesList: Array<usb.USBDevice> = usb.getDevices(); 474 if (devicesList.length == 0) { 475 console.log(`device list is empty`); 476 } 477 478 usb.requestRight(devicesList[0].name); 479 let devicepipe: usb.USBDevicePipe = usb.connectDevice(devicesList[0]); 480 let ret: number = usb.getFileDescriptor(devicepipe); 481 ``` 482 483 ## usb.controlTransfer 484 485 controlTransfer(pipe: USBDevicePipe, controlparam: USBControlParams, timeout ?: number): Promise<number> 486 487 Performs control transfer. 488 489 Before 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 510 class 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 519 let param: PARA = { 520 request: 0, 521 reqType: 0, 522 target:0, 523 value: 0, 524 index: 0, 525 data: new Uint8Array() 526 }; 527 528 let devicesList: Array<usb.USBDevice> = usb.getDevices(); 529 if (devicesList.length == 0) { 530 console.log(`device list is empty`); 531 } 532 533 usb.requestRight(devicesList[0].name); 534 let devicepipe: usb.USBDevicePipe = usb.connectDevice(devicesList[0]); 535 usb.controlTransfer(devicepipe, param).then((ret: number) => { 536 console.log(`controlTransfer = ${ret}`); 537 }) 538 ``` 539 540 ## usb.bulkTransfer 541 542 bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, timeout ?: number): Promise<number> 543 544 Performs bulk transfer. 545 546 Before 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. 571 let devicesList: Array<usb.USBDevice> = usb.getDevices(); 572 if (devicesList.length == 0) { 573 console.log(`device list is empty`); 574 } 575 576 let device: usb.USBDevice = devicesList[0]; 577 usb.requestRight(device.name); 578 579 let devicepipe: usb.USBDevicePipe = usb.connectDevice(device); 580 let interfaces: usb.USBInterface = device.configs[0].interfaces[0]; 581 let endpoint: usb.USBEndpoint = device.configs[0].interfaces[0].endpoints[0]; 582 let ret: number = usb.claimInterface(devicepipe, interfaces); 583 let buffer = new Uint8Array(128); 584 usb.bulkTransfer(devicepipe, endpoint, buffer).then((ret: number) => { 585 console.log(`bulkTransfer = ${ret}`); 586 }); 587 ``` 588 589 ## usb.closePipe 590 591 closePipe(pipe: USBDevicePipe): number 592 593 Closes a USB device pipe. 594 595 Before 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 614 let devicesList: Array<usb.USBDevice> = usb.getDevices(); 615 if (devicesList.length == 0) { 616 console.log(`device list is empty`); 617 } 618 619 usb.requestRight(devicesList[0].name); 620 let devicepipe: usb.USBDevicePipe = usb.connectDevice(devicesList[0]); 621 let ret: number = usb.closePipe(devicepipe); 622 console.log(`closePipe = ${ret}`); 623 ``` 624 625 ## usb.usbFunctionsFromString 626 627 usbFunctionsFromString(funcs: string): number 628 629 Converts 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 650 let funcs: string = "acm"; 651 let ret: number = usb.usbFunctionsFromString(funcs); 652 ``` 653 654 ## usb.usbFunctionsToString 655 656 usbFunctionsToString(funcs: FunctionType): string 657 658 Converts 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 679 let funcs: number = usb.FunctionType.ACM | usb.FunctionType.ECM; 680 let ret: string = usb.usbFunctionsToString(funcs); 681 ``` 682 683 ## usb.setCurrentFunctions 684 685 setCurrentFunctions(funcs: FunctionType): Promise\<void\> 686 687 Sets 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 701 For 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 716 import {BusinessError} from '@ohos.base'; 717 let funcs: number = usb.FunctionType.HDC; 718 usb.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 727 getCurrentFunctions(): FunctionType 728 729 Obtains 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 744 let ret: number = usb.getCurrentFunctions(); 745 ``` 746 747 ## usb.getPorts 748 749 getPorts(): Array\<USBPort\> 750 751 Obtains 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 766 let ret: Array<usb.USBPort> = usb.getPorts(); 767 ``` 768 769 ## usb.getSupportedModes 770 771 getSupportedModes(portId: number): PortModeType 772 773 Obtains 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 794 let ret: number = usb.getSupportedModes(0); 795 ``` 796 797 ## usb.setPortRoles 798 799 setPortRoles(portId: number, powerRole: PowerRoleType, dataRole: DataRoleType): Promise\<void\> 800 801 Sets 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 824 import {BusinessError} from '@ohos.base'; 825 let portId: number = 1; 826 usb.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 835 Represents 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 852 Represents 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 868 Represents 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 884 Represents 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 906 Represents 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 917 Represents 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 932 Represents 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 946 Enumerates 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 960 Enumerates 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 973 Enumerates 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 985 Enumerates 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 996 Enumerates 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 1017 Enumerates 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 1033 Enumerates 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 1047 Enumerates 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