FltLockUserBuffer 函式（fltkernel.h）

發行項
07/16/2024

FltLockUserBuffer 例程會鎖定指定 I/O 作業的用戶緩衝區。

語法

NTSTATUS FLTAPI FltLockUserBuffer(
  [in] PFLT_CALLBACK_DATA CallbackData
);

參數

[in] CallbackData

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

傳回值

FltLockUserBuffer 成功鎖定使用者緩衝區時，會傳回STATUS_SUCCESS （或如果先前呼叫 FltLockUserBuffer鎖定緩衝區則傳回。否則，它會傳回適當的NTSTATUS值，例如下列其中一個：

傳回碼	描述
STATUS_INSUFFICIENT_RESOURCES	FltLockUserBuffer 發生集區配置失敗。這是錯誤碼。
STATUS_INVALID_PARAMETER	遇到無效的參數。例如，I/O 作業沒有 MDL 參數，或IRP_MJ_READ或IRP_MJ_WRITE I/O 作業有IRP_MN_MDL的次要程式代碼。這是錯誤碼。

言論

為了獲得最佳效能，除非絕對必要，否則篩選驅動程式不應該呼叫 FltLockUserBuffer。效能變慢不是因為 FltLockUserBuffer 本身，而是因為後續呼叫 MmGetSystemAddressForMdlSafe所造成的效能損失：如需詳細資訊，請參閱稍後的。

小型篩選驅動程式可以呼叫 FltLockUserBuffer，以鎖定下列其中一項 I/O 作業的用戶緩衝區：

IRP_MJ_DEVICE_CONTROL
IRP_MJ_DIRECTORY_CONTROL
IRP_MJ_FILE_SYSTEM_CONTROL
IRP_MJ_INTERNAL_DEVICE_CONTROL
IRP_MJ_QUERY_EA
IRP_MJ_QUERY_QUOTA
IRP_MJ_QUERY_SECURITY
IRP_MJ_READ（除IRP_MN_MDL外）
IRP_MJ_SET_EA
IRP_MJ_SET_QUOTA
IRP_MJ_WRITE（除IRP_MN_MDL外）

FltLockUserBuffer 決定適當的存取方法（IoReadAccess、IoWriteAccess 或 IoModifyAccess）根據 I/O 作業類型套用鎖定的緩衝區。

FltLockUserBuffer 會設定回呼數據參數結構（FLT_PARAMETERS）中 MdlAddress （或 OutputMdlAddress）成員，以指向鎖定頁面的 MDL。如果沒有 MDL，FltLockUserBuffer 配置一個。（請注意，FltMgr 無法在文件系統之前產生 MDL，這就是為什麼 FltLockUserBuffer 傳回IRP_MJ_READ或IRP_MJ_WRITE IRP_MN_MDL STATUS_INVALID_PARAMETER的原因。

如果回呼數據參數結構包含系統緩衝區（Irp->AssociatedIrp.SystemBuffer），而且不包含用戶緩衝區（Irp->UserBuffer），FltLockUserBuffer 鎖定系統緩衝區。如果系統緩衝區沒有 MDL，FltLockUserBuffer 配置一個。

如果回呼數據參數結構包含用戶緩衝區，FltLockUserBuffer探查和鎖定用戶緩衝區。

呼叫端可以在任何進程內容中執行。 FltLockUserBuffer 會自動鎖定正確的進程內容中的緩衝區。

如果 FltLockUserBuffer 是從作業前回呼例程（PFLT_PRE_OPERATION_CALLBACK）呼叫，而且它會配置 MDL，FltLockUserBuffer 會在回呼數據結構中設定FLTFL_CALLBACK_DATA_DIRTY旗標（FLT_CALLBACK_DATA），讓 I/O 系統在 I/O 作業完成時釋放 MDL。

為了節省系統頁面數據表專案（PTE），FltLockUserBuffer 不會對應鎖定的頁面。呼叫 FltLockUserBuffer之後，呼叫者必須呼叫 MmGetSystemAddressForMdlSafe，傳遞 MdlAddress （或 OutputMdlAddress）成員作為 Mdl 參數的值，表示此記憶體的系統緩衝區。

釋放回呼數據結構時，鎖定的緩衝區會自動解除鎖定，並釋放 MDL。呼叫端絕不應釋放 MDL;I/O 系統會自動執行這項作業。

FltLockUserBuffer 可以呼叫快速 I/O 和 IRP 型作業。