IWDFUsbTargetDevice::FormatRequestForControlTransfer method (wudfusb.h)

Article
10/21/2021

[Warning: UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2. For more info, see Getting Started with UMDF.]

The FormatRequestForControlTransfer method formats an I/O request object for a USB control transfer.

Syntax

HRESULT FormatRequestForControlTransfer(
  [in]           IWDFIoRequest        *pRequest,
  [in]           PWINUSB_SETUP_PACKET SetupPacket,
  [in, optional] IWDFMemory           *pMemory,
  [in, optional] PWDFMEMORY_OFFSET    TransferOffset
);

Parameters

[in] pRequest

A pointer to the IWDFIoRequest interface for the request object to format.

[in] SetupPacket

A pointer to a WINUSB_SETUP_PACKET for the control transfer.

[in, optional] pMemory

A pointer to the IWDFMemory interface that is used to access the buffer that is used for the control transfer. This parameter is optional.

[in, optional] TransferOffset

A pointer to a WDFMEMORY_OFFSET structure that describes the memory offset that is used for the control transfer. This parameter is optional.

Return value

FormatRequestForControlTransfer returns one of the following values:

Return code	Description
S_OK	FormatRequestForControlTransfer successfully formatted an I/O request object.
E_OUTOFMEMORY	FormatRequestForControlTransfer encountered an allocation failure.
E_INVALIDARG	The memory offset that the TransferOffset parameter specified was invalid.

Remarks

After a UMDF driver calls FormatRequestForControlTransfer to format an I/O request for a control transfer operation, the framework can subsequently send the request to the I/O target.

Examples

The following code example is taken from the wdf_osrfx2_lab sample in the WDK.

    WINUSB_CONTROL_SETUP_PACKET setupPacket;

    ULONG bytesTransferred;

    HRESULT hr = S_OK;

    //
    // Setup the control packet.
    //

    WINUSB_CONTROL_SETUP_PACKET_INIT( &setupPacket,
                                      BmRequestHostToDevice,
                                      BmRequestToDevice,
                                      USBFX2LK_SET_BARGRAPH_DISPLAY,
                                      0,
                                      0 );

    //
    // Issue the request to WinUsb.
    //

    hr = SendControlTransferSynchronously(
                &(setupPacket.WinUsb),
                (PUCHAR) BarGraphState,
                sizeof(BAR_GRAPH_STATE),
                &bytesTransferred
                );
...

HRESULT
CMyDevice::SendControlTransferSynchronously(
    _In_ PWINUSB_SETUP_PACKET SetupPacket,
    _Inout_updates_(BufferLength) PBYTE Buffer,
    _In_ ULONG BufferLength,
    _Out_ PULONG LengthTransferred
    )
{
    HRESULT hr = S_OK;
    IWDFIoRequest *pWdfRequest = NULL;
    IWDFDriver * FxDriver = NULL;
    IWDFMemory * FxMemory = NULL; 
    IWDFRequestCompletionParams * FxComplParams = NULL;
    IWDFUsbRequestCompletionParams * FxUsbComplParams = NULL;

    *LengthTransferred = 0;
    
    hr = m_FxDevice->CreateRequest( NULL, //pCallbackInterface
                                    NULL, //pParentObject
                                    &pWdfRequest);

    if (SUCCEEDED(hr))
    {
        m_FxDevice->GetDriver(&FxDriver);

        hr = FxDriver->CreatePreallocatedWdfMemory( Buffer,
                                                    BufferLength,
                                                    NULL, //pCallbackInterface
                                                    pWdfRequest, //pParetObject
                                                    &FxMemory );
    }

    if (SUCCEEDED(hr))
    {
        hr = m_pIUsbTargetDevice->FormatRequestForControlTransfer( pWdfRequest,
                                                                   SetupPacket,
                                                                   FxMemory,
                                                                   NULL); //TransferOffset
    }

Requirements

Requirement	Value
End of support	Unavailable in UMDF 2.0 and later.
Target Platform	Desktop
Minimum UMDF version	1.5
Header	wudfusb.h (include Wudfusb.h)
DLL	WUDFx.dll