USB Libraries Help > USB Device Libraries > USB Device Layer Library > Library Interface > f) Control Transfer Functions > USB_DEVICE_ControlReceive Function
MPLAB Harmony USB Stack
USB_DEVICE_ControlReceive Function

This function allows the application to specify the data buffer that would be needed to receive the data stage of a control write transfer. It should be called when the application receives the USB_DEVICE_EVENT_CONTROL_TRANSFER_SETUP_REQUEST event and has identified this setup request as the setup stage of a control write transfer. The function can be called in the Application Control Transfer Event handler or can be called after the application has returned from the control transfer event handler. 

Calling this function after returning from the event handler defers the response to the event. This allows the application to prepare the data buffer out of the event handler context, especially if the data buffer to receive the data is not readily available. Note however, that there are timing considerations when responding to the control transfer. Exceeding the response time will cause the host to cancel the control transfer and may cause USB host to reject the device.

C
USB_DEVICE_CONTROL_TRANSFER_RESULT USB_DEVICE_ControlReceive(
    USB_DEVICE_HANDLE usbDeviceHandle, 
    void * data, 
    size_t length
);
Preconditions

Client handle should be valid.

Parameters
Parameters 
Description 
usbDeviceHandle 
USB device handle returned by USB_DEVICE_Open
 
data 
Pointer to buffer that holds data
 
length 
Size in bytes 
Returns

USB_DEVICE_CONTROL_TRANSFER_RESULT_FAILED - If control transfer failed due to host aborting the previous control transfer. 

USB_DEVICE_CONTROL_TRANSFER_RESULT_SUCCESS - The request was submitted successfully.

Remarks

None.

Example
// The following code example shows an example of how the
// USB_DEVICE_ControlReceive function is called in response to the
// USB_DEVICE_EVENT_CONTROL_TRANSFER_SETUP_REQUEST event to enable a control
// write transfer.

void APP_USBDeviceControlTransferEventHandler
(
    USB_DEVICE_EVENT event,
    void * pData, 
    uintptr_t context
)
{
    uint8_t * setupPkt;

    switch(event)
    {
        case USB_DEVICE_EVENT_CONTROL_TRANSFER_SETUP_REQUEST:

            setupPkt = (uint8_t *)pData;
            
            // Submit a buffer to receive 32 bytes in the  control write transfer.
            // USB_DEVICE_ControlReceive(usbDeviceHandle, data, 32); 
            break;

        case USB_DEVICE_EVENT_CONTROL_TRANSFER_DATA_RECEIVED:

            // This means that data in the data stage of the control
            // write transfer has been received. The application can either
            // accept the received data by calling the
            // USB_DEVICE_ControlStatus function with
            // USB_DEVICE_CONTROL_STATUS_OK flag (as shown in this example)
            // or it can reject it by calling the USB_DEVICE_ControlStatus()
            // function with USB_DEVICE_CONTROL_STATUS_ERROR flag. 

            USB_DEVICE_ControlStatus(usbDeviceHandle, USB_DEVICE_CONTROL_STATUS_OK);
            break;

        case USB_DEVICE_EVENT_CONTROL_TRANSFER_DATA_SENT:
            
            // This means that data in the data stage of the control
            // read transfer has been sent. This indicates that the control transfer is 
            // completed. 

            break;

        case USB_DEVICE_EVENT_CONTROL_TRANSFER_ABORTED:

            // This means the host has aborted the control transfer. The
            // application can reset its control transfer state machine.
        break;
    }
    
}