-
Notifications
You must be signed in to change notification settings - Fork 109
Expand file tree
/
Copy pathLibUsb.java
More file actions
3172 lines (2854 loc) · 121 KB
/
LibUsb.java
File metadata and controls
3172 lines (2854 loc) · 121 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
* Copyright 2013 Klaus Reimer <[email protected]>
* Copyright 2013 Luca Longinotti <[email protected]>
* See LICENSE.md for licensing information.
*
* Based on libusb <http://libusb.info/>:
*
* Copyright 2001 Johannes Erdfelt <[email protected]>
* Copyright 2007-2009 Daniel Drake <[email protected]>
* Copyright 2010-2012 Peter Stuge <[email protected]>
* Copyright 2008-2013 Nathan Hjelm <[email protected]>
* Copyright 2009-2013 Pete Batard <[email protected]>
* Copyright 2009-2013 Ludovic Rousseau <[email protected]>
* Copyright 2010-2012 Michael Plante <[email protected]>
* Copyright 2011-2013 Hans de Goede <[email protected]>
* Copyright 2012-2013 Martin Pieuchot <[email protected]>
* Copyright 2012-2013 Toby Gray <[email protected]>
*/
package org.usb4java;
import java.io.FileDescriptor;
import java.nio.ByteBuffer;
import java.nio.IntBuffer;
import java.nio.LongBuffer;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentMap;
import org.apache.commons.lang3.tuple.ImmutablePair;
/**
* Static class providing the constants and functions of libusb.
*
* @author Klaus Reimer ([email protected])
* @author Luca Longinotti ([email protected])
*/
public final class LibUsb
{
// Log message levels.
/** No messages ever printed by the library (default). */
public static final int LOG_LEVEL_NONE = 0;
/** Error messages are printed to stderr. */
public static final int LOG_LEVEL_ERROR = 1;
/** Warning and error messages are printed to stderr. */
public static final int LOG_LEVEL_WARNING = 2;
/**
* Informational messages are printed to stdout, warning and error messages
* are printed to stderr.
*/
public static final int LOG_LEVEL_INFO = 3;
/**
* Debug and informational messages are printed to stdout, warnings and
* errors to stderr.
*/
public static final int LOG_LEVEL_DEBUG = 4;
// Available option values for {@link #setOption()}
/**
* Set the log message verbosity.
*
* The default level is {@link #LOG_LEVEL_NONE}, which means no messages are ever
* printed. If you choose to increase the message verbosity level, ensure
* that your application does not close the stderr file descriptor.
*
* You are advised to use level {@link #LOG_LEVEL_WARNING}. libusb is conservative
* with its message logging and most of the time, will only log messages that
* explain error conditions and other oddities. This will help you debug
* your software.
*
* If the LIBUSB_DEBUG environment variable was set when libusb was
* initialized, this function does nothing: the message verbosity is fixed
* to the value in the environment variable.
*
* If libusb was compiled without any message logging, this function does
* nothing: you'll never get any messages.
*
* If libusb was compiled with verbose debug message logging, this function
* does nothing: you'll always get messages from all levels.
*/
public static final int OPTION_LOG_LEVEL = 0;
/**
* Use the UsbDk backend for a specific context, if available.
*
* This option should be set immediately after calling {@link #init(Context)}, otherwise
* unspecified behavior may occur.
*
* Only valid on Windows.
*/
public static final int OPTION_USE_USBDK = 1;
// Error codes. Most libusb functions return 0 on success or one of these
// codes on failure. You can call errorName() to retrieve a string
// representation of an error code.
/** Success (no error). */
public static final int SUCCESS = 0;
/** Input/output error. */
public static final int ERROR_IO = -1;
/** Invalid parameter. */
public static final int ERROR_INVALID_PARAM = -2;
/** Access denied (insufficient permissions). */
public static final int ERROR_ACCESS = -3;
/** No such device (it may have been disconnected). */
public static final int ERROR_NO_DEVICE = -4;
/** Entity not found. */
public static final int ERROR_NOT_FOUND = -5;
/** Resource busy. */
public static final int ERROR_BUSY = -6;
/** Operation timed out. */
public static final int ERROR_TIMEOUT = -7;
/** Overflow. */
public static final int ERROR_OVERFLOW = -8;
/** Pipe error. */
public static final int ERROR_PIPE = -9;
/** System call interrupted (perhaps due to signal). */
public static final int ERROR_INTERRUPTED = -10;
/** Insufficient memory. */
public static final int ERROR_NO_MEM = -11;
/** Operation not supported or unimplemented on this platform. */
public static final int ERROR_NOT_SUPPORTED = -12;
/** Other error. */
public static final int ERROR_OTHER = -99;
/** Total number of error codes. */
public static final int ERROR_COUNT = 14;
// Speed codes. Indicates the speed at which the device is operating.
/** The OS doesn't report or know the device speed. */
public static final int SPEED_UNKNOWN = 0;
/** The device is operating at low speed (1.5MBit/s). */
public static final int SPEED_LOW = 1;
/** The device is operating at full speed (12MBit/s). */
public static final int SPEED_FULL = 2;
/** The device is operating at high speed (480MBit/s). */
public static final int SPEED_HIGH = 3;
/** The device is operating at super speed (5000MBit/s). */
public static final int SPEED_SUPER = 4;
/** The device is operating at super speed plus (10000MBit/s). */
public static final int SPEED_SUPER_PLUS = 5;
// Supported speeds (wSpeedSupported) bitfield. Indicates what speeds the
// device supports.
/** Low speed operation supported (1.5MBit/s). */
public static final short LOW_SPEED_OPERATION = 1;
/** Full speed operation supported (12MBit/s). */
public static final short FULL_SPEED_OPERATION = 2;
/** High speed operation supported (480MBit/s). */
public static final short HIGH_SPEED_OPERATION = 4;
/** Superspeed operation supported (5000MBit/s). */
public static final short SUPER_SPEED_OPERATION = 8;
// Masks for the bits of the bmAttributes field of the USB 2.0 Extension
// descriptor.
/** Supports Link Power Management (LPM). */
public static final int BM_LPM_SUPPORT = 2;
// Masks for the bits of the bmAttributes field field of the SuperSpeed USB
// Device Capability descriptor.
/** Supports Latency Tolerance Messages (LTM). */
public static final byte BM_LTM_SUPPORT = 2;
// USB capability types.
/** Wireless USB device capability. */
public static final byte BT_WIRELESS_USB_DEVICE_CAPABILITY = 1;
/** USB 2.0 extensions. */
public static final byte BT_USB_2_0_EXTENSION = 2;
/** SuperSpeed USB device capability. */
public static final byte BT_SS_USB_DEVICE_CAPABILITY = 3;
/** Container ID type. */
public static final byte BT_CONTAINER_ID = 4;
// Standard requests, as defined in table 9-5 of the USB 3.0 specifications.
/** Request status of the specific recipient. */
public static final byte REQUEST_GET_STATUS = 0x00;
/** Clear or disable a specific feature. */
public static final byte REQUEST_CLEAR_FEATURE = 0x01;
/** Set or enable a specific feature. */
public static final byte REQUEST_SET_FEATURE = 0x03;
/** Set device address for all future accesses. */
public static final byte REQUEST_SET_ADDRESS = 0x05;
/** Set device address for all future accesses. */
public static final byte REQUEST_GET_DESCRIPTOR = 0x06;
/** Set device address for all future accesses. */
public static final byte REQUEST_SET_DESCRIPTOR = 0x07;
/** Get the current device configuration value. */
public static final byte REQUEST_GET_CONFIGURATION = 0x08;
/** Get the current device configuration value. */
public static final byte REQUEST_SET_CONFIGURATION = 0x09;
/** Return the selected alternate setting for the specified interface. */
public static final byte REQUEST_GET_INTERFACE = 0x0A;
/** Select an alternate interface for the specified interface. */
public static final byte REQUEST_SET_INTERFACE = 0x0B;
/** Set then report an endpoint's synchronization frame. */
public static final byte REQUEST_SYNCH_FRAME = 0x0C;
/** Sets both the U1 and U2 Exit Latency. */
public static final byte REQUEST_SET_SEL = 0x30;
/**
* Delay from the time a host transmits a packet to the time it is received
* by the device.
*/
public static final byte SET_ISOCH_DELAY = 0x31;
// Request type bits of the bmRequestType field in control transfers.
/** Standard. */
public static final byte REQUEST_TYPE_STANDARD = 0;
/** Class. */
public static final byte REQUEST_TYPE_CLASS = 32;
/** Vendor. */
public static final byte REQUEST_TYPE_VENDOR = 64;
/** Reserved. */
public static final byte REQUEST_TYPE_RESERVED = 96;
// Recipient bits of the bmRequestType field in control transfers.
// Values 4 through 31 are reserved.
/** Device. */
public static final byte RECIPIENT_DEVICE = 0x00;
/** Interface. */
public static final byte RECIPIENT_INTERFACE = 0x01;
/** Endpoint. */
public static final byte RECIPIENT_ENDPOINT = 0x02;
/** Other. */
public static final byte RECIPIENT_OTHER = 0x03;
// Capabilities supported by an instance of libusb on the current running
// platform. Test if the loaded library supports a given capability by
// calling hasCapability.
/** The {@link #hasCapability(int)} API is available. */
public static final int CAP_HAS_CAPABILITY = 0x0000;
/** Hotplug support is available on this platform. */
public static final int CAP_HAS_HOTPLUG = 0x0001;
/**
* The library can access HID devices without requiring user intervention.
* Note that before being able to actually access an HID device, you may
* still have to call additional libusb functions such as
* {@link #detachKernelDriver(DeviceHandle, int)}.
*/
public static final int CAP_HAS_HID_ACCESS = 0x0100;
/**
* The library supports detaching of the default USB driver, using
* {@link #detachKernelDriver(DeviceHandle, int)}, if one is set by the OS
* kernel.
*/
public static final int CAP_SUPPORTS_DETACH_KERNEL_DRIVER = 0x0101;
/** The size of a control setup packet. */
public static final short CONTROL_SETUP_SIZE = 8;
// Device and/or Interface Class codes.
/**
* In the context of a device descriptor, this bDeviceClass value indicates
* that each interface specifies its own class information and all
* interfaces operate independently.
*/
public static final byte CLASS_PER_INTERFACE = 0;
/** Audio class. */
public static final byte CLASS_AUDIO = 1;
/** Communications class. */
public static final byte CLASS_COMM = 2;
/** Human Interface Device class. */
public static final byte CLASS_HID = 3;
/** Physical. */
public static final byte CLASS_PHYSICAL = 5;
/** Image class. */
public static final byte CLASS_PTP = 6;
/** Image class. */
public static final byte CLASS_IMAGE = 6;
/** Printer class. */
public static final byte CLASS_PRINTER = 7;
/** Mass storage class. */
public static final byte CLASS_MASS_STORAGE = 8;
/** Hub class. */
public static final byte CLASS_HUB = 9;
/** Data class. */
public static final byte CLASS_DATA = 10;
/** Smart Card. */
public static final byte CLASS_SMART_CARD = 0x0B;
/** Content Security. */
public static final byte CLASS_CONTENT_SECURITY = 0x0D;
/** Video. */
public static final byte CLASS_VIDEO = 0x0E;
/** Personal Healthcare. */
public static final byte CLASS_PERSONAL_HEALTHCARE = 0x0F;
/** Diagnostic Device. */
public static final byte CLASS_DIAGNOSTIC_DEVICE = (byte) 0xDC;
/** Wireless class. */
public static final byte CLASS_WIRELESS = (byte) 0xE0;
/** Application class. */
public static final byte CLASS_APPLICATION = (byte) 0xFE;
/** Class is vendor-specific. */
public static final byte CLASS_VENDOR_SPEC = (byte) 0xFF;
// Descriptor types as defined by the USB specification.
/**
* Device descriptor.
*
* @see DeviceDescriptor
*/
public static final byte DT_DEVICE = 0x01;
/**
* Configuration descriptor.
*
* @see ConfigDescriptor
*/
public static final byte DT_CONFIG = 0x02;
/** String descriptor. */
public static final byte DT_STRING = 0x03;
/**
* Interface descriptor.
*
* @see InterfaceDescriptor
*/
public static final byte DT_INTERFACE = 0x04;
/**
* Endpoint descriptor.
*
* @see EndpointDescriptor
*/
public static final byte DT_ENDPOINT = 0x05;
/**
* BOS descriptor.
*
* @see BosDescriptor
*/
public static final byte DT_BOS = 0x0F;
/**
* Device Capability descriptor.
*
* @see BosDevCapabilityDescriptor
*/
public static final byte DT_DEVICE_CAPABILITY = 0x10;
/** HID descriptor. */
public static final byte DT_HID = 0x21;
/** HID report descriptor. */
public static final byte DT_REPORT = 0x22;
/** Physical descriptor. */
public static final byte DT_PHYSICAL = 0x23;
/** Hub descriptor. */
public static final byte DT_HUB = 0x29;
/** SuperSpeed Hub descriptor. */
public static final byte DT_SUPERSPEED_HUB = 0x2A;
/**
* SuperSpeed Endpoint Companion descriptor.
*
* @see SsEndpointCompanionDescriptor
*/
public static final byte DT_SS_ENDPOINT_COMPANION = 0x30;
// Descriptor sizes per descriptor type
/** Size of a device descriptor. */
public static final byte DT_DEVICE_SIZE = 18;
/** Size of a config descriptor. */
public static final byte DT_CONFIG_SIZE = 9;
/** Size of an interface descriptor. */
public static final byte DT_INTERFACE_SIZE = 9;
/** Size of an endpoint descriptor. */
public static final byte DT_ENDPOINT_SIZE = 7;
/** Size of an endpoint descriptor with audio extension. */
public static final byte DT_ENDPOINT_AUDIO_SIZE = 9;
/** Size of a hub descriptor. */
public static final byte DT_HUB_NONVAR_SIZE = 7;
/** Size of a SuperSpeed endpoint companion descriptor. */
public static final byte DT_SS_ENDPOINT_COMPANION_SIZE = 6;
/** Size of a BOS descriptor. */
public static final byte DT_BOS_SIZE = 5;
/** Size of a device capability descriptor. */
public static final byte DT_DEVICE_CAPABILITY_SIZE = 3;
// BOS descriptor sizes
/** Size of a BOS descriptor. */
public static final byte BT_USB_2_0_EXTENSION_SIZE = 7;
/** Size of a BOS descriptor. */
public static final byte BT_SS_USB_DEVICE_CAPABILITY_SIZE = 10;
/** Size of a BOS descriptor. */
public static final byte BT_CONTAINER_ID_SIZE = 20;
/** We unwrap the BOS => define its maximum size. */
public static final byte DT_BOS_MAX_SIZE = DT_BOS_SIZE
+ BT_USB_2_0_EXTENSION_SIZE + BT_SS_USB_DEVICE_CAPABILITY_SIZE
+ BT_CONTAINER_ID_SIZE;
// Endpoint direction. Values for bit 7 of the endpoint address scheme.
/** In: device-to-host. */
public static final byte ENDPOINT_IN = (byte) 0x80;
/** Out: host-to-device. */
public static final byte ENDPOINT_OUT = 0x00;
// === Masks =============================================================
/** Endpoint address mask. */
public static final byte ENDPOINT_ADDRESS_MASK = 0x0F;
/** Endpoint direction mask. */
public static final byte ENDPOINT_DIR_MASK = (byte) 0x80;
/** Transfer type mask. */
public static final byte TRANSFER_TYPE_MASK = 0x03;
// Endpoint transfer type. Values for bits 0:1 of the endpoint attributes
// field.
/** Control endpoint. */
public static final byte TRANSFER_TYPE_CONTROL = 0;
/** Isochronous endpoint. */
public static final byte TRANSFER_TYPE_ISOCHRONOUS = 1;
/** Bulk endpoint. */
public static final byte TRANSFER_TYPE_BULK = 2;
/** Interrupt endpoint. */
public static final byte TRANSFER_TYPE_INTERRUPT = 3;
/** Stream endpoint. */
public static final byte TRANSFER_TYPE_BULK_STREAM = 4;
// Synchronization type for isochronous endpoints.
// Values for bits 2:3 of the bmAttributes field in
// EndpointDescriptor.
/** The mask used to filter out sync types from attributes. */
public static final byte ISO_SYNC_TYPE_MASK = 0x0C;
/** No synchronization. */
public static final byte ISO_SYNC_TYPE_NONE = 0;
/** Asynchronous. */
public static final byte ISO_SYNC_TYPE_ASYNC = 1;
/** Adaptive. */
public static final byte ISO_SYNC_TYPE_ADAPTIVE = 2;
/** Synchronous. */
public static final byte ISO_SYNC_TYPE_SYNC = 3;
// Usage type for isochronous endpoints. Values for bits 4:5 of the
// bmAttributes field in EndpointDescriptor.
/** The mask used to filter out usage types from attributes. */
public static final byte ISO_USAGE_TYPE_MASK = 0x30;
/** Data endpoint. */
public static final byte ISO_USAGE_TYPE_DATA = 0;
/** Feedback endpoint. */
public static final byte ISO_USAGE_TYPE_FEEDBACK = 1;
/** Implicit feedback Data endpoint. */
public static final byte ISO_USAGE_TYPE_IMPLICIT = 2;
/** Report short frames as errors. */
public static final byte TRANSFER_SHORT_NOT_OK = 1;
// Transfer flags
/**
* Automatically free transfer buffer during {@link #freeTransfer(Transfer)}
*
* Please note that this flag (which is originally 2) is effectively a no-op
* (set to zero) here in the Java wrapper, since the ByteBuffer that acts as
* a buffer for transfers is allocated by the JVM and is subject to garbage
* collection like any other object at some point. Nulling the reference is
* the only needed action to take, and it is already done by the
* TRANSFER_FREE_TRANSFER flag.
*/
public static final byte TRANSFER_FREE_BUFFER = 0;
/**
* Automatically call {@link #freeTransfer(Transfer)} after callback
* returns.
*
* If this flag is set, it is illegal to call
* {@link #freeTransfer(Transfer)} from your transfer callback, as this will
* result in a double-free when this flag is acted upon.
*/
public static final byte TRANSFER_FREE_TRANSFER = 4;
/**
* Terminate transfers that are a multiple of the endpoint's wMaxPacketSize
* with an extra zero length packet.
*
* This is useful when a device protocol mandates that each logical request
* is terminated by an incomplete packet (i.e. the logical requests are not
* separated by other means).
*
* This flag only affects host-to-device transfers to bulk and interrupt
* endpoints. In other situations, it is ignored.
*
* This flag only affects transfers with a length that is a multiple of the
* endpoint's wMaxPacketSize. On transfers of other lengths, this flag has
* no effect. Therefore, if you are working with a device that needs a ZLP
* whenever the end of the logical request falls on a packet boundary, then
* it is sensible to set this flag on every transfer (you do not have to
* worry about only setting it on transfers that end on the boundary).
*
* This flag is currently only supported on Linux. On other systems,
* libusb_submit_transfer() will return {@link #ERROR_NOT_SUPPORTED} for
* every transfer where this flag is set.
*/
public static final byte TRANSFER_ADD_ZERO_PACKET = 8;
// Transfer status codes
/**
* Transfer completed without error. Note that this does not indicate that
* the entire amount of requested data was transferred.
*/
public static final int TRANSFER_COMPLETED = 0;
/** Transfer failed. */
public static final int TRANSFER_ERROR = 1;
/** Transfer timed out. */
public static final int TRANSFER_TIMED_OUT = 2;
/** Transfer was cancelled. */
public static final int TRANSFER_CANCELLED = 3;
/**
* For bulk/interrupt endpoints: halt condition detected (endpoint stalled).
* For control endpoints: control request not supported.
*/
public static final int TRANSFER_STALL = 4;
/** Device was disconnected. */
public static final int TRANSFER_NO_DEVICE = 5;
/** Device sent more data than requested. */
public static final int TRANSFER_OVERFLOW = 6;
// Flags for hotplug events
/**
* Default value when not using any flags.
*/
public static final int HOTPLUG_NO_FLAGS = 0;
/**
* Arm the callback and fire it for all matching currently attached devices.
*/
public static final int HOTPLUG_ENUMERATE = 1;
// Hotplug events
/** A device has been plugged in and is ready to use. */
public static final int HOTPLUG_EVENT_DEVICE_ARRIVED = 0x01;
/**
* A device has left and is no longer available.
* It is the user's responsibility to call {@link #close(DeviceHandle)} on
* any handle associated with a disconnected device.
* It is safe to call {@link #getDeviceDescriptor(Device, DeviceDescriptor)}
* on a device that has left.
*/
public static final int HOTPLUG_EVENT_DEVICE_LEFT = 0x02;
// Wildcard matching for hotplug events
/** Match any vendorId or productId or deviceClass. */
public static final int HOTPLUG_MATCH_ANY = -1;
/** The next global hotplug ID to use. */
private static long globalHotplugId = 1;
/**
* Hotplug callbacks (to correctly manage calls and additional data).
*/
private static final ConcurrentMap<Long,
ImmutablePair<HotplugCallback, Object>> hotplugCallbacks =
new ConcurrentHashMap<Long, ImmutablePair<HotplugCallback, Object>>();
/**
* Pollfd listeners (to support different listeners for different contexts).
*/
private static final ConcurrentMap<Long,
ImmutablePair<PollfdListener, Object>> pollfdListeners =
new ConcurrentHashMap<Long, ImmutablePair<PollfdListener, Object>>();
static
{
Loader.load();
}
/**
* Private constructor to prevent instantiation.
*/
private LibUsb()
{
// Empty
}
/**
* Returns the API version of the underlying libusb library. It is defined
* as follows: (major << 24) | (minor << 16) | (16 bit incremental)
*
* @return The API version of the underlying libusb library.
*/
public static native int getApiVersion();
/**
* Initialize libusb.
*
* This function must be called before calling any other libusb function.
*
* If you do not provide an output location for a {@link Context}, a default
* context will be created. If there was already a default context, it will
* be reused (and nothing will be initialized/reinitialized).
*
* @param context
* Optional output location for context pointer. Null to use
* default context. Only valid on return code 0.
* @return 0 on success or a error code on failure.
*/
public static synchronized native int init(final Context context);
/**
* Deinitialize libusb.
*
* Should be called after closing all open devices and before your
* application terminates.
*
* @param context
* The {@link Context} to deinitialize, or NULL for the default
* context.
*/
public static synchronized native void exit(final Context context);
/**
* Set log message verbosity.
*
* The default level is {@link #LOG_LEVEL_NONE}, which means no messages are
* ever printed. If you choose to increase the message verbosity level,
* ensure that your application does not close the stdout/stderr file
* descriptors.
*
* You are advised to use level {@link #LOG_LEVEL_WARNING}. libusb is
* conservative with its message logging and most of the time, will only log
* messages that explain error conditions and other oddities. This will help
* you debug your software.
*
* If the {@link #LOG_LEVEL_DEBUG} environment variable was set when libusb
* was initialized, this function does nothing: the message verbosity is
* fixed to the value in the environment variable.
*
* If libusb was compiled without any message logging, this function does
* nothing: you'll never get any messages.
*
* If libusb was compiled with verbose debug message logging, this function
* does nothing: you'll always get messages from all levels.
*
* @param context
* The {@link Context} to operate on, or NULL for the default
* context.
* @param level
* The log level to set.
*
* @deprecated Use {@link #setOption(Context, int, int)} instead using the {@link #OPTION_LOG_LEVEL} option.
*/
public static native void setDebug(final Context context, final int level);
/**
* Set an option in the library.
*
* Use this function to configure a specific option within the library.
*
* Some options require one or more arguments to be provided. Consult each option's documentation for specific
* requirements.
*
* @param context
* The {@link Context} on which to operate.
* @param option
* Which option to set.
* @return {@link #SUCCESS} on success, {@link #ERROR_INVALID_PARAM} if the option or arguments are invalid,
* {@link #ERROR_NOT_SUPPORTED} if the option is valid but not supported on this platform.
*/
public static int setOption(final Context context, final int option) {
return setOption(context, option, 0);
}
/**
* Set an option in the library.
*
* Use this function to configure a specific option within the library.
*
* Some options require one or more arguments to be provided. Consult each option's documentation for specific
* requirements.
*
* @param context
* The {@link Context} on which to operate.
* @param option
* Which option to set.
* @param value
* Required argument for the specified option.
* @return {@link #SUCCESS} on success, {@link #ERROR_INVALID_PARAM} if the option or arguments are invalid,
* {@link #ERROR_NOT_SUPPORTED} if the option is valid but not supported on this platform.
*/
public static native int setOption(final Context context, final int option, final int value);
/**
* Returns the version of the libusb runtime.
*
* @return The version of the libusb runtime.
*/
public static native Version getVersion();
/**
* Returns a list of USB devices currently attached to the system.
*
* This is your entry point into finding a USB device to operate.
*
* You are expected to unreference all the devices when you are done with
* them, and then free the list with
* {@link #freeDeviceList(DeviceList, boolean)}. Note that
* {@link #freeDeviceList(DeviceList, boolean)} can unref all the devices
* for you. Be careful not to unreference a device you are about to open
* until after you have opened it.
*
* @param context
* The context to operate on, or NULL for the default context.
* @param list
* Output location for a list of devices. Must be later freed
* with {@link #freeDeviceList(DeviceList, boolean)}.
* @return The number of devices in the outputted list, or any ERROR code
* according to errors encountered by the backend.
*/
public static native int getDeviceList(final Context context,
final DeviceList list);
/**
* Frees a list of devices previously discovered using
* {@link #getDeviceList(Context, DeviceList)}.
*
* If the unref_devices parameter is set, the reference count of each device
* in the list is decremented by 1.
*
* @param list
* The list to free.
* @param unrefDevices
* Whether to unref the devices in the list.
*/
public static native void freeDeviceList(final DeviceList list,
final boolean unrefDevices);
/**
* Get the number of the bus that a device is connected to.
*
* @param device
* A device.
* @return The bus number
*/
public static native int getBusNumber(final Device device);
/**
* Get the number of the port that a device is connected to.
*
* @param device
* A device
* @return The port number (0 if not available).
*/
public static native int getPortNumber(final Device device);
/**
* Get the list of all port numbers from root for the specified device.
*
* @param device
* A device.
* @param path
* The array that should contain the port numbers. As per the USB
* 3.0 specs, the current maximum limit for the depth is 7.
* @return The number of elements filled, {@link #ERROR_OVERFLOW} if the
* array is too small
*/
public static native int getPortNumbers(final Device device,
final ByteBuffer path);
/**
* Get the list of all port numbers from root for the specified device.
*
* @deprecated Please use {@link #getPortNumbers(Device, ByteBuffer)}
* instead.
*
* @param context
* The context.
* @param device
* A device.
* @param path
* The array that should contain the port numbers. As per the USB
* 3.0 specs, the current maximum limit for the depth is 7.
* @return The number of elements filled, {@link #ERROR_OVERFLOW} if the
* array is too small
*/
@Deprecated
public static int getPortPath(final Context context, final Device device,
final ByteBuffer path)
{
return getPortNumbers(device, path);
}
/**
* Get the the parent from the specified device [EXPERIMENTAL].
*
* Please note that the reference count of the returned device is not
* increased. As such, do not *ever* call {@link #unrefDevice(Device)}
* directly on the returned Device.
*
* @param device
* A device
* @return The device parent or NULL if not available. You should issue a
* {@link #getDeviceList(Context, DeviceList)} before calling this
* function and make sure that you only access the parent before
* issuing {@link #freeDeviceList(DeviceList, boolean)}. The reason
* is that libusb currently does not maintain a permanent list of
* device instances, and therefore can only guarantee that parents
* are fully instantiated within a
* {@link #getDeviceList(Context, DeviceList)} -
* {@link #freeDeviceList(DeviceList, boolean)} block.
*/
public static native Device getParent(final Device device);
/**
* Get the address of the device on the bus it is connected to.
*
* @param device
* A device.
* @return The device address
*/
public static native int getDeviceAddress(final Device device);
/**
* Get the negotiated connection speed for a device.
*
* @param device
* A device.
* @return A SPEED code, where {@link #SPEED_UNKNOWN} means that the OS
* doesn't know or doesn't support returning the negotiated speed.
*/
public static native int getDeviceSpeed(final Device device);
/**
* Convenience function to retrieve the wMaxPacketSize value for a
* particular endpoint in the active device configuration.
*
* This function was originally intended to be of assistance when setting up
* isochronous transfers, but a design mistake resulted in this function
* instead. It simply returns the wMaxPacketSize value without considering
* its contents. If you're dealing with isochronous transfers, you probably
* want {@link #getMaxIsoPacketSize(Device, byte)} instead.
*
* @param device
* A device.
* @param endpoint
* Address of the endpoint in question.
* @return the wMaxPacketSize value {@link #ERROR_NOT_FOUND} if the endpoint
* does not exist {@link #ERROR_OTHER} on other failure
*/
public static native int getMaxPacketSize(final Device device,
final byte endpoint);
/**
* Calculate the maximum packet size which a specific endpoint is capable
* sending or receiving in the duration of 1 microframe.
*
* Only the active configuration is examined. The calculation is based on
* the wMaxPacketSize field in the endpoint descriptor as described in
* section 9.6.6 in the USB 2.0 specifications.
*
* If acting on an isochronous or interrupt endpoint, this function will
* multiply the value found in bits 0:10 by the number of transactions per
* microframe (determined by bits 11:12). Otherwise, this function just
* returns the numeric value found in bits 0:10.
*
* This function is useful for setting up isochronous transfers, for example
* you might pass the return value from this function to
* {@link #setIsoPacketLengths(Transfer, int)} in order to set the length
* field of every isochronous packet in a transfer.
*
* @param device
* A device.
* @param endpoint
* Address of the endpoint in question.
* @return The maximum packet size which can be sent/received on this
* endpoint {@link #ERROR_NOT_FOUND} if the endpoint does not exist
* {@link #ERROR_OTHER} on other failure.
*/
public static native int getMaxIsoPacketSize(final Device device,
final byte endpoint);
/**
* Increment the reference count of a device.
*
* @param device