FltGetTunneledName 函式（fltkernel.h）

發行項
10/30/2024

FltGetTunneledName 例程會擷取檔案的通道名稱，因為先前 呼叫 fltGetFileNameInformation、FltGetFileNameInformationUnsafe或 FltGetDestinationFileNameInformation傳回的標準化名稱。

語法

NTSTATUS FLTAPI FltGetTunneledName(
  [in]  PFLT_CALLBACK_DATA         CallbackData,
  [in]  PFLT_FILE_NAME_INFORMATION FileNameInformation,
  [out] PFLT_FILE_NAME_INFORMATION *RetTunneledFileNameInformation
);

參數

[in] CallbackData

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

[in] FileNameInformation

FLT_FILE_NAME_INFORMATION 結構的指標，其中包含先前呼叫 FltGetFileNameInformation、FltGetFileNameInformationUnsafe或 FltGetDestinationFileNameInformation 所傳回的標準化名稱資訊。

[out] RetTunneledFileNameInformation

呼叫端配置的變數指標，該變數會接收包含通道檔名之新配置結構的位址。如果找不到通道名稱，此變數會收到 NULL。這是必要參數，無法在輸入上 NULL。

傳回值

FltGetTunneledName 如果找到通道名稱，或檔案沒有通道名稱，則會傳回STATUS_SUCCESS。否則，它會傳回NTSTATUS值，例如：

傳回碼	描述
STATUS_INSUFFICIENT_RESOURCES	FltGetTunneledName 發生集區配置失敗。這是錯誤碼。

言論

文件系統，例如NTFS和FAT，會使用個別磁碟區通道快取，針對要重新命名、鏈接或刪除的檔案，簡短保留檔名和其他元數據。檔名通道可能會導致正規化檔名資訊中的最終元件由預先操作呼叫 FltGetFileNameInformation、FltGetFileNameInformationUnsafe或 FltGetDestinationFileNameInformation 無效。

如果迷你篩選驅動程式擷取建立（IRP_MJ_CREATEPFLT_PRE_OPERATION_CALLBACK）預先操作回呼例程中的標準化檔名資訊，則硬式連結（IRP_MJ_SET_INFORMATION，且 FILE_INFORMATION_CLASS 設為 fileLinkInformation），或重新命名作業 IRP_MJ_SET_INFORMATION （FILE_INFORMATION_CLASS設定為 FileRenameInformation），它必須從後置回呼例程（PFLT_POST_OPERATION_CALLBACK）呼叫 FltGetTunneledName，以擷取檔案的正確檔名資訊。

只有標準化的檔名資訊會受到通道的影響。篩選管理員無法確保最終元件在建立、硬式連結或重新命名作業發生之後才會正常化，因為通道可能會導致簡短名稱變更為長名稱。因此，小型篩選驅動程式必須從其後置回呼例程呼叫 FltGetTunneledName，以判斷在預先操作回呼例程中擷取的標準化檔名資訊是否有效。

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

只擷取簡短或已開啟檔名資訊的迷你篩選驅動程式不應該 呼叫 fltGetTunneledName。

呼叫 FltGetFileNameInformation、FltGetFileNameInformationUnsafe或 FltGetDestinationFileNameInformation 預先操作回呼例程中，迷你篩選驅動程式必須將傳回的 fileNameInformation 指標儲存在 preoperation 回呼例程的 CompletionContext 結構中，讓後續操作回呼可以在 fileNameInformation 參數中傳遞此指標，以 FltGetTunneledName。

注意

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

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

delete（name）/create（name）
delete（name）/rename（來源，名稱）
rename（名稱，newname）/create（名稱）
rename（名稱，newname）/rename（來源，名稱）

如果找不到檔案的通道名稱，RetTunneledFileNameInformation 參數會收到 NULL。

成功呼叫 FltGetTunneledName之後，呼叫者會負責釋放 RetTunneledFileNameInformation，並在呼叫 fltReleaseFileNameInformation不再需要時，FileNameInformation 指標。

FltGetTunneledName 只能從小型篩選驅動程式的後置回呼例程呼叫IRP_MJ_CREATE或IRP_MJ_SET_INFORMATION。針對任何其他類型的 I/O 作業，或從預先操作回呼例程呼叫 FltGetTunneledName 是程式設計錯誤。

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

檔案通道可讓您與依賴文件系統的程式相容，以在短時間內保留檔案元數據;例如，針對安全儲存程式。通道會保留檔案長和短（8.3）名稱之間的關聯。從目錄移除檔名時（重新命名或刪除），其簡短和長名稱組和建立時間會儲存在通道快取中，並以移除的名稱作為索引鍵。當名稱新增至目錄（重新命名或建立）時，會搜尋快取，以判斷是否有要還原的資訊。快取會根據目錄的實例生效。如果刪除目錄，則會移除其快取。