FltSetTransactionContext 函式 (fltkernel.h)

發行項
03/01/2024

FltSetTransactionContext 例程會在交易上設定內容。

語法

NTSTATUS FLTAPI FltSetTransactionContext(
  [in]            PFLT_INSTANCE             Instance,
  [in]            PKTRANSACTION             Transaction,
  [in]            FLT_SET_CONTEXT_OPERATION Operation,
  [in]            PFLT_CONTEXT              NewContext,
  [out, optional] PFLT_CONTEXT              *OldContext
);

參數

[in] Instance

呼叫端的不透明實例指標。

[in] Transaction

正在設定內容之交易的不透明交易指標。

[in] Operation

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

旗標	意義
FLT_SET_CONTEXT_REPLACE_IF_EXISTS	如果已針對 Transaction 參數所指向的交易設定內容， FltSetTransactionContext 會將它取代為 NewContext 參數所指向的內容。否則，它會將 NewContext 參數所指向的內容設定為 Transaction 參數所指向之交易的內容。
FLT_SET_CONTEXT_KEEP_IF_EXISTS	如果已針對 Transaction 參數指向的交易設定內容， FltSetTransactionContext 會傳回STATUS_FLT_CONTEXT_ALREADY_DEFINED，而且不會取代現有的內容或遞增參考計數。如果尚未設定內容，這個例程會將 NewContext 參數所指向的內容設定為 Transaction 參數所指向之交易的內容，並遞增參考計數。

[in] NewContext

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

[out, optional] OldContext

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

傳回值

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

傳回碼	Description
STATUS_FLT_CONTEXT_ALREADY_DEFINED	如果已為 Operation 參數指定FLT_SET_CONTEXT_KEEP_IF_EXISTS，這個錯誤碼表示內容已經附加至交易。只有一個內容可以附加至指定迷你篩選驅動程式的交易。
STATUS_FLT_CONTEXT_ALREADY_LINKED	NewContext 參數所指向的內容已經連結至物件。換句話說，此錯誤碼表示 NewContext 已在使用中，因為 FltSetXxx內容例程先前呼叫成功。
STATUS_FLT_DELETING_OBJECT
Instance 參數中指定的實例正在損毀。這是錯誤碼。
STATUS_INVALID_PARAMETER	傳遞了一個無效的參數。例如， NewContext 參數不會指向有效的交易內容，或為 Operation 參數指定了無效的值。這是錯誤碼。

備註

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

迷你篩選驅動程式會呼叫 FltSetTransactionContext ，將內容附加至交易，或移除或取代現有的交易內容。迷你篩選驅動程式只能將一個內容附加至指定的交易。

參考計數

如果 FltSetTransactionContext 成功：

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

否則 ，如果 FltSetTransactionContext 失敗：

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

不論成功：

呼叫 FltSetTransactionContext 的篩選條件必須呼叫 FltReleaseContext，以遞減 FltAllocateContext 遞增之 NewContext 物件的參考計數。

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

其他內容作業

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

若要配置新的內容，請呼叫 FltAllocateContext。

若要取得交易內容，請呼叫 FltGetTransactionContext。

若要刪除交易內容，請呼叫 FltDeleteTransactionContext 或 FltDeleteContext。

規格需求

需求	值
最低支援的用戶端	Windows Vista 和更新版本的作業系統中提供及支援。
目標平台	Universal
標頭	fltkernel.h (包含 Fltkernel.h)
程式庫	FltMgr.lib
Dll	FltMgr.sys
IRQL	<= APC_LEVEL。