Fonction FltGetFileNameInformation (fltkernel.h)

Article
08/07/2023

La routine FltGetFileNameInformation retourne les informations de nom d’un fichier ou d’un répertoire.

Syntaxe

NTSTATUS FLTAPI FltGetFileNameInformation(
  [in]  PFLT_CALLBACK_DATA         CallbackData,
  [in]  FLT_FILE_NAME_OPTIONS      NameOptions,
  [out] PFLT_FILE_NAME_INFORMATION *FileNameInformation
);

Paramètres

[in] CallbackData

Pointeur vers une structure FLT_CALLBACK_DATA , qui est la structure de données de rappel pour l’opération d’E/S. Ce paramètre est obligatoire et ne peut pas avoir la valeur NULL.

[in] NameOptions

Valeur FLT_FILE_NAME_OPTIONS contenant des indicateurs qui spécifient le format des informations de nom à retourner, ainsi que la méthode de requête que le Gestionnaire de filtres doit utiliser. L’appelant doit inclure un indicateur de format de nom et un indicateur de méthode de requête. Des indicateurs supplémentaires peuvent être utilisés par les pilotes de minifiltre du fournisseur de noms pour spécifier les options de requête de nom. Ce paramètre est obligatoire et ne peut pas avoir la valeur NULL.

Voici les valeurs d’indicateur de format de nom de fichier. Un seul des indicateurs suivants peut être spécifié. Pour obtenir une explication de ces formats, consultez FLT_FILE_NAME_INFORMATION.

Valeur de l’indicateur de format de nom	Signification
FLT_FILE_NAME_NORMALIZED	Le paramètre FileNameInformation reçoit l’adresse d’une structure contenant le nom normalisé du fichier.
FLT_FILE_NAME_OPENED	Le paramètre FileNameInformation reçoit l’adresse d’une structure contenant le nom utilisé lors de l’ouverture du fichier.
FLT_FILE_NAME_SHORT	Le paramètre FileNameInformation reçoit l’adresse d’une structure contenant le nom court (8.3) du fichier. Le nom court se compose d’un maximum de 8 caractères, suivi immédiatement d’un point et de 3 caractères supplémentaires. Le nom court d’un fichier n’inclut pas le nom du volume, le chemin du répertoire ou le nom du flux. Non valide dans le chemin de précréer.

Voici les valeurs d’indicateur de méthode de requête de nom de fichier. Un seul des indicateurs suivants peut être spécifié.

Valeur de l’indicateur de méthode de requête	Signification
FLT_FILE_NAME_QUERY_DEFAULT	S’il n’est pas actuellement sûr d’interroger le système de fichiers pour le nom de fichier, FltGetFileNameInformation ne fait rien. Sinon, FltGetFileNameInformation interroge le cache de noms du Gestionnaire de filtres pour obtenir les informations de nom de fichier. Si le nom est introuvable dans le cache, FltGetFileNameInformation interroge le système de fichiers et met en cache le résultat.
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetFileNameInformation interroge le cache de noms du Gestionnaire de filtres pour les informations de nom de fichier. FltGetFileNameInformation n’interroge pas le système de fichiers.
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetFileNameInformation interroge le système de fichiers pour obtenir les informations de nom de fichier. FltGetFileNameInformation n’interroge pas le cache de noms du Gestionnaire de filtres et ne met pas en cache le résultat de la requête du système de fichiers.
FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP	FltGetFileNameInformation interroge le cache de noms du Gestionnaire de filtres pour les informations de nom de fichier. Si le nom est introuvable dans le cache et qu’il est actuellement sûr de le faire, FltGetFileNameInformation interroge le système de fichiers pour obtenir les informations de nom de fichier et met en cache le résultat.

Les minifiltres du fournisseur de noms utilisent les indicateurs suivants pour spécifier les propriétés des opérations de nom de fichier.

Valeur de l’indicateur de fournisseur de noms	Signification
FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER	Un minifiltre de fournisseur de noms peut utiliser cet indicateur pour spécifier qu’une demande de requête de nom doit être redirigée vers elle-même (le minifiltre du fournisseur de noms) plutôt que d’être satisfaite par les fournisseurs de noms inférieurs dans la pile.
FLT_FILE_NAME_DO_NOT_CACHE	Cet indicateur indique que le nom récupéré à partir de cette requête ne doit pas être mis en cache. Les minifiltres du fournisseur de noms utilisent cet indicateur quand ils exécutent des requêtes intermédiaires pour générer un nom.
FLT_FILE_NAME_ALLOW_QUERY_ON_REPARSE	Un minifiltre de fournisseur de noms peut utiliser cet indicateur pour spécifier qu’il est sûr d’interroger le nom dans le chemin d’accès post-création, même si STATUS_REPARSE a été retourné. Il incombe à l’appelant de s’assurer que le champ FileObject-FileName> n’a pas été modifié. N’utilisez pas cet indicateur avec des points de montage ou des points d’analyse de liaison symbolique.

[out] FileNameInformation

Pointeur vers une variable allouée par l’appelant qui reçoit l’adresse d’une structure de FLT_FILE_NAME_INFORMATION allouée par le système contenant les informations de nom de fichier. FltGetFileNameInformation alloue cette structure à partir d’un pool paginé. Ce paramètre est obligatoire et ne peut pas avoir la valeur NULL.

Valeur retournée

Si les informations de nom sont correctement retournées, FltGetFileNameInformation retourne STATUS_SUCCESS. Sinon, il retourne une valeur NTSTATUS appropriée telle que l’une des valeurs suivantes :

Code de retour	Description
STATUS_FLT_INVALID_NAME_REQUEST	FltGetFileNameInformation ne peut pas obtenir les informations de nom de fichier dans l’une des circonstances suivantes si la requête ne peut pas être satisfaite à partir du cache de noms du Gestionnaire de filtres : Dans le chemin d’E/S de pagination. Lorsque le champ TopLevelIrp du thread actuel n’est pas NULL, car la récursivité du système de fichiers résultante peut provoquer des interblocages ou des dépassements de pile. (Pour plus d’informations sur ce problème, consultez IoGetTopLevelIrp.) Une fois l’opération de IRP_MJ_CLEANUP terminée ; autrement dit, dans le chemin d’accès post-propre, pré-fermeture ou post-fermeture (l’objet de fichier cible a l’indicateur FO_CLEANUP_COMPLETE défini). Dans une routine de rappel de préopération (PFLT_PRE_OPERATION_CALLBACK) ou de post-opération (PFLT_POST_OPERATION_CALLBACK) pour l’une des opérations suivantes : IRP_MJ_ACQUIRE_FOR_CC_FLUSH IRP_MJ_ACQUIRE_FOR_MOD_WRITE IRP_MJ_RELEASE_FOR_CC_FLUSH IRP_MJ_RELEASE_FOR_MOD_WRITE IRP_MJ_RELEASE_FOR_SECTION_SYNCHRONIZATION Dans une routine de rappel post-opération pour IRP_MJ_ACQUIRE_FOR_SECTION_SYNCHRONIZATION. Lorsque tous les API sont désactivés ; autrement dit, lorsque KeAreAllApcsDisabled retourne TRUE. FltGetFileNameInformation ne peut pas obtenir le nom court d’un fichier dans le chemin de précréation. STATUS_FLT_INVALID_NAME_REQUEST est un code d’erreur.
STATUS_INSUFFICIENT_RESOURCES	FltGetFileNameInformation a rencontré un échec d’allocation de pool. Il s’agit d’un code d’erreur.
STATUS_INVALID_PARAMETER	Retourné lorsqu’un paramètre non valide est passé, tel que l’un des éléments suivants : Le paramètre FileNameInformation ne peut pas être NULL. Le paramètre CallbackData ne peut pas être NULL. STATUS_INVALID_PARAMETER est un code d’erreur.
STATUS_FLT_NAME_CACHE_MISS	Les informations de nom de fichier sont introuvables dans le cache de noms et NameOptions inclut FLT_FILE_NAME_QUERY_CACHE_ONLY. -ou- Les informations de nom de fichier sont introuvables dans le cache de noms lorsque NameOptions inclut FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP et que les informations de nom de fichier ne peuvent pas être interrogées à partir du système de fichiers. Un appel supplémentaire à FltGetFileNameInformation avec FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY défini dans NameOptions peut retourner les informations de nom de fichier.
STATUS_NOT_SAME_DEVICE	Le fichier interrogé lors de la pré-création se trouve sur un volume différent de son répertoire parent. Cette erreur est retournée pour les requêtes de nom normalisées, où le fichier était une jonction ou un symlink qui a été résolu en un autre volume.
STATUS_ACCESS_DENIED	Si l’utilisateur a ouvert le fichier par ID de fichier mais ne dispose pas de privilèges de traversée pour l’ensemble du chemin d’accès, FltGetFileNameInformation échoue avec cette valeur de retour. STATUS_ACCESS_DENIED est un code d’erreur. -ou- Le fichier est un fichier système avec tout accès refusé.

Remarques

FltGetFileNameInformation retourne les informations de nom demandées pour le fichier ou le répertoire qui est la cible de l’opération décrite par CallbackData, dans le format spécifié. Le fichier ou le répertoire n’a pas encore besoin d’être ouvert par le système de fichiers.

Pour une opération de précréation, si le membre CallbackData-Iopb-OperationFlags>> contient l’indicateur SL_OPEN_TARGET_DIRECTORY au niveau du bit, FltGetFileNameInformation retourne le nom du répertoire contenant (parent) pour le fichier donné. Ce nom est le chemin d’accès réel que l’opération de création ouvre.

Pour analyser le contenu de la structure FLT_FILE_NAME_INFORMATION retournée par FltGetFileNameInformation, appelez FltParseFileNameInformation. (Pour plus d’informations sur les formats de nom de fichier, consultez FLT_FILE_NAME_INFORMATION.)

Après un appel réussi à FltGetFileNameInformation, l’appelant est chargé de libérer le pointeur retourné dans le paramètre FileNameInformation lorsque le pointeur n’est plus nécessaire. Pour ce faire, l’appelant appelle FltReleaseFileNameInformation.

L’appelant ne doit pas modifier le contenu de la structure retournée dans le paramètre FileNameInformation , car cette structure est mise en cache par le Gestionnaire de filtres afin que tous les pilotes minifilter puissent l’utiliser.

Si FltGetFileNameInformation est appelé dans la routine de rappel de préopération pour une opération de création afin de récupérer le nom ouvert, FltGetFileNameInformation réussit même si le chemin d’accès au fichier en cours d’ouverture n’existe pas sur le volume.

Si FltGetFileNameInformation est appelé dans la routine de rappel de préopération pour une opération de création afin de récupérer le nom normalisé, FltGetFileNameInformation réussit même si le composant final du chemin d’accès au fichier ouvert n’existe pas sur le volume.

Notes

La prise en charge de SMB (Server Message Block) pour l’interrogation de noms de fichiers normalisés sur un volume distant varie selon les versions Windows 10. Pour plus d’informations, consultez le protocole MS-SMB2 .

Dans les opérations de création, de liaison matérielle et de renommage, le tunneling de noms de fichier peut entraîner l’invalidation du composant final dans les informations de nom de fichier normalisées qu’un pilote minifilter récupère dans une routine de rappel de préopération. Si un pilote minifilter récupère des informations de nom de fichier normalisées dans une routine de rappel de préopération (PFLT_PRE_OPERATION_CALLBACK) en appelant une routine telle que FltGetFileNameInformation, il doit appeler FltGetTunneledName à partir de sa routine de rappel postopération (PFLT_POST_OPERATION_CALLBACK) pour récupérer les informations de nom de fichier correctes pour le fichier.

Pour Windows 8.1 et versions antérieures, FltGetFileNameInformation peut inclure un type de fluxuniquement lorsqu’il est appelé à partir du rappel de précréation d’un filtre. Pour faire la distinction entre le flux par défaut d’un fichier et les flux de métadonnées, cet appel doit être effectué dans l’opération de précréer. Le type de flux résultant reste valide pendant toute la durée de vie du fichier.

Avant Windows 8, le Gestionnaire de filtres obtenait le nom normalisé d’un fichier ou d’un répertoire en collectant les informations de nom pour chaque composant du chemin d’accès du fichier. Pour cela, plusieurs requêtes ont été effectuées sur le système de fichiers pour compiler le chemin d’accès complet. À compter de Windows 8, les systèmes de fichiers locaux prennent en charge la classe d’informations de fichier FileNormalizedNameInformation et une seule requête est nécessaire pour obtenir le nom normalisé. Les systèmes de fichiers distants peuvent ne pas prendre en charge la classe d’informations de fichier FileNormalizedNameInformation . Dans ce cas, une requête pour chaque composant du chemin d’accès au fichier est toujours nécessaire pour assembler le nom normalisé. Dans certaines conditions réseau, une requête de nom complet peut nécessiter beaucoup de temps.

Pour plus d’informations sur les informations de nom de fichier normalisé, consultez FLT_FILE_NAME_INFORMATION.

Notes

Le tunneling de nom de fichier affecte uniquement les opérations de création, de liaison matérielle et de renommage de cette façon. Elle n’affecte pas les autres opérations d’E/S, telles que la lecture et l’écriture.

Les opérations appairées suivantes peuvent entraîner le tunneling du nom de fichier :

delete (name)/create(name)
delete (name)/rename(source, name)
rename (name, newname)/create(name)
rename (name, newname)/rename(source,name)

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	fltkernel.h (inclure Fltkernel.h)
Bibliothèque	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL (voir La valeur de retour)