FltAttachVolume 函式（fltkernel.h）

發行項
02/06/2025

FltAttachVolume 會建立新的迷你篩選驅動程序實例，並將它附加至指定的磁碟區。

語法

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

參數

[in, out] Filter

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

[in, out] Volume

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

[in, optional] InstanceName

包含新實例實例名稱之 UNICODE_STRING 結構的指標。這個參數是選擇性的，而且可以 NULL。如果它是 NULL，FltAttachVolume 會嘗試從登錄讀取迷你篩選驅動程式的默認實例名稱。（如需此參數的詳細資訊，請參閱下列一節。

[out] RetInstance

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

傳回值

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

傳回碼	描述
STATUS_FLT_DELETING_OBJECT	指定的篩選或磁碟區正在被拆毀。這是錯誤碼。
STATUS_FLT_FILTER_NOT_READY	迷你篩選驅動程式尚未開始篩選。如需詳細資訊，請參閱 FltStartFiltering。這是錯誤碼。
STATUS_FLT_INSTANCE_NAME_COLLISION	指定的磁碟區上已經有這個名稱的實例。
STATUS_INSUFFICIENT_RESOURCES	FltAttachVolume 發生集區配置失敗。這是錯誤碼。
STATUS_OBJECT_NAME_COLLISION	另一個實例已在從登錄讀取的實例屬性中指定的高度附加。這是錯誤碼。

言論

如果呼叫端為 InstanceName指定非NULL 值，FltAttachVolume 會讀取儲存在 HKLM\CurrentControlSet\Services\ServiceName\Instances\InstanceName 之下登錄中所指定的任何實例屬性，其中 ServiceName 是迷你篩選驅動程式的服務名稱。此服務名稱是在 minifilter 驅動程式 INF 檔案的 DefaultInstall.Services 區段的 AddService 指示詞中指定。（如需篩選驅動程式 INF 檔案的詳細資訊，請參閱安裝檔案系統篩選驅動程式。）

如果呼叫端未指定 InstanceName的值，FltAttachVolume 會使用登錄中儲存在 HKLM\CurrentControlSet\Services\ServiceName\Instances\DefaultInstance 中儲存在登錄路徑 InstanceName 部分的名稱。

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

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

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

若要將迷你篩選驅動程序實例附加至指定高度的磁碟區，請呼叫 FltAttachVolumeAtAltitude。

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

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