FltQueryDirectoryFile, fonction (fltkernel.h)

Article
12/21/2024

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

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 l’instance du pilote de filtre qui lance l’E/S.

[in] FileObject

Pointeur vers l’objet de fichier 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 à renvoyer sur les fichiers du répertoire. Consultez le paramètre FileInformationClass de NtQueryDirectoryFileEx pour obtenir la liste des valeurs possibles.

[in] ReturnSingleEntry

Défini sur TRUE si une seule entrée doit être retournée, FALSE sinon. Si ce paramètre est TRUE, FltQueryDirectoryFile retourne uniquement la première entrée trouvée.

[in, optional] FileName

Pointeur vers une chaîne Unicode allouée par l’appelant qui contient le nom d’un fichier (ou 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’est pas NULL, seuls les fichiers dont les noms correspondent à la chaîne FileName sont inclus dans l’analyse du répertoire. Si fileName est NULL, tous les fichiers sont inclus. Si RestartScan est FALSE, la valeur de FileName est ignorée.

[in] RestartScan

Défini sur TRUE si l’analyse doit commencer à la première entrée dans le répertoire. Définissez la valeur 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 de retour

FltQueryDirectoryFile retourne STATUS_SUCCESS ou un état d’erreur approprié. Notez que l’ensemble de valeurs d’état d’erreur 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 du répertoire pour tous les appels suivants, en fonction des valeurs de ReturnSingleEntry, FileNameet 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 correspondante est 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 est TRUE et FileName est NULL.
Nombre d’entrées qui correspondent à la chaîne FileName , si nom_fichier n’est pas 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 correspondent à 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 trouvée trop grande pour s’adapter à 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 sur les systèmes d’E/S 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. Lorsque cela se produit, FltQueryDirectoryFile retourne une valeur d’état appropriée telle que STATUS_BUFFER_OVERFLOW. Lors du premier appel à FltQueryDirectoryFile, s’il n’existe aucun fichier dans le répertoire FileObject qui correspond au paramètre FileName, FltQueryDirectoryFile retourne une valeur d’état appropriée telle que STATUS_NO_SUCH_FILE.

Lors de chaque appel, FltQueryDirectoryFile retourne autant de structures FILE_XXX_INFORMATION (une par entrée de répertoire) que vous pouvez contenir 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 d’état retournée est STATUS_SUCCESS. Aucune information sur les entrées restantes n’est signalée. Par conséquent, sauf dans les cas répertoriés ci-dessus où une seule entrée est retournée, FltQueryDirectoryFile doit être appelée 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 est NULL).

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

Note

Lorsque FltQueryDirectoryFile est appelé plusieurs fois sur le même répertoire, il est possible que le nombre d’entrées pour lesquelles les informations retournées soient inférieures à celles attendues. Cela est dû au fait que l’ensemble 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 où qu’elle se soit arrêté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 les autres routines de requête d’informations sur les fichiers, consultez objets de fichiers.

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

Exigences

Exigence	Valeur
client minimum pris en charge	Windows Vista
plateforme cible	Universel
d’en-tête	fltkernel.h (include Fltkernel.h)
bibliothèque	FltMgr.lib
DLL	Fltmgr.sys
IRQL	PASSIVE_LEVEL (voir la section Remarques)