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

Members Description
USB_DEVICE_HID_EVENT_GET_REPORT This event occurs when the host issues a GET REPORT command. This is a HID class specific control transfer related event. The application must interpret the pData parameter as USB_DEVICE_HID_EVENT_DATA_GET_REPORT pointer type. If the report request is supported, the application must send the report to the host by using the USB_DEVICE_ControlSend function either in the event handler or after the event handler routine has returned. The application can track the completion of the request by using the USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_SENT event. If the report request is not supported, the application must stall the request by calling the USB_DEVICE_ControlStatus function with a USB_DEVICE_CONTROL_STATUS_ERROR flag.
USB_DEVICE_HID_EVENT_GET_IDLE This event occurs when the host issues a GET IDLE command. This is a HID class specific control transfer related event. The pData parameter will be a USB_DEVICE_HID_EVENT_DATA_GET_IDLE pointer type containing the ID of the report for which the idle parameter is requested. If the request is supported, the application must send the idle rate to the host by calling the USB_DEVICE_ControlSend function. This function can be called either in the event handler or after the event handler routine has returned. The application can track the completion of the request by using the USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_SENT event. If the request is not supported, the application must stall the request by calling the USB_DEVICE_ControlStatus function with a USB_DEVICE_CONTROL_STATUS_ERROR flag.
USB_DEVICE_HID_EVENT_GET_PROTOCOL This event occurs when the host issues a GET PROTOCOL command. This is a HID class specific control transfer related event. The pData parameter will be NULL. If the request is supported, the application must send a USB_HID_PROTOCOL_CODE data type object, containing the current protocol, to the host by calling the USB_DEVICE_ControlSend function. This function can be called either in the event handler or after the event handler routine has returned. The application can track the completion of the request by using the USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_SENT event. If the request is not supported, the application must stall the request by calling the USB_DEVICE_ControlStatus function with a USB_DEVICE_CONTROL_STATUS_ERROR flag.
USB_DEVICE_HID_EVENT_SET_REPORT This event occurs when the host issues a SET REPORT command. This is a HID class specific control transfer related event. The application must interpret the pData parameter as a USB_DEVICE_HID_EVENT_DATA_SET_REPORT pointer type. If the report request is supported, the application must provide a buffer, to receive the report, to the host by calling the USB_DEVICE_ControlReceive function either in the event handler or after the event handler routine has returned. The application can track the completion of the request by using the USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_RECEIVED event. If the report request is not supported, the application must stall the request by calling the USB_DEVICE_ControlStatus function with a USB_DEVICE_CONTROL_STATUS_ERROR flag.
USB_DEVICE_HID_EVENT_SET_IDLE This event occurs when the host issues a SET IDLE command. This is a HID class specific control transfer related event. The pData parameter will be USB_DEVICE_HID_EVENT_DATA_SET_IDLE pointer type. The application can analyze the idle duration and acknowledge or reject the setting by calling the USB_DEVICE_ControlStatus function. This function can be called in the event handler or after the event handler exits. If application can reject the request by calling the USB_DEVICE_ControlStatus function with a USB_DEVICE_CONTROL_STATUS_ERROR flag. It can accept the request by calling this function with USB_DEVICE_CONTROL_STATUS_OK flag.
USB_DEVICE_HID_EVENT_SET_PROTOCOL This event occurs when the host issues a SET PROTOCOL command. This is a HID class specific control transfer related event. The pData parameter will be a pointer to a USB_DEVICE_HID_EVENT_DATA_SET_PROTOCOL data type. If the request is supported, the application must acknowledge the request by calling the USB_DEVICE_ControlStatus function with a USB_DEVICE_CONTROL_STATUS_OK flag. If the request is not supported, the application must stall the request by calling the USB_DEVICE_ControlStatus function with a USB_DEVICE_CONTROL_STATUS_ERROR flag.
USB_DEVICE_HID_EVENT_REPORT_SENT This event indicates that USB_DEVICE_HID_ReportSend function completed a report transfer on interrupt endpoint from host to device. The pData parameter will be a USB_DEVICE_HID_EVENT_DATA_REPORT_SENT type.
USB_DEVICE_HID_EVENT_REPORT_RECEIVED This event indicates that USB_DEVICE_HID_ReportReceive function completed a report transfer on interrupt endpoint from device to host. The pData parameter will be a USB_DEVICE_HID_EVENT_DATA_REPORT_RECEIVED type.
USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_RECEIVED This event occurs when the data stage of a control write transfer has completed. This happens after the application uses the USB_DEVICE_ControlReceive function to respond to a HID Function Driver Control Transfer Event that requires data to be received from the host. The pData parameter will be NULL. The application should call the USB_DEVICE_ControlStatus function with the USB_DEVICE_CONTROL_STATUS_OK flag if the received data is acceptable or should call this function with USB_DEVICE_CONTROL_STATUS_ERROR flag if the received data needs to be rejected.
USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_SENT This event occurs when the data stage of a control read transfer has completed. This happens after the application uses the USB_DEVICE_ControlSend function to respond to a HID Function Driver Control Transfer Event that requires data to be sent to the host. The pData parameter will be NULL.
USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_ABORTED This event occurs when an ongoing control transfer was aborted. The application must stop any pending control transfer related activities.

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.