FltSetInstanceContext 函式 (fltkernel.h)

發行項
02/29/2024

FltSetInstanceContext 會設定迷你篩選驅動程序實例的內容。

語法

NTSTATUS FLTAPI FltSetInstanceContext(
  [in]  PFLT_INSTANCE             Instance,
  [in]  FLT_SET_CONTEXT_OPERATION Operation,
  [in]  PFLT_CONTEXT              NewContext,
  [out] PFLT_CONTEXT              *OldContext
);

參數

[in] Instance

實例的不透明實例指標。

[in] Operation

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

旗標	意義
FLT_SET_CONTEXT_REPLACE_IF_EXISTS	如果實例已設定實例的內容，則 FltSetInstanceContext 會將該內容取代為 NewContext 中指定的內容。否則，它會將 NewContext 設定為 Instance 的內容。
FLT_SET_CONTEXT_KEEP_IF_EXISTS	如果已經為此實例設定內容， FltSetInstanceContext 會傳回STATUS_FLT_CONTEXT_ALREADY_DEFINED，而且不會取代現有的內容或遞增參考計數。如果尚未設定內容，例程會將 NewContext 設定為 Instance 的內容，並遞增參考計數。

[in] NewContext

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

[out] OldContext

如果已經設定呼叫端配置的變數，則會接收現有實例內容的位址的指標。此參數是選擇性的，可以是 NULL。如需此參數的詳細資訊，請參閱下列一節。

傳回值

FltSetInstanceContext 會傳回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	Instance 參數中指定的實例正在中斷。這是錯誤碼。
STATUS_INVALID_PARAMETER	傳遞了一個無效的參數。例如， NewContext 參數不會指向有效的檔案內容，或為 Operation 參數指定了無效的值。這是錯誤碼。

備註

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

迷你篩選驅動程式會呼叫 FltSetInstanceContext ，將實例內容附加至呼叫端擁有的迷你篩選驅動程序實例，或移除或取代現有的實例內容。迷你篩選驅動程式只能將一個內容附加至實例。

參考計數

如果 FltSetInstanceContext 成功：

NewContext 上的參考計數會遞增。當不再需要 NewContext 所指向的內容時，迷你篩選程式必須呼叫 FltReleaseContext 來遞減其參考計數。

如果 FltSetInstanceContext 失敗，則為：

NewContext 上的參考計數保持不變。
如果 OldContext 不是 NULL ，且未指向 NULL_CONTEXT則 OldContext 是目前與實例相關聯之內容的參考指標。呼叫 FltSetInstanceContext 的篩選最終必須呼叫 OldContext 的 FltReleaseContext，以及不再需要內容指標時。

不論成功為何：

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

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

其他內容作業

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

若要配置新的內容，請呼叫 FltAllocateContext。
若要取得實例內容，請呼叫 FltGetInstanceContext。
若要刪除實例內容，請呼叫 FltDeleteInstanceContext 或 FltDeleteContext。

規格需求

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