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

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)));