FsRtlCheckOplockEx2 函式（ntifs.h）

發行項
12/21/2024

FsRtlCheckOplockEx2 會同步處理檔案 I/O 作業的 IRP，以及檔案目前的機會鎖定（oplock）狀態。

語法

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

參數

[in] Oplock

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

[in] Irp

宣告所要求 I/O 作業之 IRP 的指標。

[in] Flags

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

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

[in] FlagsEx2

保留;必須設定為零。

[in, optional] CompletionRoutineContext

要傳遞至 CompletionRoutine 參數所指向之回呼例程的呼叫端定義內容資訊的指標。這個參數是選擇性的，而且可以 NULL。

[in, optional] CompletionRoutine

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

CompletionRoutine 宣告如下：

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

CompletionRoutine 具有下列參數：

Context：傳遞至 FsRtlCheckOplockEx2之 Context 參數中的內容資訊指標。
Irp：I/O 作業之 IRP 的指標。

[in, optional] PostIrpRoutine

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

PostIrpRoutine 宣告如下：

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

PostIrpRoutine 具有下列參數：

Context，這是傳遞至 FsRtlCheckOplockEx2之 Context 參數中的內容資訊指標。
Irp：I/O 作業之 IRP 的指標。

[in] Timeout

如果非零，指定逾時（以毫秒為單位）等候用來封鎖呼叫端線程的事件，以等候 oplock 中斷完成。除非下列兩個條件都成立，否則會忽略此值：CompletionRoutine 為 NULL，且 NotifyRoutine 不是 NULL。

[in, optional] NotifyContext

要傳遞至回呼例程之 OPLOCK_NOTIFY_PARAMS 結構的指標，NotifyRoutine 參數指向該例程。這個參數是選擇性的，而且可以 NULL。

[in, optional] NotifyRoutine

要針對 oplock 狀態通知呼叫的呼叫端提供的回呼例程指標。這個參數是選擇性的，而且可以 NULL。

NotifyRoutine 宣告如下：

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

NotifyRoutine 具有下列參數：

NotifyParams，其設定為傳遞至 FsRtlCheckOplockEx2NotifyContext 參數。

傳回值

FsRtlCheckOplockEx2 會傳回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	Oplock 中斷正在進行中。 IRP 是一個IRP_MJ_CREATE要求，而且已在作業的 create options 參數中指定FILE_COMPLETE_IF_OPLOCKED。 STATUS_OPLOCK_BREAK_IN_PROGRESS是成功程序代碼，如果已設定OPLOCK_FLAG_COMPLETE_IF_OPLOCKED，且oplock已中斷。
STATUS_PENDING	Oplock 中斷正在進行中，且 IRP 的控制已傳遞至 oplock 套件。如果 CompletionRoutineNULL，則在處理 oplock 中斷時，FsRtlCheckOplockEx2 區塊，而不是傳回STATUS_PENDING。 STATUS_PENDING是成功的程序代碼。

言論

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

FsRtlCheckOplockEx2 會根據下列條件，將 I/O 作業的 IRP 與檔案目前的 oplock 狀態同步處理：

如果 I/O 作業會導致 oplock 中斷，則會起始 oplock 中斷。
如果 I/O 作業必須等到 oplock 中斷完成且指定完成 完成例程 為止，FsRtlCheckOplockEx2 會傳回STATUS_PENDING，並呼叫 postIrpRoutine 中所指定的回呼例程。當認可 oplock 中斷時，會呼叫 CompletionRoutine 中的回呼例程。
如果 I/O 作業在 oplock 中斷完成且未指定完成 Routine 之前無法繼續，則呼叫端的線程會遭到封鎖，且 只有在 oplock 中斷完成時，才會傳回 FsRtlCheckOplockEx2。

如果呼叫端的線程遭到封鎖，且 NotifyRoutine 未 NULL，則會針對下列任何或所有原因呼叫 NotifyRoutine，NotifyParams：