FltGetVolumeInstanceFromName 函式 (fltkernel.h)

發行項
02/26/2024

FltGetVolumeInstanceFromName 例程會傳回指定磁碟區上指定迷你篩選驅動程序實例的不透明實例指標。

語法

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

參數

[in, optional] Filter

擁有實例之迷你篩選驅動程式的不透明篩選指標。此參數是選擇性的，可以是 NULL。

[in] Volume

實例所附加磁碟區的不透明指標。必須是有效的磁碟區句柄。這個參數是必要的，而且不能是 NULL。 (將此參數設定為無效值，會導致系統在核取的build.)

[in, optional] InstanceName

呼叫端配置的 UNICODE_STRING 結構的指標，其中包含磁碟區上實例的實例名稱。 (這是在建立實例時傳遞至 FltAttachVolume 或 FltAttachVolumeAtAltitude 的 InstanceName 值。) 此參數是選擇性的，而且可以是 NULL。如果是 NULL，FltGetVolumeInstanceFromName 會傳回找到的最高相符實例。

[out] RetInstance

呼叫端配置的變數指標，該變數會接收符合 Filter、 Volume 和 InstanceName 值的實例不透明實例指標。這個參數是必要的，而且不能是 NULL。

傳回值

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

傳回碼	Description
STATUS_FLT_DELETING_OBJECT	正在中斷實例。這是錯誤碼。
STATUS_FLT_INSTANCE_NOT_FOUND	找不到相符的實例。這是錯誤碼。

備註

FltGetVolumeInstanceFromName 會搜尋附加至 Volume 參數中所指定磁碟區的迷你篩選驅動程序實例清單，從最上層實例開始。如果多個實例符合 Filter、 Volume 和 InstanceName 參數的指定值， FltGetVolumeInstanceFromName 會傳回找到的最高相符實例。

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

高度是由 高度字串所指定，這是包含 0 到 9 之一或多個十進位數的計算 Unicode 字串，而且可以包含單一小數點。例如，“100.123456” 和 “03333” 是有效的高度字串。

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

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