2.2.4.30 USB_DEVICE_ControlSend Function

C

USB_DEVICE_CONTROL_TRANSFER_RESULT USB_DEVICE_ControlSend(
    USB_DEVICE_HANDLE usbDeviceHandle, 
    void * data, 
    size_t length
);

Summary

This function allows the application to specify the data that would be sent to host in the data stage of a control read transfer. It should be called when the application has received the USB_DEVICE_EVENT_CONTROL_TRANSFER_SETUP_REQUEST event and has identified this setup request as the setup stage of a control read transfer. The Device Layer will generate a USB_DEVICE_EVENT_CONTROL_TRANSFER_DATA_SENT event when the data stage has completed. 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.

Precondition

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.

Example

// The following code example shows an example of how the
// USB_DEVICE_ControlSend() function is called in response to the
// USB_DEVICE_EVENT_CONTROL_TRANSFER_SETUP_REQUEST event to enable a control
// read transfer.

void APP_USBDeviceEventHandler
(
    USB_DEVICE_EVENT event, 
    void * pData, 
    uintptr_t context
)
{
    USB_SETUP_PACKET * setupPkt;

    switch(event)
    {
        case USB_DEVICE_EVENT_CONTROL_TRANSFER_SETUP_REQUEST:

            setupPkt = (USB_SETUP_PACKET *)pData;
            
            // Submit a buffer to send 32 bytes in the  control read transfer.
            USB_DEVICE_ControlSend(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;
    }
    
} 

Remarks

None.