1 |
2 |
ZTEX |
/*
|
2 |
|
|
* Java libusb wrapper
|
3 |
|
|
* Copyright (c) 2005-2006 Andreas Schläpfer <spandi at users.sourceforge.net>
|
4 |
|
|
*
|
5 |
|
|
* http://libusbjava.sourceforge.net
|
6 |
|
|
* This library is covered by the LGPL, read LGPL.txt for details.
|
7 |
|
|
*/
|
8 |
|
|
package ch.ntb.usb;
|
9 |
|
|
|
10 |
|
|
/**
|
11 |
|
|
* This class represents the Java Native Interface to the shared library which
|
12 |
|
|
* is (with some exceptions) a one-to-one representation of the libusb API.<br>
|
13 |
|
|
* <br>
|
14 |
|
|
* <h1>Project Description</h1>
|
15 |
|
|
* Java libusb is a Java wrapper for the libusb and libusb-win32 USB library.
|
16 |
|
|
*
|
17 |
|
|
* <a href="http://libusb.sourceforge.net/">libusb</a> aim is to create a
|
18 |
|
|
* library for use by user level applications to access USB devices regardless
|
19 |
|
|
* of OS.<br>
|
20 |
|
|
* <a href="http://libusb-win32.sourceforge.net/">Libusb-win32</a> is a port of
|
21 |
|
|
* the USB library <a href="http://libusb.sourceforge.net/">libusb</a> to the
|
22 |
|
|
* Windows operating systems. The library allows user space applications to
|
23 |
|
|
* access any USB device on Windows in a generic way without writing any line of
|
24 |
|
|
* kernel driver code.<br>
|
25 |
|
|
* <br>
|
26 |
|
|
* The API description of this class has been copied from the <a
|
27 |
|
|
* href="http://libusb.sourceforge.net/documentation.html">libusb documentation</a>
|
28 |
|
|
* and adapted where neccessary.<br>
|
29 |
|
|
*
|
30 |
|
|
*/
|
31 |
|
|
public class LibusbJava {
|
32 |
|
|
|
33 |
|
|
/**
|
34 |
|
|
* System error codes.<br>
|
35 |
|
|
* This list is not complete! For more error codes see the file 'errorno.h'
|
36 |
|
|
* on your system.
|
37 |
|
|
*/
|
38 |
|
|
public static int ERROR_SUCCESS, ERROR_BAD_FILE_DESCRIPTOR,
|
39 |
|
|
ERROR_NO_SUCH_DEVICE_OR_ADDRESS, ERROR_BUSY,
|
40 |
|
|
ERROR_INVALID_PARAMETER, ERROR_TIMEDOUT, ERROR_IO_ERROR,
|
41 |
|
|
ERROR_NOT_ENOUGH_MEMORY;;
|
42 |
|
|
|
43 |
|
|
/**
|
44 |
|
|
* Sets the debugging level of libusb.<br>
|
45 |
|
|
*
|
46 |
|
|
* The range is from 0 to 255, where 0 disables debug output and 255 enables
|
47 |
|
|
* all output. On application start, debugging is disabled (0).
|
48 |
|
|
*
|
49 |
|
|
* @param level
|
50 |
|
|
* 0 to 255
|
51 |
|
|
*/
|
52 |
|
|
public static native void usb_set_debug(int level);
|
53 |
|
|
|
54 |
|
|
// Core
|
55 |
|
|
/**
|
56 |
|
|
* Just like the name implies, <code>usb_init</code> sets up some internal
|
57 |
|
|
* structures. <code>usb_init</code> must be called before any other
|
58 |
|
|
* libusb functions.
|
59 |
|
|
*/
|
60 |
|
|
public static native void usb_init();
|
61 |
|
|
|
62 |
|
|
/**
|
63 |
|
|
* <code>usb_find_busses</code> will find all of the busses on the system.
|
64 |
|
|
*
|
65 |
|
|
* @return the number of changes since previous call to this function (total
|
66 |
|
|
* of new busses and busses removed).
|
67 |
|
|
*/
|
68 |
|
|
public static native int usb_find_busses();
|
69 |
|
|
|
70 |
|
|
/**
|
71 |
|
|
* <code>usb_find_devices</code> will find all of the devices on each bus.
|
72 |
|
|
* This should be called after <code>usb_find_busses</code>.
|
73 |
|
|
*
|
74 |
|
|
* @return the number of changes since the previous call to this function
|
75 |
|
|
* (total of new device and devices removed).
|
76 |
|
|
*/
|
77 |
|
|
public static native int usb_find_devices();
|
78 |
|
|
|
79 |
|
|
/**
|
80 |
|
|
* <code>usb_get_busses</code> returns a tree of descriptor objects.<br>
|
81 |
|
|
* The tree represents the bus structure with devices, configurations,
|
82 |
|
|
* interfaces and endpoints. Note that this is only a copy. To refresh the
|
83 |
|
|
* information, <code>usb_get_busses()</code> must be called again.<br>
|
84 |
|
|
* The name of the objects contained in the tree is starting with
|
85 |
|
|
* <code>Usb_</code>.
|
86 |
|
|
*
|
87 |
|
|
* @return the structure of all busses and devices. <code>Note:</code> The
|
88 |
|
|
* java objects are copies of the C structs.
|
89 |
|
|
*/
|
90 |
|
|
public static native Usb_Bus usb_get_busses();
|
91 |
|
|
|
92 |
|
|
// Device Operations
|
93 |
|
|
/**
|
94 |
|
|
* <code>usb_open</code> is to be used to open up a device for use.
|
95 |
|
|
* <code>usb_open</code> must be called before attempting to perform any
|
96 |
|
|
* operations to the device.
|
97 |
|
|
*
|
98 |
|
|
* @param dev
|
99 |
|
|
* The device to open.
|
100 |
|
|
* @return a handle used in future communication with the device. 0 if an
|
101 |
|
|
* error has occurred.
|
102 |
|
|
*/
|
103 |
5 |
ZTEX |
public static native long usb_open(Usb_Device dev);
|
104 |
2 |
ZTEX |
|
105 |
|
|
/**
|
106 |
|
|
* <code>usb_close</code> closes a device opened with
|
107 |
|
|
* <code>usb_open</code>.
|
108 |
|
|
*
|
109 |
|
|
* @param dev_handle
|
110 |
|
|
* The handle to the device.
|
111 |
|
|
* @return 0 on success or < 0 on error.
|
112 |
|
|
*/
|
113 |
5 |
ZTEX |
public static native int usb_close(long dev_handle);
|
114 |
2 |
ZTEX |
|
115 |
|
|
/**
|
116 |
|
|
* Sets the active configuration of a device
|
117 |
|
|
*
|
118 |
|
|
* @param dev_handle
|
119 |
|
|
* The handle to the device.
|
120 |
|
|
* @param configuration
|
121 |
|
|
* The value as specified in the descriptor field
|
122 |
|
|
* bConfigurationValue.
|
123 |
|
|
* @return 0 on success or < 0 on error.
|
124 |
|
|
*/
|
125 |
5 |
ZTEX |
public static native int usb_set_configuration(long dev_handle,
|
126 |
2 |
ZTEX |
int configuration);
|
127 |
|
|
|
128 |
|
|
/**
|
129 |
|
|
* Sets the active alternate setting of the current interface
|
130 |
|
|
*
|
131 |
|
|
* @param dev_handle
|
132 |
|
|
* The handle to the device.
|
133 |
|
|
* @param alternate
|
134 |
|
|
* The value as specified in the descriptor field
|
135 |
|
|
* bAlternateSetting.
|
136 |
|
|
* @return 0 on success or < 0 on error.
|
137 |
|
|
*/
|
138 |
5 |
ZTEX |
public static native int usb_set_altinterface(long dev_handle, int alternate);
|
139 |
2 |
ZTEX |
|
140 |
|
|
/**
|
141 |
|
|
* Clears any halt status on an endpoint.
|
142 |
|
|
*
|
143 |
|
|
* @param dev_handle
|
144 |
|
|
* The handle to the device.
|
145 |
|
|
* @param ep
|
146 |
|
|
* The value specified in the descriptor field bEndpointAddress.
|
147 |
|
|
* @return 0 on success or < 0 on error.
|
148 |
|
|
*/
|
149 |
5 |
ZTEX |
public static native int usb_clear_halt(long dev_handle, int ep);
|
150 |
2 |
ZTEX |
|
151 |
|
|
/**
|
152 |
|
|
* Resets a device by sending a RESET down the port it is connected to.<br>
|
153 |
|
|
* <br>
|
154 |
|
|
* <b>Causes re-enumeration:</b> After calling <code>usb_reset</code>,
|
155 |
|
|
* the device will need to re-enumerate and thusly, requires you to find the
|
156 |
|
|
* new device and open a new handle. The handle used to call
|
157 |
|
|
* <code>usb_reset</code> will no longer work.
|
158 |
|
|
*
|
159 |
|
|
* @param dev_handle
|
160 |
|
|
* The handle to the device.
|
161 |
|
|
* @return 0 on success or < 0 on error.
|
162 |
|
|
*/
|
163 |
5 |
ZTEX |
public static native int usb_reset(long dev_handle);
|
164 |
2 |
ZTEX |
|
165 |
|
|
/**
|
166 |
|
|
* Claim an interface of a device.<br>
|
167 |
|
|
* <br>
|
168 |
|
|
* <b>Must be called!:</b> <code>usb_claim_interface</code> must be
|
169 |
|
|
* called before you perform any operations related to this interface (like
|
170 |
|
|
* <code>usb_set_altinterface, usb_bulk_write</code>, etc).
|
171 |
|
|
*
|
172 |
|
|
* @param dev_handle
|
173 |
|
|
* The handle to the device.
|
174 |
|
|
* @param interface_
|
175 |
|
|
* The value as specified in the descriptor field
|
176 |
|
|
* bInterfaceNumber.
|
177 |
|
|
* @return 0 on success or < 0 on error.
|
178 |
|
|
*/
|
179 |
5 |
ZTEX |
public static native int usb_claim_interface(long dev_handle, int interface_);
|
180 |
2 |
ZTEX |
|
181 |
|
|
/**
|
182 |
|
|
* Releases a previously claimed interface
|
183 |
|
|
*
|
184 |
|
|
* @param dev_handle
|
185 |
|
|
* The handle to the device.
|
186 |
|
|
* @param interface_
|
187 |
|
|
* The value as specified in the descriptor field
|
188 |
|
|
* bInterfaceNumber.
|
189 |
|
|
* @return 0 on success or < 0 on error.
|
190 |
|
|
*/
|
191 |
5 |
ZTEX |
public static native int usb_release_interface(long dev_handle,
|
192 |
2 |
ZTEX |
int interface_);
|
193 |
|
|
|
194 |
|
|
// Control Transfers
|
195 |
|
|
/**
|
196 |
|
|
* Performs a control request to the default control pipe on a device. The
|
197 |
|
|
* parameters mirror the types of the same name in the USB specification.
|
198 |
|
|
*
|
199 |
|
|
* @param dev_handle
|
200 |
|
|
* The handle to the device.
|
201 |
|
|
* @param requesttype
|
202 |
|
|
* @param request
|
203 |
|
|
* @param value
|
204 |
|
|
* @param index
|
205 |
|
|
* @param bytes
|
206 |
|
|
* @param size
|
207 |
|
|
* @param timeout
|
208 |
|
|
* @return the number of bytes written/read or < 0 on error.
|
209 |
|
|
*/
|
210 |
5 |
ZTEX |
public static native int usb_control_msg(long dev_handle, int requesttype,
|
211 |
2 |
ZTEX |
int request, int value, int index, byte[] bytes, int size,
|
212 |
|
|
int timeout);
|
213 |
|
|
|
214 |
|
|
/**
|
215 |
|
|
* Retrieves the string descriptor specified by index and langid from a
|
216 |
|
|
* device.
|
217 |
|
|
*
|
218 |
|
|
* @param dev_handle
|
219 |
|
|
* The handle to the device.
|
220 |
|
|
* @param index
|
221 |
|
|
* @param langid
|
222 |
|
|
* @return the descriptor String or null
|
223 |
|
|
*/
|
224 |
5 |
ZTEX |
public static native String usb_get_string(long dev_handle, int index,
|
225 |
2 |
ZTEX |
int langid);
|
226 |
|
|
|
227 |
|
|
/**
|
228 |
|
|
* <code>usb_get_string_simple</code> is a wrapper around
|
229 |
|
|
* <code>usb_get_string</code> that retrieves the string description
|
230 |
|
|
* specified by index in the first language for the descriptor.
|
231 |
|
|
*
|
232 |
|
|
* @param dev_handle
|
233 |
|
|
* The handle to the device.
|
234 |
|
|
* @param index
|
235 |
|
|
* @return the descriptor String or null
|
236 |
|
|
*/
|
237 |
5 |
ZTEX |
public static native String usb_get_string_simple(long dev_handle, int index);
|
238 |
2 |
ZTEX |
|
239 |
|
|
/**
|
240 |
|
|
* Retrieves a descriptor from the device identified by the type and index
|
241 |
|
|
* of the descriptor from the default control pipe.<br>
|
242 |
|
|
* <br>
|
243 |
5 |
ZTEX |
* See {@link #usb_get_descriptor_by_endpoint(long, int, byte, byte, int)}
|
244 |
2 |
ZTEX |
* for a function that allows the control endpoint to be specified.
|
245 |
|
|
*
|
246 |
|
|
* @param dev_handle
|
247 |
|
|
* The handle to the device.
|
248 |
|
|
* @param type
|
249 |
|
|
* @param index
|
250 |
|
|
* @param size
|
251 |
|
|
* number of charactes which will be retrieved (the length of the
|
252 |
|
|
* resulting String)
|
253 |
|
|
* @return the descriptor String or null
|
254 |
|
|
*/
|
255 |
5 |
ZTEX |
public static native String usb_get_descriptor(long dev_handle, byte type,
|
256 |
2 |
ZTEX |
byte index, int size);
|
257 |
|
|
|
258 |
|
|
/**
|
259 |
|
|
* Retrieves a descriptor from the device identified by the type and index
|
260 |
|
|
* of the descriptor from the control pipe identified by ep.
|
261 |
|
|
*
|
262 |
|
|
* @param dev_handle
|
263 |
|
|
* The handle to the device.
|
264 |
|
|
* @param ep
|
265 |
|
|
* @param type
|
266 |
|
|
* @param index
|
267 |
|
|
* @param size
|
268 |
|
|
* number of charactes which will be retrieved (the length of the
|
269 |
|
|
* resulting String)
|
270 |
|
|
* @return the descriptor String or null
|
271 |
|
|
*/
|
272 |
5 |
ZTEX |
public static native String usb_get_descriptor_by_endpoint(long dev_handle,
|
273 |
2 |
ZTEX |
int ep, byte type, byte index, int size);
|
274 |
|
|
|
275 |
|
|
// Bulk Transfers
|
276 |
|
|
/**
|
277 |
|
|
* Performs a bulk write request to the endpoint specified by ep.
|
278 |
|
|
*
|
279 |
|
|
* @param dev_handle
|
280 |
|
|
* The handle to the device.
|
281 |
|
|
* @param ep
|
282 |
|
|
* @param bytes
|
283 |
|
|
* @param size
|
284 |
|
|
* @param timeout
|
285 |
|
|
* @return the number of bytes written on success or < 0 on error.
|
286 |
|
|
*/
|
287 |
5 |
ZTEX |
public static native int usb_bulk_write(long dev_handle, int ep,
|
288 |
2 |
ZTEX |
byte[] bytes, int size, int timeout);
|
289 |
|
|
|
290 |
|
|
/**
|
291 |
|
|
* Performs a bulk read request to the endpoint specified by ep.
|
292 |
|
|
*
|
293 |
|
|
* @param dev_handle
|
294 |
|
|
* The handle to the device.
|
295 |
|
|
* @param ep
|
296 |
|
|
* @param bytes
|
297 |
|
|
* @param size
|
298 |
|
|
* @param timeout
|
299 |
|
|
* @return the number of bytes read on success or < 0 on error.
|
300 |
|
|
*/
|
301 |
5 |
ZTEX |
public static native int usb_bulk_read(long dev_handle, int ep,
|
302 |
2 |
ZTEX |
byte[] bytes, int size, int timeout);
|
303 |
|
|
|
304 |
|
|
// Interrupt Transfers
|
305 |
|
|
/**
|
306 |
|
|
* Performs an interrupt write request to the endpoint specified by ep.
|
307 |
|
|
*
|
308 |
|
|
* @param dev_handle
|
309 |
|
|
* The handle to the device.
|
310 |
|
|
* @param ep
|
311 |
|
|
* @param bytes
|
312 |
|
|
* @param size
|
313 |
|
|
* @param timeout
|
314 |
|
|
* @return the number of bytes written on success or < 0 on error.
|
315 |
|
|
*/
|
316 |
5 |
ZTEX |
public static native int usb_interrupt_write(long dev_handle, int ep,
|
317 |
2 |
ZTEX |
byte[] bytes, int size, int timeout);
|
318 |
|
|
|
319 |
|
|
/**
|
320 |
|
|
* Performs a interrupt read request to the endpoint specified by ep.
|
321 |
|
|
*
|
322 |
|
|
* @param dev_handle
|
323 |
|
|
* The handle to the device.
|
324 |
|
|
* @param ep
|
325 |
|
|
* @param bytes
|
326 |
|
|
* @param size
|
327 |
|
|
* @param timeout
|
328 |
|
|
* @return the number of bytes read on success or < 0 on error.
|
329 |
|
|
*/
|
330 |
5 |
ZTEX |
public static native int usb_interrupt_read(long dev_handle, int ep,
|
331 |
2 |
ZTEX |
byte[] bytes, int size, int timeout);
|
332 |
|
|
|
333 |
|
|
/**
|
334 |
|
|
* Returns the error string after an error occured.
|
335 |
|
|
*
|
336 |
|
|
* @return the last error sring.
|
337 |
|
|
*/
|
338 |
|
|
public static native String usb_strerror();
|
339 |
|
|
|
340 |
|
|
/** **************************************************************** */
|
341 |
|
|
|
342 |
|
|
/**
|
343 |
|
|
* Maps the Java error code to the system error code.<br>
|
344 |
|
|
* <br>
|
345 |
|
|
* Note that not all error codes are be mapped by this method. For more
|
346 |
|
|
* error codes see the file 'errno.h' on your system.<br>
|
347 |
|
|
* <br>
|
348 |
|
|
* 1: EBADF: Bad file descriptor.<br>
|
349 |
|
|
* 2: ENXIO: No such device or address.<br>
|
350 |
|
|
* 3: EBUSY: Device or resource busy.<br>
|
351 |
|
|
* 4: EINVAL: Invalid argument.<br>
|
352 |
|
|
* 5: ETIMEDOUT: Connection timed out.<br>
|
353 |
|
|
* 6: EIO: I/O error.<br>
|
354 |
|
|
* 7: ENOMEM: Not enough memory.<br>
|
355 |
|
|
*
|
356 |
|
|
*
|
357 |
|
|
* @return the system error code or 100000 if no mapping has been found.
|
358 |
|
|
*/
|
359 |
|
|
private static native int usb_error_no(int value);
|
360 |
|
|
|
361 |
|
|
static {
|
362 |
5 |
ZTEX |
// System.out.println("os.name: " + System.getProperty("os.name"));
|
363 |
|
|
// System.out.println("os.arch: " + System.getProperty("os.arch"));
|
364 |
2 |
ZTEX |
String os = System.getProperty("os.name");
|
365 |
|
|
if (os.contains("Windows")) {
|
366 |
5 |
ZTEX |
if ( System.getProperty("os.arch").equalsIgnoreCase("amd64") ) {
|
367 |
|
|
LibLoader.load( "libusbJava64" );
|
368 |
|
|
}
|
369 |
|
|
else {
|
370 |
|
|
LibLoader.load( "libusbJava32" );
|
371 |
|
|
}
|
372 |
|
|
}
|
373 |
|
|
else if ( System.getProperty("os.arch").equalsIgnoreCase("amd64") ) {
|
374 |
|
|
LibLoader.load( "usbJava64" );
|
375 |
|
|
// System.err.println("loaded libusbJava64");
|
376 |
|
|
}
|
377 |
|
|
else {
|
378 |
2 |
ZTEX |
try {
|
379 |
|
|
LibLoader.load( "usbJavaSh" );
|
380 |
|
|
// System.err.println("loaded libusbJavaSh");
|
381 |
|
|
}
|
382 |
|
|
catch ( UnsatisfiedLinkError e ) {
|
383 |
|
|
LibLoader.load( "usbJavaSt" );
|
384 |
|
|
// System.err.println("loaded libusbJavaSt");
|
385 |
|
|
}
|
386 |
|
|
}
|
387 |
|
|
// define the error codes
|
388 |
|
|
ERROR_SUCCESS = 0;
|
389 |
|
|
ERROR_BAD_FILE_DESCRIPTOR = -usb_error_no(1);
|
390 |
|
|
ERROR_NO_SUCH_DEVICE_OR_ADDRESS = -usb_error_no(2);
|
391 |
|
|
ERROR_BUSY = -usb_error_no(3);
|
392 |
|
|
ERROR_INVALID_PARAMETER = -usb_error_no(4);
|
393 |
|
|
ERROR_TIMEDOUT = -usb_error_no(5);
|
394 |
|
|
ERROR_IO_ERROR = -usb_error_no(6);
|
395 |
|
|
ERROR_NOT_ENOUGH_MEMORY = -usb_error_no(7);
|
396 |
|
|
}
|
397 |
|
|
}
|