IWDFUsbTargetDevice::FormatRequestForControlTransfer method

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

pRequest [in]: A pointer to the IWDFIoRequest interface for the request object to format.
SetupPacket [in]: A pointer to a WINUSB_SETUP_PACKET for the control transfer.
pMemory [in, optional]: A pointer to the IWDFMemory interface that is used to access the buffer that is used for the control transfer. This parameter is optional.
TransferOffset [in, optional]: 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

End of support	Unavailable in UMDF 2.0 and later.
Minimum UMDF version	1.5
Header	Wudfusb.h (include Wudfusb.h)
DLL	WUDFx.dll