Fungsi WdfDeviceEnqueueRequest (wdfdevice.h)

Artikel
07/02/2025

[Hanya berlaku untuk KMDF]

Metode WdfDeviceEnqueueRequest mengirimkan permintaan I/O tertentu ke kerangka kerja, sehingga kerangka kerja kemudian dapat menambahkan permintaan ke salah satu antrean I/O yang telah dibuat driver untuk perangkat yang ditentukan.

Sintaksis

NTSTATUS WdfDeviceEnqueueRequest(
  [in] WDFDEVICE  Device,
  [in] WDFREQUEST Request
);

Parameter

[in] Device

Handel ke objek perangkat kerangka kerja.

[in] Request

Handel ke objek permintaan kerangka kerja.

Mengembalikan nilai

Jika operasi berhasil, metode akan mengembalikan STATUS_SUCCESS. Nilai pengembalian tambahan meliputi:

Mengembalikan kode	Deskripsi
STATUS_INSUFFICIENT_RESOURCES	Jumlah memori yang tersedia rendah.
STATUS_INVALID_DEVICE_REQUEST	Pengandar belum membuat antrean I/O untuk perangkat, dan driver bukan pengandar filter.
STATUS_WDF_BUSY	Antrean I/O perangkat tidak menerima permintaan.

Metode ini mungkin mengembalikan nilai NTSTATUS lainnya.

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

Komentar

Driver Anda dapat memanggil WdfDeviceEnqueueRequest hanya dari fungsi panggilan balik EvtIoInCallerContext.

Metode WdfDeviceEnqueueRequest menambahkan permintaan ke antrean I/O khusus jenis permintaan driver untuk perangkat, jika driver telah membuatnya. Jika tidak, metode menambahkan permintaan ke antrean default perangkat, jika driver telah membuatnya.

Jika driver belum membuat antrean I/O apa pun untuk perangkat, WdfDeviceEnqueueRequest melakukan hal berikut:

Jika driver adalah driver filter, WdfDeviceEnqueueRequest mengirimkan permintaan ke target I/O driver.
Jika driver bukan driver filter, WdfDeviceEnqueueRequest mengembalikan STATUS_INVALID_DEVICE_REQUEST.

Saat WdfDeviceEnqueueRequeueRequest dijalankan, driver dapat menerima dan menyelesaikan atau membatalkan permintaan.

Akibatnya, jika driver perlu menggunakan permintaan atau konteksnya setelah memanggil WdfDeviceEnqueueRequeueRequest, maka itu harus mengambil referensi pada permintaan sebelum memanggil WdfDeviceEnqueueRequest.

Untuk melakukannya, driver dapat memanggil WdfObjectReference sebelum dan kemudian WdfObjectDereference setelah panggilan ke WdfDeviceEnqueueRequest. Driver harus mendereferensikan permintaan sebelum keluar EvtIoInCallerContext.

Untuk informasi selengkapnya tentang metode WdfDeviceEnqueueRequest, lihat Mengelola Antrean I/O.

Untuk KMDF versi 1.0 dan 1.5, WdfDeviceEnqueueRequest harus dipanggil pada PASSIVE_LEVEL. Untuk versi 1.7 dan yang lebih baru, WdfDeviceEnqueueRequest dapat dipanggil di IRQL <= DISPATCH_LEVEL.

Contoh

Contoh kode berikut adalah fungsi panggilan balik EvtIoInCallerContext yang mencari permintaan yang berisi kode kontrol I/O kustom, IOCTL_NONPNP_METHOD_NEITHER. Jika kode kontrol I/O tidak ditemukan, fungsi panggilan balik hanya mengembalikan permintaan ke kerangka kerja. Jika fungsi panggilan balik menemukan kode kontrol I/O, fungsi tersebut melakukan praproses permintaan lalu mengembalikannya ke kerangka kerja. Jika terjadi kesalahan, fungsi panggilan balik menyelesaikan permintaan.

VOID
MyEvtDeviceIoInCallerContext(
    IN WDFDEVICE  Device,
    IN WDFREQUEST Request
    )
{
    NTSTATUS  status = STATUS_SUCCESS;
    WDF_REQUEST_PARAMETERS  params;

    WDF_REQUEST_PARAMETERS_INIT(&params);
    WdfRequestGetParameters(
                            Request,
                            &params
                            );
    if(!(params.Type == WdfRequestTypeDeviceControl &&
         params.Parameters.DeviceIoControl.IoControlCode == IOCTL_NONPNP_METHOD_NEITHER)) {
        status = WdfDeviceEnqueueRequest(
                                         Device,
                                         Request
                                         );
        if(!NT_SUCCESS(status)) {
            goto End;
        }
        return;
    }
    //
    // Found a match for the control code. Preprocess the request, and then
    // return the request to the framework.
    //

    //...(Preprocess the request here.)

    status = WdfDeviceEnqueueRequest(
                                     Device,
                                     Request
                                     );
    if(!NT_SUCCESS(status)) {
        goto End;
    }
    return;
End:
    WdfRequestComplete(
                       Request,
                       status
                       );
    return;
}

Persyaratan

Syarat	Nilai
Platform Target	Universal
versi KMDF Minimum	1.0
Header	wdfdevice.h (termasuk Wdf.h)
Pustaka	Wdf01000.sys (lihat Penerapan Versi Pustaka Kerangka Kerja.)
IRQL	<= DISPATCH_LEVEL (Lihat bagian keterangan)
aturan kepatuhan DDI	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf)

Lihat juga

WDF_REQUEST_PARAMETERS_INIT

WdfRequestComplete

WdfRequestGetParameters

Bagikan melalui