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

Nested Class Summary

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

com.sun.jna.Library.Handler

Field Summary

Fields

Modifier and Type	Field and Description
static HidApiLibrary	INSTANCE

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

Modifier and Type	Method and 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_path(String path) Open a HID device by its path name.
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.
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_read(com.sun.jna.Pointer device, com.sun.jna.Structure.ByReference bytes, int length) Read an Input report from a HID device.
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 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 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 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