Package ch.ntb.usb

Class 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 (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​(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_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 around usb_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 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.