PFLT_NORMALIZE_NAME_COMPONENT_EX fonction de rappel (fltkernel.h)

Article
02/06/2025

Un pilote minifilter qui fournit des noms de fichiers pour le cache de noms du gestionnaire de filtres peut inscrire une routine de type PFLT_NORMALIZE_NAME_COMPONENT_EX en tant que routine de rappel NormalizeNameComponentExCallback routine de rappel.

Syntaxe

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
)
{...}

Paramètres

[in] Instance

Pointeur d’instance opaque pour l’instance de pilote minifilter pour laquelle cette routine de rappel est inscrite.

[in] FileObject

Pointeur vers l’objet de fichier du fichier dont le nom est demandé ou le fichier qui est la cible de l’opération de IRP_MJ_SET_INFORMATION si l’indicateur de FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME est défini. Pour plus d’informations, consultez le paramètre indicateurs ci-dessous.

[in] ParentDirectory

Pointeur vers une structure UNICODE_STRING qui contient le nom du répertoire parent pour ce composant de nom.

[in] VolumeNameLength

Longueur, en octets, du nom du répertoire parent stocké dans la structure vers laquelle pointe le paramètre ParentDirectory.

[in] Component

Pointeur vers une structure UNICODE_STRING qui contient le composant de nom à développer.

[out] ExpandComponentName

Pointeur vers une structure FILE_NAMES_INFORMATION qui reçoit les informations de nom de fichier développées (normalisées) pour le composant name.

[in] ExpandComponentNameLength

Longueur, en octets, de la mémoire tampon vers laquelle pointe le paramètre ExpandComponentName.

[in] Flags

Indicateurs de normalisation de nom. FLTFL_NORMALIZE_NAME_CASE_SENSITIVE spécifie que le nom à normaliser respecte la casse. FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME spécifie que la routine de rappel a été appelée pour traiter un appel de routine FltGetDestinationFileNameInformation. Si l’indicateur FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME est défini, FileObject représente le fichier/répertoire qui est la cible de l’opération de IRP_MJ_SET_INFORMATION. Si l’indicateur FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME n’est pas défini, FileObject représente le fichier/répertoire dont le nom est demandé.

[in, out] NormalizationContext

Pointeur vers les informations de contexte fournies par le pilote minifilter à transmettre dans tous les appels suivants à cette routine de rappel qui sont effectuées pour normaliser les composants restants dans le même chemin de nom de fichier.

Valeur de retour

Cette routine de rappel retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée. Si le composant de nom spécifié par le paramètre composant n’existe pas dans le répertoire parent que le paramètre ParentDirectory spécifie, cette routine de rappel doit retourner STATUS_NO_SUCH_FILE. Si cette routine de rappel émet une requête IRP_MN_QUERY_DIRECTORY (FileNamesInformation) dans le répertoire parent, le système de fichiers retourne le code d’état correct. Dans ce cas, ce rappel peut simplement retourner le code d’état retourné par le système de fichiers.

Remarques

La différence principale entre la routine de rappel NormalizeNameComponentExCallback et la routine de rappel NormalizeNameComponentCallback routine de rappel (de type PFLT_NORMALIZE_NAME_COMPONENT) est que la routine de rappel NormalizeNameComponentExCallback prend en charge le paramètre FileObject supplémentaire. L’objet fichier (FileObject) peut être utilisé par le pilote minifilter pour récupérer la structure TXN_PARAMETER_BLOCK pour l’opération dans laquelle le fichier/répertoire participe en appelant la routine IoGetTransactionParameterBlock. La structure TXN_PARAMETER_BLOCK peut être utilisée par le pilote minifilter pour émettre ses propres demandes de création dans le contexte de la transaction dans laquelle cet objet de fichier participe.

Pour inscrire cette routine de rappel, le pilote minifilter stocke l’adresse d’une routine de type PFLT_NORMALIZE_NAME_COMPONENT_EX dans la NormalizeNameComponentExCallback membre de la structure FLT_REGISTRATION que le pilote minifilter passe en tant que paramètre pour FltRegisterFilter.

Le gestionnaire de filtre appelle cette routine de rappel pour interroger le pilote minifilter pour les noms normalisés des composants dans le chemin d’accès du nom de fichier dont le nom du pilote minifilter a été modifié. Si le chemin d’accès au nom de fichier contient plusieurs composants de ce type, le gestionnaire de filtres peut appeler cette routine de rappel plusieurs fois dans le processus de normalisation de tous les composants du chemin d’accès. Le pilote minifilter peut utiliser le paramètre NormalizationContext pour transmettre des informations de contexte aux appels suivants à cette routine de rappel.

Si le pilote minifilter utilise le paramètre NormalizationContext, il doit également inscrire une routine de rappel de nettoyage du contexte de normalisation. Pour plus d’informations, consultez l’entrée de référence pour PFLT_NORMALIZE_CONTEXT_CLEANUP.