FltDeleteFileContext function (fltkernel.h)

Article
10/21/2021

The FltDeleteFileContext routine retrieves and deletes a file context that a given minifilter driver has set for a given file.

Syntax

NTSTATUS FLTAPI FltDeleteFileContext(
  [in]  PFLT_INSTANCE Instance,
  [in]  PFILE_OBJECT  FileObject,
  [out] PFLT_CONTEXT  *OldContext
);

Parameters

[in] Instance

Opaque instance pointer for the caller. This parameter is required and cannot be NULL.

[in] FileObject

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

[out] OldContext

Pointer to a caller-allocated variable that receives the address of the deleted context. If no matching context is found, this variable receives NULL_CONTEXT. This parameter is optional and can be NULL. For more information about this parameter, see the following Remarks section.

Return value

FltDeleteFileContext returns STATUS_SUCCESS or an appropriate NTSTATUS value, such as one of the following:

Return code	Description
STATUS_NOT_FOUND	No matching context was found. This is an error code.
STATUS_NOT_SUPPORTED	File contexts are not supported for this file. This is an error code.

Remarks

For more information about contexts, see About minifilter contexts.

Because contexts are reference-counted, it is not usually necessary for a minifilter driver to call a routine such as FltDeleteFileContext or FltDeleteContext to explicitly delete a context.

A minifilter driver calls FltDeleteFileContext to retrieve and delete a file context that it previously set for a file by calling FltSetFileContext.

If the OldContext parameter is NULL on input and a matching file context is found, FltDeleteFileContext releases the reference that was added by the minifilter driver's previous call to FltSetFileContext. The deleted context is usually freed immediately unless there is an outstanding reference on it (for example, because the context is still being used by another thread).

If the OldContext parameter is not NULL and a matching file context is found and returned, the caller is responsible for releasing the reference that was added by FltSetFileContext. To release this reference, the minifilter driver must call FltReleaseContext on the deleted file context as soon as possible after performing any necessary cleanup.

To allocate a new context, call FltAllocateContext.

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

Requirements

Requirement	Value
Minimum supported client	Windows Vista and later
Target Platform	Universal
Header	fltkernel.h (include Fltkernel.h)
Library	FltMgr.lib
IRQL	<= APC_LEVEL