• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1/*
2 * Copyright (c) 2021 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
16declare namespace usb {
17    /**
18     * Obtains the USB device list.
19     *
20     * @return USB device{@link USBDevice}list.
21     * @syscap SystemCapability.USB.USBManager
22     * @since 8
23     */
24    function getDevices(): Array<Readonly<USBDevice>>;
25
26    /**
27     * Connects the USB device.
28     *
29     * @param device USB device information from device list {@link getDevices()}.
30     * @return USB device pipe {@link USBDevicePipe} for data transfer.
31     * @syscap SystemCapability.USB.USBManager
32     * @since 8
33     */
34    function connectDevice(device: USBDevice): Readonly<USBDevicePipe>;
35
36    /**
37     * Checks whether the user has permission to access the device.
38     *
39     * @param deviceName Device name，{@link USBDevice.name}.
40     * @return Returns true if the user has the permission to access the device; return false otherwise.
41     * @syscap SystemCapability.USB.USBManager
42     * @since 8
43     */
44    function hasRight(deviceName: string): boolean;
45
46    /**
47     * Requests the temporary permission for the application to access the USB device.
48     *
49     * @param deviceName Device name，{@link USBDevice.name}.
50     * @return Returns true if the temporary device access permissions are granted; return false otherwise.
51     * @syscap SystemCapability.USB.USBManager
52     * @since 8
53     */
54    function requestRight(deviceName: string): Promise<boolean>;
55
56    /**
57     * Claims a USB interface.
58     *
59     * @param pipe Device pipe, which is used to determine the bus number and device address {@link USBDevicePipe}.
60     * @param iface USB interface, which is used to determine the index of the interface to claim {@link USBInterface}.
61     * @param force Optional parameter that determines whether to forcibly claim the USB interface.
62     * The default value is false, indicating not to forcibly claim the USB interface.
63     * @return Returns 0 if the USB interface is successfully claimed; returns an error code otherwise.
64     * @syscap SystemCapability.USB.USBManager
65     * @since 8
66     */
67    function claimInterface(pipe: USBDevicePipe, iface: USBInterface, force?: boolean): number;
68
69    /**
70     * Releases a USB interface.
71     *
72     * @param pipe Device pipe, which is used to determine the bus number and device address {@link USBDevicePipe}.
73     * @param iface USB interface, which is used to determine the index of the interface to release {@link USBInterface}.
74     * @return Returns 0 if the USB interface is successfully released; return an error code otherwise.
75     * @syscap SystemCapability.USB.USBManager
76     * @since 8
77     */
78    function releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number;
79
80    /**
81     * Set the device configuration.
82     *
83     * @param pipe Device pipe, which is used to determine the bus number and device address {@link USBDevicePipe}.
84     * @param config USB configuration to set {@link USBConfig}.
85     * @return Returns 0 if the USB configuration is successfully set; return an error code otherwise.
86     * @syscap SystemCapability.USB.USBManager
87     * @since 8
88     */
89    function setConfiguration(pipe: USBDevicePipe, config: USBConfig): number;
90
91    /**
92     * Sets a USB interface.
93     *
94     * @param pipe Device pipe, which is used to determine the bus number and device address {@link USBDevicePipe}.
95     * @param iface USB interface to set {@link USBInterface}.
96     * @return Returns 0 if the USB interface is successfully set; return an error code otherwise.
97     * @syscap SystemCapability.USB.USBManager
98     * @since 8
99     */
100    function setInterface(pipe: USBDevicePipe, iface: USBInterface): number;
101
102    /**
103     * Obtains the raw USB descriptor.
104     *
105     * @param pipe Device pipe, which is used to determine the bus number and device address {@link USBDevicePipe}.
106     * @return Raw descriptor data.
107     * @syscap SystemCapability.USB.USBManager
108     * @since 8
109     */
110    function getRawDescriptor(pipe: USBDevicePipe): Uint8Array;
111
112    /**
113     * Obtains the file descriptor.
114     *
115     * @param pipe Device pipe, which is used to determine the bus number and device address {@link USBDevicePipe}.
116     * @return File descriptor of the USB device.
117     * @syscap SystemCapability.USB.USBManager
118     * @since 8
119     */
120    function getFileDescriptor(pipe: USBDevicePipe): number;
121
122    /**
123     * Performs control transfer.
124     *
125     * @param pipe Device pipe, which is used to determine the bus number and device address {@link USBDevicePipe}.
126     * @param contrlparam control transfer parameters.
127     * @param timeout Timeout duration. This parameter is optional. The default value is 0, indicating no timeout.
128     * @return Returns the size of the transmitted or received data block if the control transfer is successful;
129     * return -1 if an exception occurs.
130     * @syscap SystemCapability.USB.USBManager
131     * @since 8
132     */
133    function controlTransfer(pipe: USBDevicePipe, contrlparam: USBControlParams, timeout?: number): Promise<number>;
134
135    /**
136     * Performs bulk transfer.
137     *
138     * @param pipe Device pipe, which is used to determine the bus number and device address {@link USBDevicePipe}.
139     * @param endpoint USB endpoint, which is used to determine the USB port for data transfer {@link USBEndpoint}.
140     * @param buffer Buffer for writing or reading data.
141     * @param timeout Timeout duration. This parameter is optional. The default value is 0, indicating no timeout.
142     * @return Returns the size of the transmitted or received data block if the control transfer is successful;
143     * return -1 if an exception occurs.
144     * @syscap SystemCapability.USB.USBManager
145     * @since 8
146     */
147    function bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array,
148        timeout?: number): Promise<number>;
149
150    /**
151     * Closes a USB device pipe.
152     *
153     * @param pipe USB device pipe {@link USBDevicePipe}.
154     * @return Returns 0 if the USB device pipe is closed successfully; return an error code otherwise.
155     * @syscap SystemCapability.USB.USBManager
156     * @since 8
157     */
158    function closePipe(pipe: USBDevicePipe): number;
159
160    /**
161     * Represents the USB endpoint from which data is sent or received.
162     * You can obtain the USB endpoint through USBInterface {@link USBInterface}.
163     *
164     * @syscap SystemCapability.USB.USBManager
165     * @since 8
166     */
167    interface USBEndpoint {
168        /**
169        * Endpoint address.
170        *
171        * @syscap SystemCapability.USB.USBManager
172        * @since 8
173        */
174        address: number;
175
176        /**
177        * Endpoint attributes.
178        *
179        * @syscap SystemCapability.USB.USBManager
180        * @since 8
181        */
182        attributes: number;
183
184        /**
185        * Endpoint interval.
186        *
187        * @syscap SystemCapability.USB.USBManager
188        * @since 8
189        */
190        interval: number;
191
192        /**
193        * Maximun size of data packets on the endpoint.
194        *
195        * @syscap SystemCapability.USB.USBManager
196        * @since 8
197        */
198        maxPacketSize: number;
199
200        /**
201        * Endpoint direction.
202        *
203        * @syscap SystemCapability.USB.USBManager
204        * @since 8
205        */
206        direction: USBRequestDirection;
207
208        /**
209        * Endpoint number.
210        *
211        * @syscap SystemCapability.USB.USBManager
212        * @since 8
213        */
214        number: number;
215
216        /**
217        * Endpoint type
218        *
219        * @syscap SystemCapability.USB.USBManager
220        * @since 8
221        */
222        type: number;
223
224        /**
225        * Unique ID of the interface to which the endpoint belongs {@link USBInterface.id}
226        *
227        * @syscap SystemCapability.USB.USBManager
228        * @since 8
229        */
230        interfaceId: number;
231    }
232
233
234    /**
235     * Represents a USB interface. One USBconfig {@link USBConfig} can contain multiple USBInterface instances,
236     * each providing a specific function.
237     *
238     * @syscap SystemCapability.USB.USBManager
239     * @since 8
240     */
241    interface USBInterface {
242        /**
243         * Unique ID of the USB interface.
244         *
245         * @syscap SystemCapability.USB.USBManager
246         * @since 8
247         */
248        id: number;
249
250        /**
251         * Interface protocol.
252         *
253         * @syscap SystemCapability.USB.USBManager
254         * @since 8
255         */
256        protocol: number;
257
258        /**
259         * Device type.
260         *
261         * @syscap SystemCapability.USB.USBManager
262         * @since 8
263         */
264        clazz: number;
265
266        /**
267         * Device subclass.
268         *
269         * @syscap SystemCapability.USB.USBManager
270         * @since 8
271         */
272        subClass: number;
273
274        /**
275         * Alternating between descripors of the same USB interface.
276         *
277         * @syscap SystemCapability.USB.USBManager
278         * @since 8
279         */
280        alternateSetting: number;
281
282        /**
283         * Interface name.
284         *
285         * @syscap SystemCapability.USB.USBManager
286         * @since 8
287         */
288        name: string;
289
290        /**
291         * Endpoints {@link USBEndpoint} that belongs to the USB interface.
292         *
293         * @syscap SystemCapability.USB.USBManager
294         * @since 8
295         */
296        endpoints: Array<USBEndpoint>;
297    }
298
299    /**
300     * Represents the USB configuration. One USBDevice{@link USBDevice} can contain multiple USBConfig instances.
301     *
302     * @syscap SystemCapability.USB.USBManager
303     * @since 8
304     */
305    interface USBConfig {
306        /**
307         * Unique ID if the USB configuration.
308         *
309         * @syscap SystemCapability.USB.USBManager
310         * @since 8
311         */
312        id: number;
313
314        /**
315         * Configuration attributes.
316         *
317         * @syscap SystemCapability.USB.USBManager
318         * @since 8
319         */
320        attributes: number;
321
322        /**
323         * Maximum power consumption, in mA.
324         *
325         * @syscap SystemCapability.USB.USBManager
326         * @since 8
327         */
328        maxPower: number;
329
330        /**
331         * Configuration name, which can be left empty.
332         *
333         * @syscap SystemCapability.USB.USBManager
334         * @since 8
335         */
336        name: string;
337
338        /**
339         * Support for remote wakeup.
340         *
341         * @syscap SystemCapability.USB.USBManager
342         * @since 8
343         */
344        isRemoteWakeup: boolean;
345
346        /**
347         * Support for independent power supplies.
348         *
349         * @syscap SystemCapability.USB.USBManager
350         * @since 8
351         */
352        isSelfPowered: boolean;
353
354        /**
355         * Supported interface attributes {@link USBInterface}.
356         *
357         * @syscap SystemCapability.USB.USBManager
358         * @since 8
359         */
360        interfaces: Array<USBInterface>;
361    }
362
363    /**
364     * Represents a USB device.
365     *
366     * @syscap SystemCapability.USB.USBManager
367     * @since 8
368     */
369    interface USBDevice {
370        /**
371         * Bus address.
372         *
373         * @syscap SystemCapability.USB.USBManager
374         * @since 8
375         */
376        busNum: number;
377        /**
378         * Device address.
379         *
380         * @syscap SystemCapability.USB.USBManager
381         * @since 8
382         */
383        devAddress: number;
384        /**
385         * Device SN.
386         *
387         * @syscap SystemCapability.USB.USBManager
388         * @since 8
389         */
390        serial: string;
391        /**
392         * Device name.
393         *
394         * @syscap SystemCapability.USB.USBManager
395         * @since 8
396         */
397        name: string;
398        /**
399         * Device manufacturer.
400         *
401         * @syscap SystemCapability.USB.USBManager
402         * @since 8
403         */
404        manufacturerName: string;
405        /**
406         * Product name.
407         *
408         * @syscap SystemCapability.USB.USBManager
409         * @since 8
410         */
411        productName: string;
412        /**
413         * Product version.
414         *
415         * @syscap SystemCapability.USB.USBManager
416         * @since 8
417         */
418        version: string;
419        /**
420         * Vendor ID.
421         *
422         * @syscap SystemCapability.USB.USBManager
423         * @since 8
424         */
425        vendorId: number;
426        /**
427         * Product ID.
428         *
429         * @syscap SystemCapability.USB.USBManager
430         * @since 8
431         */
432        productId: number;
433        /**
434         * Device class.
435         *
436         * @syscap SystemCapability.USB.USBManager
437         * @since 8
438         */
439        clazz: number;
440        /**
441         * Device subclass.
442         *
443         * @syscap SystemCapability.USB.USBManager
444         * @since 8
445         */
446        subClass: number;
447        /**
448         * Device protocol code.
449         *
450         * @syscap SystemCapability.USB.USBManager
451         * @since 8
452         */
453        protocol: number;
454        /**
455         * Device configuration descriptor information {@link USBConfig}.
456         *
457         * @syscap SystemCapability.USB.USBManager
458         * @since 8
459         */
460        configs: Array<USBConfig>;
461    }
462
463    /**
464     * Represents a USB device pipe, which is used to determine the USB device.
465     *
466     * @syscap SystemCapability.USB.USBManager
467     * @since 8
468     */
469    interface USBDevicePipe {
470        /**
471         * Bus address.
472         *
473         * @syscap SystemCapability.USB.USBManager
474         * @since 8
475         */
476        busNum: number;
477        /**
478         * Device address.
479         *
480         * @syscap SystemCapability.USB.USBManager
481         * @since 8
482         */
483        devAddress: number;
484    }
485
486    /**
487    * Represents control transfer parameters.
488    *
489    * @syscap SystemCapability.USB.USBManager
490    * @since 8
491    */
492    interface USBControlParams {
493        /**
494         * Request type.
495         *
496         * @syscap SystemCapability.USB.USBManager
497         * @since 8
498         */
499        request: number;
500        /**
501         * Request target tyoe.
502         *
503         * @syscap SystemCapability.USB.USBManager
504         * @since 8
505         */
506        target: USBRequestTargetType;
507        /**
508         * Request control type.
509         *
510         * @syscap SystemCapability.USB.USBManager
511         * @since 8
512         */
513        reqType: USBControlRequestType;
514        /**
515         * Request parameter value.
516         *
517         * @syscap SystemCapability.USB.USBManager
518         * @since 8
519           */
520        value: number;
521        /**
522         * Index of the parameter value.
523         *
524         * @syscap SystemCapability.USB.USBManager
525         * @since 8
526         */
527        index: number;
528        /**
529         * Data written to or read from the buffer.
530         *
531         * @syscap SystemCapability.USB.USBManager
532         * @since 8
533         */
534        data: Uint8Array;
535    }
536
537    /**
538     * Enumerates USB request target types.
539     *
540     * @syscap SystemCapability.USB.USBManager
541     * @since 8
542     */
543    enum USBRequestTargetType {
544        /**
545         * Device.
546         *
547         * @syscap SystemCapability.USB.USBManager
548         * @since 8
549         */
550        USB_REQUEST_TARGET_DEVICE = 0,
551        /**
552         * Interface.
553         *
554         * @syscap SystemCapability.USB.USBManager
555         * @since 8
556         */
557        USB_REQUEST_TARGET_INTERFACE,
558        /**
559         * Endpoint.
560         *
561         * @syscap SystemCapability.USB.USBManager
562         * @since 8
563         */
564        USB_REQUEST_TARGET_ENDPOINT,
565        /**
566         * Others.
567         *
568         * @syscap SystemCapability.USB.USBManager
569         * @since 8
570         */
571        USB_REQUEST_TARGET_OTHER
572    }
573
574    /**
575     * Enumerates control request types.
576     *
577     * @syscap SystemCapability.USB.USBManager
578     * @since 8
579     */
580    enum USBControlRequestType {
581        /**
582         * Standard.
583         *
584         * @syscap SystemCapability.USB.USBManager
585         * @since 8
586         */
587        USB_REQUEST_TYPE_STANDARD = 0,
588        /**
589         * Class.
590         *
591         * @syscap SystemCapability.USB.USBManager
592         * @since 8
593         */
594        USB_REQUEST_TYPE_CLASS,
595        /**
596         * Verdor.
597         *
598         * @syscap SystemCapability.USB.USBManager
599         * @since 8
600         */
601        USB_REQUEST_TYPE_VENDOR
602    }
603
604    /**
605     * Enumerates request directions.
606     *
607     * @syscap SystemCapability.USB.USBManager
608     * @since 8
609     */
610    enum USBRequestDirection {
611        /**
612         * Request for writing data from the host to the device.
613         *
614         * @syscap SystemCapability.USB.USBManager
615         * @since 8
616         */
617        USB_REQUEST_DIR_TO_DEVICE = 0,
618        /**
619         * Request for reading data from the device to the host.
620         *
621         * @syscap SystemCapability.USB.USBManager
622         * @since 8
623         */
624        USB_REQUEST_DIR_FROM_DEVICE = 0x80
625    }
626}
627
628export default usb;
629