FsRtlCheckOplockEx2 函式 (ntifs.h)
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 鍵。 如果 IRP 中提供金鑰，FsRtlCheckOplockEx2 就必須新增密鑰。 不會發生其他 Oplock 處理;也就是說，不會發生任何 oplock 中斷。 從 Windows 7 開始支援。 |
| OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004) | 指定 FsRtlCheckOplockEx2 應該還原先前透過呼叫 FsRtlOplockFsctrl 例程所設定的任何狀態。 FsRtlOplockFsctrl 會在處理指定 create options 參數中FILE_OPEN_REQUIRING_OPLOCK旗標的IRP_MJ_CREATE要求期間呼叫。 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_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 的內容資訊指標。
- 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，這是 在 Context 參數中傳遞至 FsRtlCheckOplockEx2 的內容資訊指標。
- Irp：I/O 作業之 IRP 的指標。
[in] Timeout
如果為非零，則指定以毫秒為單位的逾時 (，) 等候用來封鎖呼叫端線程的事件，以便等候 oplock 中斷完成。 除非下列兩個條件都成立，否則會忽略此值： CompletionRoutine 為 NULL， 而且 NotifyRoutine 不是 NULL。
[in, optional] NotifyContext
要傳遞給 NotifyRoutine 參數所指向回呼例程之OPLOCK_NOTIFY_PARAMS結構的指標。 這個參數是選擇性的，而且可以是 NULL。
[in, optional] NotifyRoutine
呼叫端提供的回呼例程指標，要針對 oplock 狀態通知呼叫。 這個參數是選擇性的，而且可以是 NULL。
NotifyRoutine 宣告如下：
typedef NTSTATUS
(*POPLOCK_NOTIFY_ROUTINE) (
IN POPLOCK_NOTIFY_PARAMS NotifyParams
);
NotifyRoutine 具有下列參數：
- NotifyParams，設定為傳遞至 FsRtlCheckOplockEx2 的 NotifyContext 參數。
傳回值
FsRtlCheckOplockEx2 會傳回STATUS_SUCCESS或適當的 NTSTATUS 程式代碼，例如下列其中一項：
| 傳回碼 | Description |
|---|---|
| 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且 oplock 已中斷時傳回的成功程序代碼。 |
| STATUS_PENDING | Oplock 中斷正在進行中，且 IRP 的控制已傳遞至 oplock 套件。 如果 CompletionRoutine 為 NULL，則會在處理 oplock 中斷時封鎖 FsRtlCheckOplockEx2 區塊，而不是傳回STATUS_PENDING。 STATUS_PENDING是成功的程序代碼。 |
備註
迷你篩選應該呼叫 FltCheckOplockEx ，而不是 FsRtlCheckOplockEx2。
FsRtlCheckOplockEx2 會根據下列條件，同步處理 I/O 作業的 IRP 與檔案目前的 oplock 狀態：
如果 I/O 作業會導致 oplock 中斷，則會起始 oplock 中斷。
如果 I/O 作業在 oplock 中斷完成且指定 CompletionRoutine 中的完成例程之前無法繼續， FsRtlCheckOplockEx2 會傳回STATUS_PENDING，並呼叫 PostIrpRoutine 中指定的回呼例程。 確認 oplock 中斷時，會呼叫 CompletionRoutine 中的回呼例程。
如果在作業鎖定中斷完成且未指定 CompletionRoutine 之前，I/O 作業無法繼續，則呼叫端的線程會遭到封鎖，而且 FsRtlCheckOplockEx2 只有在 oplock 中斷完成時才會傳回。
如果呼叫端的線程遭到封鎖，而且 NotifyRoutine 不是 NULL，則會針對 NotifyParams 中設定的任何或所有原因呼叫 NotifyRoutine：
- OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT
- OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED
只有在 CompletionRoutine 為 NULL 且必須封鎖呼叫端的線程以等候中斷完成時，才會發生上述任何原因的 NotifyRoutine 呼叫。
如果基於原因而叫用 NotifyRoutine OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT，則如果等候因任何原因而終止/完成，則一律會基於任何原因 OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED而叫用， (可能永遠不會) 。
FsRtlCheckOplockEx2 會忽略 NotifyRoutine 傳回OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT和OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED狀態代碼。
只有在已指定 CompletionRoutine 時，才應該指定 PostIrpRoutine。 當 PostIrpRoutine 不是 NULL 時，會在任何專案排入等候的 Irp 佇列之前呼叫它。
如果在 Flags 中指定OPLOCK_FLAG_PARENT_OBJECT旗標， FsRtlCheckOplockEx2 將會無條件地中斷任何現有的父 oplock;也就是說，不會考慮 Irp 中的主要程式碼。
如果文件系統使用 oplocks，它必須從任何可能導致 oplock 中斷的 I/O 作業分派例程呼叫 FsRtlCheckOplockEx2 。 此規則適用於下列 I/O 作業類型，因為這些作業可能會導致 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
如需作業鎖定的詳細資訊，請參閱 Opportunistic Locks。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows 10 (版本 2004) |
| 標頭 | ntifs.h |
另請參閱
FSCTL_OPBATCH_ACK_CLOSE_PENDING
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應