PFLT_GENERATE_FILE_NAME callback function (fltkernel.h)

Article
10/21/2021

A minifilter driver that provides file names for the filter manager's name cache can register a routine of type PFLT_GENERATE_FILE_NAME as the minifilter driver's GenerateFileNameCallback routine.

Syntax

PFLT_GENERATE_FILE_NAME PfltGenerateFileName;

NTSTATUS PfltGenerateFileName(
  [in]           PFLT_INSTANCE Instance,
  [in]           PFILE_OBJECT FileObject,
  [in, optional] PFLT_CALLBACK_DATA CallbackData,
  [in]           FLT_FILE_NAME_OPTIONS NameOptions,
  [out]          PBOOLEAN CacheFileNameInformation,
  [out]          PFLT_NAME_CONTROL FileName
)
{...}

Parameters

[in] Instance

Opaque instance pointer for the minifilter driver instance that this callback routine is registered for.

[in] FileObject

A pointer to a file object for the file whose name is being requested.

[in, optional] CallbackData

A pointer to the callback data structure for the operation during which this name is being requested. This parameter is NULL when FltGetFileNameInformationUnsafe is called to retrieve the name of the file.

[in] NameOptions

FLT_FILE_NAME_OPTIONS value that specifies the name format, query method, and flags for this file name information query.

[out] CacheFileNameInformation

A pointer to a Boolean value specifying whether this name can be cached. Set to TRUE on output if the name can be cached; set to FALSE otherwise.

[out] FileName

A pointer to a filter manager-allocated FLT_NAME_CONTROL structure to receive the file name on output.

Return value

This callback routine returns STATUS_SUCCESS or an appropriate NTSTATUS value.

Remarks

To register this callback routine, the minifilter driver stores the address of a routine of type PFLT_GENERATE_FILE_NAME in the GenerateFileNameCallback member of the FLT_REGISTRATION structure that the minifilter driver passes as a parameter to FltRegisterFilter.

The filter manager calls this callback routine to allow the minifilter driver to intercept file name requests by other minifilter drivers above it in the minifilter driver instance stack. Using this callback routine and the PFLT_NORMALIZE_NAME_COMPONENT callback routine, the minifilter driver can provide its own file name information.

To determine which file name format is being requested, call FltGetFileNameFormat on the NameOptions parameter.

Prior to Windows 8, this callback routine is called only for opened file names and short file names. When the filter manager receives a request for a normalized file name, it calls this callback routine to request the opened file name. Then it calls the minifilter driver's PFLT_NORMALIZE_NAME_COMPONENT callback to normalize each component in the file name.

Starting with Windows 8, this callback routine is also called for normalized names. When the filter manager receives a request for a normalized file name, it calls this callback routine with FLT_FILE_NAME_NORMALIZED specified in the NameOptions parameter. If the minifilter returns STATUS_SUCCESS from this callback, the minifilter’s PFLT_NORMALIZE_NAME_COMPONENT callback will not be called. If the minifilter returns a failure code (such as STATUS_NOT_SUPPORTED), the filter manager will call this callback routine again, requesting the opened file name. The filter manager will then call the minifilter driver’s PFLT_NORMALIZE_NAME_COMPONENT callback to normalize each component in the file name.

When this callback routine is invoked, the minifilter driver generates its own file name information, based on the file system's file name information for the file. To get the file system's file name information for a file, call FltGetFileNameInformation, FltGetFileNameInformationUnsafe, or FltGetDestinationFileNameInformation.

For opened file names, the generated file name information should include volume information. For a remote file, it should include share information as well.

The following is an example of an opened file name for a remote file:

\Device\LanManRedirector\MyServer\MyShare\Docume~1\MyUser\My Documents\TestRe~1.txt:stream1

For more information about file name formats, see the reference entries for FLT_FILE_NAME_INFORMATION and FltParseFileNameInformation.

After it generates the file name information, the minifilter driver must call FltCheckAndGrowNameControl to check whether the FLT_NAME_CONTROL structure that the FileName parameter points to contains a name buffer that is large enough to hold the generated file name. If the name buffer is too small, FltCheckAndGrowNameControl replaces it with a larger one. The minifilter driver then stores the file name information into the name buffer and returns.

Requirements

Requirement	Value
Target Platform	Desktop
Header	fltkernel.h (include Fltkernel.h)
IRQL	PASSIVE_LEVEL