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)
HIDInterfacehid_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.


Generated on Sun Mar 30 15:28:25 2008 for libhid by  doxygen 1.5.1