FltAttachVolumeAtAltitude 函式（fltkernel.h）

發行項
02/06/2025

FltAttachVolumeAtAltitude 是偵錯支援例程，會將小型篩選驅動程序實例附加至指定高度的磁碟區，並覆寫迷你篩選驅動程式 INF 檔案中的任何設定。

語法

NTSTATUS FLTAPI FltAttachVolumeAtAltitude(
  [in, out]       PFLT_FILTER      Filter,
  [in, out]       PFLT_VOLUME      Volume,
  [in]            PCUNICODE_STRING Altitude,
  [in, optional]  PCUNICODE_STRING InstanceName,
  [out, optional] PFLT_INSTANCE    *RetInstance
);

參數

[in, out] Filter

呼叫端的不透明篩選指標。這是必要參數，而且無法 NULL。

[in, out] Volume

要附加迷你篩選驅動程序實例之磁碟區的不透明磁碟區指標。這是必要參數，而且無法 NULL。

[in] Altitude

包含實例高度字串之 UNICODE_STRING 結構的指標。這是必要參數，而且無法 NULL。（如需此參數的詳細資訊，請參閱下列一節。

[in, optional] InstanceName

包含新實例實例名稱之 UNICODE_STRING 結構的指標。這個參數是選擇性的，而且可以 NULL。如果它 NULL，FltAttachVolumeAtAltitude 會從小型篩選驅動程式名稱和高度字串產生實例名稱，以及高度指向的高度字串。視需要截斷產生的名稱，以INSTANCE_NAME_MAX_CHARS字元。

[out, optional] RetInstance

呼叫端配置的變數指標，該變數會接收新建立實例的不透明實例指標。這個參數是選擇性的，而且可以 NULL。

傳回值

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

傳回碼	描述
STATUS_FLT_DELETING_OBJECT	指定的篩選或磁碟區正在被拆毀。這是錯誤碼。
STATUS_FLT_FILTER_NOT_READY	迷你篩選驅動程式尚未開始篩選。如需詳細資訊，請參閱 FltStartFiltering。這是錯誤碼。
STATUS_FLT_INSTANCE_ALTITUDE_COLLISION	實例已存在於指定的磁碟區上的這個高度。這是錯誤碼。
STATUS_FLT_INSTANCE_NAME_COLLISION	指定的磁碟區上已經有這個名稱的實例。這是錯誤碼。
STATUS_INSUFFICIENT_RESOURCES	FltAttachVolumeAtAltitude 發生集區配置失敗。這是錯誤碼。
STATUS_INVALID_PARAMETER	高度指向的UNICODE_STRING結構未包含有效的高度字串。這是錯誤碼。

言論

小型篩選驅動程式應該只使用 FltAttachVolumeAtAltitude 進行偵錯。它不應該在小型篩選驅動程式的零售版本中呼叫此例程。

FltAttachVolumeAtAltitude 是 Win32 FilterAttachAtAltitude 函式的核心對等專案。

「高度」一詞是指實例在磁碟區迷你篩選驅動程序實例堆疊中佔據的位置（或應該佔用）。高度越高，實例離堆疊中的基底文件系統越遠。在指定磁碟區上的指定高度只能附加一個實例。

高度是由 高度字串所指定，這是一個寬字元陣列，其中包含從 0 到 9 的一或多個十進位數：數位可以包含單一小數點。例如，“100.123456” 和 “03333” 是有效的高度字串。

字串 “033333” 代表高於 “100.123456” 的高度（會忽略前置和尾端零。換句話說，高度為 “03333” 的實例比高度為 “100.123456” 的實例遠於基底文件系統。不過，只有在這兩個實例都附加至相同的磁碟區時，此比較才有意義。

InstanceName 參數中指定的實例名稱必須在整個系統中是唯一的。

FltAttachVolumeAtAltitude 會傳回 *RetInstance中新實例的不透明實例指標。此指標值會唯一識別迷你篩選驅動程序實例，只要實例附加至磁碟區，就會維持不變。

FltAttachVolumeAtAltitude 會將 rundown 參考新增至 *RetInstance 中傳回的不透明實例指標。不再需要此指標時，呼叫端必須呼叫 FltObjectDereference來釋放它。因此，FltAttachVolumeAtAltitude 的每個成功呼叫，都必須比對 FltObjectDereference的後續呼叫。

若要比較附加至相同磁碟區的兩個小型篩選驅動程序實例的高度，請呼叫 FltCompareInstanceAltitudes。

若要將迷你篩選驅動程式實例與磁碟區中斷連結，請呼叫 FltDetachVolume。