Fungsi WdfIoTargetStop (wdfiotarget.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Metode WdfIoTargetStop berhenti mengirim permintaan antrean ke target I/O lokal atau jarak jauh.

Sintaks

void WdfIoTargetStop(
  [in] WDFIOTARGET                  IoTarget,
  [in] WDF_IO_TARGET_SENT_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 target I/O khusus.

[in] Action

Nilai berjenis WDF_IO_TARGET_SENT_IO_ACTION yang menentukan bagaimana kerangka kerja harus menangani permintaan I/O yang telah dikirim driver ke target I/O, jika target belum menyelesaikan permintaan.

Nilai kembali

Tidak ada

Keterangan

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

Jika driver Anda dapat mendeteksi kesalahan perangkat yang dapat dipulihkan, Anda mungkin ingin driver Anda memanggil WdfIoTargetStop untuk berhenti mengirim permintaan untuk sementara waktu, kemudian panggil WdfIoTargetStart untuk melanjutkan pengiriman permintaan.

Saat dihentikan, target I/O terus menerima permintaan baru tetapi tidak mengirimkan permintaan antrean ke driver yang sesuai.

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

Jika driver memanggil WdfUsbTargetPipeConfigContinuousReader untuk mengonfigurasi pembaca berkelanjutan untuk pipa USB, fungsi panggilan balik EvtDeviceD0Exit driver harus memanggil WdfIoTargetStop untuk menghentikan pembaca.

Jika driver telah memanggil WdfIoTargetStop, driver masih dapat mengirim permintaan ke target dengan mengatur bendera WDF_REQUEST_OPTION_IGNORE_TARGET_STATE dalam struktur WDF_REQUEST_SEND_OPTIONS permintaan. Jika driver mengatur bendera ini, driver dapat mengirim permintaan, seperti permintaan untuk mengatur ulang pipa USB (lihat WdfUsbTargetPipeResetSynchronously), ke perangkat setelah driver memanggil WdfIoTargetStop.

Ketika driver memanggil WdfIoTargetStop, 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.

Driver Anda harus memanggil WdfIoTargetStart dan WdfIoTargetStop secara sinkron. Setelah driver memanggil salah satu fungsi ini, driver tidak boleh memanggil salah satu fungsi sebelum panggilan pertama kembali.

Driver Anda dapat memanggil WdfIoTargetStop beberapa kali dari satu utas tanpa memanggil WdfIoTargetStart. Misalnya, driver Anda mungkin melakukan hal berikut:

Panggil WdfIoTargetStop dan tentukan nilai TindakanWdfIoTargetLeaveSentIoPending.
Tentukan apakah target harus melanjutkan pemrosesan permintaan I/O.
Jika target harus dilanjutkan, panggil WdfIoTargetStart. Jika tidak, panggil WdfIoTargetStop lagi dengan nilai TindakanWdfIoTargetCancelSentIo.

CatatanWdfIoTargetStop tidak aman untuk utas. Tidak aman untuk memanggil WdfIoTargetStop secara bersamaan dari utas yang berbeda.

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

Jika driver telah memanggil WdfUsbTargetPipeConfigContinuousReader untuk pipa, WdfIoTargetStop harus dipanggil di IRQL = PASSIVE_LEVEL.

Jika driver belum memanggil WdfUsbTargetPipeConfigContinuousReader dan jika parameter TindakanWdfIoTargetStop adalah WdfIoTargetLeaveSentIoPending, WdfIoTargetStop dapat dipanggil di IRQL <= DISPATCH_LEVEL. Jika tidak, WdfIoTargetStop dipanggil di IRQL = PASSIVE_LEVEL.

Contoh

Contoh kode berikut menunjukkan bagaimana fungsi panggilan balik EvtDeviceD0Exit dapat memanggil WdfIoTargetStop, 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);

    WdfIoTargetStop(
                    WdfUsbTargetPipeGetIoTarget(pDeviceContext->InterruptPipe),
                    WdfIoTargetCancelSentIo
                    );

    return STATUS_SUCCESS;
}

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
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), FailD0EntryIoTargetState(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)