PFREE_FUNCTION function pointer

Article
03/14/2023

A file system legacy filter driver can register a PFREE_FUNCTION typed routine as the filter's FreeCallback callback routine. The file system calls FreeCallback when the file system removes a file context object by using FsRtlTeardownPerFileContexts or removes a stream context object by using FsRtlTeardownPerStreamContexts.

You must declare the callback routine by using the FREE_FUNCTION type. For more information, see the example in the Remarks section.

Syntax

typedef VOID ( *FreeCallback)(
  _In_ PVOID Buffer
);

Parameters

Buffer [in]: A pointer to the FSRTL_PER_FILE_CONTEXT or the FSRTL_PER_STREAM_CONTEXT structure to be freed.

Return value

None

Remarks

When a file system tears down the per-file context object for a file, it must call FsRtlTeardownPerFileContexts. This routine calls the FreeCallback routines of all per-file context structures associated with the file. This callback routine must free any memory used for the FSRTL_PER_FILE_CONTEXT object and any associated context information. This is also the case for per-stream contexts when FsRtlTeardownPerStreamContexts is called and FreeCallback will free memory used for FSRTL_PER_STREAM_CONTEXT objects.

For remarks about synchronizing access to per-file context objects or to per-stream context objects during a call to FreeCallback, see FsRtlTeardownPerFileContexts and FsRtlTeardownPerStreamContexts.

Note

The FreeCallback routine cannot recursively call down into the file system or acquire any file system resources.

To define a FreeCallback callback function that is named MyFreeFunction, you must first provide a function declaration that the Static Driver Verifier (SDV) and other verification tools require, as follows:

FREE_FUNCTION MyFreeFunction;

And then implement your callback function as follows:

VOID
 MyFreeFunction (
 __in PVOID Buffer
    )
  {...}

Requirements

Requirement type	Requirement
Minimum supported client	Windows Vista
Header	Wdm.h (include Wdm.h or Ntddk.h)
IRQL	<= APC_LEVEL