Releasing Contexts

A minifilter releases a context by calling FltReleaseContext. Every successful call to one of the following routines must eventually be matched by a call to FltReleaseContext:

• Context creation routine:

  • FltAllocateContext

• Context get routines:

  • FltGetInstanceContext
  • FltGetFileContext
  • FltGetStreamContext
  • FltGetStreamHandleContext
  • FltGetTransactionContext
  • FltGetVolumeContext

• Context set routines:

  • FltSetFileContext
  • FltSetInstanceContext
  • FltSetStreamContext
  • FltSetStreamHandleContext
  • FltSetTransactionContext
  • FltSetVolumeContext

• Context reference increment routine:

  • FltReferenceContext

Note that the OldContext pointer returned by FltSetXxxContext and the Context pointer returned by FltDeleteContext must also be released when they are no longer needed.

In the following code example, taken from the CTX sample minifilter, the CtxInstanceSetup routine creates and sets an instance context and then calls FltReleaseContext:

status = FltAllocateContext(
           FltObjects->Filter,           //Filter
           FLT_INSTANCE_CONTEXT,         //ContextType
           CTX_INSTANCE_CONTEXT_SIZE,    //ContextSize
           NonPagedPool,                 //PoolType
           &instanceContext);            //ReturnedContext
...
status = FltSetInstanceContext(
           FltObjects->Instance,              //Instance
           FLT_SET_CONTEXT_KEEP_IF_EXISTS,    //Operation
           instanceContext,                   //NewContext
           NULL);                             //OldContext

if (instanceContext != NULL) {
  FltReleaseContext(instanceContext);
}
return status;

Note that FltReleaseContext is called regardless of whether the call to FltSetInstanceContext succeeds:

• If FltSetInstanceContext succeeds, it adds its own reference to the instance context (that is, it increments the reference count on the instance context). Thus, the reference set by FltAllocateContext is no longer needed, and the call to FltReleaseContext removes it.

• If FltSetInstanceContext fails, the instance context has only one reference, namely the one set by FltAllocateContext. When FltReleaseContext returns, the instance context has a reference count of zero, and it is freed by the filter manager.