Package ch.ntb.usb
Class LibusbJava
java.lang.Object
ch.ntb.usb.LibusbJava
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.
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.
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
FieldsModifier and TypeFieldDescriptionstatic int
System error codes.
This list is not complete! For more error codes see the file 'errorno.h' on your system.static int
System error codes.
This list is not complete! For more error codes see the file 'errorno.h' on your system.static int
System error codes.
This list is not complete! For more error codes see the file 'errorno.h' on your system.static int
System error codes.
This list is not complete! For more error codes see the file 'errorno.h' on your system.static int
System error codes.
This list is not complete! For more error codes see the file 'errorno.h' on your system.static int
System error codes.
This list is not complete! For more error codes see the file 'errorno.h' on your system.static int
System error codes.
This list is not complete! For more error codes see the file 'errorno.h' on your system.static int
System error codes.
This list is not complete! For more error codes see the file 'errorno.h' on your system. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic 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
will find all of the busses on the system.static int
usb_find_devices
will find all of the devices on each bus.static Usb_Bus
usb_get_busses
returns a tree of descriptor objects.
The tree represents the bus structure with devices, configurations, interfaces and endpoints.static 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 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 String
usb_get_string
(long dev_handle, int index, int langid) Retrieves the string descriptor specified by index and langid from a device.static 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 String
Returns the error string after an error occured.
-
Field Details
-
ERROR_SUCCESS
public static int ERROR_SUCCESSSystem 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_DESCRIPTORSystem 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_ADDRESSSystem 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_BUSYSystem 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_PARAMETERSystem 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_TIMEDOUTSystem 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_ERRORSystem 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_MEMORYSystem error codes.
This list is not complete! For more error codes see the file 'errorno.h' on your system.
-
-
Constructor Details
-
LibusbJava
public LibusbJava()
-
-
Method Details
-
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
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
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
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
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
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 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
Returns the error string after an error occured.- Returns:
- the last error sring.
-