FltSetTransactionContext function (fltkernel.h)

Article
10/21/2021

The FltSetTransactionContext routine sets a context on a transaction.

Syntax

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
);

Parameters

[in] Instance

Opaque instance pointer for the caller.

[in] Transaction

Opaque transaction pointer for the transaction on which the context is being set.

[in] Operation

Flag that specifies the details of the operation to be performed. This parameter must be one of the following:

Flag	Meaning
FLT_SET_CONTEXT_REPLACE_IF_EXISTS	If a context is already set for the transaction pointed to by the Transaction parameter, FltSetTransactionContext will replace it with the context pointed to by the NewContext parameter. Otherwise, it will set the context pointed to by the NewContext parameter as the context for the transaction pointed to by the Transaction parameter.
FLT_SET_CONTEXT_KEEP_IF_EXISTS	If a context is already set for the transaction pointed to by the Transaction parameter, FltSetTransactionContext will return STATUS_FLT_CONTEXT_ALREADY_DEFINED, and will not replace the existing context or increment the reference count. If a context has not already been set, this routine will set the context pointed to by the NewContext parameter as the context for transaction pointed to by the Transaction parameter, and will increment the reference count.

Flag

Meaning

FLT_SET_CONTEXT_REPLACE_IF_EXISTS

If a context is already set for the transaction pointed to by the Transaction parameter, FltSetTransactionContext will replace it with the context pointed to by the NewContext parameter. Otherwise, it will set the context pointed to by the NewContext parameter as the context for the transaction pointed to by the Transaction parameter.

FLT_SET_CONTEXT_KEEP_IF_EXISTS

If a context is already set for the transaction pointed to by the Transaction parameter, FltSetTransactionContext will return STATUS_FLT_CONTEXT_ALREADY_DEFINED, and will not replace the existing context or increment the reference count. If a context has not already been set, this routine will set the context pointed to by the NewContext parameter as the context for transaction pointed to by the Transaction parameter, and will increment the reference count.

[in] NewContext

Pointer to the new context to be set for the transaction. This parameter is required and cannot be NULL.

[out, optional] OldContext

Pointer to a caller-allocated variable that receives the address of the existing transaction context, if one is already set. This parameter is optional and can be NULL. For more information about this parameter, see the following Remarks section.

Return value

FltSetTransactionContext returns STATUS_SUCCESS or an appropriate NTSTATUS value such as one of the following:

Return code	Description
STATUS_FLT_CONTEXT_ALREADY_DEFINED	If FLT_SET_CONTEXT_KEEP_IF_EXISTS was specified for the Operation parameter, this error code indicates that a context is already attached to the transaction. Only one context can be attached to a transaction for a given minifilter driver.
STATUS_FLT_CONTEXT_ALREADY_LINKED	The context pointed to by the NewContext parameter is already linked to an object. In other words, this error code indicates that NewContext is already in use due to a successful prior call of an FltSetXxxContext routine.
STATUS_FLT_DELETING_OBJECT
The instance specified in the Instance parameter is being torn down. This is an error code.
STATUS_INVALID_PARAMETER	An invalid parameter was passed. For example, the NewContext parameter does not point to a valid transaction context, or an invalid value was specified for the Operation parameter. This is an error code.

Remarks

For more information about contexts, see About minifilter contexts.

A minifilter driver calls FltSetTransactionContext to attach a context to a transaction or to remove or replace an existing transaction context. A minifilter driver can attach only one context to a given transaction.

Reference Counting

If FltSetTransactionContext succeeds:

The reference count on NewContext is incremented. When NewContext is no longer needed, the minifilter must call FltReleaseContext to decrement its reference count.

Else if FltSetTransactionContext fails:

The reference count on NewContext remains unchanged.
If OldContext is not NULL and does not point to NULL_CONTEXT then OldContext is a referenced pointer to the context currently associated with the transaction. The filter calling FltSetTransactionContext must call FltReleaseContext for OldContext as well when the context pointer is no longer needed.

Regardless of success:

The filter calling FltSetTransactionContext must call FltReleaseContext to decrement the reference count on the NewContext object that was incremented by FltAllocateContext.

For more information, see Referencing Contexts.

Other context operations

For more information, see Setting Contexts, and Releasing Contexts:

To allocate a new context, call FltAllocateContext.

To get a transaction context, call FltGetTransactionContext.

To delete a transaction context, call FltDeleteTransactionContext or FltDeleteContext.

Requirements

Requirement	Value
Minimum supported client	Available and supported in Windows Vista and later operating systems.
Target Platform	Universal
Header	fltkernel.h (include Fltkernel.h)
Library	FltMgr.lib
DLL	FltMgr.sys
IRQL	<= APC_LEVEL.