FltCheckOplockEx 函式 (fltkernel.h)

  • 發行項

minifilter 驅動程式會呼叫 FltCheckOplockEx 例程，以同步處理 IRP 型檔案 I/O 作業的回呼數據結構，該作業具有目前的運算鎖定 (oplock) 檔案狀態。

語法

FLT_PREOP_CALLBACK_STATUS FLTAPI FltCheckOplockEx(
  [in]           POPLOCK                                 Oplock,
  [in]           PFLT_CALLBACK_DATA                      CallbackData,
  [in]           ULONG                                   Flags,
  [in, optional] PVOID                                   Context,
  [in, optional] PFLTOPLOCK_WAIT_COMPLETE_ROUTINE        WaitCompletionRoutine,
  [in, optional] PFLTOPLOCK_PREPOST_CALLBACKDATA_ROUTINE PrePostCallbackDataRoutine
);

參數

[in] Oplock

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

[in] CallbackData

I/O 作業之回呼數據的指標 FLT_CALLBACK_DATA結構。

[in] Flags

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

OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)

允許機會鎖定中斷繼續，而不會封鎖或擱置造成作業中斷的作業。

OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002)

指定 FltCheckOplockEx 應該只檢查與 I/O 作業相關聯之FILE_OBJECT上的商機鎖定鍵。 這個 I/O 作業是由 CallbackData 參數指向的回呼數據表示。 如果 I/O 作業中提供金鑰，FltCheckOplockEx 就必須新增密鑰。 不會發生其他 Oplock 處理;也就是說，不會發生任何機會鎖定中斷。

OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)

指定 FsRtlCheckOplockEx 應該還原先前透過 呼叫 FltOplockFsctrl 例程設定的任何狀態。 處理IRP_MJ_CREATE要求時，會呼叫 FltOplockFsctrl。 此IRP_MJ_CREATE要求會指定 create options 參數中的FILE_OPEN_REQUIRING_OPLOCK旗標。 OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK旗標通常用於先前失敗時，這類建立要求的最終處理。

OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)

允許所有機會鎖定中斷繼續，而不論不相依的鎖定索引鍵為何。

[in, optional] Context

要傳遞至 WaitCompletionRoutine 和 PrePostCallbackDataRoutine 所指向之回呼例程之呼叫端定義內容資訊的指標。 篩選管理員會將此資訊視為不透明。

[in, optional] WaitCompletionRoutine

呼叫端提供的回呼例程指標。 如果作業鎖定中斷正在進行中，篩選管理員會在作業鎖定中斷完成時呼叫此例程。 此參數是選擇性的，可以是 NULL。 如果是 NULL，則呼叫端會進入等候狀態，直到作業鎖定中斷完成為止。

此例程宣告如下：

typedef VOID
(*PFLTOPLOCK_WAIT_COMPLETE_ROUTINE) (
      IN PFLT_CALLBACK_DATA CallbackData,
      IN PVOID Context
      );

此例程具有下列參數：

CallbackData

I/O 作業之回呼數據結構的指標。

Context

在 Context 參數中傳遞至 FltCheckOplockEx的內容資訊指標。

[in, optional] PrePostCallbackDataRoutine

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

此例程宣告如下：

typedef VOID
(*PFLTOPLOCK_PREPOST_CALLBACKDATA_ROUTINE) (
      IN PFLT_CALLBACK_DATA CallbackData,
      IN PVOID Context
      );

CallbackData

I/O 作業之回呼數據結構的指標。

Context

在 Context 參數中傳遞至 FltCheckOplockEx的內容資訊指標。

傳回值

FltCheckOplockEx 會傳回下列其中一個FLT_PREOP_CALLBACK_STATUS代碼：

傳回碼 Description
FLT_PREOP_COMPLETE
 FltCheckOplockEx 發生集區配置失敗，或 呼叫 FsRtlCheckOplockEx 函式傳回錯誤。 FltCheckOplockEx 會在FLT_CALLBACK_DATA回呼數據結構之 IoStatus 成員之 IO_STATUS_BLOCK 結構的 Status 成員中設定錯誤碼。 CallbackData 參數指向這個FLT_CALLBACK_DATA結構。
FLT_PREOP_PENDING
 已起始作業中斷，導致篩選管理員將 I/O 作業張貼到工作佇列。 I/O 作業是由 CallbackData 參數指向的回呼數據表示。
FLT_PREOP_SUCCESS_WITH_CALLBACK
 CallbackData 參數指向的回呼數據未畫筆，而且會立即執行 I/O 作業。 請注意，如果在 Flags 參數中指定OPLOCK_FLAG_COMPLETE_IF_OPLOCKED呼叫端，即使 I/O 作業未畫筆，作業中斷也可能正在進行中。 若要判斷這種情況，呼叫端應該檢查STATUS_OPLOCK_BREAK_IN_PROGRESS FLT_CALLBACK_DATA回呼數據結構之 IoStatus 成員之IO_STATUS_BLOCK結構之狀態成員中的STATUS_OPLOCK_BREAK_IN_PROGRESS。

備註

迷你篩選驅動程式會呼叫 FltCheckOplockEx ，根據下列條件，同步處理以 IRP 為基礎的 I/O 作業與檔案目前的 oplock 狀態：

  • 如果 I/O 作業會導致 oplock 中斷，則會起始 oplock 中斷。

  • 如果 I/O 作業在作業中斷完成之前無法繼續， FltCheckOplockEx 會傳回FLT_PREOP_PENDING並呼叫 PrePostCallbackDataRoutine 參數指向的回呼例程。

  • 如果迷你篩選驅動程式使用 oplocks，它必須從任何預先操作回呼呼叫 FltCheckOplockEx ， (PFLT_PRE_OPERATION_CALLBACK) 例程造成 oplock 中斷的 I/O 作業。 此規則適用於下列 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

I/O 作業必須是 IRP 型 I/O 作業。 若要判斷指定的回呼數據結構是否代表以 IRP 為基礎的 I/O 作業，請使用 FLT_IS_IRP_OPERATION 宏。

Minifilters 不得在 WaitCompletionRoutine 中指定的回呼內再次呼叫 FltCheckOplockEx。 如果 oplock 套件在 FltCheckOplockEx 傳回之前呼叫完成回呼，則這樣做可能會導致死結狀況。

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

規格需求

需求 值
最低支援的用戶端 FltCheckOplockEx 例程可從 Windows 7 開始使用。
目標平台 Universal
標頭 fltkernel.h (包含 Fltkernel.h)
程式庫 FltMgr.lib
IRQL <= APC_LEVEL

另請參閱

FLT_CALLBACK_DATA

FLT_IS_IRP_OPERATION

FltInitializeOplock

FltOplockFsctrl

FsRtlCheckOplockEx

IO_STATUS_BLOCK

PFLT_PRE_OPERATION_CALLBACK