Class HidApi
- java.lang.Object
-
- org.hid4java.jna.HidApi
-
public class HidApi extends java.lang.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 Summary
Fields Modifier and Type Field Description private static int
DEVICE_ERROR
Device error codeprivate static java.lang.String
DEVICE_NULL
Error message if device is not initialisedprivate static HidApiLibrary
hidApiLibrary
The HID API librarystatic boolean
useLibUsbVariant
Enables use of the libusb variant of the hidapi native library when running on a Linux platform.private static int
WSTR_LEN
Default length for wide string buffer
-
Constructor Summary
Constructors Constructor Description HidApi()
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static void
close(HidDeviceStructure device)
Close a HID devicestatic HidDeviceInfoStructure
enumerateDevices(int vendor, int product)
Enumerate the attached HID devicesstatic void
exit()
Finalise the HID API librarystatic void
freeEnumeration(HidDeviceInfoStructure list)
Free an enumeration linked liststatic int
getFeatureReport(HidDeviceStructure device, byte[] data, byte reportId)
Get a feature report from a HID devicestatic java.lang.String
getIndexedString(HidDeviceStructure device, int idx)
Get a string from a HID device, based on its string indexstatic java.lang.String
getLastErrorMessage(HidDeviceStructure device)
static java.lang.String
getManufacturer(HidDeviceStructure device)
static java.lang.String
getProductId(HidDeviceStructure device)
static java.lang.String
getSerialNumber(HidDeviceStructure device)
static void
init()
Initialise the HID API library.static HidDeviceStructure
open(int vendor, int product, java.lang.String serialNumber)
Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally a serial numberstatic HidDeviceStructure
open(java.lang.String path)
Open a HID device by its path namestatic int
read(HidDeviceStructure device, byte[] buffer)
Read an Input report from a HID devicestatic int
read(HidDeviceStructure device, byte[] buffer, int timeoutMillis)
Read an Input report from a HID device with timeoutstatic int
sendFeatureReport(HidDeviceStructure device, byte[] data, byte reportId)
Send a Feature report to the device using a simplified interfacestatic boolean
setNonBlocking(HidDeviceStructure device, boolean nonBlocking)
Set the device handle to be non-blockingstatic int
write(HidDeviceStructure device, byte[] data, int len, byte reportId)
Write an Output report to a HID device using a simplified interface
-
-
-
Field Detail
-
WSTR_LEN
private static final int WSTR_LEN
Default length for wide string buffer- See Also:
- Constant Field Values
-
DEVICE_NULL
private static final java.lang.String DEVICE_NULL
Error message if device is not initialised- See Also:
- Constant Field Values
-
DEVICE_ERROR
private static final int DEVICE_ERROR
Device error code- See Also:
- Constant Field Values
-
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
-
-
Method Detail
-
open
public static HidDeviceStructure open(int vendor, int product, java.lang.String serialNumber)
Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally a serial number
- Parameters:
vendor
- The vendor IDproduct
- The product IDserialNumber
- 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(java.lang.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 IDproduct
- 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 java.lang.String getLastErrorMessage(HidDeviceStructure device)
- Parameters:
device
- The HID device structure- Returns:
- A string describing the last error which occurred
-
getManufacturer
public static java.lang.String getManufacturer(HidDeviceStructure device)
- Parameters:
device
- The HID device- Returns:
- The device manufacturer string
-
getProductId
public static java.lang.String getProductId(HidDeviceStructure device)
- Parameters:
device
- The HID device- Returns:
- The device product ID
-
getSerialNumber
public static java.lang.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 devicenonBlocking
- 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 devicebuffer
- 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 devicebuffer
- The buffer to read intotimeoutMillis
- 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 notesUnder 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 devicedata
- The buffer to contain the reportreportId
- 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 notesUnder 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 devicedata
- 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 notesIn 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 17hid_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 devicedata
- 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 java.lang.String getIndexedString(HidDeviceStructure device, int idx)
Get a string from a HID device, based on its string index
- Parameters:
device
- The HID deviceidx
- The index- Returns:
- The string
-
-