Fonction FltGetDestinationFileNameInformation (fltkernel.h)

Article
02/26/2024

La routine FltGetDestinationFileNameInformation interroge le nom de fichier du répertoire parent de la destination, puis construit un nom de chemin de destination complet pour un fichier ou un répertoire en cours de renommage ou pour lequel un lien dur NTFS est créé.

Syntaxe

NTSTATUS FLTAPI FltGetDestinationFileNameInformation(
  [in]           PFLT_INSTANCE              Instance,
  [in]           PFILE_OBJECT               FileObject,
  [in, optional] HANDLE                     RootDirectory,
  [in]           PWSTR                      FileName,
  [in]           ULONG                      FileNameLength,
  [in]           FLT_FILE_NAME_OPTIONS      NameOptions,
  [out]          PFLT_FILE_NAME_INFORMATION *RetFileNameInformation
);

Paramètres

[in] Instance

Pointeur de instance opaque pour un pilote minifilter instance attaché au volume où réside le fichier.

[in] FileObject

Pointeur vers l’objet file pour le fichier. Ce paramètre est obligatoire et ne peut pas être NULL.

[in, optional] RootDirectory

Pour les opérations de liaison : Si le lien doit être créé dans le même répertoire que le fichier lié ou si FileName contient le chemin complet du lien à créer, ce paramètre a la valeur NULL. Sinon, il s’agit d’un handle pour le répertoire dans lequel le lien doit être créé.

Pour les opérations de renommage : Si le fichier n’est pas déplacé vers un autre répertoire ou si FileName contient le chemin d’accès complet, ce paramètre est NULL. Sinon, il s’agit d’un handle pour le répertoire où réside le fichier après son renommage.

[in] FileName

Pour les opérations de liaison : Pointeur vers une chaîne de caractères larges contenant le nom à affecter au lien nouvellement créé.

Pour les opérations de renommage : Pointeur vers une chaîne de caractères larges contenant le nouveau nom du fichier.

[in] FileNameLength

Longueur, en octets, de la chaîne de caractères larges vers laquelle FileName pointe.

[in] NameOptions

Valeur FLT_FILE_NAME_OPTIONS contenant des indicateurs qui spécifient le format des informations de nom à retourner, la méthode de requête que le Gestionnaire de filtres doit utiliser et des indicateurs de nom de fichier supplémentaires. Ce paramètre est obligatoire et ne peut pas être NULL.

Voici les valeurs de l’indicateur de format de nom. Un seul indicateur de format de nom peut être spécifié. (Notez que FLT_FILE_NAME_SHORT n’est pas une valeur d’indicateur valide pour ce paramètre.)

Valeur de l’indicateur de format de nom	Signification
FLT_FILE_NAME_NORMALIZED	Le paramètre FileName reçoit le nom de destination normalisé du fichier.
FLT_FILE_NAME_OPENED	Le paramètre FileName reçoit le nom de destination du fichier, en fonction du nom utilisé lors de l’ouverture du fichier. Ce nom de fichier n’est pas normalisé.

Voici les valeurs d’indicateur de méthode de requête. Un seul indicateur de méthode de requête 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 du fichier de destination, FltGetDestinationFileNameInformation ne fait rien. Sinon, FltGetDestinationFileNameInformation interroge le cache de noms du Gestionnaire de filtres pour obtenir les informations de nom de fichier du répertoire parent de la destination, puis ajoute le nom de destination. Si le nom résultant est introuvable dans le cache, FltGetDestinationFileNameInformation interroge le système de fichiers et met en cache le résultat.
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetDestinationFileNameInformation interroge le cache de noms du Gestionnaire de filtres pour obtenir les informations de nom de fichier du répertoire parent de la destination, puis ajoute le nom de destination. Il n’interroge pas le système de fichiers.
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetDestinationFileNameInformation interroge le système de fichiers pour obtenir les informations de nom de fichier du répertoire parent de la destination, puis ajoute le nom de destination. Il 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	FltGetDestinationFileNameInformation interroge le cache de noms du Gestionnaire de filtres pour obtenir les informations de nom de fichier du répertoire parent de la destination, puis ajoute le nom de destination. Si le nom est introuvable dans le cache et qu’il est actuellement sûr de le faire, FltGetDestinationFileNameInformation interroge le système de fichiers pour obtenir les informations de nom de fichier et met en cache le résultat.

Voici les valeurs de l’indicateur de nom de fichier. Toute combinaison de ces indicateurs peut être spécifiée. (Notez que FLT_FILE_NAME_ALLOW_QUERY_ON_REPARSE n’est pas un indicateur pertinent pour ce paramètre, car FltGetDestinationFileNameInformation n’est pas utilisé dans un rappel post-création.)

Valeur de l’indicateur de nom de fichier	Signification
FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER	FltGetDestinationFileNameInformation dirige la demande de nom vers le filtre appelant instance à terminer.
FLT_FILE_NAME_DO_NOT_CACHE	FltGetDestinationFileNameInformation ne met pas en cache le nom de fichier récupéré. Les minifiltres du fournisseur de noms utilisent cet indicateur quand ils exécutent des requêtes intermédiaires pour générer un nom.

[out] RetFileNameInformation

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. FltGetDestinationFileNameInformation alloue cette structure à partir d’un pool paginé. Ce paramètre est obligatoire et ne peut pas être NULL.

Valeur retournée

FltGetDestinationFileNameInformation retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, telle que l’une des suivantes :

Code de retour	Description
STATUS_FLT_INVALID_NAME_REQUEST	Cette valeur est retournée pour l’une des raisons suivantes : (1) FltGetDestinationFileNameInformation ne peut pas obtenir d’informations de nom de fichier si le champ TopLevelIrp du thread actuel n’est pas NULL, car la récursivité du système de fichiers résultante peut entraîner des interblocages ou des dépassements de capacité de la pile. (2) FLT_FILE_NAME_SHORT a été spécifié pour l’indicateur de format de nom dans le paramètre NameOptions .
STATUS_INSUFFICIENT_RESOURCES	FltGetDestinationFileNameInformation a rencontré un échec d’allocation de pool. Il s’agit d’un code d’erreur.
STATUS_INVALID_PARAMETER	Une valeur non valide a été spécifiée pour le paramètre NameOptions . Il s’agit d’un code d’erreur.
STATUS_MOUNT_POINT_NOT_RESOLVED	Le nom du chemin d’accès de destination contient un point de montage qui est résolu en un volume autre que celui où réside le fichier. (Étant donné qu’une opération de renommage ou de création de liens durs ne peut être effectuée que dans un volume et non sur plusieurs volumes, l’opération échoue.) Il s’agit d’un code d’erreur.

Remarques

Les minifiltres appellent généralement FltGetDestinationFileNameInformation dans une routine de rappel de préopération pour une opération de renommage ou de création de liens durs, ce qui signifie que le nom du fichier de destination n’existe probablement pas. Le nom « destination » est le suivant :

Pour un renommage de fichier, le nom du fichier aura si le renommage réussit. Par exemple, lorsque vous renommez name1 en name2, name2 est le nom de destination.
Pour une opération de création de liens physiques, le nom est ajouté au système de fichiers. Par exemple, lors de l’ajout du lien physique name2 au fichier existant nommé name1, name2 est le nom de destination.

FltGetDestinationFileNameInformation retourne les informations de nom de fichier de destination au format normalisé ou « ouvert de fichier ». Pour plus d’informations sur ces formats, consultez la structure FLT_FILE_NAME_INFORMATION .

Le pointeur d’objet file passé pour le paramètre FileObject doit être le membre FileObject de la structure FLT_RELATED_OBJECTS de l’opération ou le pointeur Data-Iopb-TargetFileObject>> pour l’opération, où Data est la structure de données de rappel de l’opération (FLT_CALLBACK_DATA). Le pointeur de l’objet fichier ne peut pas être le membre Data-Iopb-Parameters.SetFileInformation.FileObject>>, car ce champ n’est pas utilisé uniformément entre les systèmes de fichiers.

Si l’utilisateur a ouvert le fichier à l’aide de l’ID de fichier, mais qu’il n’a pas de privilège de traversée pour l’ensemble du chemin d’accès, FltGetDestinationFileNameInformation retourne uniquement la partie du chemin d’accès pour laquelle l’utilisateur dispose de privilèges.

Une opération de renommage ou de création de liens physiques ne peut être effectuée que dans un volume et non sur plusieurs volumes. Par conséquent, une telle opération échoue si le nom du chemin d’accès de destination contient un point de montage qui est résolu en un volume autre que celui où réside le fichier. Pour plus d’informations sur les opérations de renommage, consultez la structure FILE_RENAME_INFORMATION . Pour plus d’informations sur les opérations de création de liens physiques, consultez les structures FILE_LINK_INFORMATION .

Après un appel réussi à FltGetDestinationFileNameInformation, l’appelant est chargé de libérer le pointeur retourné dans le paramètre RetFileNameInformation lorsqu’il n’est plus nécessaire en appelant FltReleaseFileNameInformation.

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

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 FltGetDestinationFileNameInformation, il doit appeler FltGetTunneledName à partir de sa routine de rappel postopération pour récupérer les informations de nom de fichier correctes pour le fichier.

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

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 :