| LUFA Library 140302 |

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Data Structures | Macros | Enumerations | Functions
HID Class Host Mode Driver
HID Class Driver

## Data Structures
struct | USB_ClassInfo_HID_Host_t
| HID Class Host Mode Configuration and State Structure. More...

## Macros
#define | HID_ERROR_LOGICAL 0x80

## Enumerations
enum | HID_Host_EnumerationFailure_ErrorCodes_t { HID_ENUMERROR_NoError = 0, HID_ENUMERROR_InvalidConfigDescriptor = 1, HID_ENUMERROR_NoCompatibleInterfaceFound = 2, HID_ENUMERROR_PipeConfigurationFailed = 3 }

## Functions
uint8_t | HID_Host_ConfigurePipes (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo, uint16_t ConfigDescriptorSize, void *ConfigDescriptorData) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3)
bool | HID_Host_IsReportReceived (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1)
uint8_t | HID_Host_ReceiveReport (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo, void *Buffer) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2)
uint8_t | HID_Host_ReceiveReportByID (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo, const uint8_t ReportID, void *Buffer) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3)
uint8_t | HID_Host_SendReportByID (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo, const uint8_t ReportID, const uint8_t ReportType, void *Buffer, const uint16_t ReportSize) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(4)
uint8_t | HID_Host_SetBootProtocol (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1)
uint8_t | HID_Host_SetIdlePeriod (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo, const uint16_t MS) ATTR_NON_NULL_PTR_ARG(1)
uint8_t | HID_Host_SetReportProtocol (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1)
static void | HID_Host_USBTask (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1)

## Detailed Description

# Module Source Dependencies

The following files must be built with any user project that uses this module:

- LUFA/Drivers/USB/Class/Host/HIDClassHost.c (Makefile source module name: LUFA_SRC_USBCLASS)

# Module Description

Host Mode USB Class driver framework interface, for the HID USB Class driver.

## Macro Definition Documentation

#define HID_ERROR_LOGICAL 0x80

Error code for some HID Host functions, indicating a logical (and not hardware) error.

## Enumeration Type Documentation

enum HID_Host_EnumerationFailure_ErrorCodes_t

Enum for the possible error codes returned by the HID_Host_ConfigurePipes() function.

Enumerator
HID_ENUMERROR_NoError | Configuration Descriptor was processed successfully.
HID_ENUMERROR_InvalidConfigDescriptor | The device returned an invalid Configuration Descriptor.
HID_ENUMERROR_NoCompatibleInterfaceFound | A compatible HID interface was not found in the device's Configuration Descriptor.
HID_ENUMERROR_PipeConfigurationFailed | One or more pipes for the specified interface could not be configured correctly.

## Function Documentation

uint8_t HID_Host_ConfigurePipes | ( | USB_ClassInfo_HID_Host_t *const | HIDInterfaceInfo,
|  | uint16_t | ConfigDescriptorSize,
|  | void * | ConfigDescriptorData
| ) |  |

Host interface configuration routine, to configure a given HID host interface instance using the Configuration Descriptor read from an attached USB device. This function automatically updates the given HID Host instance's state values and configures the pipes required to communicate with the interface if it is found within the device. This should be called once after the stack has enumerated the attached device, while the host state machine is in the Addressed state.

Attention
  Once the device pipes are configured, the HID device's reporting protocol must be set via a call to either the HID_Host_SetBootProtocol() or HID_Host_SetReportProtocol() function.

Parameters

  [in,out] | HIDInterfaceInfo | Pointer to a structure containing a HID Class host configuration and state.
  [in] | ConfigDescriptorSize | Length of the attached device's Configuration Descriptor.
  [in] | ConfigDescriptorData | Pointer to a buffer containing the attached device's Configuration Descriptor.

Returns
  A value from the HID_Host_EnumerationFailure_ErrorCodes_t enum.

bool HID_Host_IsReportReceived | ( | USB_ClassInfo_HID_Host_t *const | HIDInterfaceInfo | ) |

Determines if a HID IN report has been received from the attached device on the data IN pipe.

Precondition
  This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the call will fail.

Parameters

  [in,out] | HIDInterfaceInfo | Pointer to a structure containing a HID Class host configuration and state.

Returns
  Boolean `true` if a report has been received, `false` otherwise.

uint8_t HID_Host_ReceiveReport | ( | USB_ClassInfo_HID_Host_t *const | HIDInterfaceInfo,
|  | void * | Buffer
| ) |  |

Receives a HID IN report from the attached HID device, when a report has been received on the HID IN Data pipe.

Precondition
  This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the call will fail.

Attention
  The destination buffer should be large enough to accommodate the largest report that the attached device can generate.

Parameters

  [in,out] | HIDInterfaceInfo | Pointer to a structure containing a HID Class host configuration and state.
  [in] | Buffer | Buffer to store the received report into.

Returns
  An error code from the Pipe_Stream_RW_ErrorCodes_t enum.

uint8_t HID_Host_ReceiveReportByID | ( | USB_ClassInfo_HID_Host_t *const | HIDInterfaceInfo,
|  | const uint8_t | ReportID,
|  | void * | Buffer
| ) |  |

Receives a HID IN report from the attached device, by the report ID.

Precondition
  This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the call will fail.

Note
  When the `HID_HOST_BOOT_PROTOCOL_ONLY` compile time token is defined, this method is unavailable.

Parameters

  [in,out] | HIDInterfaceInfo | Pointer to a structure containing a HID Class host configuration and state.
  [in] | ReportID | Report ID of the received report if ControlRequest is false, set by the to the Report ID to fetch.
  [in] | Buffer | Buffer to store the received report into.

Returns
  A value from the USB_Host_SendControlErrorCodes_t enum.

uint8_t HID_Host_SendReportByID | ( | USB_ClassInfo_HID_Host_t *const | HIDInterfaceInfo,
|  | const uint8_t | ReportID,
|  | const uint8_t | ReportType,
|  | void * | Buffer,
|  | const uint16_t | ReportSize
| ) |  |

Sends an OUT or FEATURE report to the currently attached HID device, using the device's OUT pipe if available, or the device's Control pipe if not.

Precondition
  This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the call will fail.

Note
  When the `HID_HOST_BOOT_PROTOCOL_ONLY` compile time token is defined, the ReportID parameter is removed from the parameter list of this function.

Parameters

  [in,out] | HIDInterfaceInfo | Pointer to a structure containing a HID Class host configuration and state.
  [in] | ReportID | Report ID of the report to send to the device, or 0 if the device does not use report IDs.
  [in] | ReportType | Type of report to issue to the device, either HID_REPORT_ITEM_Out or HID_REPORT_ITEM_Feature.
  [in] | Buffer | Buffer containing the report to send to the attached device.
  [in] | ReportSize | Report size in bytes to send to the attached device.

Returns
  An error code from the USB_Host_SendControlErrorCodes_t enum if the DeviceUsesOUTPipe flag is set in the interface's state structure, a value from the Pipe_Stream_RW_ErrorCodes_t enum otherwise.

uint8_t HID_Host_SetBootProtocol | ( | USB_ClassInfo_HID_Host_t *const | HIDInterfaceInfo | ) |

Switches the attached HID device's reporting protocol over to the Boot Report protocol mode, on supported devices.

Note
  When the `HID_HOST_BOOT_PROTOCOL_ONLY` compile time token is defined, this method must still be called to explicitly place the attached device into boot protocol mode before use.

Parameters

  [in,out] | HIDInterfaceInfo | Pointer to a structure containing a HID Class host configuration and state.

Returns
  HID_ERROR_LOGICAL if the device does not support Boot Protocol mode, a value from the USB_Host_SendControlErrorCodes_t enum otherwise.

uint8_t HID_Host_SetIdlePeriod | ( | USB_ClassInfo_HID_Host_t *const | HIDInterfaceInfo,
|  | const uint16_t | MS
| ) |  |

Sets the idle period for the attached HID device to the specified interval. The HID idle period determines the rate at which the device should send a report, when no state changes have occurred; i.e. on HID keyboards, this sets the hardware key repeat interval.

Parameters

  [in,out] | HIDInterfaceInfo | Pointer to a structure containing a HID Class host configuration and state.
  [in] | MS | Idle period as a multiple of four milliseconds, zero to disable hardware repeats

Returns
  A value from the USB_Host_SendControlErrorCodes_t enum.

uint8_t HID_Host_SetReportProtocol | ( | USB_ClassInfo_HID_Host_t *const | HIDInterfaceInfo | ) |

Switches the attached HID device's reporting protocol over to the standard Report protocol mode. This also retrieves and parses the device's HID report descriptor, so that the size of each report can be determined in advance.

Attention
  Whether this function is used or not, the CALLBACK_HIDParser_FilterHIDReportItem() callback from the HID Report Parser this function references must be implemented in the user code.

Note
  When the `HID_HOST_BOOT_PROTOCOL_ONLY` compile time token is defined, this method is unavailable.

Parameters

  [in,out] | HIDInterfaceInfo | Pointer to a structure containing a HID Class host configuration and state.

Returns
  A value from the USB_Host_SendControlErrorCodes_t enum if an error occurs while retrieving the HID Report descriptor or the setting of the Report protocol, HID_ERROR_LOGICAL if the HID interface does not have a valid HID_ReportInfo_t structure set in its configuration, a mask of HID_ERROR_LOGICAL and a value from the HID_Parse_ErrorCodes_t otherwise.

static void HID_Host_USBTask | ( | USB_ClassInfo_HID_Host_t *const | HIDInterfaceInfo | ) |
| inline static

General management task for a given Human Interface Class host class interface, required for the correct operation of the interface. This should be called frequently in the main program loop, before the master USB management task USB_USBTask().

Parameters

  [in,out] | HIDInterfaceInfo | Pointer to a structure containing a HID Class host configuration and state.