hid.h File Reference

Main libhid API header file. More...

#include <stdio.h>
#include <usb.h>
#include <hidparser.h>

Go to the source code of this file.

Data Structures
struct	HIDInterface_t
	Interface description. More...
struct	HIDInterfaceMatcher_t
Defines
#define	bool   _Bool
#define	true   1
#define	false   0
#define	HID_ID_MATCH_ANY   0x0000
Typedefs
typedef unsigned char	byte
typedef enum hid_return_t	hid_return
typedef HIDInterface_t	HIDInterface
	Interface description.
typedef _Bool(*)	matcher_fn_t (struct usb_dev_handle const *usbdev, void *custom, unsigned int len)
typedef HIDInterfaceMatcher_t	HIDInterfaceMatcher
typedef enum HIDDebugLevel_t	HIDDebugLevel
	Bitmask for selection of debugging messages.
Enumerations
enum	hid_return_t {   HID_RET_SUCCESS = 0, HID_RET_INVALID_PARAMETER, HID_RET_NOT_INITIALISED, HID_RET_ALREADY_INITIALISED,   HID_RET_FAIL_FIND_BUSSES, HID_RET_FAIL_FIND_DEVICES, HID_RET_FAIL_OPEN_DEVICE, HID_RET_DEVICE_NOT_FOUND,   HID_RET_DEVICE_NOT_OPENED, HID_RET_DEVICE_ALREADY_OPENED, HID_RET_FAIL_CLOSE_DEVICE, HID_RET_FAIL_CLAIM_IFACE,   HID_RET_FAIL_DETACH_DRIVER, HID_RET_NOT_HID_DEVICE, HID_RET_HID_DESC_SHORT, HID_RET_REPORT_DESC_SHORT,   HID_RET_REPORT_DESC_LONG, HID_RET_FAIL_ALLOC, HID_RET_OUT_OF_SPACE, HID_RET_FAIL_SET_REPORT,   HID_RET_FAIL_GET_REPORT, HID_RET_FAIL_INT_READ, HID_RET_NOT_FOUND, HID_RET_TIMEOUT }
enum	HIDDebugLevel_t {   HID_DEBUG_NONE = 0x0, HID_DEBUG_ERRORS = 0x1, HID_DEBUG_WARNINGS = 0x2, HID_DEBUG_NOTICES = 0x4,   HID_DEBUG_TRACES = 0x8, HID_DEBUG_ASSERTS = 0x10, HID_DEBUG_NOTRACES = HID_DEBUG_ERRORS | HID_DEBUG_WARNINGS | HID_DEBUG_NOTICES | HID_DEBUG_ASSERTS, HID_DEBUG_ALL = HID_DEBUG_ERRORS | HID_DEBUG_WARNINGS | HID_DEBUG_NOTICES | HID_DEBUG_TRACES | HID_DEBUG_ASSERTS }
	Bitmask for selection of debugging messages. More...
Functions
void	hid_set_debug (HIDDebugLevel const level)
void	hid_set_debug_stream (FILE *const outstream)
void	hid_set_usb_debug (int const level)
HIDInterface *	hid_new_HIDInterface ()
void	hid_delete_HIDInterface (HIDInterface **const hidif)
void	hid_reset_HIDInterface (HIDInterface *const hidif)
hid_return	hid_init ()
	Initialize libhid: scan for USB busses and devices using libusb.
hid_return	hid_cleanup ()
	Complement to hid_init(): cleans up after libhid.
_Bool	hid_is_initialised ()
	Check to see that hid_init() has been called.
hid_return	hid_open (HIDInterface *const hidif, int const interface, HIDInterfaceMatcher const *const matcher)
hid_return	hid_force_open (HIDInterface *const hidif, int const interface, HIDInterfaceMatcher const *const matcher, unsigned short retries)
hid_return	hid_close (HIDInterface *const hidif)
_Bool	hid_is_opened (HIDInterface const *const hidif)
const char *	hid_strerror (hid_return ret)
hid_return	hid_get_input_report (HIDInterface *const hidif, int const path[], unsigned int const depth, char *const buffer, unsigned int const size)
	Send a control message to retrieve an entire input report.
hid_return	hid_set_output_report (HIDInterface *const hidif, int const path[], unsigned int const depth, char const *const buffer, unsigned int const size)
	Send an entire output report to the device.
hid_return	hid_get_feature_report (HIDInterface *const hidif, int const path[], unsigned int const depth, char *const buffer, unsigned int const size)
	Send a control message to retrieve an entire feature report.
hid_return	hid_set_feature_report (HIDInterface *const hidif, int const path[], unsigned int const depth, char const *const buffer, unsigned int const size)
	Send an entire feature report to the device.
hid_return	hid_get_item_value (HIDInterface *const hidif, int const path[], unsigned int const depth, double *const value)
	Retrieve a numeric input item.
hid_return	hid_write_identification (FILE *const out, HIDInterface const *const hidif)
hid_return	hid_dump_tree (FILE *const out, HIDInterface *const hidif)
hid_return	hid_interrupt_read (HIDInterface *const hidif, unsigned int const ep, char *const bytes, unsigned int const size, unsigned int const timeout)
	Read from the interrupt endpoint.
hid_return	hid_interrupt_write (HIDInterface *const hidif, unsigned int const ep, const char *const bytes, unsigned int const size, unsigned int const timeout)
	Write to the interrupt endpoint.
hid_return	hid_set_idle (HIDInterface *const hidif, unsigned duration, unsigned report_id)
	Execute a Set_Idle request on an Interrupt In pipe.

---

Detailed Description

Main libhid API header file.

This header file forms the public API for libhid. Functions not prototyped here are most likely for internal use only, and may change without notice.

Definition in file hid.h.

---

Define Documentation

#define bool   _Bool

Definition at line 22 of file hid.h.

#define false   0

Definition at line 24 of file hid.h.

#define HID_ID_MATCH_ANY   0x0000

Definition at line 86 of file hid.h.

#define true   1

Definition at line 23 of file hid.h.

---

Typedef Documentation

typedef unsigned char byte

Definition at line 16 of file hid.h.

typedef enum hid_return_t hid_return

typedef enum HIDDebugLevel_t HIDDebugLevel

Bitmask for selection of debugging messages.

The values of this enumeration can be combined with the bitwise-OR operator to select which debug messages should be printed. The selection can be set with hid_set_debug(). You can set a file descriptor for error messages with hid_set_debug_stream().

typedef struct HIDInterface_t HIDInterface

Interface description.

This structure contains information associated with a given USB device interface. The identification information allows multiple HID-class interfaces to be accessed on a single device.

Also available are raw and parsed descriptor information.

typedef struct HIDInterfaceMatcher_t HIDInterfaceMatcher

typedef _Bool(*) matcher_fn_t(struct usb_dev_handle const *usbdev, void *custom, unsigned int len)

Definition at line 73 of file hid.h.

---

Enumeration Type Documentation

enum hid_return_t

Enumerator:

HID_RET_SUCCESS
HID_RET_INVALID_PARAMETER
HID_RET_NOT_INITIALISED
HID_RET_ALREADY_INITIALISED
HID_RET_FAIL_FIND_BUSSES
HID_RET_FAIL_FIND_DEVICES
HID_RET_FAIL_OPEN_DEVICE
HID_RET_DEVICE_NOT_FOUND
HID_RET_DEVICE_NOT_OPENED
HID_RET_DEVICE_ALREADY_OPENED
HID_RET_FAIL_CLOSE_DEVICE
HID_RET_FAIL_CLAIM_IFACE
HID_RET_FAIL_DETACH_DRIVER
HID_RET_NOT_HID_DEVICE
HID_RET_HID_DESC_SHORT
HID_RET_REPORT_DESC_SHORT
HID_RET_REPORT_DESC_LONG
HID_RET_FAIL_ALLOC
HID_RET_OUT_OF_SPACE
HID_RET_FAIL_SET_REPORT
HID_RET_FAIL_GET_REPORT
HID_RET_FAIL_INT_READ
HID_RET_NOT_FOUND
HID_RET_TIMEOUT

Definition at line 27 of file hid.h.

enum HIDDebugLevel_t

Bitmask for selection of debugging messages.

The values of this enumeration can be combined with the bitwise-OR operator to select which debug messages should be printed. The selection can be set with hid_set_debug(). You can set a file descriptor for error messages with hid_set_debug_stream().

Enumerator:

HID_DEBUG_NONE	Default.
HID_DEBUG_ERRORS	Serious conditions.
HID_DEBUG_WARNINGS	Less serious conditions.
HID_DEBUG_NOTICES	Informational messages.
HID_DEBUG_TRACES	Verbose tracing of functions.
HID_DEBUG_ASSERTS	Assertions for sanity checking.
HID_DEBUG_NOTRACES	This is what you probably want to start with while developing with libhid.
HID_DEBUG_ALL

Definition at line 95 of file hid.h.

---

Function Documentation

hid_return hid_cleanup

(

)

Complement to hid_init(): cleans up after libhid.

Definition at line 96 of file hid_initialisation.c.

References ERROR, hid_is_initialised(), HID_RET_NOT_INITIALISED, HID_RET_SUCCESS, initialised, and NOTICE.

Referenced by main().

hid_return hid_close

(

HIDInterface *const

hidif

)

Definition at line 290 of file hid_opening.c.

References HIDInterface_t::dev_handle, HIDInterface_t::hid_data, hid_is_opened(), HIDInterface_t::hid_parser, hid_reset_HIDInterface(), hid_reset_parser(), HID_RET_FAIL_CLOSE_DEVICE, HID_RET_SUCCESS, HIDInterface_t::id, HIDInterface_t::interface, NOTICE, remove_open_device(), TRACE, and WARNING.

Referenced by hid_force_open(), hid_open(), hid_prepare_interface(), and main().

void hid_delete_HIDInterface

(

HIDInterface **const

hidif

)

Definition at line 31 of file hid_initialisation.c.

References ERROR.

Referenced by main().

hid_return hid_dump_tree	(	FILE *const	out,
		HIDInterface *const	hidif
	)

Definition at line 66 of file hid_presentation.c.

References ERROR, HIDInterface_t::hid_data, hid_is_opened(), HIDInterface_t::hid_parser, hid_reset_parser(), HID_RET_DEVICE_NOT_OPENED, HID_RET_INVALID_PARAMETER, HID_RET_SUCCESS, HIDParse(), HIDInterface_t::id, HIDPath::Node, HIDData::Path, HIDPath::Size, TRACE, HIDData::Type, HIDNode::UPage, and HIDNode::Usage.

hid_return hid_force_open	(	HIDInterface *const	hidif,
		int const	interface,
		HIDInterfaceMatcher const *const	matcher,
		unsigned short	retries
	)

Definition at line 241 of file hid_opening.c.

References add_open_device(), ERROR, hid_close(), hid_get_usb_handle(), hid_is_initialised(), hid_is_opened(), hid_os_force_claim(), hid_prepare_interface(), HID_RET_DEVICE_ALREADY_OPENED, HID_RET_INVALID_PARAMETER, HID_RET_NOT_INITIALISED, HID_RET_SUCCESS, HIDInterface_t::id, HIDInterface_t::interface, NOTICE, TRACE, and WARNING.

Referenced by main().

hid_return hid_get_feature_report	(	HIDInterface *const	hidif,
		int const	path[],
		unsigned int const	depth,
		char *const	buffer,
		unsigned int const	size
	)

Send a control message to retrieve an entire feature report.

To use an interrupt endpoint instead of EP0, use hid_interrupt_read().

Parameters:

[in]	hidif	Which interface to query
[in]	path	Path to input item (to find Report ID)
[in]	depth	See hid_find_object()
[out]	buffer	Result is stored here
[in]	size	How many bytes to fetch

Definition at line 135 of file hid_exchange.c.

References ASSERT, HIDInterface_t::dev_handle, HIDInterface_t::hid_data, hid_find_object(), hid_is_initialised(), hid_is_opened(), HID_REPORT_GET, HID_RET_DEVICE_NOT_OPENED, HID_RET_FAIL_GET_REPORT, HID_RET_INVALID_PARAMETER, HID_RET_SUCCESS, HID_RT_FEATURE, HIDInterface_t::id, HIDInterface_t::interface, ITEM_FEATURE, NOTICE, HIDData::ReportID, TRACE, HIDData::Type, USB_TIMEOUT, and WARNING.

hid_return hid_get_input_report	(	HIDInterface *const	hidif,
		int const	path[],
		unsigned int const	depth,
		char *const	buffer,
		unsigned int const	size
	)

Send a control message to retrieve an entire input report.

To use an interrupt endpoint instead of EP0, use hid_interrupt_read().

Parameters:

[in]	hidif	Which interface to query
[in]	path	Path to input item (to find Report ID)
[in]	depth	See hid_find_object()
[out]	buffer	Result is stored here
[in]	size	How many bytes to fetch

Definition at line 23 of file hid_exchange.c.

References ASSERT, HIDInterface_t::dev_handle, HIDInterface_t::hid_data, hid_find_object(), hid_is_initialised(), hid_is_opened(), HID_REPORT_GET, HID_RET_DEVICE_NOT_OPENED, HID_RET_FAIL_GET_REPORT, HID_RET_INVALID_PARAMETER, HID_RET_SUCCESS, HID_RT_INPUT, HIDInterface_t::id, HIDInterface_t::interface, ITEM_INPUT, NOTICE, HIDData::ReportID, TRACE, HIDData::Type, USB_TIMEOUT, and WARNING.

hid_return hid_get_item_value	(	HIDInterface *const	hidif,
		int const	path[],
		unsigned int const	depth,
		double *const	value
	)

Retrieve a numeric input item.

Parameters:

[in]	hidif	Which interface to send to
[in]	path	Path to input item
[in]	depth	See hid_find_object()
[out]	value	Result from hid_extract_value()

Todo:

Handle exponent and unit conversion (separate library?)

Todo:

Dynamically allocate the item buffer

Definition at line 246 of file hid_exchange.c.

References ASSERT, HIDInterface_t::dev_handle, HIDInterface_t::hid_data, hid_extract_value(), hid_find_object(), hid_get_report_size(), hid_is_initialised(), hid_is_opened(), HID_REPORT_GET, HID_RET_DEVICE_NOT_OPENED, HID_RET_FAIL_GET_REPORT, HID_RET_SUCCESS, HID_RT_FEATURE, HIDInterface_t::id, HIDInterface_t::interface, ITEM_FEATURE, NOTICE, HIDData::ReportID, TRACE, HIDData::Type, USB_TIMEOUT, and WARNING.

hid_return hid_init

(

)

Initialize libhid: scan for USB busses and devices using libusb.

Call this routine before making any other libhid calls.

Returns:

HID_RET_SUCCESS if everything was properly initialized.

Definition at line 63 of file hid_initialisation.c.

References ERROR, hid_is_initialised(), HID_RET_ALREADY_INITIALISED, HID_RET_FAIL_FIND_BUSSES, HID_RET_FAIL_FIND_DEVICES, HID_RET_SUCCESS, initialised, NOTICE, and TRACE.

Referenced by main().

hid_return hid_interrupt_read	(	HIDInterface *const	hidif,
		unsigned int const	ep,
		char *const	bytes,
		unsigned int const	size,
		unsigned int const	timeout
	)

Read from the interrupt endpoint.

Parameters:

[in]	hidif	Which interface to send to
[in]	ep	Which endpoint to read
[out]	bytes	Buffer to store results
[in]	size	How many bytes to read
[in]	timeout	How long to wait, in milliseconds

Upon successful completion, the bytes array will contain an input report from the device. It is up to the programmer to determine which input endpoint to read, and to ensure that the endpoint is bitwise-ORed with 0x80 (USB_ENDPOINT_IN).

Definition at line 332 of file hid_exchange.c.

References ASSERT, HIDInterface_t::dev_handle, hid_is_initialised(), hid_is_opened(), HID_RET_DEVICE_NOT_OPENED, HID_RET_FAIL_INT_READ, HID_RET_INVALID_PARAMETER, HID_RET_SUCCESS, HID_RET_TIMEOUT, HIDInterface_t::id, NOTICE, TRACE, and WARNING.

hid_return hid_interrupt_write	(	HIDInterface *const	hidif,
		unsigned int const	ep,
		const char *const	bytes,
		unsigned int const	size,
		unsigned int const	timeout
	)

Write to the interrupt endpoint.

Parameters:

[in]	hidif	Which interface to send to
[in]	ep	Which endpoint to write
[out]	bytes	Buffer to send
[in]	size	How many bytes to write
[in]	timeout	How long to wait, in milliseconds

It is up to the programmer to determine which input endpoint to write.

Definition at line 386 of file hid_exchange.c.

References ASSERT, HIDInterface_t::dev_handle, hid_is_initialised(), hid_is_opened(), HID_RET_DEVICE_NOT_OPENED, HID_RET_FAIL_INT_READ, HID_RET_INVALID_PARAMETER, HID_RET_SUCCESS, HID_RET_TIMEOUT, HIDInterface_t::id, NOTICE, TRACE, and WARNING.

_Bool hid_is_initialised

(

)

Check to see that hid_init() has been called.

Returns:

Non-zero if libhid has been initialized.

Definition at line 111 of file hid_initialisation.c.

References initialised.

Referenced by hid_cleanup(), hid_force_open(), hid_get_feature_report(), hid_get_input_report(), hid_get_item_value(), hid_init(), hid_interrupt_read(), hid_interrupt_write(), hid_open(), hid_set_feature_report(), and hid_set_output_report().

_Bool hid_is_opened

(

HIDInterface const *const

hidif

)

Definition at line 331 of file hid_opening.c.

References HIDInterface_t::dev_handle, and WARNING.

Referenced by hid_close(), hid_dump_tree(), hid_extract_value(), hid_find_object(), hid_find_usb_device(), hid_force_open(), hid_get_feature_report(), hid_get_input_report(), hid_get_item_value(), hid_get_report_size(), hid_get_usb_handle(), hid_init_parser(), hid_interrupt_read(), hid_interrupt_write(), hid_open(), hid_os_force_claim(), hid_prepare_hid_descriptor(), hid_prepare_interface(), hid_prepare_parse_path(), hid_prepare_parser(), hid_prepare_report_descriptor(), hid_reset_parser(), hid_set_feature_report(), hid_set_output_report(), and hid_write_identification().

HIDInterface* hid_new_HIDInterface

(

)

Definition at line 17 of file hid_initialisation.c.

References ERROR, hid_reset_HIDInterface(), and TRACE.

Referenced by main().

hid_return hid_open	(	HIDInterface *const	hidif,
		int const	interface,
		HIDInterfaceMatcher const *const	matcher
	)

Definition at line 194 of file hid_opening.c.

References add_open_device(), HIDInterface_t::dev_handle, ERROR, hid_close(), hid_get_usb_handle(), hid_is_initialised(), hid_is_opened(), hid_prepare_interface(), HID_RET_DEVICE_ALREADY_OPENED, HID_RET_FAIL_CLAIM_IFACE, HID_RET_INVALID_PARAMETER, HID_RET_NOT_INITIALISED, HID_RET_SUCCESS, HIDInterface_t::id, HIDInterface_t::interface, NOTICE, TRACE, and WARNING.

void hid_reset_HIDInterface

(

HIDInterface *const

hidif

)

Definition at line 42 of file hid_initialisation.c.

References HIDInterface_t::dev_handle, HIDInterface_t::device, ERROR, HIDInterface_t::hid_data, HIDInterface_t::hid_parser, HIDInterface_t::id, and HIDInterface_t::interface.

Referenced by hid_close(), and hid_new_HIDInterface().

void hid_set_debug

(

HIDDebugLevel const

level

)

Definition at line 9 of file debug.c.

References hid_debug_level.

void hid_set_debug_stream

(

FILE *const

outstream

)

Definition at line 14 of file debug.c.

References hid_debug_stream.

hid_return hid_set_feature_report	(	HIDInterface *const	hidif,
		int const	path[],
		unsigned int const	depth,
		char const *const	buffer,
		unsigned int const	size
	)

Send an entire feature report to the device.

This routine uses a control message to send the report. To use an interrupt endpoint, use hid_interrupt_write().

Parameters:

[in]	hidif	Which interface to send to
[in]	path	Path to an output item (to find Report ID)
[in]	depth	See hid_find_object()
[in]	buffer	Output Report
[in]	size	How many bytes to send

Definition at line 191 of file hid_exchange.c.

References ASSERT, HIDInterface_t::dev_handle, HIDInterface_t::hid_data, hid_find_object(), hid_is_initialised(), hid_is_opened(), HID_REPORT_SET, HID_RET_DEVICE_NOT_OPENED, HID_RET_FAIL_SET_REPORT, HID_RET_INVALID_PARAMETER, HID_RET_SUCCESS, HID_RT_FEATURE, HIDInterface_t::id, HIDInterface_t::interface, ITEM_FEATURE, NOTICE, HIDData::ReportID, TRACE, HIDData::Type, USB_TIMEOUT, and WARNING.

hid_return hid_set_idle	(	HIDInterface *const	hidif,
		unsigned	duration,
		unsigned	report_id
	)

Execute a Set_Idle request on an Interrupt In pipe.

This is used to tell a device not to send reports unless something has changed (duration = 0), or unless a minimum time interval has passed.

Parameters:

[in]	hidif	Which interface to send to
[in]	duration	0 for indefinite, otherwise in increments of 4 ms (to 1020 ms)
[in]	report_id	0 for all reports, otherwise a Report ID

Definition at line 439 of file hid_exchange.c.

References HIDInterface_t::dev_handle, HID_RET_FAIL_GET_REPORT, HID_RET_INVALID_PARAMETER, HID_RET_SUCCESS, HID_SET_IDLE, HIDInterface_t::id, HIDInterface_t::interface, USB_TIMEOUT, and WARNING.

hid_return hid_set_output_report	(	HIDInterface *const	hidif,
		int const	path[],
		unsigned int const	depth,
		char const *const	buffer,
		unsigned int const	size
	)

Send an entire output report to the device.

This routine uses a control message to send the report. To use an interrupt endpoint, use hid_interrupt_write().

Parameters:

[in]	hidif	Which interface to send to
[in]	path	Path to an output item (to find Report ID)
[in]	depth	See hid_find_object()
[in]	buffer	Output Report
[in]	size	How many bytes to send

Definition at line 79 of file hid_exchange.c.

References ASSERT, HIDInterface_t::dev_handle, HIDInterface_t::hid_data, hid_find_object(), hid_is_initialised(), hid_is_opened(), HID_REPORT_SET, HID_RET_DEVICE_NOT_OPENED, HID_RET_FAIL_SET_REPORT, HID_RET_INVALID_PARAMETER, HID_RET_SUCCESS, HID_RT_OUTPUT, HIDInterface_t::id, HIDInterface_t::interface, ITEM_OUTPUT, NOTICE, HIDData::ReportID, TRACE, HIDData::Type, USB_TIMEOUT, and WARNING.

void hid_set_usb_debug

(

int const

level

)

Definition at line 19 of file debug.c.

const char* hid_strerror

(

hid_return

ret

)

Definition at line 102 of file hid_presentation.c.

References HID_RET_ALREADY_INITIALISED, HID_RET_DEVICE_ALREADY_OPENED, HID_RET_DEVICE_NOT_FOUND, HID_RET_DEVICE_NOT_OPENED, HID_RET_FAIL_ALLOC, HID_RET_FAIL_CLAIM_IFACE, HID_RET_FAIL_CLOSE_DEVICE, HID_RET_FAIL_DETACH_DRIVER, HID_RET_FAIL_FIND_BUSSES, HID_RET_FAIL_FIND_DEVICES, HID_RET_FAIL_GET_REPORT, HID_RET_FAIL_INT_READ, HID_RET_FAIL_OPEN_DEVICE, HID_RET_FAIL_SET_REPORT, HID_RET_HID_DESC_SHORT, HID_RET_INVALID_PARAMETER, HID_RET_NOT_FOUND, HID_RET_NOT_HID_DEVICE, HID_RET_NOT_INITIALISED, HID_RET_OUT_OF_SPACE, HID_RET_REPORT_DESC_LONG, HID_RET_REPORT_DESC_SHORT, HID_RET_SUCCESS, and HID_RET_TIMEOUT.

hid_return hid_write_identification	(	FILE *const	out,
		HIDInterface const *const	hidif
	)

Definition at line 9 of file hid_presentation.c.

References HIDInterface_t::dev_handle, HIDInterface_t::device, ERROR, hid_is_opened(), HID_RET_DEVICE_NOT_OPENED, HID_RET_INVALID_PARAMETER, HID_RET_SUCCESS, and HIDInterface_t::id.

---