FltGetDestinationFileNameInformation 函式（fltkernel.h）

發行項
02/06/2025

FltGetDestinationFileNameInformation 例程會查詢目的地父目錄的檔名，然後為要重新命名或建立 NTFS 硬鏈接的檔案或目錄建構完整的目的地路徑名稱。

語法

NTSTATUS FLTAPI FltGetDestinationFileNameInformation(
  [in]           PFLT_INSTANCE              Instance,
  [in]           PFILE_OBJECT               FileObject,
  [in, optional] HANDLE                     RootDirectory,
  [in]           PWSTR                      FileName,
  [in]           ULONG                      FileNameLength,
  [in]           FLT_FILE_NAME_OPTIONS      NameOptions,
  [out]          PFLT_FILE_NAME_INFORMATION *RetFileNameInformation
);

參數

[in] Instance

附加至檔案所在磁碟區之迷你篩選驅動程序實例的不透明實例指標。

[in] FileObject

檔案物件的指標。這是必要參數，而且不能是 NULL。

[in, optional] RootDirectory

連結作業： 如果要在與所連結檔案相同的目錄中建立連結，或如果 fileName 包含要建立之連結的完整路徑名稱，則此參數為 NULL。否則，它是要建立連結之目錄的句柄。

若要重新命名作業： 如果檔案未移至不同的目錄，或 FileName 包含完整路徑名稱，則此參數為 NULL。否則，它是檔案重新命名之後所在目錄的句柄。

[in] FileName

連結作業： 包含要指派給新建立連結之名稱之寬字元字串的指標。

若要重新命名作業： 包含檔案新名稱之寬字元字串的指標。

[in] FileNameLength

FileName 指向之寬字元字串的長度，以位元組為單位。

[in] NameOptions

FLT_FILE_NAME_OPTIONS 值，其中包含指定要傳回之名稱資訊格式的旗標、篩選管理員要使用的查詢方法，以及其他檔名旗標。這是必要參數，而且不能是 NULL。

以下是名稱格式旗標值。只能指定一個名稱格式旗標。（請注意，FLT_FILE_NAME_SHORT不是此參數的有效旗標值。

名稱格式旗標值	意義
FLT_FILE_NAME_NORMALIZED	FileName 參數會接收檔案的標準化目的地名稱。
FLT_FILE_NAME_OPENED	FileName 參數會根據開啟檔案時所使用的名稱，接收檔案的目的地名稱。此檔名未正規化。

以下是查詢方法旗標值。只能指定一個查詢方法旗標。

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

以下是檔名旗標值。您可以指定這些旗標的任何組合。（請注意，FLT_FILE_NAME_ALLOW_QUERY_ON_REPARSE不是此參數的相關旗標，因為 FltGetDestinationFileNameInformation 不會在建立後回呼中使用。

檔名旗標值	意義
FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER	FltGetDestinationFileNameInformation 將名稱要求導向呼叫篩選實例以完成。
FLT_FILE_NAME_DO_NOT_CACHE	FltGetDestinationFileNameInformation 不會快取擷取的檔名。名稱提供者迷你篩選程式會使用此旗標來執行中繼查詢來產生名稱。

[out] RetFileNameInformation

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

傳回值

FltGetDestinationFileNameInformation 會傳回STATUS_SUCCESS或適當的 NTSTATUS 值，例如下列其中一項：

傳回碼	描述
STATUS_FLT_INVALID_NAME_REQUEST	如果目前線程的 topLevelIrp 字段不是 NULL，FltGetDestinationFileNameInformation 無法取得檔名資訊，因為產生的文件系統遞歸可能會導致死結或堆棧溢位。（2） FLT_FILE_NAME_SHORT 在 nameOptions 參數中指定名稱格式旗標。
STATUS_INSUFFICIENT_RESOURCES	FltGetDestinationFileNameInformation 發生集區配置失敗。這是錯誤碼。
STATUS_INVALID_PARAMETER	NameOptions 參數指定了無效的值。這是錯誤碼。
STATUS_MOUNT_POINT_NOT_RESOLVED	目的地路徑名稱包含一個裝入點，可解析為檔案所在磁碟區以外的磁碟區。（因為重新命名或硬式連結建立作業只能在磁碟區內執行，而不是跨磁碟區執行，因此作業會失敗。這是錯誤碼。

言論

小型篩選程式通常會在重新命名或硬式連結建立作業的預先作回呼例程中呼叫 FltGetDestinationFileNameInform ation，這表示目的地檔名很可能不存在。 “destination” 名稱為：

對於檔案重新命名，如果重新命名成功，檔案的名稱將會是。例如，將 name1 重新命名為 name2時，name2 是目的地名稱。
針對硬式連結建立作業，要新增至文件系統的名稱。例如，將硬式連結 name2 新增至名為 name1的現有檔案時，name2 是目的地名稱。

FltGetDestinationFileNameInformation 會以正規化或「開啟的檔案」格式傳回目的地檔名資訊。如需這些格式的詳細資訊，請參閱 FLT_FILE_NAME_INFORMATION 結構。

針對 FileObject 參數傳遞的檔案對象指標必須是作業 FLT_RELATED_OBJECTS 結構的 FileObject 成員，或是作業 Data->Iopb->TargetFileObject 指標，其中 Data 是作業的回呼數據結構（FLT_CALLBACK_DATA）。檔案對象指標不能是 Data->Iopb->Parameters.SetFileInformation.FileObject 成員，因為此字段不會在文件系統之間統一使用。

如果使用者使用檔案標識碼開啟檔案，但沒有整個路徑的周遊許可權，FltGetDestinationFileNameInformation 只會傳回使用者具有許可權的路徑部分。

重新命名或硬連結建立作業只能在磁碟區內執行，而不是跨磁碟區執行。因此，如果目的地路徑名稱包含解析為檔案所在磁碟區以外的磁碟區，這類作業就會失敗。如需重新命名作業的詳細資訊，請參閱 FILE_RENAME_INFORMATION 結構。如需硬式連結建立作業的詳細資訊，請參閱 FILE_LINK_INFORMATION 結構。

成功呼叫 FltGetDestinationFileNameInformation之後，呼叫端會負責釋放 RetFileNameInformation 參數中傳回的指標，因為呼叫 fltReleaseFileNameInformation不再需要。

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

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

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

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

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