Export (0) Print
Expand All
Expand Minimize

FltSetStreamContext routine

The FltSetStreamContext routine sets a context for a file stream.

Syntax


NTSTATUS FltSetStreamContext(
  _In_   PFLT_INSTANCE Instance,
  _In_   PFILE_OBJECT FileObject,
  _In_   FLT_SET_CONTEXT_OPERATION Operation,
  _In_   PFLT_CONTEXT NewContext,
  _Out_  PFLT_CONTEXT *OldContext
);

Parameters

Instance [in]

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 file stream.

FileObject [in]

A pointer to a file object for the file stream.

Operation [in]

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 file stream.

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 file stream.

NewContext [in]

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

OldContext [out]

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

Return value

The FltSetStreamContext routine 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 Operation, this error code indicates that a stream context is already attached to the file stream.

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 a FltSetXxxContext routine.

STATUS_FLT_DELETING_OBJECT

The specified Instance is being torn down. This is an error code.

STATUS_INVALID_PARAMETER

This can be one of the following:

  • The NewContext parameter does not point to a valid stream context.

  • An invalid value was specified for Operation.

STATUS_INVALID_PARAMETER is an error code.

STATUS_NOT_SUPPORTED

The file system does not support per-stream contexts for this file stream. This is an error code.

 

Remarks

A minifilter driver calls FltSetStreamContext to attach a stream context to a file stream, or to remove or replace an existing stream context. A minifilter driver can attach one context per minifilter driver instance to the file stream.

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

Note that the OldContext pointer returned by FltSetStreamContext 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 FltSetStreamContext cannot be called on an unopened FileObject. Hence FltSetStreamContext cannot be called from a pre-create callback for a stream because the stream has not been opened at that point. A minifilter driver can, however, allocate and set up the stream context in the pre-create callback, pass it to the post-create callback using the completion context parameter and set the stream context on the stream in the post-create callback.

To get a stream context, call FltGetStreamContext.

To allocate a new context, call FltAllocateContext.

To delete a stream context, call FltDeleteStreamContext or FltDeleteContext.

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

Requirements

Version

Available and supported in Microsoft Windows 2000 Update Rollup 1 for SP4, Windows XP SP2, Windows Server 2003 SP1, and later operating systems. Not available nor supported in Windows 2000 SP4 and earlier operating systems.

Header

Fltkernel.h (include Fltkernel.h)

Library

FltMgr.lib

IRQL

<= APC_LEVEL

See also

FltAllocateContext
FltDeleteContext
FltDeleteStreamContext
FltGetStreamContext
FltReleaseContext

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft