Package ch.ntb.usb

Class LibusbJava

java.lang.Object
ch.ntb.usb.LibusbJava

public class LibusbJava extends 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
    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
    Constructor
    Description
     
  • Method Summary

    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 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.

    See usb_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 around usb_get_string that retrieves the string description specified by index in the first language for the descriptor.
    static void
    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 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 String
    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 Details

    • 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 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 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 invalid input: '<' 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 invalid input: '<' 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 invalid input: '<' 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 invalid input: '<' 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 invalid input: '<' 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 invalid input: '<' 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 invalid input: '<' 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 invalid input: '<' 0 on error.
    • usb_get_string

      public static 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 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 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 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 invalid input: '<' 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 invalid input: '<' 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 invalid input: '<' 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 invalid input: '<' 0 on error.
    • usb_strerror

      public static String usb_strerror()
      Returns the error string after an error occured.
      Returns:
      the last error sring.