Class HidApi

java.lang.Object
org.hid4java.jna.HidApi

public class HidApi extends Object

JNA utility class to provide the following to low level operations:

  • Direct access to the HID API library through JNA
Since:
0.0.1  
  • Field Details

    • WSTR_LEN

      private static final int WSTR_LEN
      Default length for wide string buffer
      See Also:
    • DEVICE_NULL

      private static final String DEVICE_NULL
      Error message if device is not initialised
      See Also:
    • DEVICE_ERROR

      private static final int DEVICE_ERROR
      Device error code
      See Also:
    • useLibUsbVariant

      public static boolean useLibUsbVariant

      Enables use of the libusb variant of the hidapi native library when running on a Linux platform.

      The default is hidraw which enables Bluetooth devices but requires udev rules.

    • hidApiLibrary

      private static HidApiLibrary hidApiLibrary
      The HID API library
  • Constructor Details

    • HidApi

      public HidApi()
  • Method Details

    • open

      public static HidDeviceStructure open(int vendor, int product, String serialNumber)

      Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally a serial number

      Parameters:
      vendor - The vendor ID
      product - The product ID
      serialNumber - The serial number
      Returns:
      The device or null if not found
    • init

      public static void init()

      Initialise the HID API library. Should always be called before using any other API calls.

    • exit

      public static void exit()

      Finalise the HID API library

    • open

      public static HidDeviceStructure open(String path)

      Open a HID device by its path name

      Parameters:
      path - The device path (e.g. "0003:0002:00")
      Returns:
      The device or null if not found
    • close

      public static void close(HidDeviceStructure device)

      Close a HID device

      Parameters:
      device - The HID device structure
    • enumerateDevices

      public static HidDeviceInfoStructure enumerateDevices(int vendor, int product)

      Enumerate the attached HID devices

      Parameters:
      vendor - The vendor ID
      product - The product ID
      Returns:
      The device info of the matching device
    • freeEnumeration

      public static void freeEnumeration(HidDeviceInfoStructure list)

      Free an enumeration linked list

      Parameters:
      list - The list to free
    • getLastErrorMessage

      public static String getLastErrorMessage(HidDeviceStructure device)
      Parameters:
      device - The HID device structure
      Returns:
      A string describing the last error which occurred
    • getManufacturer

      public static String getManufacturer(HidDeviceStructure device)
      Parameters:
      device - The HID device
      Returns:
      The device manufacturer string
    • getProductId

      public static String getProductId(HidDeviceStructure device)
      Parameters:
      device - The HID device
      Returns:
      The device product ID
    • getSerialNumber

      public static String getSerialNumber(HidDeviceStructure device)
      Parameters:
      device - The HID device
      Returns:
      The device serial number
    • setNonBlocking

      public static boolean setNonBlocking(HidDeviceStructure device, boolean nonBlocking)

      Set the device handle to be non-blocking

      In non-blocking mode calls to hid_read() will return immediately with a value of 0 if there is no data to be read. In blocking mode, hid_read() will wait (block) until there is data to read before returning

      Non-blocking can be turned on and off at any time

      Parameters:
      device - The HID device
      nonBlocking - True if non-blocking mode is required
      Returns:
      True if successful
    • read

      public static int read(HidDeviceStructure device, byte[] buffer)

      Read an Input report from a HID device

      Input reports are returned to the host through the INTERRUPT IN endpoint. The first byte will contain the Report ID if the device uses numbered reports.

      Parameters:
      device - The HID device
      buffer - The buffer to read into (allow an extra byte if device supports multiple report IDs)
      Returns:
      The actual number of bytes read and -1 on error. If no packet was available to be read and the handle is in non-blocking mode, this function returns 0.
    • read

      public static int read(HidDeviceStructure device, byte[] buffer, int timeoutMillis)

      Read an Input report from a HID device with timeout

      Parameters:
      device - The HID device
      buffer - The buffer to read into
      timeoutMillis - The number of milliseconds to wait before giving up
      Returns:
      The actual number of bytes read and -1 on error. If no packet was available to be read within the timeout period returns 0.
    • getFeatureReport

      public static int getFeatureReport(HidDeviceStructure device, byte[] data, byte reportId)

      Get a feature report from a HID device

      HID API notes

      Under the covers the HID library will set the first byte of data[] to the Report ID of the report to be read. Upon return, the first byte will still contain the Report ID, and the report data will start in data[1]

      This method handles all the wide string and array manipulation for you

      Parameters:
      device - The HID device
      data - The buffer to contain the report
      reportId - The report ID (or (byte) 0x00)
      Returns:
      The number of bytes read plus one for the report ID (which has been removed from the first byte), or -1 on error.
    • sendFeatureReport

      public static int sendFeatureReport(HidDeviceStructure device, byte[] data, byte reportId)

      Send a Feature report to the device using a simplified interface

      HID API notes

      Under the covers, feature reports are sent over the Control endpoint as a Set_Report transfer. The first byte of data[] must contain the Report ID. For devices which only support a single report, this must be set to 0x0. The remaining bytes contain the report data

      Since the Report ID is mandatory, calls to hid_send_feature_report() will always contain one more byte than the report contains.

      For example, if a hid report is 16 bytes long, 17 bytes must be passed to hid_send_feature_report(): the Report ID (or 0x00, for devices which do not use numbered reports), followed by the report data (16 bytes). In this example, the bytes written would be 17.

      This method handles all the array manipulation for you

      Parameters:
      device - The HID device
      data - The feature report data (will be widened and have the report ID pre-pended)
      reportId - The report ID (or (byte) 0x00)
      Returns:
      This function returns the actual number of bytes written and -1 on error.
    • write

      public static int write(HidDeviceStructure device, byte[] data, int len, byte reportId)

      Write an Output report to a HID device using a simplified interface

      HID API notes

      In USB HID the first byte of the data packet must contain the Report ID. For devices which only support a single report, this must be set to 0x00. The remaining bytes contain the report data. Since the Report ID is mandatory, calls to hid_write() will always contain one more byte than the report contains.

      For example, if a hid report is 16 bytes long, 17 bytes must be passed to hid_write(), the Report ID (or 0x00, for devices with a single report), followed by the report data (16 bytes). In this example, the length passed in would be 17

      hid_write() will send the data on the first OUT endpoint, if one exists. If it does not, it will send the data through the Control Endpoint (Endpoint 0)

      Parameters:
      device - The device
      data - The report data to write (should not include the Report ID)
      len - The length of the report data (should not include the Report ID)
      reportId - The report ID (or (byte) 0x00)
      Returns:
      The number of bytes written, or -1 if an error occurs
    • getIndexedString

      public static String getIndexedString(HidDeviceStructure device, int idx)

      Get a string from a HID device, based on its string index

      Parameters:
      device - The HID device
      idx - The index
      Returns:
      The string