Metode IWDFUsbTargetDevice::FormatRequestForControlTransfer (wudfusb.h)

Artikel
08/08/2023

[Peringatan: UMDF 2 adalah versi terbaru UMDF dan pengganti UMDF 1. Semua driver UMDF baru harus ditulis menggunakan UMDF 2. Tidak ada fitur baru yang ditambahkan ke UMDF 1 dan ada dukungan terbatas untuk UMDF 1 pada versi Windows 10 yang lebih baru. Driver Universal Windows harus menggunakan UMDF 2. Untuk informasi selengkapnya, lihat Mulai menggunakan UMDF.]

Metode FormatRequestForControlTransfer memformat objek permintaan I/O untuk transfer kontrol USB.

Sintaks

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

Parameter

[in] pRequest

Penunjuk ke antarmuka IWDFIoRequest untuk objek permintaan yang akan diformat.

[in] SetupPacket

Penunjuk ke WINUSB_SETUP_PACKET untuk transfer kontrol.

[in, optional] pMemory

Penunjuk ke antarmuka IWDFMemory yang digunakan untuk mengakses buffer yang digunakan untuk transfer kontrol. Parameter ini bersifat opsional.

[in, optional] TransferOffset

Penunjuk ke struktur WDFMEMORY_OFFSET yang menjelaskan offset memori yang digunakan untuk transfer kontrol. Parameter ini bersifat opsional.

Nilai kembali

FormatRequestForControlTransfer mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
S_OK	FormatRequestForControlTransfer berhasil memformat objek permintaan I/O.
E_OUTOFMEMORY	FormatRequestForControlTransfer mengalami kegagalan alokasi.
E_INVALIDARG	Offset memori yang ditentukan parameter TransferOffset tidak valid.

Keterangan

Setelah driver UMDF memanggil FormatRequestForControlTransfer untuk memformat permintaan I/O untuk operasi transfer kontrol, kerangka kerja kemudian dapat mengirim permintaan ke target I/O.

Contoh

Contoh kode berikut diambil dari sampel wdf_osrfx2_lab di 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
    }

Persyaratan

Persyaratan	Nilai
Akhir dukungan	Tidak tersedia di UMDF 2.0 dan yang lebih baru.
Target Platform	Desktop
Versi UMDF minimum	1,5
Header	wudfusb.h (termasuk Wudfusb.h)
DLL	WUDFx.dll