Export (0) Print
Expand All
Expand Minimize

FltSetTransactionContext routine

The FltSetTransactionContext routine sets a context on a transaction.

Syntax


NTSTATUS FltSetTransactionContext(
  _In_       PFLT_INSTANCE Instance,
  _In_       PKTRANSACTION Transaction,
  _In_       FLT_SET_CONTEXT_OPERATION Operation,
  _In_       PFLT_CONTEXT NewContext,
  _Out_opt_  PFLT_CONTEXT *OldContext
);

Parameters

Instance [in]

Opaque instance pointer for the caller.

Transaction [in]

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

Operation [in]

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

ValueMeaning
FLT_SET_CONTEXT_REPLACE_IF_EXISTS

If a context is already set for the transaction pointed to by the Transaction parameter, replace the existing context with the context pointed to by the NewContext parameter. Otherwise, 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, return STATUS_FLT_CONTEXT_ALREADY_DEFINED. Otherwise, set the context pointed to by the NewContext parameter as the context for transaction pointed to by the Transaction parameter.

 

NewContext [in]

Pointer to the new context to be set for the instance. The context must have been allocated by a previous call to FltAllocateContext. This parameter is required and cannot be NULL.

OldContext [out, optional]

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 codeDescription
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

STATUS_INVALID_PARAMETER

One of the following:

  • The NewContext parameter does not point to a valid transaction context.
  • An invalid value was specified for the Operation parameter.

STATUS_INVALID_PARAMETER is an error code.

 

Remarks

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.

Before calling FltSetTransactionContext to set a new transaction context, the caller must call FltAllocateContext to allocate the context object.

A successful call to FltSetTransactionContext increments the reference count on NewContext. If FltSetTransactionContext fails, the reference count remains unchanged. In either case, the filter calling FltSetTransactionContext must call FltReleaseContext to decrement the NewContext object. If FltSetTransactionContext fails and if the OldContext parameter 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.

Note that the OldContext pointer returned by FltSetTransactionContext must also be released by calling FltReleaseContext when it is no longer needed. For more information, see Setting Contexts and Releasing Contexts.

To retrieve a transaction context, call FltGetTransactionContext.

To allocate a new transaction context, call FltAllocateContext.

To delete a transaction context, call FltDeleteTransactionContext or FltDeleteContext.

For more information about context reference counting, see Referencing Contexts.

Requirements

Version

Available and supported in Windows Vista and later operating systems.

Header

Fltkernel.h (include Fltkernel.h)

Library

FltMgr.lib

IRQL

<= APC_LEVEL.

See also

FltAllocateContext
FltCommitComplete
FltDeleteContext
FltDeleteTransactionContext
FltEnlistInTransaction
FltGetTransactionContext
FltPrepareComplete
FltPrePrepareComplete
FltReleaseContext
FltRollbackComplete
FltRollbackEnlistment

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft