FltSetStreamHandleContext function

Download EaseFilter Filter Driver SDK Setup File
Download EaseFilter Filter Driver SDK Zip File

NTSTATUS FLTAPI FltSetStreamHandleContext(
  PFLT_INSTANCE             Instance,
  PFILE_OBJECT              FileObject,
  FLT_SET_CONTEXT_OPERATION Operation,
  PFLT_CONTEXT              NewContext,
  PFLT_CONTEXT              *OldContext
);

Parameters

Instance

An opaque instance pointer for the minifilter driver instance whose context is to be inserted into, removed from, or replaced in the list of contexts attached to the stream handle.

FileObject

A pointer to a file object for the file stream.

Operation

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

FLT_SET_CONTEXT_REPLACE_IF_EXISTS

If a context is already set for this Instance, replace it with NewContext. Otherwise, insert NewContext into the list of contexts for the stream handle.

FLT_SET_CONTEXT_KEEP_IF_EXISTS

If a context is already set for this Instance, return STATUS_FLT_CONTEXT_ALREADY_DEFINED. Otherwise, insert NewContext into the list of contexts for the stream handle.

NewContext

A pointer to the new context to be set for the stream handle. This parameter is required and cannot be NULL.

OldContext

A pointer to a caller-allocated variable that receives the address of the existing stream handle context for the Instance parameter. This parameter is optional and can be NULL. (For more information about this parameter, see the following Remarks section.)

Return value

The FltSetStreamHandleContext routine returns STATUS_SUCCESS or an appropriate NTSTATUS value such as one of the following:

Remarks

The FltSetStreamHandleContext routine adds, removes, or replaces a context for a minifilter driver instance on a stream handle. A minifilter driver can attach one context per minifilter driver instance to the stream handle.

A successful call to FltSetStreamHandleContext increments the reference count on NewContext. When the context pointed to by NewContext is no longer needed, the minifilter must call FltReleaseContext to decrement its reference count.

If FltSetStreamHandleContext fails, the reference count remains unchanged. In this case, the filter calling FltSetStreamHandleContext must call FltReleaseContext for the NewContext object that was allocated and referenced in FltAllocateContext. If FltSetStreamHandleContext 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 FltSetStreamHandleContext must call FltReleaseContext for OldContext as well.

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

Also note that FltSetStreamHandleContext cannot be called on an unopened FileObject. Hence FltSetStreamHandleContext cannot be called from a pre-create callback for a stream because the stream has not been opened at that point. A minifilter can, however, allocate and set up the stream handle context in the pre-create callback, pass it to the post-create callback using the completion context parameter and set the stream handle context on the stream in the post-create callback.

To get a stream handle context, call FltGetStreamHandleContext.

To allocate a new context, call FltAllocateContext.

To delete a stream handle context, call FltDeleteStreamHandleContext or FltDeleteContext.

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

Requirements