FltGetFileNameInformation 函式 (fltkernel.h)

發行項
02/29/2024

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值，例如下列其中一個：

傳回碼	Description
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-Iopb-OperationFlags>> 成員包含SL_OPEN_TARGET_DIRECTORY位旗標，FltGetFileNameInformation 會傳回指定檔案包含 (父系) 目錄的名稱。此名稱是建立作業開啟的實際路徑。

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

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

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

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

如果在建立作業的預先操作回呼例程中呼叫 FltGetFileNameInformation 來擷取正規化名稱， 則 FltGetFileNameInformation 即使開啟之檔案路徑的最後元件不存在於磁碟區上也一樣。

注意

伺服器消息塊 (SMB) 支援在遠端磁碟區上查詢標準化檔名，會因不同 Windows 10 版本而有所不同。如需詳細資訊，請參閱 MS-SMB2 通訊協定。

在建立、硬式連結和重新命名作業中，檔名通道可能會導致標準化檔名資訊中迷你篩選驅動程式在預先操作回呼例程中擷取的最終元件失效。如果迷你篩選驅動程式透過呼叫 FltGetFileNameInformation 之類的例程，從其後置回呼中擷取正規化的檔名) PFLT_PRE_OPERATION_CALLBACK (資訊， ( PFLT_POST_OPERATION_CALLBACK) 例程擷取正確的檔名資訊，以擷取檔案的正確檔名資訊。

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

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

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

注意

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

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