Fonction FltGetTunneledName (fltkernel.h)

Article
02/26/2024

La routine FltGetTunneledName récupère le nom tunnelé d’un fichier, compte tenu du nom normalisé retourné pour le fichier par un appel précédent à FltGetFileNameInformation, FltGetFileNameInformationUnsafe ou FltGetDestinationFileNameInformationInformation.

Syntaxe

NTSTATUS FLTAPI FltGetTunneledName(
  [in]  PFLT_CALLBACK_DATA         CallbackData,
  [in]  PFLT_FILE_NAME_INFORMATION FileNameInformation,
  [out] PFLT_FILE_NAME_INFORMATION *RetTunneledFileNameInformation
);

Paramètres

[in] CallbackData

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

[in] FileNameInformation

Pointeur vers une structure FLT_FILE_NAME_INFORMATION contenant des informations de nom normalisées retournées par un appel précédent à FltGetFileNameInformation, FltGetFileNameInformationUnsafe ou FltGetDestinationFileNameInformation pour le fichier.

[out] RetTunneledFileNameInformation

Pointeur vers une variable allouée par l’appelant qui reçoit l’adresse d’une structure nouvellement allouée contenant le nom de fichier tunnelisé. Si aucun nom tunnelé n’est trouvé, cette variable reçoit NULL. Ce paramètre est obligatoire et ne peut pas être NULL en entrée.

Valeur retournée

FltGetTunneledName retourne STATUS_SUCCESS si le nom tunnelisé est trouvé ou s’il n’existe aucun nom tunnelé pour le fichier. Sinon, il retourne une valeur NTSTATUS, telle que :

Code de retour	Description
STATUS_INSUFFICIENT_RESOURCES	FltGetTunneledName a rencontré un échec d’allocation de pool. Il s’agit d’un code d’erreur.

Remarques

Les systèmes de fichiers, tels que NTFS et FAT, utilisent un cache tunnel par volume pour conserver brièvement les noms de fichiers et autres métadonnées pour les fichiers qui sont renommés, liés à ou supprimés. Le tunneling de nom de fichier peut entraîner l’invalidation du composant final dans les informations de nom de fichier normalisées retournées par un appel de préopération à FltGetFileNameInformation, FltGetFileNameInformationUnsafe ou FltGetDestinationFileNameInformation .

Si un pilote de minifiltre récupère des informations de nom de fichier normalisées dans la routine de rappel de préopération (PFLT_PRE_OPERATION_CALLBACK) pour une création (IRP_MJ_CREATE), un lien physique (IRP_MJ_SET_INFORMATION avec FILE_INFORMATION_CLASS défini sur FileRenameInformation) ou une opération de renommage (IRP_MJ_SET_INFORMATION avec FILE_INFORMATION_CLASS défini sur FileLinkInformation), il doit appeler FltGetTunneledName à partir de sa routine de rappel de post-opération (PFLT_POST_OPERATION_CALLBACK) pour récupérer les informations de nom de fichier appropriées pour le fichier.

Seules les informations de nom de fichier normalisées sont affectées par le tunneling. Le Gestionnaire de filtres ne peut pas garantir que le composant final est normalisé tant que l’opération de création, de liaison matérielle ou de renommage ne s’est pas réellement produite, car le tunneling peut entraîner la modification d’un nom court en nom long. Par conséquent, un pilote de minifiltre doit appeler FltGetTunneledName à partir de sa routine de rappel post-opération pour déterminer si les informations de nom de fichier normalisées récupérées dans la routine de rappel de préopération sont valides.

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

Les pilotes de minifiltre qui récupèrent uniquement des informations de nom de fichier court ou ouvert ne doivent pas appeler FltGetTunneledName.

Après avoir appelé FltGetFileNameInformation, FltGetFileNameInformationUnsafe ou FltGetDestinationFileNameInformation dans la routine de rappel de préopération, le pilote de minifiltre doit stocker le pointeur FileNameInformation retourné dans la structure CompletionContext de la routine de rappel de préopération afin que le rappel postopératoire puisse passer ce pointeur dans le paramètre FileNameInformation à FltGetTunneledName.

Notes

Le tunneling de noms de fichiers affecte uniquement les opérations de création, de liaison matérielle et de renommage de cette manière. Elle n’affecte pas d’autres opérations d’E/S, telles que la lecture et l’écriture.

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

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

Si aucun nom tunnelé n’est trouvé pour le fichier, le paramètre RetTunneledFileNameInformation reçoit NULL.

Après un appel réussi à FltGetTunneledName, l’appelant est responsable de libérer les pointeurs RetTunneledFileNameInformation et FileNameInformation lorsqu’ils ne sont plus nécessaires en appelant FltReleaseFileNameInformation.

FltGetTunneledName ne doit être appelé qu’à partir de la routine de rappel post-opération d’un pilote minifiltre pour IRP_MJ_CREATE ou IRP_MJ_SET_INFORMATION. L’appel de FltGetTunneledName à partir d’une routine de rappel post-opération pour tout autre type d’opération d’E/S, ou son appel à partir d’une routine de rappel de préopération, est une erreur de programmation.

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

Le tunneling de fichiers permet la compatibilité avec les programmes qui s’appuient sur des systèmes de fichiers pour conserver les méta-informations de fichier pendant une courte période ; par exemple, pour le processus d’enregistrement sécurisé. Le tunneling conserve l’association entre le nom long et le nom court (8.3) d’un fichier. Lorsqu’un nom de fichier est supprimé d’un répertoire (renommage ou suppression), sa paire de noms court et long et son temps de création sont enregistrés dans un cache de tunnel, clé par le nom qui a été supprimé. Lorsqu’un nom est ajouté à un répertoire (renommage ou création), le cache est recherché pour déterminer s’il existe des informations à restaurer. Le cache est effectif par instance d’un répertoire. Si un répertoire est supprimé, son cache est supprimé.