PFLT_NORMALIZE_NAME_COMPONENT_EX fonction de rappel (fltkernel.h)

Article
08/07/2023

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 du pilote minifilter.

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 de instance opaque pour le pilote minifilter instance pour lequel cette routine de rappel est inscrite.

[in] FileObject

Pointeur vers l’objet file pour le fichier dont le nom est demandé ou le fichier qui est la cible de l’opération IRP_MJ_SET_INFORMATION si l’indicateur FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME est défini. Pour plus d’informations, consultez le paramètre Flags 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 name à développer.

[out] ExpandComponentName

Pointeur vers une structure de FILE_NAMES_INFORMATION qui reçoit les informations de nom de fichier développé (normalisé) 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 à passer dans tous les appels ultérieurs à cette routine de rappel qui sont effectués pour normaliser les composants restants dans le même chemin de nom de fichier.

Valeur retournée

Cette routine de rappel retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée. Si le composant name spécifié par le paramètre Component n’existe pas dans le répertoire parent spécifié par le paramètre ParentDirectory , 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 de status correct. Dans ce cas, ce rappel peut simplement retourner le code status que le système de fichiers retourne.

Remarques

La principale différence entre la routine de rappel NormalizeNameComponentExCallback et la routine de rappel NormalizeNameComponentCallback (de type PFLT_NORMALIZE_NAME_COMPONENT) est que la routine de rappel NormalizeNameComponentExCallback prend en charge le paramètre FileObject supplémentaire. L’objet file (FileObject) peut être utilisé par le pilote minifilter pour récupérer la structure TXN_PARAMETER_BLOCK de l’opération à 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 à 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 le membre NormalizeNameComponentExCallback de la structure FLT_REGISTRATION que le pilote minifilter transmet en tant que paramètre à FltRegisterFilter.

Le gestionnaire de filtres appelle cette routine de rappel pour interroger le pilote minifilter pour obtenir les noms normalisés des composants dans le chemin d’accès de nom de fichier dont le pilote minifilter a modifié les noms. 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.