2.2.4.31 USB_DEVICE_ControlStatus Function

C

USB_DEVICE_CONTROL_TRANSFER_RESULT USB_DEVICE_ControlStatus(
    USB_DEVICE_HANDLE usbDeviceHandle, 
    USB_DEVICE_CONTROL_STATUS status
);

Summary

This function allows the application to complete the status stage of the of an on-going control transfer. The application must call this function when the data stage of the control transfer is complete or when a Setup Request has been received (in case of a zero data stage control transfer). The application can either accept the data stage/setup command or reject it. Calling this function with status set to USB_DEVICE_CONTROL_STATUS_OK will acknowledge the status stage of the control transfer. The control transfer can be stalled by setting the status parameter to USB_DEVICE_CONTROL_STATUS_ERROR.

The function can be called in the Application Control Transfer event handler or can be called after returning from this event handler. Calling this function after returning from the control transfer event handler defers the response to the event. This allows the application to analyze the event response outside the event handler. 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.

The application must be aware of events and associated control transfers that do or do not require data stages. Incorrect usage of the USB_DEVICE_ControlStatus function could cause the device function to be non-compliant.

Description

Description of the function.

Precondition

Client handle should be valid. This function should only be called to complete an on-going control transfer.

Parameters

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_ControlStatus() function is called in response to the
// USB_DEVICE_EVENT_CONTROL_TRANSFER_DATA_RECEIVED event to complete the 
// control transfer. Here, the application code acknowledges the status 
// stage of the control transfer.

void APP_USBDeviceControlTransferEventHandler
(
    USB_DEVICE_EVENT event,
    void * data, 
    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 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;
    }
} 

Remarks

None.