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