Fonction NtQueryDirectoryFileEx (ntifs.h)

Article
02/07/2025

La routine NtQueryDirectoryFileEx retourne différents types d’informations sur les fichiers du répertoire spécifié par un handle de fichier donné.

Syntaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryDirectoryFileEx(
  [in]           HANDLE                 FileHandle,
  [in, optional] HANDLE                 Event,
  [in, optional] PIO_APC_ROUTINE        ApcRoutine,
  [in, optional] PVOID                  ApcContext,
  [out]          PIO_STATUS_BLOCK       IoStatusBlock,
  [out]          PVOID                  FileInformation,
  [in]           ULONG                  Length,
                 FILE_INFORMATION_CLASS FileInformationClass,
  [in]           ULONG                  QueryFlags,
  [in, optional] PUNICODE_STRING        FileName
);

Paramètres

[in] FileHandle

Handle retourné par NtCreateFile ou NtOpenFile pour l’objet de fichier qui représente le répertoire pour lequel les informations sont demandées. L’objet de fichier doit avoir été ouvert pour les E/S asynchrones si l’appelant spécifie une valeur non NULL pour Event ou ApcRoutine.

[in, optional] Event

Handle facultatif pour un événement créé par l’appelant. Si ce paramètre est fourni, l’appelant est placé dans un état d’attente jusqu’à ce que l’opération demandée soit terminée et que l’événement donné soit défini sur l’état Signaled. Ce paramètre est facultatif et peut être NULL. Elle doit être NULL si l’appelant attend que le FileHandle soit défini sur l’état Signaled.

[in, optional] ApcRoutine

Adresse d’une routine APC facultative fournie par l’appelant à appeler une fois l’opération demandée terminée. Ce paramètre est facultatif et peut être NULL. S’il existe un objet d’achèvement d’E/S associé à l’objet fichier, ce paramètre doit être NULL.

[in, optional] ApcContext

Pointeur facultatif vers une zone de contexte déterminée par l’appelant si l’appelant fournit un APC ou si un objet d’achèvement d’E/S est associé à l’objet de fichier. Une fois l’opération terminée, ce contexte est transmis à l’APC, s’il a été spécifié ou est inclus dans le message de saisie semi-automatique que le Gestionnaire d’E/S publie sur l’objet d’achèvement d’E/S associé.

Ce paramètre est facultatif et peut être NULL. Elle doit être NULL si ApcRoutine a la valeur NULL et qu’aucun objet d’achèvement d’E/S n’est associé à l’objet de fichier.

[out] IoStatusBlock

Pointeur vers une structure IO_STATUS_BLOCK qui reçoit l’état d’achèvement final et les informations relatives à l’opération. Pour les appels réussis qui retournent des données, le nombre d’octets écrits dans la mémoire tampon FileInformation est retourné dans le membre Information de la structure.

[out] FileInformation

Pointeur vers une mémoire tampon de sortie 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.

FileInformationClass

Type d’informations à renvoyer sur les fichiers du répertoire. Type d’informations à renvoyer sur les fichiers du répertoire. FileInformationClass peut être l’une des valeurs de FILE_INFORMATION_CLASS suivantes.

Valeur	Signification
FileDirectoryInformation (1)	Retourne une structure FILE_DIRECTORY_INFORMATION pour chaque fichier.
FileFullDirectoryInformation (2)	Retourne une structure FILE_FULL_DIR_INFORMATION pour chaque fichier.
FileBothDirectoryInformation (3)	Retourne une structure FILE_BOTH_DIR_INFORMATION pour chaque fichier.
FileNamesInformation (12)	Retourne une structure FILE_NAMES_INFORMATION pour chaque fichier.
FileObjectIdInformation (29)	Retourne une structure FILE_OBJECTID_INFORMATION pour chaque fichier qui a un ID d’objet sur le volume. Cette classe d’informations est valide uniquement pour le répertoire spécial « \$Extend\$ObjId :$O :$INDEX_ALLOCATION » sur les volumes NTFS.
FileQuotaInformation (32)	Retourne une structure FILE_QUOTA_INFORMATION unique pour chaque utilisateur sur le volume qui a des quotas appliqués. Cette classe d’informations est valide uniquement pour le répertoire spécial « \$Extend\$Quota :$Q :$INDEX_ALLOCATION » sur les volumes NTFS.
FileReparsePointInformation (33)	Retourne une structure de FILE_REPARSE_POINT_INFORMATION unique pour chaque fichier qui a un point d’analyse sur le volume. Cette classe d’informations est valide uniquement pour le répertoire spécial « \$Extend\$Reparse :$R :$INDEX_ALLOCATION » sur les volumes NTFS et ReFS.
FileIdBothDirectoryInformation (37)	Retourne une structure FILE_ID_BOTH_DIR_INFORMATION pour chaque fichier.
FileIdFullDirectoryInformation (38)	Retourne une structure FILE_ID_FULL_DIR_INFORMATION pour chaque fichier.
FileIdGlobalTxDirectoryInformation (50)	Retourne une structure FILE_ID_GLOBAL_TX_DIR_INFORMATION pour chaque fichier.
FileIdExtdDirectoryInformation (60)	Retourne une structure FILE_ID_EXTD_DIR_INFORMATION pour chaque fichier.
FileIdExtdBothDirectoryInformation (63)	Retourne une structure FILE_ID_EXTD_BOTH_DIR_INFORMATION pour chaque fichier.

[in] QueryFlags

Un ou plusieurs indicateurs contenus dans SL_QUERY_DIRECTORY_MASK. Les valeurs possibles sont spécifiées dans le tableau suivant.

Valeur	Signification
SL_RESTART_SCAN (0x00000001)	L’analyse démarre à la première entrée du répertoire. Si cet indicateur n’est pas défini, l’analyse reprend à partir de laquelle la dernière requête s’est terminée.
SL_RETURN_SINGLE_ENTRY (0x00000002)	Normalement, la mémoire tampon de retour est empaquetée avec autant d’entrées de répertoire correspondantes qui conviennent. Si cet indicateur est défini, le système de fichiers retourne une seule entrée de répertoire à la fois. Cela rend l’opération moins efficace.
SL_INDEX_SPECIFIED (0x00000004)	L’analyse doit commencer à une position indexée spécifiée dans le répertoire. Cet indicateur ne peut être défini que si vous générez vos propres IRP_MJ_DIRECTORY_CONTROL IRP ; l’index est spécifié dans l’IRP. La façon dont la position est spécifiée varie du système de fichiers au système de fichiers.
SL_RETURN_ON_DISK_ENTRIES_ONLY (0x00000008)	Tous les filtres de système de fichiers qui effectuent une virtualisation de répertoire ou une extension juste-à-temps doivent simplement transmettre la requête au système de fichiers et retourner des entrées actuellement sur le disque. Tous les systèmes de fichiers ne prennent pas en charge cet indicateur.
SL_NO_CURSOR_UPDATE_QUERY (0x00000010)	Les systèmes de fichiers conservent les informations du curseur du répertoire FileObject par utilisateur. Lorsque plusieurs threads effectuent des requêtes à l’aide du même FileObject, l’accès à la structure per-FileObject est un thread unique pour empêcher l’altération de l’état du curseur. Cet indicateur indique au système de fichiers de ne pas mettre à jour les informations d’état du curseur par fileObject, ce qui permet à plusieurs threads d’interroger en parallèle à l’aide du même handle. Il se comporte comme si SL_RESTART_SCAN est spécifié sur chaque appel. Si un modèle de caractères génériques est donné lors de l’appel suivant, l’opération ne récupère pas l’emplacement où la dernière requête s’est terminée. Cela permet la prise en charge des requêtes d’annuaire asynchrones. Si cet indicateur est utilisé à l’intérieur d’une transaction TxF, l’opération échoue. Tous les systèmes de fichiers ne prennent pas en charge cet indicateur.

[in, optional] FileName

Pointeur facultatif vers une chaîne Unicode allouée par l’appelant contenant 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 FileHandle. Ce paramètre est facultatif :

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 a la valeur NULL :
- Si SL_RETURN_SINGLE_ENTRY n’est pas défini dans QueryFlags, tous les fichiers sont inclus.
- Si SL_RETURN_SINGLE_ENTRY est définie, un seul fichier est inclus.

Le FileName est utilisé comme expression de recherche et est capturé lors du tout premier appel à NtQueryDirectoryFileEx pour un handle donné. Les appels suivants à NtQueryDirectoryFileEx utiliseront l’expression de recherche définie dans le premier appel. Le paramètre FileName passé aux appels suivants sera ignoré.

Valeur de retour

NtQueryDirectoryFileEx retourne STATUS_SUCCESS ou un état d’erreur approprié. L’ensemble de valeurs d’état d’erreur qui peuvent être retournées est spécifique au système de fichiers. NtQueryDirectoryFileEx retourne également le nombre d’octets réellement écrits dans la mémoire tampon FileInformation donnée dans le membre Information de IoStatusBlock. Certains codes d’erreur et raisons possibles peuvent être les suivants :

Retourner le code	Signification
STATUS_BUFFER_OVERFLOW	La mémoire tampon de sortie n’est pas suffisamment grande pour retourner le nom de fichier complet.
STATUS_BUFFER_TOO_SMALL	La mémoire tampon de sortie n’est pas suffisamment grande pour au moins la structure de base identifiée par FileInformationClass.
STATUS_INVALID_INFO_CLASS	Une FileInformationClass non valide a été spécifiée, ou la classe d’informations est valide uniquement pour une condition spéciale (par exemple, valide uniquement pour un répertoire spécial).
STATUS_INVALID_PARAMETER	L’un des paramètres n’est pas valide pour le système de fichiers.

Remarques

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

Si elle est fournie, FileName détermine les entrées incluses dans l’analyse du répertoire pour tous les appels suivants à NtQueryDirectoryFileEx pour un FileHandle donné.

S’il existe au moins une entrée correspondante, NtQueryDirectoryFileEx crée une structure FILE_XXX_INFORMATION pour chaque entrée et les stocke 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 la la plus petite des éléments suivants :

Une entrée, si SL_RETURN_SINGLE_ENTRY est définie dans QueryFlags et FileName a la valeur NULL.
Nombre d’entrées qui correspondent à la chaîne FileName, si FileName n’est pas NULL. 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 à NtQueryDirectoryFileEx, si la structure qu’elle crée pour la première entrée trouvée est trop grande pour s’adapter à la mémoire tampon de sortie, cette routine effectue les opérations suivantes :

Écrit la partie fixe de la structure dans Mémoire tampon de sortie de FileInformation. La partie fixe se compose de tous les champs, à 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.
Écrit dans la mémoire tampon de sortie autant que la plupart des FileName chaîne comme il convient.
Retourne une valeur d’état appropriée telle que STATUS_BUFFER_OVERFLOW.

Lors de chaque appel, NtQueryDirectoryFileEx retourne autant de structures de_INFORMATION XXX FILE_(une par entrée de répertoire) que vous pouvez contenir entièrement dans la mémoire tampon pointée par FileInformation:

Lors du premier appel, NtQueryDirectoryFileEx retourne STATUS_SUCCESS uniquement si la mémoire tampon de sortie contient au moins une structure complète.
Lors des appels suivants, si la mémoire tampon de sortie ne contient aucune structure, NtQueryDirectoryFileEx retourne STATUS_SUCCESS mais définit IoStatusBlock->Information = 0 pour notifier l’appelant de cette condition. Dans ce cas, l’appelant doit allouer une mémoire tampon plus grande et appeler NtQueryDirectoryFileEx à nouveau. 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, NtQueryDirectoryFileEx doit être appelée au moins deux fois pour énumérer le contenu d’un répertoire entier.

Lorsque vous appelez NtQueryDirectoryFileEx, vous pouvez voir les modifications apportées au répertoire qui se produisent en parallèle avec appels NtQueryDirectoryFileEx. Ce comportement dépend de l’implémentation du système de fichiers sous-jacent.

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

Si NtQueryDirectoryFileEx est appelé plusieurs fois sur le même répertoire et que d’autres opérations modifient le contenu de ce répertoire, toutes les modifications peuvent ou ne pas être visibles, en fonction du minutage des opérations.

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

Les appelants de NtQueryDirectoryFileEx doivent s’exécuter à IRQL = PASSIVE_LEVEL et avec des API de noyau spéciales activées.

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

Note

Si l’appel à la fonction NtQueryDirectoryFileEx se produit en mode noyau, vous devez utiliser le nom «ZwQueryDirectoryFileEx» au lieu de «NtQueryDirectoryFileEx».

Pour les appels à partir de pilotes en mode noyau, les versions NtXxx et ZwXxx d’une routine Windows Native System Services peuvent se comporter différemment de la façon dont elles gèrent et interprètent les paramètres d’entrée. Pour plus d’informations sur la relation entre les versions NtXxx et ZwXxx d’une routine, consultez Using Nt and Zw Versions of the Native System Services Routines.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 10, version 1709
d’en-tête	ntifs.h
bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (voir la section Remarques)