Fungsi FsRtlCheckOplockEx (ntifs.h)

Artikel
10/04/2023

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

Sintaks

NTSTATUS FsRtlCheckOplockEx(
  [in]           POPLOCK                       Oplock,
  [in]           PIRP                          Irp,
  [in]           ULONG                         Flags,
  [in, optional] PVOID                         Context,
  [in, optional] POPLOCK_WAIT_COMPLETE_ROUTINE CompletionRoutine,
  [in, optional] POPLOCK_FS_PREPOST_IRP        PostIrpRoutine
);

Parameter

[in] Oplock

Penunjuk kunci oportunistik buram untuk file. Pointer ini harus diinisialisasi oleh panggilan sebelumnya ke FsRtlInitializeOplock.

[in] Irp

Penunjuk ke IRP untuk operasi I/O.

[in] Flags

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

Nilai	Makna
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)	Menentukan untuk memungkinkan pemutusan kunci oportunistik untuk melanjutkan tanpa memblokir atau menunggu operasi yang menyebabkan oplock rusak.
OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002)	Didukung dimulai dengan Windows 7. Menentukan bahwa FsRtlCheckOplockEx hanya boleh memeriksa kunci kunci oportunistik pada FILE_OBJECT yang terkait dengan IRP yang dituju parameter Irp . FsRtlCheckOplockEx kemudian harus menambahkan kunci jika kunci disediakan di IRP. Tidak ada pemrosesan oplock lain yang terjadi; artinya, tidak ada pemutusan kunci oportunistik yang akan terjadi.
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)	Didukung dimulai dengan Windows 7. Menentukan bahwa FsRtlCheckOplockEx 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.
OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)	Didukung dimulai dengan Windows 7. Menentukan untuk mengizinkan semua pemutusan kunci oportunistik untuk melanjutkan terlepas dari kunci kunci oportunistik.
OPLOCK_FLAG_PARENT_OBJECT (0x00000010)	Didukung dimulai dengan Windows 8. Menentukan bahwa Oplock dikaitkan dengan induk (direktori) file atau direktori tempat IRP dalam parameter Irp diarahkan.
OPLOCK_FLAG_CLOSING_DELETE_ON_CLOSE (0x00000020)	Didukung dimulai dengan Windows 8. 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 pemutusan kunci oportunistik.
OPLOCK_FLAG_REMOVING_FILE_OR_LINK (0x00000040)	Didukung dimulai dengan Windows 8. Menentukan penanganan pemutusan kunci oportunistik pada direktori induk saat menghapus file atau tautan di direktori tersebut. Jika ditentukan, bendera ini harus digabungkan dengan OPLOCK_FLAG_PARENT_OBJECT. Bendera ini harus ditentukan ketika sistem file memproses operasi yang menghasilkan penghapusan tautan atau file.

[in, optional] Context

Penunjuk ke informasi konteks yang ditentukan penelepon untuk diteruskan ke rutinitas panggilan balik yang ditunjukkan oleh parameter CompletionRoutine dan PostIrpRoutine .

[in, optional] CompletionRoutine

Penunjuk ke rutinitas panggilan balik yang disediakan penelepon. Jika pemutusan kunci oportunistik sedang berlangsung, rutinitas ini dipanggil ketika istirahat selesai. Parameter ini bersifat opsional dan dapat berupa NULL. Jika NULL, penelepon dimasukkan ke dalam status tunggu sampai pemutusan kunci oportunistik selesai.

Rutinitas ini dinyatakan sebagai berikut:

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

Rutinitas ini memiliki parameter berikut:

Parameter	Deskripsi
Konteks	Penunjuk informasi konteks yang diteruskan dalam parameter Konteks ke FsRtlCheckOplockEx.
Irp	Penunjuk ke IRP untuk operasi I/O.

[in, optional] PostIrpRoutine

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
(*POPLOCK_FS_PREPOST_IRP) (
      IN PVOID Context,
      IN PIRP Irp
      );

Rutinitas ini memiliki parameter berikut:

Parameter	Deskripsi
Konteks	Penunjuk informasi konteks yang diteruskan dalam parameter Konteks ke FsRtlCheckOplockEx.
Irp	Penunjuk ke IRP untuk operasi I/O.

Nilai kembali

FsRtlCheckOplockEx 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	Pemutusan kunci oportunistik (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	Pemutusan kunci oportunistik 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 ditetapkan, dan kunci oportunistik telah rusak.
STATUS_PENDING	Pemutusan kunci oportunistik telah dimulai, dan kontrol IRP telah diteruskan ke paket oplock. Jika CompletionRoutine adalah NULL, rutinitas ini akan memblokir saat jeda oplock diproses, bukan mengembalikan STATUS_PENDING. STATUS_PENDING adalah kode sukses.

Keterangan

FsRtlCheckOplockEx menyinkronkan IRP untuk operasi I/O dengan status kunci oportunistik file saat ini sesuai dengan kondisi berikut:

Jika operasi I/O akan menyebabkan kunci oportunistik rusak, pemutusan kunci oportunistik dimulai.
Jika operasi I/O tidak dapat dilanjutkan sampai pemutusan kunci oportunistik selesai dan rutinitas penyelesaian dalam CompletionRoutine ditentukan, FsRtlCheckOplockEx mengembalikan STATUS_PENDING dan memanggil rutinitas panggilan balik yang ditentukan dalam PostIrpRoutine. Ketika pemutusan kunci oportunistik telah diakui, rutinitas panggilan balik dalam CompletionRoutine dipanggil.
Jika operasi I/O tidak dapat dilanjutkan sampai pemutusan kunci oportunistik selesai dan CompletionRoutine tidak ditentukan, FsRtlCheckOplockEx tidak akan kembali sampai pemutusan kunci oportunistik diakui.

PostIrpRoutine harus ditentukan hanya jika CompletionRoutine telah ditentukan.

Jika sistem file atau driver filter menggunakan kunci oportunistik, itu harus memanggil FsRtlCheckOplockEx dari rutinitas pengiriman apa pun untuk operasi I/O yang dapat menyebabkan pemutusan kunci oportunistik. Aturan ini berlaku untuk jenis operasi I/O berikut, karena operasi ini dapat menyebabkan pemutusan kunci oportunistik:

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

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

Minifilter harus memanggil FltCheckOplockEx alih-alih FsRtlCheckOplockEx.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista
Target Platform	Universal
Header	ntifs.h (termasuk Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL