Metode IWDFIoRequest2::RetrieveOutputBuffer (wudfddi.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 RequestRetrieveOutputBuffer mengambil buffer output permintaan I/O.

Sintaks

HRESULT RetrieveOutputBuffer(
  [in]            SIZE_T MinimumRequiredCb,
  [out]           PVOID  *Buffer,
  [out, optional] SIZE_T *BufferCb
);

Parameter

[in] MinimumRequiredCb

Ukuran buffer minimum, dalam byte, yang dibutuhkan driver untuk memproses permintaan I/O. Nilai ini bisa nol jika tidak ada ukuran buffer minimum.

[out] Buffer

Penunjuk ke lokasi yang menerima alamat buffer.

[out, optional] BufferCb

Penunjuk ke lokasi yang menerima ukuran buffer, dalam byte. Parameter ini bersifat opsional dan dapat berupa NULL.

Nilai kembali

RequestRetrieveOutputBuffer mengembalikan S_OK jika operasi berhasil. Jika tidak, metode ini dapat mengembalikan nilai berikut:

Menampilkan kode	Deskripsi
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	Permintaan I/O tidak menyediakan buffer output, atau ukuran buffer output kurang dari ukuran minimum yang ditentukan MinimumRequiredCb .
E_OUTOFMEMORY	Tidak tersedia cukup memori untuk mengambil buffer. Driver harus menyelesaikan permintaan dengan nilai status kesalahan.

Metode ini mungkin mengembalikan salah satu nilai lain yang dikandung Winerror.h.

Keterangan

Buffer output permintaan menerima informasi, seperti data dari disk, yang disediakan driver kepada penawali permintaan. Driver Anda dapat memanggil RequestRetrieveOutputBuffer untuk mendapatkan buffer output untuk permintaan baca atau permintaan kontrol I/O perangkat, tetapi tidak untuk permintaan tulis (karena permintaan tulis tidak menyediakan data output).

Metode RequestRetrieveOutputBuffer mengambil buffer output untuk permintaan I/O yang menggunakan I/O yang di-buffer atau metode I/O langsung untuk mengakses buffer data.

Jika RequestRetrieveOutputBuffer mengembalikan S_OK, driver menerima alamat dan, secara opsional, ukuran buffer output.

Driver dapat mengakses buffer yang diambil sampai menyelesaikan permintaan I/O.

Alih-alih memanggil RequestRetrieveOutputBuffer, driver dapat memanggil IWDFIoRequest2::RetrieveOutputMemory, yang membuat objek memori kerangka kerja yang mewakili buffer.

Untuk informasi selengkapnya tentang mengakses buffer data permintaan I/O, lihat Mengakses Buffer Data di Driver UMDF-Based.

Contoh

Contoh kode berikut menunjukkan segmen fungsi panggilan balik IQueueCallbackDeviceIoControl::OnDeviceIoControl driver serial. Segmen kode mendapatkan buffer output permintaan I/O dan kemudian mentransfer informasi laju baud dari perangkat ke buffer.

VOID
STDMETHODCALLTYPE
  CMyQueue::OnDeviceIoControl(
    __in IWDFIoQueue *pWdfQueue,
    __in IWDFIoRequest *pWdfRequest,
    __in ULONG ControlCode,
    __in SIZE_T InputBufferSizeInBytes,
    __in SIZE_T OutputBufferSizeInBytes
    )
{
    HRESULT hr;
    //
    // Declare an IWDFIoRequest2 interface pointer and obtain the
    // IWDFIoRequest2 interface from the IWDFIoRequest interface.
    //
    CComQIPtr<IWDFIoRequest2> r2 = pWdfRequest;

    switch (ControlCode)
    {
        case IOCTL_SERIAL_GET_BAUD_RATE:
        {
            SERIAL_BAUD_RATE *pBaudRateBuffer;
            hr = pWdfRequest2->RetrieveOutputBuffer(sizeof(SERIAL_BAUD_RATE),
                                                    (PVOID*) &pBaudRateBuffer,
                                                    NULL);
            if (SUCCEEDED(hr))
                  {
                      RtlZeroMemory(pBaudRateBuffer, sizeof(SERIAL_BAUD_RATE));
                      pBaudRateBuffer->BaudRate = m_Device->GetBaudRate();
                      reqCompletionInfo = sizeof(SERIAL_BAUD_RATE);
                  }
            
        }
        break;
        ...
    }
    ...
}

Persyaratan

Persyaratan	Nilai
Akhir dukungan	Tidak tersedia di UMDF 2.0 dan yang lebih baru.
Target Platform	Desktop
Versi UMDF minimum	1.9
Header	wudfddi.h (termasuk Wudfddi.h)
DLL	WUDFx.dll