2.6.4.3 USB_DEVICE_HID_ReportSend Function

C

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

Description

This function places a request to send a HID report with the USB Device HID Function Driver Layer. The function places a requests with driver, the request will get serviced when report is requested by the USB Host. A handle to the request is returned in the transferHandle parameter. The termination of the request is indicated by the USB_DEVICE_HID_EVENT_REPORT_SENT event. The amount of data sent, a pointer to the report and the transfer handle associated with the request is returned along with the event in the pData parameter of the event handler. The transfer handle expires when event handler for the USB_DEVICE_HID_EVENT_REPORT_SENT exits. If the send 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 send request was successful. transferHandle contains a valid transfer handle.

USB_DEVICE_HID_RESULT_ERROR_TRANSFER_QUEUE_FULL - Internal request queue is full. The send 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_ReportSend( 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_SENT * reportSentEventData;

    // Handle HID events here.
    switch (event)
    {
        case USB_DEVICE_HID_EVENT_REPORT_SENT:
            
            reportSentEventData = (USB_DEVICE_HID_EVENT_REPORT_SENT *)pData;
            if(reportSentEventData->reportSize == sizeof(appReport))
            {
                // The report was sent completely.
            }
            break;

            ....

    }
    return(USB_DEVICE_HID_EVENT_RESPONSE_NONE);
}

Remarks

While the using the HID Function Driver with the PIC32MZ USB module, the report data buffer provided to the USB_DEVICE_HID_ReportSend 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)));