FltAttachVolume 函式 (fltkernel.h)

發行項
02/26/2024

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 值，例如下列其中一項：

傳回碼	Description
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 是迷你篩選驅動程式的服務名稱。此服務名稱是在迷你篩選器驅動程式 INF 檔案之 DefaultInstall.Services 區段的 AddService 指示詞中指定。 (如需篩選驅動程式 INF 檔案的詳細資訊，請參閱安裝文件系統篩選器驅動程式.)

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

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

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

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

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

若要比較連結至相同磁碟區的兩個迷你篩選驅動程序實例的高度，請呼叫 FltCompareInstanceAltitudes。

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