IWDFUsbTargetDevice::FormatRequestForControlTransfer method (wudfusb.h)

[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

See also

IWDFIoRequest

IWDFMemory

IWDFUsbTargetDevice

WDFMEMORY_OFFSET