PFLT_NORMALIZE_NAME_COMPONENT_EX回呼函式（fltkernel.h）

發行項
02/06/2025

提供篩選管理員名稱快取檔名的迷你篩選驅動程式，可以將類型為 PFLT_NORMALIZE_NAME_COMPONENT_EX 的例程註冊為迷你篩選驅動程式的 NormalizeNameComponentExCallback 回呼例程。

語法

PFLT_NORMALIZE_NAME_COMPONENT_EX PfltNormalizeNameComponentEx;

NTSTATUS PfltNormalizeNameComponentEx(
  [in]      PFLT_INSTANCE Instance,
  [in]      PFILE_OBJECT FileObject,
  [in]      PCUNICODE_STRING ParentDirectory,
  [in]      USHORT VolumeNameLength,
  [in]      PCUNICODE_STRING Component,
  [out]     PFILE_NAMES_INFORMATION ExpandComponentName,
  [in]      ULONG ExpandComponentNameLength,
  [in]      FLT_NORMALIZE_NAME_FLAGS Flags,
  [in, out] PVOID *NormalizationContext
)
{...}

參數

[in] Instance

這個回呼例程已註冊之迷你篩選驅動程序實例的不透明實例指標。

[in] FileObject

如果已設定FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME旗標，則為要求名稱之檔案的檔案物件，或是 IRP_MJ_SET_INFORMATION 作業目標檔案的指標。如需詳細資訊，請參閱下方旗標參數。

[in] ParentDirectory

UNICODE_STRING 結構的指標，其中包含這個名稱元件的父目錄名稱。

[in] VolumeNameLength

父目錄名稱的長度，以位元組為單位，其儲存在 ParentDirectory 參數指向的結構中。

[in] Component

包含要展開之名稱元件之UNICODE_STRING結構的指標。

[out] ExpandComponentName

FILE_NAMES_INFORMATION 結構的指標，這個結構會接收名稱元件已展開的（正規化）檔名資訊。

[in] ExpandComponentNameLength

ExpandComponentName 參數指向的緩衝區長度，以位元組為單位。

[in] Flags

名稱正規化旗標。 FLTFL_NORMALIZE_NAME_CASE_SENSITIVE指定要正規化的名稱區分大小寫。 FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME指定呼叫回呼例程來服務 FltGetDestinationFileNameInformation 例程呼叫。如果已設定FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME旗標，FileObject 代表IRP_MJ_SET_INFORMATION作業目標的檔案/目錄。如果未設定FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME旗標，FileObject 代表要求其名稱的檔案/目錄。

[in, out] NormalizationContext

要傳遞至此回呼例程的任何後續呼叫中要傳遞的迷你篩選驅動程式提供內容資訊的指標，這些呼叫會讓相同檔名路徑中的其餘元件正規化。

傳回值

此回呼例程會傳回STATUS_SUCCESS或適當的NTSTATUS值。如果 Component 參數所指定的名稱元件不存在於父目錄中，ParentDirectory 參數所指定，則此回呼例程應該會傳回STATUS_NO_SUCH_FILE。如果這個回呼例程對父目錄發出IRP_MN_QUERY_DIRECTORY （FileNamesInformation）要求，則文件系統會傳回正確的狀態代碼。在此情況下，此回呼可以直接傳回檔系統傳回的狀態代碼。

言論

NormalizeNameComponentExCallback 回呼例程與 NormalizeNameComponentCallback 回呼例程（類型為 PFLT_NORMALIZE_NAME_COMPONENT）之間的主要差異在於，NormalizeNameComponentExCallback 回呼例程支援其他 FileObject 参数。小型篩選驅動程式可以使用檔案物件（FileObject），藉由呼叫 IoGetTransactionParameterBlock 例程，擷取檔案/目錄參與之作業的 TXN_PARAMETER_BLOCK 結構。小型篩選驅動程式可以使用TXN_PARAMETER_BLOCK結構，在參與此檔案物件的交易內容中發出自己的建立要求。

若要註冊此回呼例程，minifilter 驅動程式會將類型PFLT_NORMALIZE_NAME_COMPONENT_EX的例程位址儲存在 NormalizeNameComponentExCallbackFLT_REGISTRATION 結構的成員，而迷你篩選驅動程式會以參數的形式傳遞給 FltRegisterFilter。

篩選管理員會呼叫這個回呼例程來查詢迷你篩選驅動程式，以查詢檔名路徑中已修改迷你篩選驅動程式名稱之元件的標準化名稱。如果檔名路徑包含多個這類元件，篩選管理員可以在將路徑中的所有元件正規化的過程中多次呼叫此回呼例程。迷你篩選驅動程式可以使用 NormalizationContext 參數，將內容資訊傳遞至這個回呼例程的後續呼叫。

如果迷你篩選驅動程式使用 NormalizationContext 參數，它也應該註冊正規化內容清除回呼例程。如需詳細資訊，請參閱 PFLT_NORMALIZE_CONTEXT_CLEANUP的參考專案。