Jump to main content

##

# 2.6.4.2 USB_DEVICE_HID_ReportReceive Function

## C

    USB_DEVICE_HID_RESULT USB_DEVICE_HID_ReportReceive(
        USB_DEVICE_HID_INDEX instanceIndex,
        USB_DEVICE_HID_TRANSFER_HANDLE * handle,
        void * buffer,
        size_t size
    );

## Summary

This function submits the buffer to HID function driver library to receive a report from host to device. On completion of the transfer the library generates USB_DEVICE_HID_EVENT_REPORT_RECEIVED event to the application. A handle to the request is passed in the transferHandle parameter. The transfer handle expires when event handler for the USB_DEVICE_HID_EVENT_REPORT_RECEIVED exits. If the receive request could not be accepted, the function returns an error code and transferHandle will contain the value USB_DEVICE_HID_TRANSFER_HANDLE_INVALID.

## Precondition

USB device layer must be initialized.

## Parameters

Parameters | Description
instanceIndex | HID instance index.
handle | HID transfer handle.
buffer | Pointer to buffer where the received report has to be received stored.
size | Buffer size.

## Returns

USB_DEVICE_HID_RESULT_OK - The receive request was successful. transferHandle contains a valid transfer handle.

USB_DEVICE_HID_RESULT_ERROR_TRANSFER_QUEUE_FULL - internal request queue is full. The receive request could not be added.

USB_DEVICE_HID_RESULT_ERROR_INSTANCE_NOT_CONFIGURED - The specified instance is not configured yet.

USB_DEVICE_HID_RESULT_ERROR_INSTANCE_INVALID - The specified instance was not provisioned in the application and is invalid.

## Example

    USB_DEVICE_HID_TRANSFER_HANDLE hidTransferHandle;
      USB_DEVICE_HID_RESULT result;

      // Register APP_HIDEventHandler function
      USB_DEVICE_HID_EventHandlerSet( USB_DEVICE_HID_INDEX_0 ,
                                      APP_HIDEventHandler );

      // Prepare report and request HID to send the report.
      result = USB_DEVICE_HID_ReportReceive( USB_DEVICE_HID_INDEX_0,
                                 &hidTransferHandle ,
                                 &appReport[0], sizeof(appReport));

      if( result != USB_DEVICE_HID_RESULT_OK)
      {
         //Handle error.

      }

      //Implementation of APP_HIDEventHandler

      USB_DEVICE_HIDE_EVENT_RESPONSE APP_HIDEventHandler
      {
        USB_DEVICE_HID_INDEX instanceIndex,
        USB_DEVICE_HID_EVENT event,
        void * pData,
        uintptr_t context
      }
      {
          USB_DEVICE_HID_EVENT_DATA_REPORT_RECEIVED reportReceivedEventData;
          // Handle HID events here.
          switch (event)
          {
              case USB_DEVICE_HID_EVENT_REPORT_RECEIVED:
                 if( (reportReceivedEventData->reportSize == sizeof(appReport)
                      && reportReceivedEventData->report == &appReport[0])
                 {
                    // Previous transfer was complete.
                 }
                 break;
              ....
          }
      }

## Remarks

While the using the HID Function Driver with the PIC32MZ USB module, the report data buffer provided to the USB_DEVICE_HID_ReportReceive function should be placed in coherent memory and aligned at a 16 byte boundary. This can be done by declaring the buffer using the __attribute__((coherent, aligned(16))) attribute. An example is shown here:

    uint8_t data[256] __attribute__((coherent, aligned(16)));