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

[in] FileObject

Pointeur vers un objet file pour le fichier dont le nom est demandé.

[in, optional] CallbackData

Pointeur vers la structure de données de rappel pour l’opération au cours de laquelle ce nom est demandé. Ce paramètre a la valeur 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 sur TRUE à la sortie si le nom peut être mis en cache ; définissez sur FALSE dans le cas contraire.

[out] FileName

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

Valeur retournée

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 transmet en tant que paramètre à FltRegisterFilter.

Le gestionnaire de filtres 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 dans la pile instance pilote minifilter. À l’aide de cette routine de rappel et de la PFLT_NORMALIZE_NAME_COMPONENT routine de rappel, 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ée 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 minifiltre retourne un code d’échec (tel que STATUS_NOT_SUPPORTED), le gestionnaire de filtres appelle à nouveau cette routine de rappel, en 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 du système de fichiers pour un fichier, appelez FltGetFileNameInformation, FltGetFileNameInformationUnsafe ou 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.

Une fois qu’il a généré les informations de nom de fichier, le pilote minifilter doit appeler FltCheckAndGrowNameControl pour case activée si la structure FLT_NAME_CONTROL vers laquelle le paramètre FileName pointe contient 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 noms et retourne.