FltGetFileNameInformation 函式（fltkernel.h）

發行項
02/06/2025

FltGetFileNameInformation 例程會傳回檔案或目錄的名稱資訊。

語法

NTSTATUS FLTAPI FltGetFileNameInformation(
  [in]  PFLT_CALLBACK_DATA         CallbackData,
  [in]  FLT_FILE_NAME_OPTIONS      NameOptions,
  [out] PFLT_FILE_NAME_INFORMATION *FileNameInformation
);

參數

[in] CallbackData

FLT_CALLBACK_DATA 結構的指標，這是 I/O 作業的回呼數據結構。這是必要參數，而且無法 NULL。

[in] NameOptions

FLT_FILE_NAME_OPTIONS 值，其中包含指定要傳回之名稱資訊格式的旗標，以及篩選管理員要使用的查詢方法。呼叫端必須包含名稱格式旗標和查詢方法旗標。名稱提供者迷你篩選驅動程式可以使用其他旗標來指定名稱查詢選項。這是必要參數，而且無法 NULL。

以下是檔名格式旗標值。只能指定下列其中一個旗標。如需這些格式的說明，請參閱 FLT_FILE_NAME_INFORMATION。

名稱格式旗標值	意義
FLT_FILE_NAME_NORMALIZED	FileNameInformation 參數會接收包含檔案標準化名稱的結構位址。
FLT_FILE_NAME_OPENED	FileNameInformation 參數會接收包含開啟檔案時所用名稱的結構位址。
FLT_FILE_NAME_SHORT	FileNameInformation 參數會接收包含檔案簡短（8.3）名稱的結構位址。簡短名稱由最多8個字元組成，後面緊接句點，最多3個字元。檔案的簡短名稱不包含磁碟區名稱、目錄路徑或數據流名稱。在預先建立路徑中無效。

以下是檔名查詢方法旗標值。只能指定下列其中一個旗標。

查詢方法旗標值	意義
FLT_FILE_NAME_QUERY_DEFAULT	如果目前無法查詢文件系統的檔名，FltGetFileNameInformation 不會執行任何動作。否則，FltGetFileNameInformation 查詢篩選管理員的名稱快取以取得檔名資訊。如果在快取中找不到名稱，FltGetFileNameInformation 查詢文件系統並快取結果。
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetFileNameInformation 查詢篩選管理員的名稱快取以取得檔名資訊。 FltGetFileNameInformation 不會查詢文件系統。
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetFileNameInformation 查詢文件系統的檔名資訊。 FltGetFileNameInformation 不會查詢篩選管理員的名稱快取，也不會快取檔系統查詢的結果。
FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP	FltGetFileNameInformation 查詢篩選管理員的名稱快取以取得檔名資訊。如果在快取中找不到名稱，而且目前安全這樣做，FltGetFileNameInformation 查詢文件系統的檔名資訊，並快取結果。

名稱提供者迷你篩選會使用下列旗標來指定檔名作業的屬性。

名稱提供者旗標值	意義
FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER	名稱提供者迷你篩選可以使用這個旗標來指定名稱查詢要求應該重新導向至本身（名稱提供者迷你篩選），而不是由堆疊中較低的名稱提供者滿足。
FLT_FILE_NAME_DO_NOT_CACHE	此旗標表示不應該快取從此查詢擷取的名稱。名稱提供者迷你篩選程式會使用此旗標來執行中繼查詢來產生名稱。
FLT_FILE_NAME_ALLOW_QUERY_ON_REPARSE	名稱提供者迷你篩選可以使用這個旗標來指定即使傳回STATUS_REPARSE，在建立後路徑中查詢名稱是安全的。呼叫者必須負責確保 fileObject->FileName 字段未變更。請勿將此旗標與裝入點或符號連結重新分析點搭配使用。

[out] FileNameInformation

呼叫端配置的變數指標，該變數會接收包含檔名資訊之系統配置之 FLT_FILE_NAME_INFORMATION 結構的位址。 FltGetFileNameInformation 從分頁集區配置此結構。這是必要參數，而且無法 NULL。

傳回值

如果成功傳回名稱資訊，FltGetFileNameInformation 會傳回STATUS_SUCCESS。否則，它會傳回適當的NTSTATUS值，例如下列其中一個：

傳回碼	描述
STATUS_FLT_INVALID_NAME_REQUEST	FltGetFileNameInformation 在下列任何情況下，如果無法從篩選管理員的名稱快取中滿足查詢，則無法取得檔名資訊：在分頁 I/O 路徑中。當目前線程的 TopLevelIrp 字段未 NULL時，因為產生的文件系統遞歸可能會導致死結或堆棧溢位。（如需此問題的詳細資訊，請參閱 IoGetTopLevelIrp。完成 IRP_MJ_CLEANUP 作業之後;也就是說，在清除后、關閉前或關閉后路徑中（目標檔案對象已設定FO_CLEANUP_COMPLETE旗標）。在下列任一作業的預先作（PFLT_PRE_OPERATION_CALLBACK）或後續作（PFLT_POST_OPERATION_CALLBACK）回呼例程中： IRP_MJ_ACQUIRE_FOR_CC_FLUSH IRP_MJ_ACQUIRE_FOR_MOD_WRITE IRP_MJ_RELEASE_FOR_CC_FLUSH IRP_MJ_RELEASE_FOR_MOD_WRITE IRP_MJ_RELEASE_FOR_SECTION_SYNCHRONIZATION 在IRP_MJ_ACQUIRE_FOR_SECTION_SYNCHRONIZATION的後續作回呼例程中。停用所有 APC 時;也就是說，KeAreAllApcsDisabled 傳回 TRUE 時。 FltGetFileNameInformation 無法在建立前路徑中取得檔案的簡短名稱。 STATUS_FLT_INVALID_NAME_REQUEST是錯誤碼。
STATUS_INSUFFICIENT_RESOURCES	FltGetFileNameInformation 發生集區配置失敗。這是錯誤碼。
STATUS_INVALID_PARAMETER	傳遞無效的參數時傳回，例如下列其中一項： FileNameInformation 參數不能 NULL。 CallbackData 參數不能 NULL。 STATUS_INVALID_PARAMETER是錯誤碼。
STATUS_FLT_NAME_CACHE_MISS	在名稱快取中找不到檔名資訊，NameOptions 包含FLT_FILE_NAME_QUERY_CACHE_ONLY。 -或- 當 NameOptions 包含 FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP，而且無法從文件系統查詢檔名資訊時，在名稱快取中找不到檔名資訊。 NameOptions 中設定FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY的其他呼叫 fltGetFileNameInformation 可能會傳回檔名資訊。
STATUS_NOT_SAME_DEVICE	在預先建立期間查詢的檔案位於與其父目錄不同的磁碟區上。標準化名稱查詢會傳回此錯誤，其中檔案是解析為不同磁碟區的連接點或符號連結。
STATUS_ACCESS_DENIED	如果使用者依檔案標識碼開啟檔案，但沒有整個路徑的周遊許可權，FltGetFileNameInformation 會因為這個傳回值而失敗。 STATUS_ACCESS_DENIED是錯誤碼。 -或- 檔案是系統檔案，所有存取都遭到拒絕。

言論

FltGetFileNameInformation 會以指定格式傳回 CallbackData所描述作業目標之檔案或目錄的要求名稱資訊。檔系統尚不需要開啟檔案或目錄。

針對預先建立作業，如果 CallbackData->Iopb->OperationFlags 成員包含SL_OPEN_TARGET_DIRECTORY位旗標，FltGetFileNameInformation 會傳回指定檔案的 contain （parent）目錄名稱。此名稱是建立作業開啟的實際路徑。

若要剖析 FltGetFileNameInformation所傳回之FLT_FILE_NAME_INFORMATION結構的內容，請呼叫 FltParseFileNameInformation。（如需檔案名格式的詳細資訊，請參閱 FLT_FILE_NAME_INFORMATION。）

成功呼叫 FltGetFileNameInformation之後，呼叫者會負責在不再需要指標時釋放在 FileNameInformation 參數中傳回的指標。呼叫者會呼叫 FltReleaseFileNameInformation來執行此作業。

呼叫端不得修改 FileNameInformation 參數中傳回的結構內容，因為此結構是由篩選管理員快取，因此所有迷你篩選驅動程式都可以使用它。

如果在建立作業的預先作回呼例程中呼叫 FltGetFileNameInformation，即使磁碟區上開啟的檔案路徑不存在，FltGetFileNameInformation 仍會成功。

如果在建立作業的預先作回呼例程中呼叫 FltGetFileNameInformation，即使磁碟區上開啟檔案的最後元件不存在，FltGetFileNameInformation 仍會成功。

注意

伺服器消息塊（SMB）支援在不同 Windows 10 版本上查詢遠端磁碟區上的正規化檔名。如需詳細資訊，請參閱 MS-SMB2 通訊協定。

在建立、硬式連結和重新命名作業中，檔名通道可能會導致標準化檔名資訊中的最終元件，小型篩選驅動程式在預先作回呼例程中擷取的無效。如果小型篩選驅動程式在預先作回呼（PFLT_PRE_OPERATION_CALLBACK）例程中擷取正規化的檔名資訊，方法是呼叫 FltGetFileNameInformation等例程，則必須從其後續作回呼（PFLT_POST_OPERATION_CALLBACK）例程呼叫 FltGetTunneledName，以擷取檔案的正確檔名資訊。

針對 Windows 8.1 和更早版本，FltGetFileNameInformation 可以包含數據流類型，只有在從篩選的預先建立回呼呼叫時才會。若要區分檔案的預設數據流和元數據數據流，應該在預先建立作業中進行此呼叫。產生的數據流類型在檔案的存留期內會維持有效狀態。

在 Windows 8 之前，篩選管理員會收集檔案路徑每個元件的名稱資訊，以取得檔案或目錄的標準化名稱。這需要文件系統的多個查詢，才能編譯完整的路徑。從 Windows 8 開始，本機文件系統支援 FileNormalizedNameInformation 檔案資訊類別，而且只需要單一查詢，才能取得正規化的名稱。遠端檔案系統可能不支援 FileNormalizedNameInformation 檔案資訊類別。在此情況下，仍然需要查詢檔案路徑的每個元件，才能組合標準化名稱。在特定網路條件下，完整名稱查詢可能需要大量的時間才能完成。

如需標準化檔名資訊的詳細資訊，請參閱 FLT_FILE_NAME_INFORMATION。

注意

檔名通道只會以這種方式影響建立、硬連結和重新命名作業。它不會影響其他 I/O 作業，例如讀取和寫入。

下列配對作業可能會導致檔案名名稱通道：