Package 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 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 Description LibusbJava()
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method 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 (likeusb_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 withusb_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(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.
Seeusb_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_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_string(long dev_handle, int index, int langid)
Retrieves the string descriptor specified by index and langid from a device.static java.lang.String
usb_get_string_simple(long dev_handle, int index)
usb_get_string_simple
is a wrapper aroundusb_get_string
that retrieves the string description specified by index in the first language for the descriptor.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 interfacestatic int
usb_reset(long dev_handle)
Resets a device by sending a RESET down the port it is connected to.
Causes re-enumeration: After callingusb_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 interfacestatic int
usb_set_configuration(long dev_handle, int configuration)
Sets the active configuration of a devicestatic 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.
-
-
-
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.
-
-
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 afterusb_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 withUsb_
.- 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 withusb_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 callingusb_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 callusb_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 (likeusb_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 aroundusb_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.
Seeusb_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.
-
-