Export (0) Print
Expand All
Expand Minimize

FltSetFileContext routine

The FltSetFileContext routine sets a context for a file.

Syntax


NTSTATUS FltSetFileContext(
  _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 pointer to a minifilter driver instance for the caller. This parameter is required and cannot be NULL.

FileObject [in]

A file object pointer for the file. This parameter is required and cannot be NULL.

Operation [in]

A flag that specifies the type of operation for FltSetFileContext to perform. This parameter must be one of the following flags:

FLT_SET_CONTEXT_REPLACE_IF_EXISTS

If a context is already set for the instance that the Instance parameter points to, FltSetFileContext will replace that context with the context specified in NewContext. Otherwise, the routine will insert the context specified in NewContext into the list of contexts for the file.

FLT_SET_CONTEXT_KEEP_IF_EXISTS

If a context is already set for the instance that the Instance parameter points to, FltSetFileContext will return STATUS_FLT_CONTEXT_ALREADY_DEFINED. Otherwise, the routine will insert the context specified in NewContext into the list of contexts for the file.

NewContext [in]

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

OldContext [out]

A pointer to a caller-allocated variable that receives the address of the existing file context for the instance pointed to by 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 FltSetFileContext 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 the Operation parameter, this error code indicates that a context is already attached to the file.

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 instance specified in the Instance parameter is being torn down. This is an error code.

STATUS_INVALID_PARAMETER

This error code indicates one of the following problems:

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

  • An invalid value was specified for the Operation parameter.

STATUS_NOT_SUPPORTED

File contexts are not supported for this file. This is an error code.

 

Remarks

The FltSetFileContext routine is available on Microsoft Windows 2000 Update Rollup 1 for SP4, Windows XP SP2, Windows Server 2003 SP1, and later operating systems. This routine is available and supported starting with Windows Vista (file contexts are only supported starting with Windows Vista). If FltSetFileContext is called on an operating system where this routine is available but file contexts are not supported, it returns STATUS_NOT_SUPPORTED. This routine is not available on Windows 2000 SP4 and earlier operating systems.

A minifilter driver calls FltSetFileContext to set or replace its own file context on a file. A minifilter driver can attach one context per minifilter driver instance to the file.

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

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

Be aware that FltSetFileContext cannot be called on an unopened FileObject. Hence FltSetFileContext 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 file context in the pre-create callback, pass it to the post-create callback using the completion context parameter and set the stream file context on the file corresponding to that stream in the post-create callback.

To get a file context, call FltGetFileContext.

To allocate a new context, call FltAllocateContext.

To delete a file context, call FltDeleteFileContext or FltDeleteContext.

To determine whether file contexts are supported for a given file, call FltSupportsFileContexts or FltSupportsFileContextsEx.

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

Requirements

Version

Available and supported starting with Windows Vista. For more information, see the Remarks section.

Header

Fltkernel.h (include Fltkernel.h)

Library

Fltmgr.lib

IRQL

<= APC_LEVEL

See also

FLT_CONTEXT_REGISTRATION
FltAllocateContext
FltDeleteContext
FltDeleteFileContext
FltGetFileContext
FltReleaseContext
FltSupportsFileContexts
FltSupportsFileContextsEx

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft