Fungsi FltCheckOplock (fltkernel.h)

Artikel
03/05/2024

Driver minifilter memanggil FltCheckOplock untuk menyinkronkan struktur data panggilan balik untuk operasi I/O file berbasis IRP dengan status kunci oportunistik (oplock) file saat ini.

Sintaks

FLT_PREOP_CALLBACK_STATUS FLTAPI FltCheckOplock(
  [in]           POPLOCK                                 Oplock,
  [in]           PFLT_CALLBACK_DATA                      CallbackData,
  [in, optional] PVOID                                   Context,
  [in, optional] PFLTOPLOCK_WAIT_COMPLETE_ROUTINE        WaitCompletionRoutine,
  [in, optional] PFLTOPLOCK_PREPOST_CALLBACKDATA_ROUTINE PrePostCallbackDataRoutine
);

Parameter

[in] Oplock

Penunjuk oplock buram untuk file. Pointer ini harus diinisialisasi oleh panggilan sebelumnya ke FltInitializeOplock.

[in] CallbackData

Penunjuk ke struktur data panggilan balik (FLT_CALLBACK_DATA) untuk operasi I/O.

[in, optional] Context

Penunjuk ke informasi konteks yang ditentukan pemanggil untuk diteruskan ke rutinitas panggilan balik yang ditunjukkan oleh WaitCompletionRoutine dan PrePostCallbackDataRoutine . Manajer Filter memperlakukan informasi ini sebagai buram.

[in, optional] WaitCompletionRoutine

Penunjuk ke rutinitas panggilan balik yang disediakan penelepon. Jika pemutusan oplock sedang berlangsung, Manajer Filter memanggil rutinitas ini ketika pemutusan oplock selesai. Parameter ini bersifat opsional dan dapat berupa NULL. Jika NULL, penelepon dimasukkan ke dalam status tunggu sampai pemecahan oplock selesai.

Rutinitas ini dinyatakan sebagai berikut:

typedef VOID
(*PFLTOPLOCK_WAIT_COMPLETE_ROUTINE) (
      IN PFLT_CALLBACK_DATA CallbackData,
      IN PVOID Context
      );

Rutinitas ini memiliki parameter berikut:

CallbackData

Arahkan ke struktur data panggilan balik untuk operasi I/O.

Konteks

Penunjuk informasi konteks yang diteruskan dalam parameter Konteks ke FltCheckOplock.

[in, optional] PrePostCallbackDataRoutine

Penunjuk ke rutinitas panggilan balik yang disediakan penelepon untuk dipanggil jika operasi I/O diposting ke antrean kerja. Parameter ini bersifat opsional dan dapat berupa NULL.

Rutinitas ini dinyatakan sebagai berikut:

typedef VOID
(*PFLTOPLOCK_PREPOST_CALLBACKDATA_ROUTINE) (
      IN PFLT_CALLBACK_DATA CallbackData,
      IN PVOID Context
      );

CallbackData

Penunjuk ke struktur data panggilan balik untuk operasi I/O.

Konteks

Penunjuk informasi konteks yang diteruskan dalam parameter Konteks ke FltCheckOplock.

Nilai kembali

FltCheckOplock mengembalikan salah satu kode FLT_PREOP_CALLBACK_STATUS berikut:

Menampilkan kode	Deskripsi
FLT_PREOP_COMPLETE	FltCheckOplock mengalami kegagalan alokasi kumpulan, atau panggilan ke fungsi FsRtlCheckOplock mengembalikan kesalahan. FltCheckOplock akan mengatur kode kesalahan di anggota Status dari struktur IO_STATUS_BLOCK anggota IoStatus dari struktur data panggilan balik FLT_CALLBACK_DATA . Parameter CallbackData menunjuk ke FLT_CALLBACK_DATA ini.
FLT_PREOP_PENDING	Pemutusan oplock dimulai, yang menyebabkan Manajer Filter memposting operasi I/O ke antrean kerja. Operasi I/O diwakili oleh data panggilan balik yang ditunjuk oleh parameter CallbackData .
FLT_PREOP_SUCCESS_WITH_CALLBACK	Operasi I/O segera dilakukan. Ketahuilah bahwa jika operasi ini adalah operasi buat yang ditentukan FILE_COMPLETE_IF_OPLOCKED dalam parameter create-options, mungkin sebenarnya ada pemutusan oplock yang sedang berlangsung meskipun operasi dilakukan segera. Untuk menentukan apakah ini situasinya, pemanggil harus memeriksa status di anggota Status struktur IO_STATUS_BLOCK anggota IoStatus dari struktur data panggilan balik FLT_CALLBACK_DATA .

Keterangan

Driver minifilter memanggil FltCheckOplock untuk menyinkronkan operasi I/O berbasis IRP dengan status oplock file saat ini sesuai dengan kondisi berikut:

Jika operasi I/O akan menyebabkan oplock rusak, jeda oplock dimulai.
Jika operasi I/O tidak dapat dilanjutkan sampai jeda oplock selesai, FltCheckOplock mengembalikan FLT_PREOP_PENDING dan memanggil rutinitas panggilan balik yang ditunjuk oleh parameter PrePostCallbackDataRoutine .

Jika driver minifilter menggunakan oplock, driver harus memanggil FltCheckOplock dari rutinitas callback praoperasi (PFLT_PRE_OPERATION_CALLBACK) untuk operasi I/O yang dapat menyebabkan jeda oplock. Aturan ini berlaku untuk jenis operasi I/O berikut, karena operasi ini dapat menyebabkan jeda oplock:

IRP_MJ_CLEANUP

IRP_MJ_CREATE

IRP_MJ_FILE_SYSTEM_CONTROL

IRP_MJ_FLUSH_BUFFERS

IRP_MJ_LOCK_CONTROL

IRP_MJ_READ

IRP_MJ_SET_INFORMATION

IRP_MJ_WRITE

Operasi I/O harus merupakan operasi I/O berbasis IRP. Untuk menentukan apakah struktur data panggilan balik tertentu mewakili operasi I/O berbasis IRP, gunakan makro FLT_IS_IRP_OPERATION .

Minifilter tidak boleh memanggil FltCheckOplock lagi dalam panggilan balik yang ditentukan dalam WaitCompletionRoutine. Melakukannya dapat mengakibatkan kondisi kebuntuan jika paket oplock memanggil panggilan balik penyelesaian sebelum FltCheckOplock kembali.

Untuk informasi mendetail tentang kunci oportunistik, lihat dokumentasi Microsoft Windows SDK.