Interface HidApiLibrary

All Superinterfaces:
com.sun.jna.Library
All Known Subinterfaces:
HidrawHidApiLibrary, LibusbHidApiLibrary

public interface HidApiLibrary extends com.sun.jna.Library

JNA library interface to act as the proxy for the underlying native library

This approach removes the need for any JNI or native code

  • Nested Class Summary

    Nested classes/interfaces inherited from interface com.sun.jna.Library

    com.sun.jna.Library.Handler
  • Field Summary

    Fields inherited from interface com.sun.jna.Library

    OPTION_ALLOW_OBJECTS, OPTION_CALLING_CONVENTION, OPTION_CLASSLOADER, OPTION_FUNCTION_MAPPER, OPTION_INVOCATION_MAPPER, OPTION_OPEN_FLAGS, OPTION_STRING_ENCODING, OPTION_STRUCTURE_ALIGNMENT, OPTION_SYMBOL_PROVIDER, OPTION_TYPE_MAPPER
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    hid_close(com.sun.jna.Pointer device)
    Close a HID device
    hid_enumerate(short vendor_id, short product_id)
    Enumerate the HID Devices.
    com.sun.jna.Pointer
    hid_error(com.sun.jna.Pointer device)
    Get a string describing the last error which occurred.
    void
    Finalize the HIDAPI library.
    void
    hid_free_enumeration(com.sun.jna.Pointer devs)
    Free an enumeration linked list
    int
    hid_get_feature_report(com.sun.jna.Pointer device, com.sun.jna.Structure.ByReference data, int length)
    Get a feature report from a HID device.
    int
    hid_get_indexed_string(com.sun.jna.Pointer device, int idx, com.sun.jna.Structure.ByReference string, int len)
    Get a string from a HID device, based on its string index.
    int
    hid_get_manufacturer_string(com.sun.jna.Pointer device, com.sun.jna.Structure.ByReference str, int len)
    Get the manufacturer string from a HID device
    int
    hid_get_product_string(com.sun.jna.Pointer device, com.sun.jna.Structure.ByReference str, int len)
    Get the product number string from a HID device
    int
    hid_get_serial_number_string(com.sun.jna.Pointer device, com.sun.jna.Structure.ByReference str, int len)
    Get the serial number string from a HID device
    void
    Initialize the HIDAPI library.
    com.sun.jna.Pointer
    hid_open(short vendor_id, short product_id, com.sun.jna.WString serial_number)
    Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally a serial number.
    com.sun.jna.Pointer
    Open a HID device by its path name.
    int
    hid_read(com.sun.jna.Pointer device, com.sun.jna.Structure.ByReference bytes, int length)
    Read an Input report from a HID device.
    int
    hid_read_timeout(com.sun.jna.Pointer device, com.sun.jna.Structure.ByReference bytes, int length, int timeout)
    Read an Input report from a HID device with timeout.
    int
    hid_send_feature_report(com.sun.jna.Pointer device, com.sun.jna.Structure.ByReference data, int length)
    Send a Feature report to the device.
    int
    hid_set_nonblocking(com.sun.jna.Pointer device, int nonblock)
    Set the device handle to be non-blocking.
    int
    hid_write(com.sun.jna.Pointer device, com.sun.jna.Structure.ByReference data, int len)
    Write an Output report to a HID device.
  • Method Details

    • hid_init

      void hid_init()

      Initialize the HIDAPI library.

      This function initializes the HIDAPI library. Calling it is not strictly necessary, as it will be called automatically by hid_enumerate() and any of the hid_open_*() functions if it is needed. This function should be called at the beginning of execution however, if there is a chance of HIDAPI handles being opened by different threads simultaneously.

    • hid_exit

      void hid_exit()

      Finalize the HIDAPI library.

      This function frees all of the static data associated with HIDAPI. It should be called at the end of execution to avoid memory leaks.

    • hid_open

      com.sun.jna.Pointer hid_open(short vendor_id, short product_id, com.sun.jna.WString serial_number)
      Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally a serial number. If serial_number is NULL, the first device with the specified VID and PID is opened.
      Parameters:
      vendor_id - The vendor ID
      product_id - The product ID
      serial_number - The serial number (or null for wildcard)
      Returns:
      A pointer to a HidDevice on success or null on failure
    • hid_close

      void hid_close(com.sun.jna.Pointer device)
      Close a HID device
      Parameters:
      device - A device handle
    • hid_error

      com.sun.jna.Pointer hid_error(com.sun.jna.Pointer device)
      Get a string describing the last error which occurred.
      Parameters:
      device - A device handle
      Returns:
      A string containing the last error which occurred or null if none has occurred.
    • hid_read

      int hid_read(com.sun.jna.Pointer device, com.sun.jna.Structure.ByReference bytes, int length)
      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 number if the device uses numbered reports.
      Parameters:
      device - A device handle returned from hid_open().
      bytes - A buffer to put the read data into.
      length - The number of bytes to read. For devices with multiple reports, make sure to read an extra byte for the report number.
      Returns:
      This function 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.
    • hid_read_timeout

      int hid_read_timeout(com.sun.jna.Pointer device, com.sun.jna.Structure.ByReference bytes, int length, int timeout)
      Read an Input report from a HID device with timeout. Input reports are returned to the host through the INTERRUPT IN endpoint. The first byte will contain the Report number if the device uses numbered reports.
      Parameters:
      device - A device handle
      bytes - A buffer to put the read data into.
      length - The number of bytes to read. For devices with multiple reports, make sure to read an extra byte for the report number.
      timeout - The timeout in milliseconds or -1 for blocking wait.
      Returns:
      This function returns the actual number of bytes read and -1 on error. If no packet was available to be read within the timeout period, this function returns 0.
    • hid_write

      int hid_write(com.sun.jna.Pointer device, com.sun.jna.Structure.ByReference data, int len)
      Write an Output report to a HID device. 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_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 0x0, 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 - A device handle
      data - the data to send, including the report number as the first byte
      len - The length in bytes of the data to send
      Returns:
      The actual number of bytes written, -1 on error
    • hid_get_feature_report

      int hid_get_feature_report(com.sun.jna.Pointer device, com.sun.jna.Structure.ByReference data, int length)
      Get a feature report from a HID device. Set the first byte of data[] to the Report ID of the report to be read. Make sure to allow space for this extra byte in data[]. Upon return, the first byte will still contain the Report ID, and the report data will start in data[1].
      Parameters:
      device - A device handle
      data - A buffer to put the read data into, including the Report ID. Set the first byte of data[] to the Report ID of the report to be read, or set it to zero if your device does not use numbered reports.
      length - The number of bytes to read, including an extra byte for the report ID. The buffer can be longer than the actual report.
      Returns:
      The number of bytes read plus one for the report ID (which is still in the first byte), or -1 on error
    • hid_send_feature_report

      int hid_send_feature_report(com.sun.jna.Pointer device, com.sun.jna.Structure.ByReference data, int length)
      Send a Feature report to the device. 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 0x0, for devices which do not use numbered reports), followed by the report data (16 bytes). In this example, the length passed in would be 17.
      Parameters:
      device - The device handle
      data - The data to send, including the report number as the first byte
      length - The length in bytes of the data to send, including the report number
      Returns:
      The actual number of bytes written, -1 on error
    • hid_get_indexed_string

      int hid_get_indexed_string(com.sun.jna.Pointer device, int idx, com.sun.jna.Structure.ByReference string, int len)
      Get a string from a HID device, based on its string index.
      Parameters:
      device - the device handle
      idx - The index of the string to get
      string - A wide string buffer to put the data into
      len - The length of the buffer in multiples of wchar_t
      Returns:
      0 on success, -1 on failure
    • hid_get_manufacturer_string

      int hid_get_manufacturer_string(com.sun.jna.Pointer device, com.sun.jna.Structure.ByReference str, int len)
      Get the manufacturer string from a HID device
      Parameters:
      device - the device handle
      str - A wide string buffer to put the data into
      len - The length of the buffer in multiple of wchar_t
      Returns:
      0 on success, -1 on failure
    • hid_get_product_string

      int hid_get_product_string(com.sun.jna.Pointer device, com.sun.jna.Structure.ByReference str, int len)
      Get the product number string from a HID device
      Parameters:
      device - the device handle
      str - A wide string buffer to put the data into
      len - The length of the buffer in multiple of wchar_t
      Returns:
      0 on success, -1 on failure
    • hid_get_serial_number_string

      int hid_get_serial_number_string(com.sun.jna.Pointer device, com.sun.jna.Structure.ByReference str, int len)
      Get the serial number string from a HID device
      Parameters:
      device - the device handle
      str - A wide string buffer to put the data into
      len - The length of the buffer in multiple of wchar_t
      Returns:
      0 on success, -1 on failure
    • hid_set_nonblocking

      int hid_set_nonblocking(com.sun.jna.Pointer device, int nonblock)
      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. Nonblocking can be turned on and off at any time.
      Parameters:
      device - The device handle
      nonblock - 0 disables non-blocking, 1 enables non-blocking
      Returns:
      0 on success, -1 on error
    • hid_enumerate

      HidDeviceInfoStructure hid_enumerate(short vendor_id, short product_id)
      Enumerate the HID Devices. This function returns a linked list of all the HID devices attached to the system which match vendor_id and product_id. If vendor_id is set to 0 then any vendor matches. If product_id is set to 0 then any product matches. If vendor_id and product_id are both set to 0, then all HID devices will be returned.
      Parameters:
      vendor_id - The vendor ID
      product_id - The product ID
      Returns:
      A linked list of all discovered matching devices
    • hid_free_enumeration

      void hid_free_enumeration(com.sun.jna.Pointer devs)
      Free an enumeration linked list
      Parameters:
      devs - The device information pointer
    • hid_open_path

      com.sun.jna.Pointer hid_open_path(String path)
      Open a HID device by its path name. The path name be determined by calling hid_enumerate(), or a platform-specific path name can be used (eg: "/dev/hidraw0" on Linux).
      Parameters:
      path - The path name
      Returns:
      The pointer if successful or null