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_TYPE_MAPPER
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void hid_close​(com.sun.jna.Pointer device)
      Close a HID device
      HidDeviceInfoStructure 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 hid_exit()
      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 hid_init()
      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 hid_open_path​(java.lang.String path)
      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 Detail

      • 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​(java.lang.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