2.6.4.5 USB_DEVICE_HID_EVENT Enumeration

C

typedef enum {
  USB_DEVICE_HID_EVENT_GET_REPORT,
  USB_DEVICE_HID_EVENT_GET_IDLE,
  USB_DEVICE_HID_EVENT_GET_PROTOCOL,
  USB_DEVICE_HID_EVENT_SET_REPORT,
  USB_DEVICE_HID_EVENT_SET_IDLE,
  USB_DEVICE_HID_EVENT_SET_PROTOCOL,
  USB_DEVICE_HID_EVENT_REPORT_SENT,
  USB_DEVICE_HID_EVENT_REPORT_RECEIVED,
  USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_RECEIVED,
  USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_SENT,
  USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_ABORTED
} USB_DEVICE_HID_EVENT;

Description

USB Device HID Function Driver Events

These events are specific to the USB Device HID Function Driver instance. Each event description contains details about the parameters passed with event. The contents of pData depends on the generated event.

Events that are associated with the HID Function Driver Specific Control Transfers require application response. The application should respond to these events by using the USB_DEVICE_ControlReceive, USB_DEVICE_ControlSend and USB_DEVICE_ControlStatus functions.

Calling the USB_DEVICE_ControlStatus function with a USB_DEVICE_CONTROL_STATUS_ERROR will stall the control transfer request. The application would do this if the control transfer request is not supported. Calling the USB_DEVICE_ControlStatus function with a USB_DEVICE_CONTROL_STATUS_OK will complete the status stage of the control transfer request. The application would do this if the control transfer request is supported.

The following code snippet shows an example of a possible event handling scheme.

// This code example shows all HID Function Driver events and a possible
// scheme for handling these events. In this example event responses are not
// deferred.

USB_DEVICE_HID_EVENT_RESPONSE USB_AppHIDEventHandler
(
    USB_DEVICE_HID_INDEX instanceIndex, 
    USB_DEVICE_HID_EVENT event, 
    void * pData,
    uintptr_t userData
)
{
    uint8_t currentIdleRate;
    uint8_t someHIDReport[128];
    uint8_t someHIDDescriptor[128];
    USB_DEVICE_HANDLE       usbDeviceHandle;
    USB_HID_PROTOCOL_CODE  currentProtocol;
    USB_DEVICE_HID_EVENT_DATA_GET_REPORT        * getReportEventData;
    USB_DEVICE_HID_EVENT_DATA_SET_IDLE          * setIdleEventData;
    USB_DEVICE_HID_EVENT_DATA_SET_DESCRIPTOR    * setDescriptorEventData;
    USB_DEVICE_HID_EVENT_DATA_SET_REPORT        * setReportEventData;

    switch(event)
    {
        case USB_DEVICE_HID_EVENT_GET_REPORT:

            // In this case, pData should be interpreted as a
            // USB_DEVICE_HID_EVENT_DATA_GET_REPORT pointer. The application
            // must send the requested report by using the
            // USB_DEVICE_ControlSend() function. 

            getReportEventData = (USB_DEVICE_HID_EVENT_DATA_GET_REPORT *)pData;
            USB_DEVICE_ControlSend(usbDeviceHandle, someHIDReport, getReportEventData->reportLength);

            break;

        case USB_DEVICE_HID_EVENT_GET_PROTOCOL:

            // In this case, pData will be NULL. The application
            // must send the current protocol to the host by using
            // the USB_DEVICE_ControlSend() function.

           USB_DEVICE_ControlSend(usbDeviceHandle, &currentProtocol, sizeof(USB_HID_PROTOCOL_CODE)); 
           break;
            
        case USB_DEVICE_HID_EVENT_GET_IDLE:

            // In this case, pData will be a
            // USB_DEVICE_HID_EVENT_DATA_GET_IDLE pointer type containing the
            // ID of the report for which the idle rate is being requested.
            // The application must send the current idle rate to the host
            // by using the USB_DEVICE_ControlSend() function.

           USB_DEVICE_ControlSend(usbDeviceHandle, &currentIdleRate, 1); 
           break;

        case USB_DEVICE_HID_EVENT_SET_REPORT:
            
            // In this case, pData should be interpreted as a
            // USB_DEVICE_HID_EVENT_DATA_SET_REPORT type pointer. The
            // application can analyze the request and then obtain the
            // report by using the USB_DEVICE_ControlReceive() function.

            setReportEventData = (USB_DEVICE_HID_EVENT_DATA_SET_REPORT *)pData;
            USB_DEVICE_ControlReceive(deviceHandle, someHIDReport, setReportEventData->reportLength);
            break;

        case USB_DEVICE_HID_EVENT_SET_PROTOCOL:

            // In this case, pData should be interpreted as a 
            // USB_DEVICE_HID_EVENT_DATA_SET_PROTOCOL type pointer. The application can
            // analyze the data and decide to stall or accept the setting.
            // This shows an example of accepting the protocol setting.

            USB_DEVICE_ControlStatus(deviceHandle, USB_DEVICE_CONTROL_STATUS_OK);
            break;
        
        case USB_DEVICE_HID_EVENT_SET_IDLE:
        
            // In this case, pData should be interpreted as a 
            // USB_DEVICE_HID_EVENT_DATA_SET_IDLE type pointer. The
            // application can analyze the data and decide to stall
            // or accept the setting. This shows an example of accepting
            // the protocol setting.

            setIdleEventData = (USB_DEVICE_HID_EVENT_DATA_SET_IDLE *)pData;
            USB_DEVICE_ControlStatus(deviceHandle, USB_DEVICE_CONTROL_STATUS_OK);
            break;

        case USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_RECEIVED:

            // In this case, control transfer data was received. The 
            // application can inspect that data and then stall the
            // handshake stage of the control transfer or accept it
            // (as shown here).
            
            USB_DEVICE_ControlStatus(deviceHandle, USB_DEVICE_CONTROL_STATUS_OK);
            break;

        case USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_SENT:
            
            // This means that control transfer data was sent. The
            // application would typically acknowledge the handshake
            // stage of the control transfer.

            break;

        case USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_ABORTED:

            // This is an indication only event. The application must
            // reset any HID control transfer related tasks when it receives
            // this event.

        break;

        case USB_DEVICE_HID_EVENT_REPORT_RECEIVED:
            
            // This means a HID report receive request has completed.
            // The pData member should be interpreted as a 
            // USB_DEVICE_HID_EVENT_DATA_REPORT_RECEIVED pointer type. 
            
            break;

        case USB_DEVICE_HID_EVENT_REPORT_SENT:
            
            // This means a HID report send request has completed.
            // The pData member should be interpreted as a 
            // USB_DEVICE_HID_EVENT_DATA_REPORT_SENT pointer type. 
            
            break;
    }

    return(USB_DEVICE_HID_EVENT_RESPONSE_NONE);
}

Members

Remarks

Some of the events allow the application to defer responses. This allows the application some time to obtain the response data rather than having to respond to the event immediately. Note that a USB host will typically wait for event response for a finite time duration before timing out and canceling the event and associated transactions. Even when deferring response, the application must respond promptly if such timeouts have to be avoided.