ch.ntb.usb

Class LibusbJava

java.lang.Object

ch.ntb.usb.LibusbJava

public class LibusbJava
extends java.lang.Object

This class represents the Java Native Interface to the shared library which is (with some exceptions) a one-to-one representation of the libusb API.

Project Description

Java libusb is a Java wrapper for the libusb and libusb-win32 USB library. libusb aim is to create a library for use by user level applications to access USB devices regardless of OS.
Libusb-win32 is a port of the USB library libusb to the Windows operating systems. The library allows user space applications to access any USB device on Windows in a generic way without writing any line of kernel driver code.

The API description of this class has been copied from the libusb documentation and adapted where neccessary.

Field Summary

Fields

Modifier and Type	Field and Description
static int	ERROR_BAD_FILE_DESCRIPTOR System error codes. This list is not complete! For more error codes see the file 'errorno.h' on your system.
static int	ERROR_BUSY System error codes. This list is not complete! For more error codes see the file 'errorno.h' on your system.
static int	ERROR_INVALID_PARAMETER System error codes. This list is not complete! For more error codes see the file 'errorno.h' on your system.
static int	ERROR_IO_ERROR System error codes. This list is not complete! For more error codes see the file 'errorno.h' on your system.
static int	ERROR_NO_SUCH_DEVICE_OR_ADDRESS System error codes. This list is not complete! For more error codes see the file 'errorno.h' on your system.
static int	ERROR_NOT_ENOUGH_MEMORY System error codes. This list is not complete! For more error codes see the file 'errorno.h' on your system.
static int	ERROR_SUCCESS System error codes. This list is not complete! For more error codes see the file 'errorno.h' on your system.
static int	ERROR_TIMEDOUT System error codes. This list is not complete! For more error codes see the file 'errorno.h' on your system.

Constructor Summary

Constructors

Constructor and Description
LibusbJava()

Method Summary

Methods

Modifier and Type	Method and Description
static int	usb_bulk_read(long dev_handle, int ep, byte[] bytes, int size, int timeout) Performs a bulk read request to the endpoint specified by ep.
static int	usb_bulk_write(long dev_handle, int ep, byte[] bytes, int size, int timeout) Performs a bulk write request to the endpoint specified by ep.
static int	usb_claim_interface(long dev_handle, int interface_) Claim an interface of a device. Must be called!: usb_claim_interface must be called before you perform any operations related to this interface (like usb_set_altinterface, usb_bulk_write, etc).
static int	usb_clear_halt(long dev_handle, int ep) Clears any halt status on an endpoint.
static int	usb_close(long dev_handle) usb_close closes a device opened with usb_open.
static int	usb_control_msg(long dev_handle, int requesttype, int request, int value, int index, byte[] bytes, int size, int timeout) Performs a control request to the default control pipe on a device.
static int	usb_find_busses() usb_find_busses will find all of the busses on the system.
static int	usb_find_devices() usb_find_devices will find all of the devices on each bus.
static Usb_Bus	usb_get_busses() usb_get_busses returns a tree of descriptor objects. The tree represents the bus structure with devices, configurations, interfaces and endpoints.
static java.lang.String	usb_get_descriptor_by_endpoint(long dev_handle, int ep, byte type, byte index, int size) Retrieves a descriptor from the device identified by the type and index of the descriptor from the control pipe identified by ep.
static java.lang.String	usb_get_descriptor(long dev_handle, byte type, byte index, int size) Retrieves a descriptor from the device identified by the type and index of the descriptor from the default control pipe. See usb_get_descriptor_by_endpoint(long, int, byte, byte, int) for a function that allows the control endpoint to be specified.
static java.lang.String	usb_get_string_simple(long dev_handle, int index) usb_get_string_simple is a wrapper around usb_get_string that retrieves the string description specified by index in the first language for the descriptor.
static java.lang.String	usb_get_string(long dev_handle, int index, int langid) Retrieves the string descriptor specified by index and langid from a device.
static void	usb_init() Just like the name implies, usb_init sets up some internal structures.
static int	usb_interrupt_read(long dev_handle, int ep, byte[] bytes, int size, int timeout) Performs a interrupt read request to the endpoint specified by ep.
static int	usb_interrupt_write(long dev_handle, int ep, byte[] bytes, int size, int timeout) Performs an interrupt write request to the endpoint specified by ep.
static long	usb_open(Usb_Device dev) usb_open is to be used to open up a device for use.
static int	usb_release_interface(long dev_handle, int interface_) Releases a previously claimed interface
static int	usb_reset(long dev_handle) Resets a device by sending a RESET down the port it is connected to. Causes re-enumeration: After calling usb_reset, the device will need to re-enumerate and thusly, requires you to find the new device and open a new handle.
static int	usb_set_altinterface(long dev_handle, int alternate) Sets the active alternate setting of the current interface
static int	usb_set_configuration(long dev_handle, int configuration) Sets the active configuration of a device
static void	usb_set_debug(int level) Sets the debugging level of libusb. The range is from 0 to 255, where 0 disables debug output and 255 enables all output.
static java.lang.String	usb_strerror() Returns the error string after an error occured.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ERROR_SUCCESS

public static int ERROR_SUCCESS

System error codes.
This list is not complete! For more error codes see the file 'errorno.h' on your system.

ERROR_BAD_FILE_DESCRIPTOR

public static int ERROR_BAD_FILE_DESCRIPTOR

System error codes.
This list is not complete! For more error codes see the file 'errorno.h' on your system.

ERROR_NO_SUCH_DEVICE_OR_ADDRESS

public static int ERROR_NO_SUCH_DEVICE_OR_ADDRESS

System error codes.
This list is not complete! For more error codes see the file 'errorno.h' on your system.

ERROR_BUSY

public static int ERROR_BUSY

System error codes.
This list is not complete! For more error codes see the file 'errorno.h' on your system.

ERROR_INVALID_PARAMETER

public static int ERROR_INVALID_PARAMETER

System error codes.
This list is not complete! For more error codes see the file 'errorno.h' on your system.

ERROR_TIMEDOUT

public static int ERROR_TIMEDOUT

System error codes.
This list is not complete! For more error codes see the file 'errorno.h' on your system.

ERROR_IO_ERROR

public static int ERROR_IO_ERROR

System error codes.
This list is not complete! For more error codes see the file 'errorno.h' on your system.

ERROR_NOT_ENOUGH_MEMORY

public static int ERROR_NOT_ENOUGH_MEMORY

System error codes.
This list is not complete! For more error codes see the file 'errorno.h' on your system.

Constructor Detail

LibusbJava

public LibusbJava()

Method Detail

usb_set_debug

public static void usb_set_debug(int level)

Sets the debugging level of libusb.
The range is from 0 to 255, where 0 disables debug output and 255 enables all output. On application start, debugging is disabled (0).

Parameters:

level - 0 to 255

usb_init

public static void usb_init()

Just like the name implies, usb_init sets up some internal structures. usb_init must be called before any other libusb functions.

usb_find_busses

public static int usb_find_busses()

usb_find_busses will find all of the busses on the system.

Returns:

the number of changes since previous call to this function (total of new busses and busses removed).

usb_find_devices

public static int usb_find_devices()

usb_find_devices will find all of the devices on each bus. This should be called after usb_find_busses.

Returns:

the number of changes since the previous call to this function (total of new device and devices removed).

usb_get_busses

public static Usb_Bus usb_get_busses()

usb_get_busses returns a tree of descriptor objects.
The tree represents the bus structure with devices, configurations, interfaces and endpoints. Note that this is only a copy. To refresh the information, usb_get_busses() must be called again.
The name of the objects contained in the tree is starting with Usb_.

Returns:

the structure of all busses and devices. Note: The java objects are copies of the C structs.

usb_open

public static long usb_open(Usb_Device dev)

usb_open is to be used to open up a device for use. usb_open must be called before attempting to perform any operations to the device.

Parameters:

dev - The device to open.

Returns:

a handle used in future communication with the device. 0 if an error has occurred.

usb_close

public static int usb_close(long dev_handle)

usb_close closes a device opened with usb_open.

Parameters:

dev_handle - The handle to the device.

Returns:

0 on success or < 0 on error.

usb_set_configuration

public static int usb_set_configuration(long dev_handle,
                        int configuration)

Sets the active configuration of a device

Parameters:

dev_handle - The handle to the device.

configuration - The value as specified in the descriptor field bConfigurationValue.

Returns:

0 on success or < 0 on error.

usb_set_altinterface

public static int usb_set_altinterface(long dev_handle,
                       int alternate)

Sets the active alternate setting of the current interface

Parameters:

dev_handle - The handle to the device.

alternate - The value as specified in the descriptor field bAlternateSetting.

Returns:

0 on success or < 0 on error.

usb_clear_halt

public static int usb_clear_halt(long dev_handle,
                 int ep)

Clears any halt status on an endpoint.

Parameters:

dev_handle - The handle to the device.

ep - The value specified in the descriptor field bEndpointAddress.

Returns:

0 on success or < 0 on error.

usb_reset

public static int usb_reset(long dev_handle)

Resets a device by sending a RESET down the port it is connected to.

Causes re-enumeration: After calling usb_reset, the device will need to re-enumerate and thusly, requires you to find the new device and open a new handle. The handle used to call usb_reset will no longer work.

Parameters:

dev_handle - The handle to the device.

Returns:

0 on success or < 0 on error.

usb_claim_interface

public static int usb_claim_interface(long dev_handle,
                      int interface_)

Claim an interface of a device.

Must be called!: usb_claim_interface must be called before you perform any operations related to this interface (like usb_set_altinterface, usb_bulk_write, etc).

Parameters:

dev_handle - The handle to the device.

interface_ - The value as specified in the descriptor field bInterfaceNumber.

Returns:

0 on success or < 0 on error.

usb_release_interface

public static int usb_release_interface(long dev_handle,
                        int interface_)

Releases a previously claimed interface

Parameters:

dev_handle - The handle to the device.

interface_ - The value as specified in the descriptor field bInterfaceNumber.

Returns:

0 on success or < 0 on error.

usb_control_msg

public static int usb_control_msg(long dev_handle,
                  int requesttype,
                  int request,
                  int value,
                  int index,
                  byte[] bytes,
                  int size,
                  int timeout)

Performs a control request to the default control pipe on a device. The parameters mirror the types of the same name in the USB specification.

Parameters:

dev_handle - The handle to the device.

requesttype -

request -

value -

index -

bytes -

size -

timeout -

Returns:

the number of bytes written/read or < 0 on error.

usb_get_string

public static java.lang.String usb_get_string(long dev_handle,
                              int index,
                              int langid)

Retrieves the string descriptor specified by index and langid from a device.

Parameters:

dev_handle - The handle to the device.

index -

langid -

Returns:

the descriptor String or null

usb_get_string_simple

public static java.lang.String usb_get_string_simple(long dev_handle,
                                     int index)

usb_get_string_simple is a wrapper around usb_get_string that retrieves the string description specified by index in the first language for the descriptor.

Parameters:

dev_handle - The handle to the device.

index -

Returns:

the descriptor String or null

usb_get_descriptor

public static java.lang.String usb_get_descriptor(long dev_handle,
                                  byte type,
                                  byte index,
                                  int size)

Retrieves a descriptor from the device identified by the type and index of the descriptor from the default control pipe.

See usb_get_descriptor_by_endpoint(long, int, byte, byte, int) for a function that allows the control endpoint to be specified.

Parameters:

dev_handle - The handle to the device.

type -

index -

size - number of charactes which will be retrieved (the length of the resulting String)

Returns:

the descriptor String or null

usb_get_descriptor_by_endpoint

public static java.lang.String usb_get_descriptor_by_endpoint(long dev_handle,
                                              int ep,
                                              byte type,
                                              byte index,
                                              int size)

Retrieves a descriptor from the device identified by the type and index of the descriptor from the control pipe identified by ep.

Parameters:

dev_handle - The handle to the device.

ep -

type -

index -

size - number of charactes which will be retrieved (the length of the resulting String)

Returns:

the descriptor String or null

usb_bulk_write

public static int usb_bulk_write(long dev_handle,
                 int ep,
                 byte[] bytes,
                 int size,
                 int timeout)

Performs a bulk write request to the endpoint specified by ep.

Parameters:

dev_handle - The handle to the device.

ep -

bytes -

size -

timeout -

Returns:

the number of bytes written on success or < 0 on error.

usb_bulk_read

public static int usb_bulk_read(long dev_handle,
                int ep,
                byte[] bytes,
                int size,
                int timeout)

Performs a bulk read request to the endpoint specified by ep.

Parameters:

dev_handle - The handle to the device.

ep -

bytes -

size -

timeout -

Returns:

the number of bytes read on success or < 0 on error.

usb_interrupt_write

public static int usb_interrupt_write(long dev_handle,
                      int ep,
                      byte[] bytes,
                      int size,
                      int timeout)

Performs an interrupt write request to the endpoint specified by ep.

Parameters:

dev_handle - The handle to the device.

ep -

bytes -

size -

timeout -

Returns:

the number of bytes written on success or < 0 on error.

usb_interrupt_read

public static int usb_interrupt_read(long dev_handle,
                     int ep,
                     byte[] bytes,
                     int size,
                     int timeout)

Performs a interrupt read request to the endpoint specified by ep.

Parameters:

dev_handle - The handle to the device.

ep -

bytes -

size -

timeout -

Returns:

the number of bytes read on success or < 0 on error.

usb_strerror

public static java.lang.String usb_strerror()

Returns the error string after an error occured.

Returns:

the last error sring.