PFLT_GENERATE_FILE_NAME

PFLT_GENERATE_FILE_NAME routine

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 GenerateFileNameCallback;

NTSTATUS GenerateFileNameCallback(
  _In_     PFLT_INSTANCE         Instance,
  _In_     PFILE_OBJECT          FileObject,
  _In_opt_ PFLT_CALLBACK_DATA    CallbackData,
  _In_     FLT_FILE_NAME_OPTIONS NameOptions,
  _Out_    PBOOLEAN              CacheFileNameInformation,
  _Out_    PFLT_NAME_CONTROL     FileName
)
{ ... }

Parameters

Instance [in]

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

FileObject [in]

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

CallbackData [in, optional]

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.

NameOptions [in]

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

CacheFileNameInformation [out]

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.

FileName [out]

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

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.

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

Target platform

Header

Fltkernel.h (include Fltkernel.h)

IRQL

PASSIVE_LEVEL

See also

FLT_CALLBACK_DATA
FLT_FILE_NAME_INFORMATION
FLT_FILE_NAME_OPTIONS
FLT_NAME_CONTROL
FLT_REGISTRATION
FltCheckAndGrowNameControl
FltGetDestinationFileNameInformation
FltGetFileNameFormat
FltGetFileNameInformation
FltGetFileNameInformationUnsafe
FltGetFileNameQueryMethod
FltParseFileName
FltParseFileNameInformation
FltPurgeFileNameInformationCache
FltRegisterFilter
PFLT_NORMALIZE_CONTEXT_CLEANUP
PFLT_NORMALIZE_NAME_COMPONENT
PFLT_NORMALIZE_NAME_COMPONENT_EX

 

 

Send comments about this topic to Microsoft

Show:
© 2016 Microsoft