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 |
---|---|
|
FormatRequestForControlTransfer successfully formatted an I/O request object. |
|
FormatRequestForControlTransfer encountered an allocation failure. |
|
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 |