Fungsi WdfRequestStopAcknowledge (wdfrequest.h)

  • Artikel

[Berlaku untuk KMDF dan UMDF]

Metode WdfRequestStopAcknowledge menginformasikan kerangka kerja bahwa driver telah berhenti memproses permintaan I/O tertentu.

Sintaks

void WdfRequestStopAcknowledge(
  [in] WDFREQUEST Request,
  [in] BOOLEAN    Requeue
);

Parameter

[in] Request

Handel ke objek permintaan kerangka kerja.

[in] Requeue

Nilai Boolean yang, jika TRUE, menyebabkan kerangka kerja mengantre ulang permintaan ke dalam antrean sehingga kerangka kerja akan mengirimkannya ke driver lagi. Jika FALSE, kerangka kerja tidak mengantre ulang permintaan. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

Nilai kembali

Tidak ada

Keterangan

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

Jika driver mendaftarkan fungsi panggilan balik EvtIoStop untuk antrean I/O, kerangka kerja memanggilnya ketika perangkat yang mendasar antrean membiarkan status berfungsi (D0). Kerangka kerja memanggil fungsi panggilan balik EvtIoStop untuk setiap permintaan I/O yang belum diselesaikan driver, termasuk permintaan yang dimiliki driver dan yang telah diteruskan ke target I/O. Driver harus menyelesaikan, membatalkan, atau menunda pemrosesan setiap permintaan dengan melakukan salah satu hal berikut:

  • Jika driver memiliki permintaan, driver dapat memanggil WdfRequestComplete untuk menyelesaikan atau membatalkan permintaan.
  • Jika driver telah meneruskan permintaan ke target I/O, driver dapat memanggil WdfRequestCancelSentRequest untuk mencoba membatalkan permintaan.
  • Jika driver menunda pemrosesan permintaan, driver harus memanggil WdfRequestStopAcknowledge.
Jika driver Anda memanggil WdfRequestStopAcknowledge, itu harus memanggil metode ini dari dalam fungsi panggilan balik EvtIoStop-nya .

Kerangka kerja tidak mengizinkan perangkat untuk membiarkan status berfungsi (D0) sampai driver selesai, dibatalkan, atau ditunda setiap permintaan yang diterima fungsi panggilan balik EvtIoStop . Berpotensi, tindakan ini dapat mencegah sistem memasuki status hibernasinya atau status daya sistem rendah lainnya.

Ketika fungsi panggilan balik EvtIoStop driver memanggil WdfRequestStopAcknowledge, fungsi ini dapat mengatur parameter Requeue ke TRUE atau FALSE:

  • Mengatur Antrean Ulang ke TRUE menyebabkan kerangka kerja menempatkan permintaan kembali ke antrean I/O-nya.

    Ketika perangkat yang mendasar kembali ke status berfungsi (D0), kerangka kerja akan mengirimkan kembali permintaan ke driver.

  • Mengatur Antrean Ulang ke FALSE menyebabkan kerangka kerja tidak mengantre ulang permintaan. Jika pengemudi memiliki permintaan, kepemilikan tetap ada pada pengemudi. Jika driver telah meneruskan permintaan, driver bertanggung jawab untuk menangani permintaan ketika selesai. Driver harus berhenti melakukan pemrosesan I/O apa pun yang memerlukan akses perangkat keras.

    Ketika perangkat yang mendasar kembali ke status berfungsi (D0), kerangka kerja akan memanggil fungsi panggilan balik EvtIoResume driver, sehingga driver dapat terus memproses permintaan.

Jika sebelumnya driver telah memanggil WdfRequestMarkCancelable atau WdfRequestMarkCancelableEx, driver harus memanggil WdfRequestUnmarkCancelable sebelum memanggil WdfRequestStopAcknowledge dengan Requeue diatur ke TRUE.

Sebelum memanggil WdfRequestStopAcknowledge, fungsi panggilan balik EvtIoStop driver harus menghentikan semua pemrosesan permintaan I/O yang memerlukan akses perangkat yang mendasar, karena perangkat akan memasuki status daya rendah.

Untuk informasi selengkapnya tentang metode WdfRequestStopAcknowledge , lihat Menggunakan Antrean I/O Power-Managed.

Contoh

Jika driver memanggil WdfRequestStopAcknowledge dengan Requeue diatur ke TRUE, sebelumnya harus memanggil WdfRequestUnmarkCancelable.

Contoh kode berikut adalah fungsi panggilan balik EvtIoStop yang memeriksa untuk melihat apakah permintaan yang diterima dapat dibatalkan dan, jika ya, memanggil WdfRequestUnmarkCancelable. Jika WdfRequestUnmarkCancelable mengembalikan STATUS_CANCELLED, contoh hanya mengembalikan karena fungsi panggilan balik EvtRequestCancel driver akan menangani permintaan. Jika tidak, contoh memanggil WdfRequestStopAcknowledge dan menentukan TRUE sehingga kerangka kerja mengantre ulang permintaan saat perangkat yang mendasar kembali ke status kerja (D0).

VOID
MyEvtIoStop(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN ULONG  ActionFlags
    )
{
    NTSTATUS status;

    // TODO: Take steps here to suspend and, if necessary, roll back any processing that has already occurred on this request

    if (ActionFlags & WdfRequestStopRequestCancelable) {
        status = WdfRequestUnmarkCancelable(Request);
        if (status == STATUS_CANCELLED) {
            return;
        }
    }

    // Inform framework that driver is postponing processing, cause framework to redeliver request when device returns to D0

    WdfRequestStopAcknowledge(Request, TRUE);
}

Biasanya, jika driver memanggil WdfRequestStopAcknowledge dengan Requeue diatur ke FALSE, itu membuat permintaan dapat dibatalkan.

Contoh kode berikut adalah fungsi panggilan balik EvtIoStop yang memanggil WdfRequestStopAcknowledge dan menentukan FALSE sehingga kerangka kerja akhirnya memanggil fungsi panggilan balik EvtIoResume driver, tempat driver melanjutkan pemrosesan permintaan.

Anda mungkin menggunakan kode seperti ini jika dapat diterima untuk menghentikan pemrosesan permintaan tertentu dan melanjutkannya nanti, daripada meminta permintaan dikirim ulang dan memulai ulang pemrosesan dari awal.

VOID
MyEvtIoStop(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN ULONG  ActionFlags
    )
{

    //TODO: Take steps here to suspend processing of the request so it can be resumed when power returns
	 
    // Acknowledge the stop, but leave the request under driver's ownership.
    // Provide a corresponding EvtIoResume handler to resume processing when power returns

    WdfRequestStopAcknowledge(Request, FALSE);
}

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), EvtIoStopCancel(kmdf), EvtIoStopCompleteOrStopAck(kmdf), EvtIoStopResume(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), StopAckWithinEvtIoStop(kmdf)

Lihat juga

EvtIoStop

EvtRequestCancel

WdfRequestComplete