FltGetTunneledName, fonction (fltkernel.h)

Article
10/30/2024

La routine FltGetTunneledName récupère le nom tunnelisé d’un fichier, en fonction du nom normalisé renvoyé pour le fichier par un appel précédent à FltGetFileNameInformation, FltGetFileNameInformationUnsafe, ou FltGetDestinationFileNameInformation.

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 être 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 tunnelisé n’est trouvé, cette variable reçoit NULL. Ce paramètre est obligatoire et ne peut pas être NULL lors de l’entrée.

Valeur de retour

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

Retourner le code	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 de tunnel par volume pour conserver brièvement les noms de fichiers et d’autres métadonnées pour les fichiers renommés, liés ou supprimés. Le tunneling de noms de fichier peut entraîner la fin du composant dans les informations de nom de fichier normalisées retournées par un appel de préopération à FltGetFileNameInformation, FltGetFileNameInformationUnsafe, ou FltGetDestinationFileNameInformation à invalider.

Si un pilote minifilter récupère les 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 dur (IRP_MJ_SET_INFORMATION avec FILE_INFORMATION_CLASS défini sur FileLinkInformation) ou une opération de renommage (IRP_MJ_SET_INFORMATION avec FILE_INFORMATION_CLASS défini sur FileRenameInformation), il doit appeler FltGetTunneledName à partir de sa routine de rappel de postopération (PFLT_POST_OPERATION_CALLBACK) pour récupérer les informations de nom de fichier correctes 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 s’assurer que le composant final est normalisé jusqu’à ce que l’opération de création, de liaison en dur ou de renommage ait réellement eu lieu, car le tunneling peut entraîner la modification d’un nom court par un nom long. Par conséquent, un pilote minifilter doit appeler FltGetTunneledName de sa routine de rappel postopératoire 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 les informations sur le nom de fichier normalisé, consultez FLT_FILE_NAME_INFORMATION.

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

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

Note

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

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

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 la publication des RetTunneledFileNameInformation et pointeurs FileNameInformation lorsqu’ils ne sont plus nécessaires en appelant FltReleaseFileNameInformation.

FltGetTunneledName ne doit être appelée qu’à partir d’une routine de rappel de post-opération du pilote minifilter pour IRP_MJ_CREATE ou IRP_MJ_SET_INFORMATION. L’appel FltGetTunneledName à partir d’une routine de rappel de postopération pour tout autre type d’opération d’E/S, ou l’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 minifilter puissent l’utiliser.

Le tunneling de fichiers permet la compatibilité avec les programmes qui s’appuient sur les 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 court (8.3) d’un fichier. Lorsqu’un nom de fichier est supprimé d’un répertoire (renommage ou suppression), sa paire de noms courte et longue et son temps de création sont enregistrés dans un cache de tunnel, clé par le nom 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é.