Fungsi WdfRequestProbeAndLockUserBufferForRead (wdfrequest.h)

Artikel
02/27/2024

[Berlaku untuk KMDF saja]

Metode WdfRequestProbeAndLockUserBufferForRead memverifikasi bahwa buffer mode pengguna permintaan I/O dapat dibaca, dan kemudian mengunci halaman memori fisik buffer sehingga driver di tumpukan driver dapat membaca buffer.

Sintaks

NTSTATUS WdfRequestProbeAndLockUserBufferForRead(
  [in]  WDFREQUEST Request,
  [in]  PVOID      Buffer,
  [in]  size_t     Length,
  [out] WDFMEMORY  *MemoryObject
);

Parameter

[in] Request

Handel ke objek permintaan kerangka kerja.

[in] Buffer

Penunjuk ke buffer input permintaan. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

[in] Length

Panjangnya, dalam byte, dari buffer input permintaan.

[out] MemoryObject

Penunjuk ke lokasi yang menerima handel ke objek memori kerangka kerja yang mewakili buffer input pengguna.

Nilai kembali

WdfRequestProbeAndLockUserBufferForRead mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, metode ini mungkin mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETER	Parameter input tidak valid.
STATUS_INVALID_USER_BUFFER	Parameter Panjang adalah nol.
STATUS_INVALID_DEVICE_REQUEST	Permintaan telah selesai atau tidak valid.
STATUS_ACCESS_VIOLATION	Utas saat ini bukan pembuat permintaan I/O.
STATUS_INSUFFICIENT_RESOURCES	Memori tidak cukup untuk menyelesaikan operasi.

Metode ini mungkin juga mengembalikan nilai NTSTATUS lainnya.

Pemeriksaan bug terjadi jika driver menyediakan handel objek yang tidak valid.

Keterangan

Hanya driver tingkat atas yang dapat memanggil metode WdfRequestProbeAndLockUserBufferForRead , karena metode memerlukan konteks proses proses yang membuat permintaan I/O.

Buffer input pengguna biasanya berisi informasi yang akan ditulis ke perangkat.

Buffer mode pengguna yang ditentukan parameter Buffer dapat menjadi buffer yang diambil WdfRequestRetrieveUnsafeUserInputBuffer , atau dapat menjadi buffer input mode pengguna yang berbeda. Misalnya, kode kontrol I/O yang menggunakan metode akses buffer mungkin melewati struktur yang berisi penunjuk tersemat ke buffer mode pengguna. Dalam kasus seperti itu, driver dapat menggunakanWdfRequestProbeAndLockUserBufferForRead untuk mendapatkan objek memori untuk buffer.

Panjang buffer yang ditentukan parameter Panjang tidak boleh lebih besar dari ukuran aktual buffer. Jika tidak, driver dapat mengakses memori di luar buffer, yang merupakan risiko keamanan.

Jika WdfRequestProbeAndLockUserBufferForRead mengembalikan STATUS_SUCCESS, driver menerima handel ke objek memori kerangka kerja yang mewakili buffer mode pengguna. Untuk mengakses buffer, driver harus memanggil WdfMemoryGetBuffer.

Objek memori kerangka kerja secara otomatis dirilis ketika driver memanggil WdfRequestComplete.

Untuk informasi selengkapnya tentang WdfRequestProbeAndLockUserBufferForRead, lihat Mengakses Buffer Data di Driver Framework-Based.

Contoh

Contoh kode berikut adalah versi singkat dari fungsi panggilan balik EvtIoInCallerContext yang dikandung driver sampel NONPNP . Ketika fungsi panggilan balik menerima permintaan I/O, fungsi ini menentukan apakah permintaan berisi kode kontrol I/O dengan jenis transfer METHOD_NEITHER. Jika permintaan berisi kode kontrol I/O seperti itu, fungsi :

Memanggil WdfRequestRetrieveUnsafeUserInputBuffer dan WdfRequestRetrieveUnsafeUserOutputBuffer untuk mendapatkan alamat virtual buffer baca dan tulis permintaan.
Memanggil WdfRequestProbeAndLockUserBufferForRead dan WdfRequestProbeAndLockUserBufferForWrite untuk memeriksa dan mengunci buffer dan untuk mendapatkan handel ke objek memori kerangka kerja yang mewakili setiap buffer.

VOID
NonPnpEvtIoInCallerContext(
    IN WDFDEVICE  Device,
    IN WDFREQUEST Request
    )
{
    NTSTATUS  status = STATUS_SUCCESS;
    PREQUEST_CONTEXT  reqContext = NULL;
    WDF_OBJECT_ATTRIBUTES  attributes;
    WDF_REQUEST_PARAMETERS  params;
    size_t  inBufLen, outBufLen;
    PVOID  inBuf, outBuf;

    WDF_REQUEST_PARAMETERS_INIT(&params);
    WdfRequestGetParameters(
                            Request,
                            &params
                            );

    //
    // Check to see whether the driver received a METHOD_NEITHER I/O control code.
    // If not, just send the request back to the framework.
    //
    if(!(params.Type == WdfRequestTypeDeviceControl &&
            params.Parameters.DeviceIoControl.IoControlCode ==
                                    IOCTL_NONPNP_METHOD_NEITHER)) {
        status = WdfDeviceEnqueueRequest(
                                         Device,
                                         Request
                                         );
        if( !NT_SUCCESS(status) ) {
            goto End;
        }
        return;
    }

    //
    // The I/O control code is METHOD_NEITHER.
    // First, retrieve the virtual addresses of 
    // the input and output buffers.
    //
    status = WdfRequestRetrieveUnsafeUserInputBuffer(
                                                     Request,
                                                     0,
                                                     &inBuf,
                                                     &inBufLen
                                                     );
    if(!NT_SUCCESS(status)) {
        goto End;
    }
    status = WdfRequestRetrieveUnsafeUserOutputBuffer(
                                                      Request,
                                                      0,
                                                      &outBuf,
                                                      &outBufLen
                                                      );
    if(!NT_SUCCESS(status)) {
       goto End;
    }

    //
    // Next, allocate context space for the request, so that the
    // driver can store handles to the memory objects that will
    // be created for input and output buffers.
    //
    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attributes,
                                        REQUEST_CONTEXT);
    status = WdfObjectAllocateContext(
                                      Request,
                                      &attributes,
                                      &reqContext
                                      );
    if(!NT_SUCCESS(status)) {
        goto End;
    }

    //
    // Next, probe and lock the read and write buffers.
    //
    status = WdfRequestProbeAndLockUserBufferForRead(
                                                     Request,
                                                     inBuf,
                                                     inBufLen,
                                                     &reqContext->InputMemoryBuffer
                                                     );
    if(!NT_SUCCESS(status)) {
        goto End;
    }

    status = WdfRequestProbeAndLockUserBufferForWrite(
                                                      Request,
                                                      outBuf,
                                                      outBufLen,
                                                      &reqContext->OutputMemoryBuffer
                                                      );
    if(!NT_SUCCESS(status)) {
        goto End;
    }

    //
    // Finally, return the request to the framework.
    //
    status = WdfDeviceEnqueueRequest(
                                     Device,
                                     Request
                                     );
    if(!NT_SUCCESS(status)) {
        goto End;
    }
    return;

End:
    WdfRequestComplete(
                       Request,
                       status
                       );
    return;
}

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
Header	wdfrequest.h (termasuk Wdf.h)
Pustaka	Wdf01000.sys (lihat Penerapan Versi Pustaka Kerangka Kerja.)
IRQL	PASSIVE_LEVEL
Aturan kepatuhan DDI	DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Lihat juga

WdfMemoryGetBuffer

WdfRequestProbeAndLockUserBufferForWrite

WdfRequestRetrieveUnsafeUserInputBuffer