Package org.hid4java.jna
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 TypeMethodDescriptionvoid
hid_close
(com.sun.jna.Pointer device) Close a HID devicehid_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 listint
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 deviceint
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 deviceint
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 devicevoid
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
(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 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 IDproduct_id
- The product IDserial_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 handlebytes
- 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 handledata
- the data to send, including the report number as the first bytelen
- 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 handledata
- 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 handledata
- The data to send, including the report number as the first bytelength
- 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 handleidx
- The index of the string to getstring
- A wide string buffer to put the data intolen
- 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 handlestr
- A wide string buffer to put the data intolen
- 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 handlestr
- A wide string buffer to put the data intolen
- 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 handlestr
- A wide string buffer to put the data intolen
- 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 handlenonblock
- 0 disables non-blocking, 1 enables non-blocking- Returns:
- 0 on success, -1 on error
-
hid_enumerate
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 IDproduct_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
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
-