Package org.hid4java.jna
Interface HidApiLibrary
-
- All Superinterfaces:
com.sun.jna.Library
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
-
-
Field Summary
Fields Modifier and Type Field Description static HidApiLibrary
INSTANCE
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
hid_close(com.sun.jna.Pointer device)
Close a HID deviceHidDeviceInfoStructure
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 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(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.
-
-
-
Field Detail
-
INSTANCE
static final HidApiLibrary INSTANCE
-
-
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 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 inbytes 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
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 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
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
-
-