Fonction FltQueryDirectoryFile (fltkernel.h)

Article
08/07/2023

La routine FltQueryDirectoryFile retourne différents types d’informations sur les fichiers dans le répertoire spécifié par un objet de fichier donné. Utilisez FltQueryDirectoryFileEx pour un contrôle de requête plus important.

Syntaxe

NTSTATUS FLTAPI FltQueryDirectoryFile(
  [in]            PFLT_INSTANCE          Instance,
  [in]            PFILE_OBJECT           FileObject,
  [out]           PVOID                  FileInformation,
  [in]            ULONG                  Length,
  [in]            FILE_INFORMATION_CLASS FileInformationClass,
  [in]            BOOLEAN                ReturnSingleEntry,
  [in, optional]  PUNICODE_STRING        FileName,
  [in]            BOOLEAN                RestartScan,
  [out, optional] PULONG                 LengthReturned
);

Paramètres

[in] Instance

Pointeur opaque vers le pilote de filtre instance qui lance les E/S.

[in] FileObject

Pointeur vers l’objet file qui représente le répertoire à analyser.

[out] FileInformation

Pointeur vers une mémoire tampon qui reçoit les informations souhaitées sur le fichier. La structure des informations retournées dans la mémoire tampon est définie par le paramètre FileInformationClass .

[in] Length

Taille, en octets, de la mémoire tampon pointée par FileInformation. L’appelant doit définir ce paramètre en fonction de la FileInformationClass donnée.

[in] FileInformationClass

Type d’informations à retourner sur les fichiers du répertoire. Pour obtenir la liste des valeurs possibles, consultez le paramètre FileInformationClass de NtQueryDirectoryFileEx .

[in] ReturnSingleEntry

Définissez sur TRUE si une seule entrée doit être retournée, false dans le cas contraire. Si ce paramètre a la valeur TRUE, FltQueryDirectoryFile retourne uniquement la première entrée trouvée.

[in, optional] FileName

Pointeur vers une chaîne Unicode allouée à l’appelant qui contient le nom d’un fichier (ou de plusieurs fichiers, si des caractères génériques sont utilisés) dans le répertoire spécifié par FileObject. Ce paramètre est facultatif et peut être NULL.

Si FileName n’a pas la valeur NULL, seuls les fichiers dont le nom correspond à la chaîne FileName sont inclus dans l’analyse du répertoire. Si FileName a la valeur NULL, tous les fichiers sont inclus. Si RestartScan a la valeur FALSE, la valeur de FileName est ignorée.

[in] RestartScan

Définissez sur TRUE si l’analyse doit commencer à la première entrée du répertoire. Définissez sur FALSE si vous reprenez l’analyse à partir d’un appel précédent. L’appelant doit définir ce paramètre sur TRUE lors de l’appel de FltQueryDirectoryFile pour la première fois.

[out, optional] LengthReturned

Reçoit le nombre d’octets réellement écrits dans la mémoire tampon FileInformation donnée.

Valeur retournée

FltQueryDirectoryFile retourne STATUS_SUCCESS ou une status d’erreur appropriée. Notez que l’ensemble des valeurs d’erreur status qui peuvent être retournées est spécifique au système de fichiers.

Remarques

FltQueryDirectoryFile retourne des informations sur les fichiers contenus dans le répertoire représenté par FileObject.

Le premier appel à FltQueryDirectoryFile détermine le jeu d’entrées à inclure dans l’analyse de répertoire pour tous les appels suivants, en fonction des valeurs de ReturnSingleEntry, FileName et RestartScan. S’il existe au moins une entrée correspondante, FltQueryDirectoryFile crée une structure FILE_XXX_INFORMATION (voir le tableau ci-dessus) pour chaque entrée à son tour et stocke la structure dans la mémoire tampon.

En supposant qu’au moins une entrée de répertoire correspondant soit trouvée, le nombre d’entrées pour lesquelles les informations sont retournées est le plus petit des éléments suivants :

Une entrée, si ReturnSingleEntry a la valeur TRUE et FileName a la valeur NULL.
Nombre d’entrées qui correspondent à la chaîne FileName , si FileName n’a pas la valeur NULL. (Notez que si la chaîne ne contient pas de caractères génériques, il peut y avoir au maximum une entrée correspondante.)
Nombre d’entrées dont les informations sont insérées dans la mémoire tampon spécifiée.
Nombre d’entrées contenues dans le répertoire.

Lors du premier appel à FltQueryDirectoryFile, si la structure créée pour la première entrée est trop grande pour tenir dans la mémoire tampon de sortie, seule la partie fixe de la structure est retournée. La partie fixe se compose de tous les champs de la structure, à l’exception de la chaîne FileName finale. Lors du premier appel, mais pas lors des appels suivants, le système d’E/S garantit que la mémoire tampon est suffisamment grande pour contenir la partie fixe de la structure FILE_XXX_INFORMATION appropriée. Dans ce cas, FltQueryDirectoryFile retourne une valeur de status appropriée, telle que STATUS_BUFFER_OVERFLOW. De même, lors du premier appel à FltQueryDirectoryFile, s’il n’existe aucun fichier dans le répertoire FileObject correspondant au paramètre FileName, FltQueryDirectoryFile renvoie une valeur de status appropriée, telle que STATUS_NO_SUCH_FILE.

À chaque appel, FltQueryDirectoryFile retourne autant de structures FILE_XXX_INFORMATION (une par entrée de répertoire) que peuvent être contenues entièrement dans la mémoire tampon pointée par FileInformation. Tant que la mémoire tampon de sortie contient au moins une structure complète, la valeur status retournée est STATUS_SUCCESS. Aucune information sur les entrées restantes n’est signalée. Ainsi, sauf dans les cas répertoriés ci-dessus où une seule entrée est retournée, FltQueryDirectoryFile doit être appelé au moins deux fois pour énumérer le contenu d’un répertoire entier (par exemple, lorsque le paramètre FileName contient un ou plusieurs caractères génériques ou a la valeur NULL).

L’appel final à FltQueryDirectoryFile retourne une mémoire tampon de sortie vide et signale une valeur de status appropriée, telle que STATUS_NO_MORE_FILES.

Notes

Lorsque FltQueryDirectoryFile est appelé plusieurs fois dans le même répertoire, il est possible que le nombre d’entrées pour lesquelles des informations sont retournées soit inférieur à ce qui était prévu. Cela est dû au fait que le jeu d’entrées à inclure dans l’analyse du répertoire est résolu lors du premier appel à FltQueryDirectoryFile. Dans les appels suivants, FltQueryDirectoryFile reprend l’analyse du répertoire partout où elle s’est laissée dans cette même énumération. Toutefois, entre les appels à FltQueryDirectoryFile, les entrées de répertoire réelles peuvent changer afin qu’elles ne soient plus synchronisées avec l’énumération d’origine.

FltQueryDirectoryFile retourne zéro dans n’importe quel membre d’une structure FILE_XXX_INFORMATION qui n’est pas prise en charge par le système de fichiers.

Pour plus d’informations sur d’autres routines de requête d’informations sur les fichiers, consultez Objets de fichier.

Les appelants de FltQueryDirectoryFile doivent s’exécuter sur IRQL = PASSIVE_LEVEL et avec les API activées. Pour plus d’informations, consultez Désactivation des API.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista
Plateforme cible	Universal
En-tête	fltkernel.h (inclure Fltkernel.h)
Bibliothèque	FltMgr.lib
DLL	Fltmgr.sys
IRQL	PASSIVE_LEVEL (voir la section Remarques)