HID Class Host Mode Driver
[HID Class Driver - LUFA/Drivers/Class/HID.h]

Data Structures

struct  USB_ClassInfo_HID_Host_t
 HID Class Host Mode Configuration and State Structure. More...

Defines

#define HID_ERROR_LOGICAL   0x80

Enumerations

enum  HIDHost_EnumerationFailure_ErrorCodes_t {
  HID_ENUMERROR_NoError = 0,
  HID_ENUMERROR_InvalidConfigDescriptor = 1,
  HID_ENUMERROR_NoHIDInterfaceFound = 2,
  HID_ENUMERROR_NoHIDDescriptorFound = 3,
  HID_ENUMERROR_EndpointsNotFound = 4
}

Functions

uint8_t HID_Host_ConfigurePipes (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo, uint16_t ConfigDescriptorSize, void *DeviceConfigDescriptor) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3)
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)
bool HID_Host_IsReportReceived (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1)
uint8_t HID_Host_SetBootProtocol (USB_ClassInfo_HID_Host_t *const HIDInterfaceInfo) 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)

Detailed Description

Module Source Dependencies

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

Description

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


Define Documentation

#define HID_ERROR_LOGICAL   0x80

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


Enumeration Type Documentation

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_NoHIDInterfaceFound 

A compatible HID interface was not found in the device's Configuration Descriptor

HID_ENUMERROR_NoHIDDescriptorFound 

The HID descriptor was not found in the device's HID interface

HID_ENUMERROR_EndpointsNotFound 

Compatible HID endpoints were not found in the device's HID interface


Function Documentation

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

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.

Note:
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] DeviceConfigDescriptor Pointer to a buffer containing the attached device's Configuration Descriptor
Returns:
A value from the HIDHost_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.

Note:
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.

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

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.

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

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.

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

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 REPORT_ITEM_TYPE_Out or REPORT_ITEM_TYPE_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_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.

Note:
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.

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
Generated by  doxygen 1.6.3