PFLT_NORMALIZE_NAME_COMPONENT_EX 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_NORMALIZE_NAME_COMPONENT_EX as the minifilter driver's NormalizeNameComponentExCallback callback routine.

Syntax

PFLT_NORMALIZE_NAME_COMPONENT_EX PfltNormalizeNameComponentEx;

NTSTATUS PfltNormalizeNameComponentEx(
  [in]      PFLT_INSTANCE Instance,
  [in]      PFILE_OBJECT FileObject,
  [in]      PCUNICODE_STRING ParentDirectory,
  [in]      USHORT VolumeNameLength,
  [in]      PCUNICODE_STRING Component,
  [out]     PFILE_NAMES_INFORMATION ExpandComponentName,
  [in]      ULONG ExpandComponentNameLength,
  [in]      FLT_NORMALIZE_NAME_FLAGS Flags,
  [in, out] PVOID *NormalizationContext
)
{...}

Parameters

[in] Instance

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

[in] FileObject

Pointer to the file object for the file whose name is being requested or the file that is the target of the IRP_MJ_SET_INFORMATION operation if the FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME flag is set. See the Flags parameter below for more information.

[in] ParentDirectory

Pointer to a UNICODE_STRING structure that contains the name of the parent directory for this name component.

[in] VolumeNameLength

Length, in bytes, of the parent directory name that is stored in the structure that the ParentDirectory parameter points to.

[in] Component

Pointer to a UNICODE_STRING structure that contains the name component to be expanded.

[out] ExpandComponentName

Pointer to a FILE_NAMES_INFORMATION structure that receives the expanded (normalized) file name information for the name component.

[in] ExpandComponentNameLength

Length, in bytes, of the buffer that the ExpandComponentName parameter points to.

[in] Flags

Name normalization flags. FLTFL_NORMALIZE_NAME_CASE_SENSITIVE specifies that the name to be normalized is case-sensitive. FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME specifies that the callback routine has been called to service an FltGetDestinationFileNameInformation routine call. If the FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME flag is set, FileObject represents the file/directory that is the target of the IRP_MJ_SET_INFORMATION operation. If the FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME flag is not set, FileObject represents the file/directory whose name is being requested.

[in, out] NormalizationContext

Pointer to minifilter driver-provided context information to be passed in any subsequent calls to this callback routine that are made to normalize the remaining components in the same file name path.

Return value

This callback routine returns STATUS_SUCCESS or an appropriate NTSTATUS value. If the name component that the Component parameter specifies does not exist in the parent directory that the ParentDirectory parameter specifies, this callback routine should return STATUS_NO_SUCH_FILE. If this callback routine issues an IRP_MN_QUERY_DIRECTORY (FileNamesInformation) request to the parent directory, the file system returns the correct status code. In this situation, this callback can simply return the status code that the file system returns.

Remarks

The principal difference between the NormalizeNameComponentExCallback callback routine and the NormalizeNameComponentCallback callback routine (of type PFLT_NORMALIZE_NAME_COMPONENT) is that the NormalizeNameComponentExCallback callback routine supports the additional FileObject parameter. The file object (FileObject) can be used by the minifilter driver to retrieve the TXN_PARAMETER_BLOCK structure for the operation that the file/directory is participating in by calling the IoGetTransactionParameterBlock routine. The TXN_PARAMETER_BLOCK structure can be used by the minifilter driver to issue its own create requests in the context of the transaction that this file object is participating in.

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

The filter manager calls this callback routine to query the minifilter driver for the normalized names for components in the file name path whose names the minifilter driver has modified. If the file name path contains more than one such component, the filter manager can call this callback routine multiple times in the process of normalizing all the components in the path. The minifilter driver can use the NormalizationContext parameter to pass context information to subsequent calls to this callback routine.

If the minifilter driver uses the NormalizationContext parameter, it should also register a normalization context cleanup callback routine. For more information, see the reference entry for PFLT_NORMALIZE_CONTEXT_CLEANUP.

Requirements

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