Fungsi WdfRequestForwardToIoQueue (wdfrequest.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Metode WdfRequestForwardToIoQueue mengantre ulang permintaan I/O ke salah satu antrean I/O driver panggilan.

Sintaks

NTSTATUS WdfRequestForwardToIoQueue(
  [in] WDFREQUEST Request,
  [in] WDFQUEUE   DestinationQueue
);

Parameter

[in] Request

Handel ke objek permintaan kerangka kerja.

[in] DestinationQueue

Handel ke objek antrean kerangka kerja.

Nilai kembali

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

Menampilkan kode	Deskripsi
STATUS_INVALID_DEVICE_REQUEST	Nilai ini dikembalikan jika salah satu hal berikut ini terjadi: Driver tidak mendapatkan permintaan dari antrean I/O. Antrean sumber dan tujuan sama. Antrean sumber dan tujuan bukan milik perangkat yang sama. Driver tidak memiliki permintaan. Permintaan dapat dibatalkan.
STATUS_WDF_BUSY	Antrean tujuan tidak menerima permintaan baru.

Metode ini mungkin juga mengembalikan nilai NTSTATUS lainnya.

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

Keterangan

Driver harus memiliki permintaan I/O dan harus mendapatkan permintaan dari salah satu antrean I/O-nya.

Antrean sumber dan tujuan tidak boleh sama. Dengan kata lain, driver tidak dapat memanggil WdfRequestForwardToIoQueue untuk mengembalikan permintaan ke antrean asalnya. Untuk mengantrekan ulang permintaan ke antrean yang sama, gunakan WdfRequestRequeue.

Antrean sumber dan tujuan harus milik perangkat yang sama.

Permintaan tidak boleh dibatalkan. Jika driver telah memanggil WdfRequestMarkCancelable atau WdfRequestMarkCancelableEx untuk membuat permintaan dapat dibatalkan, itu harus memanggil WdfRequestUnmarkCancelable sebelum memanggil WdfRequestForwardToIoQueue.

Setelah driver memanggil WdfRequestForwardToIoQueue, driver tidak memiliki permintaan antrean ulang sampai kerangka kerja mengirimkan permintaan dari antrean baru ke driver. Saat permintaan berada dalam antrean baru, kerangka kerja memiliki permintaan dan dapat membatalkannya tanpa memberi tahu driver.

Sebelum WdfRequestForwardToIoQueue kembali, peristiwa berikut dapat terjadi:

Jika antrean tujuan kosong, kerangka kerja dapat mengirimkan permintaan I/O yang diantrekan kembali ke salah satu penangan permintaan antrean tujuan.
Jika metode pengiriman antrean sumber berurutan atau paralel, kerangka kerja dapat mengirimkan permintaan lain ke salah satu penangan permintaan antrean sumber.

Untuk informasi selengkapnya tentang WdfRequestForwardToIoQueue, lihat Mengantre ulang Permintaan I/O dan Mengelola Antrean I/O.

Contoh

Contoh kode berikut adalah fungsi panggilan balik EvtIoDeviceControl dari driver sampel PCIDRV . Jika permintaan yang diterima berisi kode kontrol I/O IOCTL_NDISPROT_INDICATE_STATUS, driver memanggil WdfRequestForwardToIoQueue untuk memindahkan permintaan ke antrean I/O yang berbeda.

VOID
PciDrvEvtIoDeviceControl(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  OutputBufferLength,
    IN size_t  InputBufferLength,
    IN ULONG  IoControlCode
    )
{
    NTSTATUS  status= STATUS_SUCCESS;
    PFDO_DATA  fdoData = NULL;
    WDFDEVICE  hDevice;
    WDF_REQUEST_PARAMETERS  params;

    UNREFERENCED_PARAMETER(OutputBufferLength);
    UNREFERENCED_PARAMETER(InputBufferLength);

    hDevice = WdfIoQueueGetDevice(Queue);
    fdoData = FdoGetData(hDevice);

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

    switch (IoControlCode)
    {
        case IOCTL_NDISPROT_QUERY_OID_VALUE:
            NICHandleQueryOidRequest(
                                     Queue,
                                     Request,
                                     &params
                                     );
            break;

        case IOCTL_NDISPROT_SET_OID_VALUE:
            NICHandleSetOidRequest(
                                   Queue,
                                   Request,
                                   &params
                                   );
            break;

        case IOCTL_NDISPROT_INDICATE_STATUS:
            status = WdfRequestForwardToIoQueue(
                                                Request,
                                                fdoData->PendingIoctlQueue
                                                );
            if(!NT_SUCCESS(status)){
                WdfRequestComplete(
                                   Request,
                                   status
                                   );
                break;
            }
            break;

        default:
            WdfRequestComplete(
                               Request,
                               STATUS_INVALID_DEVICE_REQUEST
                               );
            break;
    }
    return;
}

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
Versi UMDF minimum	2.0
Header	wdfrequest.h (termasuk Wdf.h)
Pustaka	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Aturan kepatuhan DDI	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf)