PFLT_NORMALIZE_NAME_COMPONENT callback function (fltkernel.h)

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

Syntax

PFLT_NORMALIZE_NAME_COMPONENT PfltNormalizeNameComponent;

NTSTATUS PfltNormalizeNameComponent(
  [in]      PFLT_INSTANCE Instance,
  [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] 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 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 a FltGetDestinationFileNameInformation routine call.

[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

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

To register this callback routine, the minifilter driver stores the address of a routine of type PFLT_NORMALIZE_NAME_COMPONENT in the NormalizeNameComponentCallback 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

See also

FILE_NAMES_INFORMATION

FLT_REGISTRATION

FltRegisterFilter

PFLT_GENERATE_FILE_NAME

PFLT_NORMALIZE_CONTEXT_CLEANUP

PFLT_NORMALIZE_NAME_COMPONENT_EX

UNICODE_STRING