FltGetDestinationFileNameInformation 函式 (fltkernel.h)

發行項
02/26/2024

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

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

備註

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

若為檔案重新命名，如果重新命名成功，則文件名將具有。例如，將 name1 重新命名為 name2 時， name2 是目的地名稱。
針對硬式連結建立作業，要新增至文件系統的名稱。例如，將硬式連結 名稱2 新增至名為 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 之後，呼叫端會負責在呼叫 FltReleaseFileNameInformation 參數不再需要時釋放在 RetFileNameInformation 參數中傳回的指標。

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

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

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

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

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