Data Structures | Defines | 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...

Defines

#define HID_ERROR_LOGICAL   0x80

Enumerations

enum  HID_Host_EnumerationFailure_ErrorCodes_t {
  HID_ENUMERROR_NoError = 0,
  HID_ENUMERROR_InvalidConfigDescriptor = 1,
  HID_ENUMERROR_NoCompatibleInterfaceFound = 2
}

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_NoCompatibleInterfaceFound 

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


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:
The pipe index numbers as given in the interface's configuration structure must not overlap with any other interface, or pipe bank corruption will occur. Gaps in the allocated pipe numbers or non-sequential indexes within a single interface is allowed, but no two interfaces of any type have have interleaved pipe indexes.

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]HIDInterfaceInfoPointer to a structure containing a HID Class host configuration and state.
[in]ConfigDescriptorSizeLength of the attached device's Configuration Descriptor.
[in]DeviceConfigDescriptorPointer 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]HIDInterfaceInfoPointer 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.
Note:
The destination buffer should be large enough to accommodate the largest report that the attached device can generate.
Parameters:
[in,out]HIDInterfaceInfoPointer to a structure containing a HID Class host configuration and state.
[in]BufferBuffer 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]HIDInterfaceInfoPointer to a structure containing a HID Class host configuration and state.
[in]ReportIDReport ID of the received report if ControlRequest is false, set by the to the Report ID to fetch.
[in]BufferBuffer 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]HIDInterfaceInfoPointer to a structure containing a HID Class host configuration and state.
[in]ReportIDReport ID of the report to send to the device, or 0 if the device does not use report IDs.
[in]ReportTypeType of report to issue to the device, either HID_REPORT_ITEM_Out or HID_REPORT_ITEM_Feature.
[in]BufferBuffer containing the report to send to the attached device.
[in]ReportSizeReport 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]HIDInterfaceInfoPointer 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]HIDInterfaceInfoPointer 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]HIDInterfaceInfoPointer to a structure containing a HID Class host configuration and state.