IWDFUsbTargetDevice：：FormatRequestForControlTransfer 方法 (wudfusb.h)

發行項
03/01/2024

[警告： UMDF 2 是最新版的 UMDF，並取代 UMDF 1。所有新的UMDF驅動程式都應該使用UMDF 2撰寫。未將新功能新增至 UMDF 1，且較新版本的 #D9127083A0C894E058B1FBE71C045ECC9 上，UMDF 1 的支援有限。通用 Windows 驅動程式必須使用 UMDF 2。如需詳細資訊，請參閱使用 UMDF 使用者入門。]

FormatRequestForControlTransfer 方法會格式化 USB 控件傳輸的 I/O 要求物件。

語法

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

參數

[in] pRequest

要格式化之要求物件的 IWDFIoRequest 介面指標。

[in] SetupPacket

控件傳輸 WINUSB_SETUP_PACKET 的指標。

[in, optional] pMemory

IWDFMemory 介面的指標，用來存取用於控制傳輸的緩衝區。這是選擇性參數。

[in, optional] TransferOffset

WDFMEMORY_OFFSET 結構的指標，描述用於控制傳輸的記憶體位移。這是選擇性參數。

傳回值

FormatRequestForControlTransfer 會傳回下列其中一個值：

傳回碼	Description
S_OK	FormatRequestForControlTransfer 已成功格式化 I/O 要求物件。
E_OUTOFMEMORY	FormatRequestForControlTransfer 發生配置失敗。
E_INVALIDARG	指定的 TransferOffset 參數無效的記憶體位移。

備註

在UMDF驅動程式呼叫 FormatRequestForControlTransfer 來格式化控件傳輸作業的 I/O 要求之後，架構接著可以將要求傳送至 I/O 目標。

範例

下列程式代碼範例取自 WDK 中的 wdf_osrfx2_lab 範例。

    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
    }

規格需求

需求	值
終止支援	在 UMDF 2.0 和更新版本中無法使用。
目標平台	桌面
最低UMDF版本	1.5
標頭	wudfusb.h (包含 Wudfusb.h)
Dll	WUDFx.dll