Fungsi FltCancellableWaitForSingleObject (fltkernel.h)

Artikel
02/29/2024

Rutinitas FltCancellableWaitForSingleObject menjalankan operasi tunggu yang dapat dibatalkan (tunggu yang dapat dihentikan) pada objek dispatcher.

Sintaks

NTSTATUS FLTAPI FltCancellableWaitForSingleObject(
  [in]           PVOID              Object,
  [in, optional] PLARGE_INTEGER     Timeout,
  [in, optional] PFLT_CALLBACK_DATA CallbackData
);

Parameter

[in] Object

Penunjuk ke objek dispatcher yang diinisialisasi (peristiwa, mutex, semaphore, thread, atau timer) tempat penelepon memasok penyimpanan.

[in, optional] Timeout

Penunjuk ke nilai batas waktu opsional. Parameter ini menentukan waktu absolut atau relatif, dalam 100 unit nanodetik, ketika penantian selesai.

Jika Timeout menunjuk ke nilai nol (yaitu, *Waktu habis == 0), rutinitas akan kembali tanpa menunggu. Jika pemanggil menyediakan penunjuk NULL (yaitu, Timeout == NULL), rutin menunggu tanpa batas waktu hingga objek diatur ke status sinyal.

Nilai Batas Waktu positif menentukan waktu absolut, relatif terhadap 1 Januari 1601. Nilai Batas Waktu negatif menentukan interval relatif terhadap waktu saat ini. Waktu kedaluwarsa absolut melacak perubahan apa pun dalam waktu sistem. Waktu kedaluwarsa relatif tidak terpengaruh oleh perubahan waktu sistem.

Jika Waktu habis ditentukan, penantian secara otomatis terpenuhi jika objek tidak diatur ke status yang disinyalkan saat interval yang diberikan kedaluwarsa.

Nilai batas waktu nol (yaitu, *Waktu habis == 0) memungkinkan Anda untuk menguji serangkaian kondisi tunggu, dan untuk melakukan tindakan tambahan secara kondisional jika penantian dapat segera terpenuhi, seperti dalam akuisisi mutex.

[in, optional] CallbackData

Penunjuk ke struktur FLT_CALLBACK_DATA yang mewakili operasi I/O yang dikeluarkan oleh pengguna dan yang dapat dibatalkan oleh pengguna. Pemanggil harus memastikan bahwa operasi I/O akan tetap valid selama durasi rutinitas ini dan bahwa I/O tidak boleh memiliki set rutin pembatalan (misalnya, fungsi FltSetCancelCompletion tidak boleh dipanggil pada operasi I/O). Perhatikan bahwa penelepon harus menahan CallbackData; tidak dapat diteruskan ke driver tingkat bawah.

Nilai kembali

FltCancellableWaitForSingleObject dapat mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
STATUS_SUCCESS	Objek dispatcher yang ditentukan oleh parameter Object telah diatur ke status sinyal.
STATUS_TIMEOUT	Waktu habis terjadi sebelum objek diatur ke status bersinyali. Nilai ini juga dapat dikembalikan ketika kondisi tunggu yang ditentukan tidak dapat segera terpenuhi dan Batas waktu diatur ke nol.
STATUS_ABANDONED_WAIT_0	Penelepon berusaha menunggu mutex yang telah ditinggalkan.
STATUS_CANCELLED	Penantian terganggu oleh permintaan pembatalan yang tertunda pada operasi I/O. Perhatikan bahwa nilai ini dikembalikan hanya jika CallbackData sesuai dengan operasi berbasis IRP diteruskan ke FltCancellableWaitForSingleObject dan I/O dibatalkan oleh rutinitas seperti FltCancelIo.
STATUS_THREAD_IS_TERMINATING	Penantian terganggu karena aplikasi atau pengguna telah mengakhiri utas.

Nilai yang dikembalikan hanya menunjukkan status tunggu.

Perhatikan bahwa makro NT_SUCCESS mengembalikan FALSE ("kegagalan") untuk nilai status STATUS_CANCELLED dan STATUS_THREAD_IS_TERMINATING dan TRUE ("berhasil") untuk semua nilai status lainnya.

Keterangan

Rutinitas FltCancellableWaitForSingleObject menjalankan operasi tunggu yang dapat dibatalkan pada objek dispatcher. Jika pengguna atau aplikasi mengakhiri utas, atau jika I/O yang terkait dengan utas dibatalkan oleh rutinitas seperti FltCancelIo, penantian dibatalkan.

Rutinitas ini dirancang untuk mendukung Pedoman Penyelesaian/Pembatalan I/O. Tujuan dari panduan ini adalah untuk memungkinkan pengguna menghentikan aplikasi dengan cepat. Ini, pada gilirannya, mengharuskan aplikasi memiliki kemampuan untuk dengan cepat mengakhiri utas yang menjalankan I/O dan operasi I/O saat ini. Rutinitas ini menyediakan cara bagi utas pengguna untuk memblokir (yaitu, tunggu) di kernel untuk penyelesaian I/O, objek dispatcher, atau variabel sinkronisasi dengan cara yang memungkinkan penantian dibatalkan dengan mudah. Rutinitas ini juga memungkinkan penantian utas dihentikan jika utas dihentikan oleh pengguna atau aplikasi.

Misalnya, pengalih mungkin perlu membuat operasi I/O sekunder untuk memproses I/O mode pengguna dan secara sinkron menunggu permintaan sekunder selesai. Salah satu cara untuk melakukan ini adalah dengan menyiapkan peristiwa yang akan disinyalkan oleh rutinitas penyelesaian operasi I/O sekunder dan kemudian menunggu peristiwa disinyalkan. Kemudian, untuk melakukan operasi tunggu yang dapat dibatalkan, FltCancellableWaitForSingleObject disebut melewati peristiwa yang terkait dengan operasi I/O sekunder, dan operasi I/O mode pengguna asli. Rangkaian menunggu peristiwa disinyalkan dibatalkan jika peristiwa penghentian tertunda terjadi atau jika operasi I/O mode pengguna asli dibatalkan.

Perhatikan bahwa mengakhiri penantian tidak secara otomatis membatalkan operasi I/O apa pun yang dikeluarkan oleh pemanggil - yang harus ditangani secara terpisah oleh pemanggil.

Pertimbangan khusus berlaku ketika parameter Objek yang diteruskan ke FltCancellableWaitForSingleObject adalah mutex. Jika objek dispatcher yang ditunggu adalah mutex, pengiriman APC sama dengan untuk semua objek dispatcher lainnya selama penantian. Namun, setelah FltCancellableWaitForSingleObject kembali dengan STATUS_SUCCESS dan utas benar-benar memegang mutex, hanya APC mode kernel khusus yang dikirimkan. Pengiriman semua APC lainnya, baik mode kernel maupun mode pengguna, dinonaktifkan. Pembatasan pengiriman APC ini berlanjut hingga mutex dirilis.

Mutex hanya dapat diperoleh secara rekursif waktu MINLONG. Jika batas ini terlampaui, rutinitas akan menimbulkan pengecualian STATUS_MUTANT_LIMIT_EXCEEDED.

FltCancellableWaitForSingleObject harus dipanggil di IRQL PASSIVE_LEVEL jika parameter CallbackData mewakili IRP manajer filter yang valid. Jika tidak, rutinitas dapat dipanggil di IRQL kurang atau sama dengan APC_LEVEL. APC kernel normal dapat dinonaktifkan oleh pemanggil, jika diperlukan, dengan memanggil rutinitas KeEnterCriticalRegion atau FsRtlEnterFileSystem . Namun, APC kernel khusus tidak boleh dinonaktifkan.

Rutinitas FltCancellableWaitForSingleObject akan menegaskan pada build debug jika CallbackData mewakili operasi IRP Filter Manager, tetapi IRP dalam struktur CallbackData adalah NULL.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista
Target Platform	Universal
Header	fltkernel.h (termasuk Fltkernel.h, Ntifs.h)
Pustaka	Fltmgr.lib
DLL	Fltmgr.sys
IRQL	Lihat bagian Keterangan.