FsRtlCheckOplockEx 函式（ntifs.h）

發行項
12/21/2024

FsRtlCheckOplockEx 例程會將檔案 I/O 作業的 IRP 與檔案目前的機會鎖定（oplock）狀態同步處理。

語法

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
);

參數

[in] Oplock

檔案不透明的不透明鎖定指標。此指標必須由先前呼叫 FsRtlInitializeOplock初始化。

[in] Irp

I/O 作業之 IRP 的指標。

[in] Flags

相關聯檔案 I/O 作業的位掩碼。文件系統或篩選驅動程式會設定位，以指定 FsRtlCheckOplockEx的行為。 Flags 參數具有下列選項：

價值	意義
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED（0x00000001）	指定允許機會鎖定中斷繼續，而不會封鎖或擱置造成 oplock 中斷的作業。
OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY （0x00000002）	從 Windows 7 開始支援。指定 FsRtlCheckOplockEx 應該只檢查與 Irp 參數指向之 IRP 相關聯的FILE_OBJECT上是否有機會鎖定密鑰。 FsRtlCheckOplockEx 必須在 IRP 中提供金鑰時新增金鑰。不會發生其他 oplock 處理;也就是說，不會發生機會性鎖定中斷。
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK （0x00000004）	從 Windows 7 開始支援。指定 FsRtlCheckOplockEx 應該還原先前透過呼叫 FsRtlOplockFsctrl 例程設定的任何狀態。 FsRtlOplockFsctrl 會在處理IRP_MJ_CREATE要求時呼叫，該要求會指定 create options 參數中的FILE_OPEN_REQUIRING_OPLOCK旗標。 OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK旗標通常會在先前失敗時，用於這類建立要求的最終處理中。
OPLOCK_FLAG_IGNORE_OPLOCK_KEYS （0x00000008）	從 Windows 7 開始支援。指定允許所有機會鎖定中斷繼續進行，而不論機會鎖定索引鍵為何。
OPLOCK_FLAG_PARENT_OBJECT （0x00000010）	從 Windows 8 開始支援。指定 Oplock 與導向 Irp 參數中 IRP 之檔案或目錄的父系（目錄）相關聯。
OPLOCK_FLAG_CLOSING_DELETE_ON_CLOSE（0x00000020）	從 Windows 8 開始支援。指定在 Irp 中指定的 I/O 作業，是原本在其建立選項中設定之FILE_DELETE_ON_CLOSE旗標所開啟之句柄的IRP_MJ_CLEANUP。如果 Irp Irp 不是IRP_MJ_CLEANUP作業，則此旗標不會有任何作用。指定此旗標可能會導致機會鎖定中斷。
OPLOCK_FLAG_REMOVING_FILE_OR_LINK （0x00000040）	從 Windows 8 開始支援。指定刪除該目錄中的檔案或連結時，處理父目錄上的機會鎖定中斷。如果指定，則必須將此旗標與OPLOCK_FLAG_PARENT_OBJECT結合。當檔案系統正在處理會導致移除連結或檔案的作業時，必須指定此旗標。

[in, optional] Context

要傳遞至回呼例程的呼叫端定義內容資訊的指標，CompletionRoutine 和 PostIrpRoutine 參數所指向的回呼例程。

[in, optional] CompletionRoutine

呼叫端提供的回呼例程指標。如果機會鎖定中斷正在進行中，當中斷完成時，就會呼叫此例程。這個參數是選擇性的，而且可以是 NULL。如果是 NULL，呼叫端會進入等候狀態，直到機會鎖定中斷完成為止。

此例程宣告如下：

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

此例程具有下列參數：

參數	描述
上下文	在 Context 參數中傳遞至 FsRtlCheckOplockEx的內容資訊指標。
Irp	I/O 作業之 IRP 的指標。

[in, optional] PostIrpRoutine

如果 I/O 作業張貼至工作佇列，則會呼叫呼叫端提供的回呼例程指標。這個參數是選擇性的，而且可以是 NULL。

此例程宣告如下：

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

此例程具有下列參數：

參數	描述
上下文	在 Context 參數中傳遞至 FsRtlCheckOplockEx的內容資訊指標。
Irp	I/O 作業之 IRP 的指標。

傳回值

FsRtlCheckOplockEx 會傳回STATUS_SUCCESS或適當的 NTSTATUS 程式代碼，例如下列其中一項：

傳回碼	描述
STATUS_CANCELLED	IRP 已取消。 STATUS_CANCELLED是錯誤碼。
STATUS_CANNOT_BREAK_OPLOCK	無法完成機會鎖定（oplock）中斷。 IRP 是IRP_MJ_CREATE要求。 FILE_OPEN_REQUIRING_OPLOCK是在作業的 create options 參數中指定，而且有授與的 oplock。
STATUS_OPLOCK_BREAK_IN_PROGRESS	機會主義鎖定中斷正在進行中。 IRP 是一個IRP_MJ_CREATE要求，而且已在作業的 create options 參數中指定FILE_COMPLETE_IF_OPLOCKED。 STATUS_OPLOCK_BREAK_IN_PROGRESS是成功程序代碼，如果已設定OPLOCK_FLAG_COMPLETE_IF_OPLOCKED，且機會鎖定已中斷，則會傳回。
STATUS_PENDING	已起始機會鎖定中斷，且 IRP 的控制已傳遞至 oplock 套件。如果 CompletionRoutine 為 NULL，此例程會在處理 oplock 中斷時封鎖，而不是傳回STATUS_PENDING。 STATUS_PENDING是成功的程序代碼。

言論

FsRtlCheckOplockEx 會根據下列條件，同步處理 I/O 作業的 IRP 與檔案目前的機會鎖定狀態：

如果 I/O 作業會導致機會鎖定中斷，則會起始機會鎖定中斷。
如果 I/O 作業無法繼續，直到機會性鎖定中斷完成，且已指定完成 CompletionRoutine 中的完成例程，FsRtlCheckOplockEx 會傳回STATUS_PENDING，並呼叫 PostIrpRoutine 中所指定的回呼例程。當認可機會鎖定中斷時，會呼叫 CompletionRoutine 中的回呼例程。
如果 I/O 作業無法繼續，直到機會性鎖定中斷完成且未指定完成Routine ，FsRtlCheckOplockEx 才會返回，直到認可機會主義鎖定中斷為止。

只有在指定 CompletionRoutine 時，才應指定 PostIrpRoutine。

如果文件系統或篩選驅動程式使用機會鎖定，則必須從任何可能導致機會鎖定中斷的分派例程 呼叫 FsRtlCheckOplockEx FsRtlCheckOplockEx。此規則適用於下列類型的 I/O 作業，因為這些作業可能會導致機會鎖定中斷：

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

如需機會鎖定的詳細資訊，請參閱 Microsoft Windows SDK 檔。

迷你篩選程序應該呼叫 FltCheckOplockEx，而不是 FsRtlCheckOplockEx。

要求

要求	價值
最低支援的用戶端	Windows Vista
目標平臺	普遍
標頭	ntifs.h （include Ntifs.h）
連結庫	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL