From cf711435ec976e196c5b5f9a599b292fa9d1f78a Mon Sep 17 00:00:00 2001 From: Klaus Reimer Date: Sun, 6 Feb 2011 00:46:52 +0100 Subject: [PATCH] Added some documentation to the site. --- src/site/apt/index.apt.vm | 5 +- src/site/apt/manual.apt.vm | 176 ++++++++++++++++++++++++++++++++++++- src/site/site.xml | 1 + 3 files changed, 177 insertions(+), 5 deletions(-) diff --git a/src/site/apt/index.apt.vm b/src/site/apt/index.apt.vm index 5176862..c3d1f8e 100644 --- a/src/site/apt/index.apt.vm +++ b/src/site/apt/index.apt.vm @@ -8,8 +8,7 @@ What is usb4java? based on the native {{{http://www.libusb.org/}libusb 0.1}} shared library and reflects this API as complete as possible. Java NIO buffers are used for data exchange between libusb and Java. The high-level part implements - the {{{http://www.java-usb.org/}javax.usb standard (JSR-80)}} but this part - is not well tested at the moment. + the {{{http://www.javax-usb.org/}javax.usb standard (JSR-80)}}. Supported platforms are Linux (Intel 32/64 bit), Mac OS X (Intel 32/64 bit, PowerPC 32 bit) and Windows (Intel 32/64 bit). But other platforms may work @@ -25,7 +24,7 @@ What is usb4java? News - * 2011/01/29 - Version 0.1.12-1 has been released. + * 2011/02/05 - Version 0.1.0 has been released. [] diff --git a/src/site/apt/manual.apt.vm b/src/site/apt/manual.apt.vm index a10ec05..8a8cc05 100644 --- a/src/site/apt/manual.apt.vm +++ b/src/site/apt/manual.apt.vm @@ -1,7 +1,179 @@ ----------------------------------------------------------------------------- Manual ----------------------------------------------------------------------------- + +Installation -Manual + {{{./download.html}Download}} the and a binary JAR matching + your platform. Copy the into your class path and extract + the binary JAR to a directory from which Java can load JNI shared libraries. + You may specify a custom directory with the java option + <-Djava.library.path=some/dir> when running your java programs. + + If you are using the high-level API then you also need the + which can be downloaded from the + {{{http://sourceforge.net/projects/javax-usb/files/}javax.usb project site}}. + This JAR must also be copied into your class path. + - TODO +The low-level API + + It is recommended to use the high-level javax.usb API but there are + situations where you might want to use the low-level API instead. + For example if you are already familiar with libusb or if you + are porting a C program to Java then it might be easier to use the + low-level API which is based on libusb version 0.1.12. + + All global functions and constants of libusb are defined as static + members of the class + {{{./apidocs/de/ailis/usb4java/jni/USB.html}de.ailis.usb4java.jni.USB}}. + All structures of libusb are defined in separate classes which are named + similiar to the original struct names. For example the struct + is defined in the class + {{{./apidocs/de/ailis/usb4java/jni/USB_Device.html}USB_Device}}. Struct + members are represented by static methods in the corresponding class. + + The following differences exists between the and + the low-level API of : + + * of the configuration descriptor is named because + is a reserved word in Java. + + * of the configuration descriptor is named to + be compatible to the USB specification and because method names starting + with upper-case letters are quite unusual in Java. + + * Whenever libusb expects a byte pointer and a length you have to use + a Java NIO ByteBuffer instead. + + * The method can be used to check if the + platform-dependent method is available. + + * The method can be used to check if + the platform-dependent method is available. + + * All methods which are returning a string through a byte buffer which was + passed as argument have additional simplified overloaded method + equivalents which are returning a Java String directly. + + [] + + It is recommended to use static imports to access the API. Here is a small + example which iterates over all USB devices and prints the vendor and + product IDs: + ++-----------------------------------------------------------------------------+ +import static de.ailis.usb4java.jni.USB.*; + +public class Dump +{ + public static void main(String[] args) + { + usb_init(); + usb_find_busses(); + usb_find_devices(); + USB_Bus bus = usb_get_busses(); + while (bus != null) + { + USB_Device device = bus.devices(); + while (device != null) + { + USB_Device_Descriptor desc = device.descriptor(); + System.out.format("%04x:%04x%n", desc.idVendor(), desc.idProduct()); + device = device.next(); + } + bus = bus.next(); + } + } +} ++-----------------------------------------------------------------------------+ + +* More information about the low-level API + + * {{{./apidocs/de/ailis/usb4java/jni/package-summary.html}Low-level API documentation of usb4java}} + + * {{{http://libusb.sourceforge.net/doc/}API documentatiaon of libusb 0.1}} + + [] + + +The high-level API + + The high-level API implements the + {{{http://www.javax-usb.org/}javax.usb (JSR-80)}} standard. It is + recommended to use this API because it is object-oriented, event-driven and + uses exceptions for error-handling instead of negative return values like + the low-level API. Another advantage is that you may switch to a + different implementation later without changing your code. + For example instead of using you may try out the reference + implementation for Linux and Windows. + + +* Configuration + + To use the implementation you have to create a file named + in the root of your class path with the following + content: + ++-----------------------------------------------------------------------------+ +javax.usb.services = de.ailis.usb4java.Services ++-----------------------------------------------------------------------------+ + + +* Finding USB devices + + USB devices are managed in a tree. The root of this tree is a virtual + USB hub to which all physical root hubs are connected. More hubs can be + connected to these root hubs and any hub can have a number of connected + USB devices. The following source shows how to iterate over all devices: + ++-----------------------------------------------------------------------------+ +public class Dump +{ + private static void dump(UsbDevice device) + { + UsbDeviceDescriptor desc = device.getUsbDeviceDescriptor(); + System.out.format("%04x:%04x%n", desc.idVendor() & 0xffff, desc.idProduct() & 0xffff); + if (device.isUsbHub()) + { + UsbHub hub = (UsbHub) device; + for (UsbDevice child : (List) hub.getAttachedUsbDevices()) + { + dump(child); + } + } + } + + public static void main(String[] args) throws UsbException + { + UsbServices services = UsbHostManager.getUsbServices(); + UsbHub rootHub = services.getRootUsbHub(); + dump(rootHub); + } +} ++-----------------------------------------------------------------------------+ + + You may notice some annoyances here. First of all the API doesn't + use generics so type casting is needed when some method returns a List. + The second annoyance is that all descriptors of use signed + types where the USB specification defines unsigned types. So an unsigned + 8 bit value is of type (which is signed 8 bit) and an unsigned 16 + bit value is of type (signed 16 bit). This means that in some + situations like the formatted output in the example above the values must + be converted to unsigned values by performing operations like <<& 0xff>> + for 8-bit values and <<& 0xffff>> for 16 bit values. + + By the way: If you execute this program and no USB device is found at all + (except the virtual root hub) then this simply means that you have no + permissions to use any USB device on your machine. On Linux for example + write permissions are needed on the device files. So you have to fix the + permissions of the USB device file or execute your program as root. + +* More information about the high-level API + + * {{{./apidocs/index.html}API documentation of usb4java}} + + * {{{http://www.javax-usb.org/}javax-usb website}} + + [] + \ No newline at end of file diff --git a/src/site/site.xml b/src/site/site.xml index 25304f8..a16bc8b 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -9,6 +9,7 @@ +