FltGetTunneledName 函式 (fltkernel.h)

發行項
02/26/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值，例如：

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

備註

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

如果迷你篩選驅動程式在預先操作回呼例程中擷取正規化的檔名資訊， (PFLT_PRE_OPERATION_CALLBACK) 建立 (IRP_MJ_CREATE) 、將FILE_INFORMATION_CLASS設為 FileRenameInformation) 的硬式連結 (IRP_MJ_SET_INFORMATION，或將FILE_INFORMATION_CLASS設定為 FileLinkInformation) 重新命名作業 (IRP_MJ_SET_INFORMATION，它必須從其後置回呼例程呼叫 FltGetTunneledName (PFLT_POST_OPERATION_CALLBACK) ，以擷取檔案的正確檔名資訊。

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

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

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

呼叫 FltGetFileNameInformation 之後， FltGetFileNameInformationUnsafe 或 FltGetDestinationFileNameInformation 在 preoperation 回呼例程中，minifilter 驅動程式必須將傳回的 FileNameInformation 指標儲存在預先操作回呼例程的 CompletionContext 結構中，讓後置回呼可以將 FileNameInformation 參數中的這個指標傳遞至 FltGetTunneledName。

注意

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

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

delete (name) /create (name)
刪除 (名稱) /rename (來源、名稱)
重新命名 (名稱、 newname) /create (name)
rename (name， newname) /rename (source， name)

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

成功呼叫 FltGetTunneledName 之後，呼叫端會負責在呼叫 FltReleaseFileNameInformation 時釋出 RetTunneledFileNameInformation 和 FileNameInformation 指標。

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

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

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