Fungsi WdfIoTargetPurge (wdfiotarget.h)

Artikel
02/29/2024

[Berlaku untuk KMDF dan UMDF]

Metode WdfIoTargetPurge membatalkan semua permintaan I/O yang diantrekan ke target I/O lokal, jarak jauh, atau khusus dan mencegah permintaan I/O baru diantrekan. Metode ini juga mencoba membatalkan permintaan I/O yang telah meninggalkan antrean target I/O dan memasukkan driver yang lebih rendah.

Sintaks

void WdfIoTargetPurge(
  [in] WDFIOTARGET                   IoTarget,
  [in] WDF_IO_TARGET_PURGE_IO_ACTION Action
);

Parameter

[in] IoTarget

Handel ke objek target I/O lokal atau jarak jauh yang diperoleh dari panggilan sebelumnya ke WdfDeviceGetIoTarget atau WdfIoTargetCreate, atau dari metode yang disediakan oleh target I/O khusus, seperti WdfUsbTargetPipeGetIoTarget.

[in] Action

Nilai berjenis WDF_IO_TARGET_PURGE_IO_ACTION yang menunjukkan apakah kerangka kerja harus menunggu untuk kembali dari WdfIoTargetPurge hingga semua permintaan yang dikirim selesai atau dibatalkan.

Nilai kembali

Tidak ada

Keterangan

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

Jika sebelumnya driver telah memanggil WdfUsbTargetPipeConfigContinuousReader, WdfIoTargetPurge harus dipanggil di IRQL = PASSIVE_LEVEL. Jika driver belum memanggil WdfUsbTargetPipeConfigContinuousReader dan jika parameter TindakanWdfIoTargetPurge adalah WdfIoTargetPurgeIo, WdfIoTargetPurge dapat dipanggil di IRQL <= DISPATCH_LEVEL. Jika tidak, WdfIoTargetPurge harus dipanggil di IRQL = PASSIVE_LEVEL.

Untuk menjadikan WdfIoTargetPurge sebagai panggilan sinkron, driver dapat mengatur nilai WdfIoTargetPurgeIoAndWait dari parameter Tindakan . Dalam hal ini, WdfIoTargetPurge menunggu untuk kembali sampai semua permintaan yang dikirim selesai atau dibatalkan.

Setelah driver memanggil WdfIoTargetPurge, driver masih dapat mengirim permintaan ke target dengan mengatur bendera WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE dalam struktur WDF_REQUEST_SEND_OPTIONS permintaan. Misalnya, driver mungkin mengirim permintaan, seperti permintaan untuk mengatur ulang pipa USB (lihat WdfUsbTargetPipeResetSynchronously), ke perangkat setelah driver memanggil WdfIoTargetPurge.

Ketika driver memanggil WdfIoTargetPurge, kerangka kerja tidak mencoba membatalkan atau menunggu permintaan I/O yang sebelumnya dikirim ke target menggunakan bendera WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE atau bendera WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET dalam struktur WDF_REQUEST_SEND_OPTIONS permintaan.

Setelah driver menghapus antrean I/O, driver dapat memulai ulang antrean dengan memanggil WdfIoTargetStart.

Driver Anda harus memanggil WdfIoTargetStart, WdfIoTargetStop dan WdfIoTargetPurge secara sinkron. Setelah driver memanggil salah satu fungsi ini, driver tidak boleh memanggil salah satu yang lain sampai panggilan sebelumnya kembali.

Driver Anda dapat memanggil WdfIoTargetPurge beberapa kali tanpa memanggil WdfIoTargetStart. Misalnya, driver Anda mungkin melakukan hal berikut:

Panggil WdfIoTargetPurge dan tentukan nilai TindakanWdfIoTargetPurgeIo.
Tentukan apakah target harus melanjutkan pemrosesan permintaan I/O.
Jika target harus dilanjutkan, panggil WdfIoTargetStart. Jika tidak, panggil WdfIoTargetPurge lagi dengan nilai TindakanWdfIoTargetPurgeIoAndWait.

Untuk informasi selengkapnya tentang status target I/O, lihat Mengontrol Status Target I/O Umum.

Untuk informasi selengkapnya tentang target I/O, lihat Menggunakan Target I/O.

Contoh

Contoh kode berikut menunjukkan bagaimana fungsi panggilan balik EvtDeviceD0Exit dapat memanggil WdfIoTargetPurge, jika driver menggunakan pembaca berkelanjutan untuk pipa USB.

NTSTATUS
MyEvtDeviceD0Exit(
    IN  WDFDEVICE Device,
    IN  WDF_POWER_DEVICE_STATE TargetState
)
{
    PDEVICE_CONTEXT  pDeviceContext;
    pDeviceContext = GetMyDeviceContext(Device);

    WdfIoTargetPurge(
                    WdfUsbTargetPipeGetIoTarget(pDeviceContext->InterruptPipe),
                    WdfIoTargetPurgeIoAndWait
                    );

    return STATUS_SUCCESS;
}

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1.11
Versi UMDF minimum	2.0
Header	wdfiotarget.h (termasuk Wdf.h)
Pustaka	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	Lihat bagian Keterangan.
Aturan kepatuhan DDI	DriverCreate(kmdf)