Fungsi FsRtlCheckOplockEx2 (ntifs.h)

Artikel
02/26/2024

FsRtlCheckOplockEx2 menyinkronkan IRP untuk operasi I/O file dengan status kunci oportunistik (oplock) file saat ini.

Sintaks

NTSTATUS FsRtlCheckOplockEx2(
  [in]           POPLOCK                       Oplock,
  [in]           PIRP                          Irp,
  [in]           ULONG                         Flags,
  [in]           ULONG                         FlagsEx2,
  [in, optional] PVOID                         CompletionRoutineContext,
  [in, optional] POPLOCK_WAIT_COMPLETE_ROUTINE CompletionRoutine,
  [in, optional] POPLOCK_FS_PREPOST_IRP        PostIrpRoutine,
  [in]           ULONGLONG                     Timeout,
  [in, optional] PVOID                         NotifyContext,
  [in, optional] POPLOCK_NOTIFY_ROUTINE        NotifyRoutine
);

Parameter

[in] Oplock

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

[in] Irp

Arahkan ke IRP yang menyatakan operasi I/O yang diminta.

[in] Flags

Bitmask untuk operasi I/O file terkait. Sistem file atau driver filter mengatur bit untuk menentukan perilaku FsRtlCheckOplockEx2. Bendera memiliki opsi berikut:

Nilai Bendera	Makna
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)	Menentukan untuk mengizinkan jeda oplock untuk melanjutkan tanpa memblokir atau menunggu operasi yang menyebabkan jeda oplock.
OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002)	Menentukan bahwa FsRtlCheckOplockEx2 hanya boleh memeriksa kunci oplock pada FILE_OBJECT yang terkait dengan IRP yang ditunjukkan parameter Irp . FsRtlCheckOplockEx2 kemudian harus menambahkan kunci jika ada yang disediakan di IRP. Tidak ada pemrosesan oplock lain yang terjadi; artinya, tidak ada jeda oplock yang akan terjadi. Didukung dimulai dengan Windows 7.
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)	Menentukan bahwa FsRtlCheckOplockEx2 harus mengembalikan status apa pun yang sebelumnya disiapkan melalui panggilan ke rutinitas FsRtlOplockFsctrl . FsRtlOplockFsctrl dipanggil selama pemrosesan permintaan IRP_MJ_CREATE yang menentukan bendera FILE_OPEN_REQUIRING_OPLOCK dalam parameter opsi buat. Bendera OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK biasanya digunakan dalam pemrosesan akhir permintaan buat seperti itu ketika sebelumnya gagal. Didukung dimulai dengan Windows 7.
OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)	Menentukan untuk mengizinkan semua jeda oplock untuk melanjutkan terlepas dari kunci oplock. Didukung dimulai dengan Windows 7.
OPLOCK_FLAG_PARENT_OBJECT (0x00000010)	Menentukan bahwa Oplock dikaitkan dengan induk (direktori) file atau direktori tempat IRP dalam parameter Irp diarahkan. Didukung dimulai dengan Windows 8.
OPLOCK_FLAG_CLOSING_DELETE_ON_CLOSE (0x00000020)	Menentukan bahwa operasi I/O yang ditentukan dalam Irp adalah IRP_MJ_CLEANUP untuk handel yang awalnya dibuka dengan bendera FILE_DELETE_ON_CLOSE yang diatur dalam opsi pembuatannya. Bendera ini tidak berpengaruh jika Irp bukan operasi IRP_MJ_CLEANUP. Menentukan bendera ini dapat mengakibatkan jeda oplock. Didukung dimulai dengan Windows 8.
OPLOCK_FLAG_REMOVING_FILE_OR_LINK (0x00000040)	Menentukan penanganan jeda oplock pada direktori induk saat menghapus file atau tautan di direktori tersebut. Jika ditentukan, bendera ini harus dikombinasikan dengan OPLOCK_FLAG_PARENT_OBJECT. Bendera ini harus ditentukan ketika sistem file memproses operasi yang menghasilkan penghapusan tautan atau file. Didukung dimulai dengan Windows 8.

[in] FlagsEx2

Dipesan; harus diatur ke nol.

[in, optional] CompletionRoutineContext

Arahkan ke informasi konteks yang ditentukan pemanggil untuk diteruskan ke rutinitas panggilan balik yang ditujukan parameter CompletionRoutine . Parameter ini bersifat opsional dan dapat berupa NULL.

[in, optional] CompletionRoutine

Penunjuk ke rutinitas panggilan balik yang disediakan penelepon. Jika pembobolan oplock sedang berlangsung, rutinitas ini dipanggil ketika jeda selesai. Parameter ini bersifat opsional dan dapat berupa NULL. Jika NULL, FsRtlCheckOpLockEx2 beroperasi secara sinkron, menempatkan pemanggil ke dalam status tunggu hingga jeda oplock selesai.

CompletionRoutine dinyatakan sebagai berikut:

typedef VOID
(*POPLOCK_WAIT_COMPLETE_ROUTINE) (
      IN PVOID Context,
      IN PIRP Irp
      );

CompletionRoutine memiliki parameter berikut:

Konteks: Penunjuk informasi konteks yang diteruskan dalam parameter Konteks ke FsRtlCheckOplockEx2.
Irp: Pointer ke IRP untuk operasi I/O.

[in, optional] PostIrpRoutine

Arahkan 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.

PostIrpRoutine dinyatakan sebagai berikut:

typedef VOID
(*POPLOCK_FS_PREPOST_IRP) (
      IN PVOID Context,
      IN PIRP Irp
      );

PostIrpRoutine memiliki parameter berikut:

Konteks, yang merupakan penunjuk informasi konteks yang diteruskan dalam parameter Konteks ke FsRtlCheckOplockEx2.
Irp: Pointer ke IRP untuk operasi I/O.

[in] Timeout

Jika bukan nol, menentukan batas waktu (dalam milidetik) untuk menunggu peristiwa yang digunakan untuk memblokir utas penelepon agar menunggu jeda oplock selesai. Nilai ini diabaikan kecuali kedua kondisi berikut ini benar: CompletionRoutine adalah NULL dan NotifyRoutine bukan NULL.

[in, optional] NotifyContext

Arahkan ke struktur OPLOCK_NOTIFY_PARAMS untuk diteruskan ke rutinitas panggilan balik yang ditujukan parameter NotifyRoutine . Parameter ini bersifat opsional dan dapat berupa NULL.

[in, optional] NotifyRoutine

Penunjuk ke rutinitas panggilan balik yang disediakan penelepon untuk dipanggil untuk pemberitahuan status oplock. Parameter ini bersifat opsional dan dapat berupa NULL.

NotifyRoutine dinyatakan sebagai berikut:

typedef NTSTATUS
(*POPLOCK_NOTIFY_ROUTINE) (
      IN POPLOCK_NOTIFY_PARAMS NotifyParams
      );

NotifyRoutine memiliki parameter berikut:

NotifyParams, yang diatur menjadi parameter NotifyContext yang diteruskan ke FsRtlCheckOplockEx2.

Nilai kembali

FsRtlCheckOplockEx2 mengembalikan STATUS_SUCCESS atau kode NTSTATUS yang sesuai seperti salah satu hal berikut ini:

Menampilkan kode	Deskripsi
STATUS_CANCELLED	IRP dibatalkan. STATUS_CANCELLED adalah kode kesalahan.
STATUS_CANNOT_BREAK_OPLOCK	Pembobolan oplock tidak dapat dicapai. IRP adalah permintaan IRP_MJ_CREATE. FILE_OPEN_REQUIRING_OPLOCK ditentukan dalam parameter opsi buat untuk operasi, dan ada oplock yang diberikan.
STATUS_OPLOCK_BREAK_IN_PROGRESS	Pembobolan oplock sedang berlangsung. IRP adalah permintaan IRP_MJ_CREATE, dan FILE_COMPLETE_IF_OPLOCKED ditentukan dalam parameter opsi buat untuk operasi. STATUS_OPLOCK_BREAK_IN_PROGRESS adalah kode keberhasilan yang dikembalikan jika OPLOCK_FLAG_COMPLETE_IF_OPLOCKED diatur, dan oplock telah rusak.
STATUS_PENDING	Pembobolan oplock sedang berlangsung, dan kontrol IRP diteruskan ke paket oplock. Jika CompletionRoutineADALAH NULL, FsRtlCheckOplockEx2 memblokir saat jeda oplock diproses daripada mengembalikan STATUS_PENDING. STATUS_PENDING adalah kode sukses.

Keterangan

Minifilter harus memanggil FltCheckOplockEx alih-alih FsRtlCheckOplockEx2.

FsRtlCheckOplockEx2 menyinkronkan IRP untuk operasi I/O 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 dan rutinitas penyelesaian dalam CompletionRoutine ditentukan, FsRtlCheckOplockEx2 mengembalikan STATUS_PENDING dan memanggil rutinitas panggilan balik yang ditentukan dalam PostIrpRoutine. Ketika jeda oplock telah diakui, rutinitas panggilan balik dalam CompletionRoutine dipanggil.
Jika operasi I/O tidak dapat dilanjutkan sampai jeda oplock selesai dan CompletionRoutine tidak ditentukan, utas penelepon diblokir dan FsRtlCheckOplockEx2 hanya akan kembali ketika jeda oplock selesai.

Jika utas penelepon diblokir dan NotifyRoutine bukan NULL, NotifyRoutine akan dipanggil karena salah satu atau semua alasan berikut yang ditetapkan di NotifyParams:

OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT
OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED

Panggilan ke NotifyRoutine karena salah satu alasan di atas hanya terjadi jika CompletionRoutine adalah NULL dan perlu untuk memblokir utas penelepon untuk menunggu jeda selesai.

Jika NotifyRoutine dipanggil karena alasan OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT, notifyRoutine akan selalu dipanggil karena alasan OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED jika tunggu berakhir/selesai karena alasan apa pun (yang mungkin tidak pernah).

FsRtlCheckOplockEx2 mengabaikan kode status OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT dan OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED yang dikembalikan oleh NotifyRoutine.

PostIrpRoutine harus ditentukan hanya jika CompletionRoutine telah ditentukan. Ketika PostIrpRoutine bukan NULL, postIrpRoutine dipanggil sebelum apa pun diantrekan ke antrean Irp yang menunggu.

Jika bendera OPLOCK_FLAG_PARENT_OBJECT ditentukan dalam Bendera, FsRtlCheckOplockEx2 akan secara tanpa syarat merusak oplock induk yang ada; artinya, kode utama dalam Irp tidak dipertimbangkan.

Jika sistem file menggunakan oplock, sistem harus memanggil FsRtlCheckOplockEx2 dari rutinitas pengiriman apa pun 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: