1/* 2 * Copyright (c) 2021-2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @deprecated since 9 18 * @useinstead ohos.usbManager 19 */ 20declare namespace usb { 21 /** 22 * Obtains the USB device list. 23 * 24 * @returns Returns the {@link USBDevice} list. 25 * @syscap SystemCapability.USB.USBManager 26 * @since 8 27 */ 28 function getDevices(): Array<Readonly<USBDevice>>; 29 30 /** 31 * Connects to the USB device based on the device information returned by {@link getDevices()}. 32 * 33 * @param device USB device on the device list returned by {@link getDevices()}. 34 * @returns Returns the {@link USBDevicePipe} object for data transfer. 35 * @syscap SystemCapability.USB.USBManager 36 * @since 8 37 */ 38 function connectDevice(device: USBDevice): Readonly<USBDevicePipe>; 39 40 /** 41 * Checks whether the application has the permission to access the device. 42 * 43 * @param deviceName Device name defined by {@link USBDevice.name}. 44 * @returns Returns **true** if the user has the permission to access the device; return **false** otherwise. 45 * @syscap SystemCapability.USB.USBManager 46 * @since 8 47 */ 48 function hasRight(deviceName: string): boolean; 49 50 /** 51 * Requests the temporary permission for a given application to access the USB device. 52 * 53 * @param deviceName Device name defined by {@link USBDevice.name}. 54 * @returns Returns **true** if the temporary device access permissions are granted; return **false** otherwise. 55 * @syscap SystemCapability.USB.USBManager 56 * @since 8 57 */ 58 function requestRight(deviceName: string): Promise<boolean>; 59 60 /** 61 * Converts the string descriptor of a given USB function list to a numeric mask combination. 62 * 63 * @param funcs Descriptor of the supported function list. 64 * @returns Returns the numeric mask combination of the function list. 65 * @systemapi 66 * @syscap SystemCapability.USB.USBManager 67 * @since 9 68 */ 69 function usbFunctionsFromString(funcs: string): number; 70 71 /** 72 * Converts the numeric mask combination of a given USB function list to a string descriptor. 73 * 74 * @param funcs Numeric mask combination of the function list. 75 * @returns Returns the string descriptor of the supported function list. 76 * @systemapi 77 * @syscap SystemCapability.USB.USBManager 78 * @since 9 79 */ 80 function usbFunctionsToString(funcs: FunctionType): string; 81 82 /** 83 * Sets the current USB function list in Device mode. 84 * 85 * @param funcs Numeric mask combination of the supported function list. 86 * @returns Returns **true** if the setting is successful; returns **false** otherwise. 87 * @systemapi 88 * @syscap SystemCapability.USB.USBManager 89 * @since 9 90 */ 91 function setCurrentFunctions(funcs: FunctionType): Promise<boolean>; 92 93 /** 94 * Obtains the numeric mask combination for the current USB function list in Device mode. 95 * 96 * @returns Returns the numeric mask combination for the current USB function list in {@link FunctionType}. 97 * @systemapi 98 * @syscap SystemCapability.USB.USBManager 99 * @since 9 100 */ 101 function getCurrentFunctions(): FunctionType; 102 103 /* usb port functions begin */ 104 /** 105 * Obtains the {@link USBPort} list. 106 * 107 * @returns Returns the {@link USBPort} list. 108 * @systemapi 109 * @syscap SystemCapability.USB.USBManager 110 * @since 9 111 */ 112 function getPorts(): Array<USBPort>; 113 114 /** 115 * Gets the mask combination for the supported mode list of the specified {@link USBPort}. 116 * 117 * @returns Returns the mask combination for the supported mode list in {@link PortModeType}. 118 * @systemapi 119 * @syscap SystemCapability.USB.USBManager 120 * @since 9 121 */ 122 function getSupportedModes(portId: number): PortModeType; 123 124 /** 125 * Sets the role types supported by the specified {@link USBPort}, which can be powerRole (for charging) and dataRole (for data transfer). 126 * 127 * @param portId Unique ID of the port. 128 * @param powerRole Charging role defined by {@link PowerRoleType}. 129 * @param dataRole Data role defined by {@link DataRoleType}. 130 * @returns Returns the supported role type. 131 * @systemapi 132 * @syscap SystemCapability.USB.USBManager 133 * @since 9 134 */ 135 function setPortRoles(portId: number, powerRole: PowerRoleType, dataRole: DataRoleType): Promise<boolean>; 136 137 /* usb pipe functions begin */ 138 /** 139 * Claims a USB interface. 140 * 141 * @param pipe Device pipe defined by {@link USBDevicePipe}, which is used to determine the bus number and device address. 142 * @param iface USB interface defined by {@link USBInterface}, which is used to determine the interface to claim. 143 * @param force Optional parameter that determines whether to forcibly claim the USB interface. 144 * @returns Returns **0** if the USB interface is successfully claimed; returns an error code otherwise. 145 * @syscap SystemCapability.USB.USBManager 146 * @since 8 147 */ 148 function claimInterface(pipe: USBDevicePipe, iface: USBInterface, force?: boolean): number; 149 150 /** 151 * Releases a USB interface. 152 * 153 * @param pipe Device pipe defined by {@link USBDevicePipe}, which is used to determine the bus number and device address. 154 * @param iface USB interface defined by {@link USBInterface}, which is used to determine the interface to release. 155 * @returns Returns **0** if the USB interface is successfully released; returns an error code otherwise. 156 * @syscap SystemCapability.USB.USBManager 157 * @since 8 158 */ 159 function releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number; 160 161 /** 162 * Sets the device configuration. 163 * 164 * @param pipe Device pipe defined by {@link USBDevicePipe}, which is used to determine the bus number and device address. 165 * @param config Device configuration defined by {@link USBConfig}. 166 * @returns Returns **0** if the device configuration is successfully set; returns an error code otherwise. 167 * @syscap SystemCapability.USB.USBManager 168 * @since 8 169 */ 170 function setConfiguration(pipe: USBDevicePipe, config: USBConfig): number; 171 172 /** 173 * Sets a USB interface. 174 * 175 * @param pipe Device pipe defined by {@link USBDevicePipe}, which is used to determine the bus number and device address. 176 * @param iface USB interface defined by {@link USBInterface}, which is used to determine the interface to set. 177 * @returns Returns **0** if the USB interface is successfully set; return an error code otherwise. 178 * @syscap SystemCapability.USB.USBManager 179 * @since 8 180 */ 181 function setInterface(pipe: USBDevicePipe, iface: USBInterface): number; 182 183 /** 184 * Obtains the raw USB descriptor. 185 * 186 * @param pipe Device pipe defined by {@link USBDevicePipe}, which is used to determine the bus number and device address. 187 * @returns Returns the raw descriptor data. 188 * @syscap SystemCapability.USB.USBManager 189 * @since 8 190 */ 191 function getRawDescriptor(pipe: USBDevicePipe): Uint8Array; 192 193 /** 194 * Obtains the file descriptor. 195 * 196 * @param pipe Device pipe defined by {@link USBDevicePipe}, which is used to determine the USB device. 197 * @returns Returns the file descriptor of the USB device. 198 * @syscap SystemCapability.USB.USBManager 199 * @since 8 200 */ 201 function getFileDescriptor(pipe: USBDevicePipe): number; 202 203 /** 204 * Performs control transfer. 205 * 206 * @param pipe Device pipe defined by {@link USBDevicePipe}, which is used to determine the USB device. 207 * @param controlparam Control transfer parameters. 208 * @param timeout Timeout duration. This parameter is optional. The default value is **0**, indicating no timeout. 209 * @returns Returns the size of the transmitted or received data block if the control transfer is successful; return **-1** if an exception occurs. 210 * @syscap SystemCapability.USB.USBManager 211 * @since 8 212 */ 213 function controlTransfer(pipe: USBDevicePipe, controlparam: USBControlParams, timeout?: number): Promise<number>; 214 215 /** 216 * Performs bulk transfer. 217 * 218 * @param pipe Device pipe defined by {@link USBDevicePipe}, which is used to determine the USB device. 219 * @param endpoint USB endpoint defined by {@link USBEndpoint}, which is used to determine the USB port for data transfer. 220 * @param buffer Buffer for writing or reading data. 221 * @param timeout Timeout duration. This parameter is optional. The default value is **0**, indicating no timeout. 222 * @returns Returns the size of the transmitted or received data block if the control transfer is successful; return **-1** if an exception occurs. 223 * @syscap SystemCapability.USB.USBManager 224 * @since 8 225 */ 226 function bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, 227 timeout?: number): Promise<number>; 228 229 /** 230 * Closes a USB device pipe. 231 * 232 * @param pipe Device pipe defined by {@link USBDevicePipe}, which is used to determine the USB device. 233 * @returns Returns **0** if the USB device pipe is closed successfully; return an error code otherwise. 234 * @syscap SystemCapability.USB.USBManager 235 * @since 8 236 */ 237 function closePipe(pipe: USBDevicePipe): number; 238 239 /** 240 * Represents the USB endpoint from which data is sent or received. You can obtain the USB endpoint through {@link USBInterface}. 241 * 242 * @syscap SystemCapability.USB.USBManager 243 * @since 8 244 */ 245 interface USBEndpoint { 246 /** 247 * Endpoint address 248 * 249 * @since 8 250 */ 251 address: number; 252 253 /** 254 * Endpoint attributes 255 * 256 * @since 8 257 */ 258 attributes: number; 259 260 /** 261 * Endpoint interval 262 * 263 * @since 8 264 */ 265 interval: number; 266 267 /** 268 * Maximum size of data packets on the endpoint 269 * 270 * @since 8 271 */ 272 maxPacketSize: number; 273 274 /** 275 * Endpoint direction 276 * 277 * @since 8 278 */ 279 direction: USBRequestDirection; 280 281 /** 282 * Endpoint number 283 * 284 * @since 8 285 */ 286 number: number; 287 288 /** 289 * Endpoint type 290 * 291 * @since 8 292 */ 293 type: number; 294 295 /** 296 * Unique ID defined by {@link USBInterface.id}, which indicates the interface to which the endpoint belongs 297 * 298 * @since 8 299 */ 300 interfaceId: number; 301 } 302 303 304 /** 305 * Represents a USB interface. One config {@link USBConfig} can contain multiple **USBInterface** instances, each providing a specific function. 306 * 307 * @syscap SystemCapability.USB.USBManager 308 * @since 8 309 */ 310 interface USBInterface { 311 /** 312 * Unique ID of the USB interface 313 * 314 * @since 8 315 */ 316 id: number; 317 318 /** 319 * Interface protocol 320 * 321 * @since 8 322 */ 323 protocol: number; 324 325 /** 326 * Device type 327 * 328 * @since 8 329 */ 330 clazz: number; 331 332 /** 333 * Device subclass 334 * 335 * @since 8 336 */ 337 subClass: number; 338 339 /** 340 * Alternation between descriptors of the same USB interface 341 * 342 * @since 8 343 */ 344 alternateSetting: number; 345 346 /** 347 * Interface name 348 * 349 * @since 8 350 */ 351 name: string; 352 353 /** 354 * {@link USBEndpoint} that belongs to the USB interface 355 * 356 * @since 8 357 */ 358 endpoints: Array<USBEndpoint>; 359 } 360 361 /** 362 * USB configuration. One {@link USBDevice} can contain multiple USBConfig instances. 363 * 364 * @syscap SystemCapability.USB.USBManager 365 * @since 8 366 */ 367 interface USBConfig { 368 /** 369 * Unique ID of the USB configuration 370 * 371 * @since 8 372 * 373 * 374 */ 375 id: number; 376 377 /** 378 * Configuration attributes 379 * 380 * @since 8 381 */ 382 attributes: number; 383 384 /** 385 * Maximum power consumption, in mA 386 * 387 * @since 8 388 */ 389 maxPower: number; 390 391 /** 392 * Configuration name, which can be left empty 393 * 394 * @since 8 395 */ 396 name: string; 397 398 /** 399 * Support for remote wakeup 400 * 401 * @since 8 402 */ 403 isRemoteWakeup: boolean; 404 405 /** 406 * Support for independent power supplies 407 * 408 * @since 8 409 */ 410 isSelfPowered: boolean; 411 412 /** 413 * Supported interface attributes defined by {@link USBInterface} 414 * 415 * @since 8 416 */ 417 interfaces: Array<USBInterface>; 418 } 419 420 /** 421 * Represents a USB device. 422 * 423 * @syscap SystemCapability.USB.USBManager 424 * @since 8 425 */ 426 interface USBDevice { 427 /** 428 * Bus address 429 * 430 * @since 8 431 */ 432 busNum: number; 433 434 /** 435 * Device address 436 * 437 * @since 8 438 */ 439 devAddress: number; 440 441 /** 442 * Device SN 443 * 444 * @since 8 445 */ 446 serial: string; 447 448 /** 449 * Device name 450 * 451 * @since 8 452 */ 453 name: string; 454 455 /** 456 * Device manufacturer 457 * 458 * @since 8 459 */ 460 manufacturerName: string; 461 462 /** 463 * Product information 464 * 465 * @since 8 466 */ 467 productName: string; 468 469 /** 470 * Product version 471 * 472 * @since 8 473 */ 474 version: string; 475 476 /** 477 * Vendor ID 478 * 479 * @since 8 480 */ 481 vendorId: number; 482 483 /** 484 * Product ID 485 * 486 * @since 8 487 */ 488 productId: number; 489 490 /** 491 * Device class 492 * 493 * @since 8 494 */ 495 clazz: number; 496 497 /** 498 * Device subclass 499 * 500 * @since 8 501 */ 502 subClass: number; 503 504 /** 505 * Device protocol code 506 * 507 * @since 8 508 */ 509 protocol: number; 510 511 /** 512 * Device configuration descriptor information defined by {@link USBConfig} 513 * 514 * @since 8 515 */ 516 configs: Array<USBConfig>; 517 } 518 519 /** 520 * Represents a USB device pipe, which is used to determine the USB device. 521 * 522 * @syscap SystemCapability.USB.USBManager 523 * @since 8 524 */ 525 interface USBDevicePipe { 526 /** 527 * Bus address. 528 * 529 * @since 8 530 */ 531 busNum: number; 532 533 /** 534 * Device address 535 * 536 * @since 8 537 */ 538 devAddress: number; 539 } 540 541 /** 542 * Enumerates power role types. 543 * 544 * @syscap SystemCapability.USB.USBManager 545 * @systemapi 546 * @since 9 547 */ 548 export enum PowerRoleType { 549 /** 550 * None 551 * 552 * @since 9 553 */ 554 NONE = 0, 555 556 /** 557 * External power supply 558 * 559 * @since 9 560 */ 561 SOURCE = 1, 562 563 /** 564 * Internal power supply 565 * 566 * @since 9 567 */ 568 SINK = 2 569 } 570 571 /** 572 * Enumerates data role types. 573 * 574 * @syscap SystemCapability.USB.USBManager 575 * @systemapi 576 * @since 9 577 */ 578 export enum DataRoleType { 579 /** 580 * None 581 * 582 * @since 9 583 */ 584 NONE = 0, 585 586 /** 587 * Host mode 588 * 589 * @since 9 590 */ 591 HOST = 1, 592 593 /** 594 * Device mode 595 * 596 * @since 9 597 */ 598 DEVICE = 2 599 } 600 601 /** 602 * Enumerates port mode types 603 * 604 * @syscap SystemCapability.USB.USBManager 605 * @systemapi 606 * @since 9 607 */ 608 export enum PortModeType { 609 /** 610 * None 611 * 612 * @since 9 613 */ 614 NONE = 0, 615 616 /** 617 * Upstream facing port, which functions as the sink of power supply 618 * 619 * @since 9 620 */ 621 UFP = 1, 622 623 /** 624 * Downstream facing port, which functions as the source of power supply 625 * 626 * @since 9 627 */ 628 DFP = 2, 629 630 /** 631 * Dynamic reconfiguration port (DRP), which can function as the DFP (host) or UFP (device). It is not supported currently. 632 * 633 * @since 9 634 */ 635 DRP = 3, 636 637 /** 638 * Not supported currently 639 * 640 * @since 9 641 */ 642 NUM_MODES = 4 643 } 644 645 /** 646 * Enumerates USB device port roles. 647 * 648 * @syscap SystemCapability.USB.USBManager 649 * @systemapi 650 * @since 9 651 */ 652 interface USBPortStatus { 653 /** 654 * USB mode 655 * 656 * @since 9 657 */ 658 currentMode: number; 659 660 /** 661 * Power role 662 * 663 * @since 9 664 */ 665 currentPowerRole: number; 666 667 /** 668 * Data role 669 * 670 * @since 9 671 */ 672 currentDataRole: number; 673 } 674 675 /** 676 * Represents a USB device port. 677 * 678 * @syscap SystemCapability.USB.USBManager 679 * @systemapi 680 * @since 9 681 */ 682 interface USBPort { 683 /** 684 * Unique ID of the USB port 685 * 686 * @since 9 687 */ 688 id: number; 689 690 /** 691 * Mask combination for the supported mode list of the USB port 692 * 693 * @since 9 694 */ 695 supportedModes: PortModeType; 696 697 /** 698 * USB port role defined by {@link USBPortStatus} 699 * 700 * @since 9 701 */ 702 status: USBPortStatus; 703 } 704 705 /** 706 * Represents control transfer parameters. 707 * 708 * @syscap SystemCapability.USB.USBManager 709 * @since 8 710 */ 711 interface USBControlParams { 712 /** 713 * Request type 714 * 715 * @since 8 716 */ 717 request: number; 718 719 /** 720 * Request target type 721 * 722 * @since 8 723 */ 724 target: USBRequestTargetType; 725 726 /** 727 * Control request type 728 * 729 * @since 8 730 */ 731 reqType: USBControlRequestType; 732 733 /** 734 * Request parameter value 735 * 736 * @since 8 737 */ 738 value: number; 739 740 /** 741 * Index of the parameter value 742 * 743 * @since 8 744 */ 745 index: number; 746 747 /** 748 * Data written to or read from the buffer 749 * @since 8 750 */ 751 data: Uint8Array; 752 } 753 754 /** 755 * Enumerates USB request target types. 756 * 757 * @syscap SystemCapability.USB.USBManager 758 * @since 8 759 */ 760 export enum USBRequestTargetType { 761 /** 762 * USB device 763 * 764 * @since 8 765 */ 766 USB_REQUEST_TARGET_DEVICE = 0, 767 768 /** 769 * USB interface 770 * 771 * @since 8 772 */ 773 USB_REQUEST_TARGET_INTERFACE = 1, 774 775 /** 776 * Endpoint 777 * 778 * @since 8 779 */ 780 USB_REQUEST_TARGET_ENDPOINT = 2, 781 782 /** 783 * Others 784 * 785 * @since 8 786 */ 787 USB_REQUEST_TARGET_OTHER = 3 788 } 789 790 /** 791 * Enumerates control request types. 792 * 793 * @syscap SystemCapability.USB.USBManager 794 * @since 8 795 */ 796 export enum USBControlRequestType { 797 /** 798 * Standard 799 * 800 * @since 8 801 */ 802 USB_REQUEST_TYPE_STANDARD = 0, 803 804 /** 805 * Class 806 * 807 * @since 8 808 */ 809 USB_REQUEST_TYPE_CLASS = 1, 810 811 /** 812 * Vendor 813 * 814 * @since 8 815 */ 816 USB_REQUEST_TYPE_VENDOR = 2 817 } 818 819 /** 820 * Enumerates request directions. 821 * 822 * @syscap SystemCapability.USB.USBManager 823 * @since 8 824 */ 825 export enum USBRequestDirection { 826 /** 827 * Request for writing data from the host to the device 828 * 829 * @since 8 830 */ 831 USB_REQUEST_DIR_TO_DEVICE = 0, 832 833 /** 834 * Request for reading data from the device to the host 835 * 836 * @since 8 837 */ 838 USB_REQUEST_DIR_FROM_DEVICE = 0x80 839 } 840 841 /** 842 * Enumerates function modes. 843 * 844 * @syscap SystemCapability.USB.USBManager 845 * @systemapi 846 * @since 9 847 */ 848 export enum FunctionType { 849 /** 850 * None 851 * 852 * @since 9 853 */ 854 NONE = 0, 855 856 /** 857 * Serial port device 858 * 859 * @since 9 860 */ 861 ACM = 1, 862 863 /** 864 * Ethernet port device 865 * 866 * @since 9 867 */ 868 ECM = 2, 869 870 /** 871 * HDC device 872 * 873 * @since 9 874 */ 875 HDC = 4, 876 877 /** 878 * MTP device 879 * 880 * @since 9 881 */ 882 MTP = 8, 883 884 /** 885 * PTP device 886 * 887 * @since 9 888 */ 889 PTP = 16, 890 891 /** 892 * RNDIS device 893 * 894 * @since 9 895 */ 896 RNDIS = 32, 897 898 /** 899 * MIDI device 900 * 901 * @since 9 902 */ 903 MIDI = 64, 904 905 /** 906 * Audio source device 907 * 908 * @since 9 909 */ 910 AUDIO_SOURCE = 128, 911 912 /** 913 * NCM device 914 * 915 * @since 9 916 */ 917 NCM = 256 918 } 919 920} 921 922export default usb; 923