PFLT_GENERATE_FILE_NAME 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_GENERATE_FILE_NAME en tant que routine GenerateFileNameCallback du pilote minifilter.

Syntaxe

PFLT_GENERATE_FILE_NAME PfltGenerateFileName;

NTSTATUS PfltGenerateFileName(
  [in]           PFLT_INSTANCE Instance,
  [in]           PFILE_OBJECT FileObject,
  [in, optional] PFLT_CALLBACK_DATA CallbackData,
  [in]           FLT_FILE_NAME_OPTIONS NameOptions,
  [out]          PBOOLEAN CacheFileNameInformation,
  [out]          PFLT_NAME_CONTROL FileName
)
{...}

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 un objet de fichier pour le fichier dont le nom est demandé.

[in, optional] CallbackData

Pointeur vers la structure de données de rappel pour l’opération pendant laquelle ce nom est demandé. Ce paramètre est NULL lorsque FltGetFileNameInformationUnsafe est appelé pour récupérer le nom du fichier.

[in] NameOptions

FLT_FILE_NAME_OPTIONS valeur qui spécifie le format de nom, la méthode de requête et les indicateurs pour cette requête d’informations de nom de fichier.

[out] CacheFileNameInformation

Pointeur vers une valeur booléenne spécifiant si ce nom peut être mis en cache. Définissez la valeur TRUE en sortie si le nom peut être mis en cache ; défini sur FALSE sinon.

[out] FileName

Pointeur vers une structure FLT_NAME_CONTROL allouée par le gestionnaire de filtres pour recevoir le nom de fichier en sortie.

Valeur de retour

Cette routine de rappel retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée.

Remarques

Pour inscrire cette routine de rappel, le pilote minifilter stocke l’adresse d’une routine de type PFLT_GENERATE_FILE_NAME dans le membre GenerateFileNameCallback 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 permettre au pilote minifilter d’intercepter les demandes de nom de fichier par d’autres pilotes minifilter au-dessus de celle-ci dans la pile d’instances de pilote minifilter. À l’aide de cette routine de rappel et de la routine de rappel PFLT_NORMALIZE_NAME_COMPONENT, le pilote minifilter peut fournir ses propres informations de nom de fichier.

Pour déterminer le format de nom de fichier demandé, appelez FltGetFileNameFormat sur le paramètre NameOptions.

Avant Windows 8, cette routine de rappel est appelée uniquement pour les noms de fichiers ouverts et les noms de fichiers courts. Lorsque le gestionnaire de filtres reçoit une demande de nom de fichier normalisé, il appelle cette routine de rappel pour demander le nom de fichier ouvert. Ensuite, il appelle le rappel PFLT_NORMALIZE_NAME_COMPONENT du pilote minifilter pour normaliser chaque composant dans le nom de fichier.

À compter de Windows 8, cette routine de rappel est également appelée pour les noms normalisés. Lorsque le gestionnaire de filtres reçoit une demande de nom de fichier normalisé, il appelle cette routine de rappel avec FLT_FILE_NAME_NORMALIZED spécifié dans le paramètre NameOptions. Si le minifilter retourne STATUS_SUCCESS à partir de ce rappel, le rappel PFLT_NORMALIZE_NAME_COMPONENT du minifilter ne sera pas appelé. Si le minifilter retourne un code d’échec (par exemple, STATUS_NOT_SUPPORTED), le gestionnaire de filtres appelle à nouveau cette routine de rappel, demandant le nom du fichier ouvert. Le gestionnaire de filtres appelle ensuite le rappel PFLT_NORMALIZE_NAME_COMPONENT du pilote minifilter pour normaliser chaque composant dans le nom de fichier.

Lorsque cette routine de rappel est appelée, le pilote minifilter génère ses propres informations de nom de fichier, en fonction des informations de nom de fichier du système de fichiers pour le fichier. Pour obtenir les informations de nom de fichier d’un système de fichiers, appelez FltGetFileNameInformation, FltGetFileNameInformationUnsafeou FltGetDestinationFileNameInformation.

Pour les noms de fichiers ouverts, les informations de nom de fichier générées doivent inclure des informations de volume. Pour un fichier distant, il doit également inclure des informations de partage.

Voici un exemple de nom de fichier ouvert pour un fichier distant :

\Device\LanManRedirector\MyServer\MyShare\Docume~1\MyUser\My Documents\TestRe~1.txt:stream1

Pour plus d’informations sur les formats de nom de fichier, consultez les entrées de référence pour FLT_FILE_NAME_INFORMATION et FltParseFileNameInformation.

Après avoir généré les informations de nom de fichier, le pilote minifilter doit appeler FltCheckAndGrowNameControl pour vérifier si la structure FLT_NAME_CONTROL que le paramètre FileName pointe pour contenir une mémoire tampon de nom suffisamment grande pour contenir le nom de fichier généré. Si la mémoire tampon de nom est trop petite, FltCheckAndGrowNameControl la remplace par une mémoire tampon plus grande. Le pilote minifilter stocke ensuite les informations de nom de fichier dans la mémoire tampon de nom et retourne.