Fonction FltGetFileNameInformation (fltkernel.h)
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 |
|---|---|
|
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 :
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. |
|
FltGetFileNameInformation a rencontré un échec d’allocation de pool. Il s’agit d’un code d’erreur. |
|
Retourné lorsqu’un paramètre non valide est passé, tel que l’un des éléments suivants :
|
|
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. |
|
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. |
|
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) |
Voir aussi
FltGetDestinationFileNameInformation
FltGetFileNameInformationUnsafe