FltSetVolumeContext 函式 (fltkernel.h)

發行項
02/26/2024

FltSetVolumeContext 會設定磁碟區的內容。

語法

NTSTATUS FLTAPI FltSetVolumeContext(
  [in]            PFLT_VOLUME               Volume,
  [in]            FLT_SET_CONTEXT_OPERATION Operation,
  [in]            PFLT_CONTEXT              NewContext,
  [out, optional] PFLT_CONTEXT              *OldContext
);

參數

[in] Volume

磁碟區的不透明磁碟區指標。

[in] Operation

指定要執行之作業詳細數據的旗標。此參數必須是下列其中一項：

旗標	意義
FLT_SET_CONTEXT_REPLACE_IF_EXISTS	如果已針對 Volume 設定內容， FltSetVolumeContext 會將它取代為 NewContext>。否則，它會將 NewContext 插入磁碟區的內容清單中。
FLT_SET_CONTEXT_KEEP_IF_EXISTS	如果已經為此磁碟區設定內容， FltSetVolumeContext 會傳回STATUS_FLT_CONTEXT_ALREADY_DEFINED，而且不會取代現有的內容或遞增參考計數。如果尚未設定內容，例程會將 NewContext 插入磁碟區的內容清單中，並遞增參考計數。

[in] NewContext

要為磁碟區設定之新內容的指標。這個參數是必要的，而且不能是 NULL。

[out, optional] OldContext

呼叫端配置的變數指標，該變數會接收 Volume 現有磁碟區內容的位址。 這個參數是選擇性的，而且可以是 NULL。如需此參數的詳細資訊，請參閱下列一節。

傳回值

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

傳回碼	Description
STATUS_FLT_CONTEXT_ALREADY_DEFINED	如果已為 Operation 指定FLT_SET_CONTEXT_KEEP_IF_EXISTS，這個錯誤碼表示內容已經附加至磁碟區。
STATUS_FLT_CONTEXT_ALREADY_LINKED	NewContext 參數所指向的內容已經連結至物件。換句話說，這個錯誤碼表示 NewContext 已在使用中，因為 FltSetXxxContext 例程的呼叫成功。
STATUS_FLT_DELETING_OBJECT	指定的磁碟區正在損毀。這是錯誤碼。
STATUS_INVALID_PARAMETER	傳遞了一個無效的參數。例如， NewContext 參數不會指向有效的磁碟區內容，或為 Operation 指定了無效的值。這是錯誤碼。

備註

如需內容的詳細資訊，請參閱關於迷你篩選內容。

迷你篩選驅動程式會呼叫 FltSetVolumeContext ，將內容附加至磁碟區，或移除或取代現有的磁碟區內容。迷你篩選驅動程式只能將一個內容附加至磁碟區。

參考計數

如果 FltSetVolumeContext 成功：

NewContext 上的參考計數會遞增。不再需要 NewContext 時，迷你篩選必須呼叫 FltReleaseContext 以遞減其參考計數。

否則 ，如果 FltSetVolumeContext 失敗：

NewContext 上的參考計數保持不變。
如果 OldContext 不是 NULL 且未指向 NULL_CONTEXT則 OldContext 是目前與磁碟區相關聯之內容的參考指標。呼叫 FltSetVolumeContext 的篩選條件，也必須在不再需要內容指標時呼叫 OldContext 的 FltReleaseContext。

不論成功：

呼叫 FltSetVolumeContext 的篩選條件必須呼叫 FltReleaseContext，以遞減由 FltAllocateContext 遞增之 NewContext 對象的參考計數。

如需詳細資訊，請參閱參考內容。

其他內容作業

如需詳細資訊，請參閱設定內容和釋放內容：

若要配置新的內容，請呼叫 FltAllocateContext。
若要取得磁碟區內容，請呼叫 FltGetVolumeContext。
若要刪除磁碟區內容，請呼叫 FltDeleteVolumeContext 或 FltDeleteContext。

規格需求

需求	值
最低支援的用戶端	適用於 SP4、Windows XP SP2、Windows Server 2003 SP1 和更新版本的作業系統的 Microsoft Windows 2000 Update 匯總 1 中提供及支援。
目標平台	Universal
標頭	fltkernel.h (包含 Fltkernel.h)
程式庫	FltMgr.lib
Dll	Fltmgr.sys
IRQL	<= APC_LEVEL