PFLT_GENERATE_FILE_NAME回呼函式（fltkernel.h）

發行項
02/06/2025

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

語法

PFLT_GENERATE_FILE_NAME PfltGenerateFileName;

NTSTATUS PfltGenerateFileName(
  [in]           PFLT_INSTANCE Instance,
  [in]           PFILE_OBJECT FileObject,
  [in, optional] PFLT_CALLBACK_DATA CallbackData,
  [in]           FLT_FILE_NAME_OPTIONS NameOptions,
  [out]          PBOOLEAN CacheFileNameInformation,
  [out]          PFLT_NAME_CONTROL FileName
)
{...}

參數

[in] Instance

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

[in] FileObject

要求其名稱之檔案之檔案物件的指標。

[in, optional] CallbackData

要求此名稱之作業之回呼數據結構的指標。呼叫 fltGetFileNameInformationUnsafe 時，此參數會 NULL，以擷取檔名。

[in] NameOptions

FLT_FILE_NAME_OPTIONS 值，指定此檔名資訊查詢的名稱格式、查詢方法和旗標。

[out] CacheFileNameInformation

布爾值的指標，指定是否可以快取此名稱。如果可以快取名稱，則設定為 輸出上的 TRUE;否則會設定為 FALSE。

[out] FileName

篩選管理員配置的 FLT_NAME_CONTROL 結構的指標，以在輸出時接收檔名。

傳回值

此回呼例程會傳回STATUS_SUCCESS或適當的NTSTATUS值。

言論

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

若要註冊此回呼例程，迷你篩選驅動程式會將類型 PFLT_GENERATE_FILE_NAME 的例程位址儲存在 GenerateFileNameCallback 中，FLT_REGISTRATION 結構的成員 迷你篩選驅動程式傳遞為參數，以 FltRegisterFilter。

篩選管理員會呼叫此回呼例程，以允許迷你篩選驅動程式攔截小型篩選驅動程序實例堆疊中其他小型篩選驅動程式的檔名要求。使用此回呼例程和 PFLT_NORMALIZE_NAME_COMPONENT 回呼例程，迷你篩選驅動程式可以提供自己的檔名資訊。

若要判斷所要求的檔名格式，請在 NameOptions 參數上呼叫 FltGetFileNameFormat。

在 Windows 8 之前，此回呼例程只會針對開啟的檔名和簡短檔名呼叫。當篩選管理員收到標準化檔名的要求時，它會呼叫這個回呼例程來要求開啟的檔名。然後它會呼叫迷你篩選驅動程式的 PFLT_NORMALIZE_NAME_COMPONENT 回呼，將檔名中的每個元件正規化。

從 Windows 8 開始，此回呼例程也會針對正規化名稱呼叫。當篩選管理員收到標準化檔名的要求時，它會呼叫這個回呼例程，並在 NameOptions 參數中指定FLT_FILE_NAME_NORMALIZED。如果迷你篩選程序從這個回呼傳回STATUS_SUCCESS，則不會呼叫迷你篩選程式的 PFLT_NORMALIZE_NAME_COMPONENT 回呼。如果迷你篩選程式傳回失敗碼（例如STATUS_NOT_SUPPORTED），篩選管理員會再次呼叫此回呼例程，要求開啟的檔名。篩選管理員接著會呼叫迷你篩選驅動程式的 PFLT_NORMALIZE_NAME_COMPONENT 回呼，將檔名中的每個元件正規化。

叫用此回呼例程時，迷你篩選驅動程式會根據文件系統的檔名資訊，產生自己的檔名資訊。若要取得檔案的文件系統檔名資訊，請呼叫 FltGetFileNameInformation、FltGetFileNameInformationUnsafe或 FltGetDestinationFileNameInformation。

針對開啟的檔名，產生的檔名資訊應該包含磁碟區資訊。針對遠端檔案，它也應該包含共用資訊。

以下是遠端檔案開啟的檔案名範例：

\Device\LanManRedirector\MyServer\MyShare\Docume~1\MyUser\My Documents\TestRe~1.txt:stream1

如需檔名格式的詳細資訊，請參閱 FLT_FILE_NAME_INFORMATION 和 FltParseFileNameInformation的參考專案。

產生檔名資訊之後，迷你篩選驅動程式必須呼叫 FltCheckAndGrowNameControl，檢查 FileName 參數指向的 FLT_NAME_CONTROL 結構，以包含足以保存所產生檔名的名稱緩衝區。如果名稱緩衝區太小，FltCheckAndGrowNameControl 將它取代為較大的緩衝區。迷你篩選驅動程式接著會將檔案名資訊儲存到名稱緩衝區中，並傳回。