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