Fonction NtQueryDirectoryFileEx (ntifs.h)

Article
08/07/2023

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 file qui représente le répertoire pour lequel les informations sont demandées. L’objet file 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 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. Si un objet d’achèvement d’E/S est associé à l’objet file, 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 fichier. Une fois l’opération terminée, ce contexte est transmis à l’APC, s’il en a été spécifié, ou est inclus dans le message d’achèvement 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 file.

[out] IoStatusBlock

Pointeur vers une structure de IO_STATUS_BLOCK qui reçoit l’achèvement final status et des informations sur 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 à retourner sur les fichiers du répertoire. Type d’informations à retourner sur les fichiers du répertoire. FileInformationClass peut être l’une des valeurs 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 de FILE_QUOTA_INFORMATION unique pour chaque utilisateur sur le volume auquel des quotas sont 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 des 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 l’endroit où la dernière requête s’est terminée.
SL_RETURN_SINGLE_ENTRY (0x00000002)	Normalement, la mémoire tampon de retour est emballé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 votre propre IRP_MJ_DIRECTORY_CONTROL IRP ; l’index est spécifié dans l’IRP. La façon dont la position est spécifiée varie d’un système de fichiers à l’autre.
SL_RETURN_ON_DISK_ENTRIES_ONLY (0x00000008)	Tous les filtres de système de fichiers qui effectuent la virtualisation de répertoires ou l’expansion juste-à-temps doivent simplement transmettre la demande au système de fichiers et retourner les entrées qui se trouvent 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 de curseur par répertoire FileObject. Lorsque plusieurs threads effectuent des requêtes à l’aide du même FileObject, l’accès à la structure par FileObject est à 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 était spécifié à chaque appel. Si un modèle de carte générique est donné lors de l’appel suivant, l’opération ne reprend pas là où la dernière requête s’est terminée. Cela permet une véritable 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 à l’appelant contenant 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 FileHandle. Ce paramètre est facultatif :

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

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 est ignoré.

Valeur retournée

NtQueryDirectoryFileEx retourne STATUS_SUCCESS ou une status d’erreur appropriée. L’ensemble des valeurs d’erreur status 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 Informationd’IoStatusBlock. Certains codes et raisons d’erreur possibles peuvent être les suivants :

Code de retour	Signification
STATUS_BUFFER_OVERFLOW	La mémoire tampon de sortie n’est pas assez grande pour renvoyer le nom de fichier complet.
STATUS_BUFFER_TOO_SMALL	La mémoire tampon de sortie n’est pas assez grande pour au moins la structure de base identifiée par FileInformationClass.
STATUS_INVALID_INFO_CLASS	Un FileInformationClass non valide a été spécifié, 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.

S’il est fourni, 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 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 SL_RETURN_SINGLE_ENTRY est défini dans QueryFlags et FileName a la valeur NULL.
Nombre d’entrées qui correspondent à la chaîne FileName , si FileName n’a pas la valeur 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 s’intègrent dans 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’il crée pour la première entrée trouvée est trop volumineuse pour tenir dans la mémoire tampon de sortie, cette routine effectue les opérations suivantes :

Écrit la partie fixe de la structure dans la 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 de chaîne FileName que vous le souhaitez.
Retourne une valeur de status appropriée, telle que STATUS_BUFFER_OVERFLOW.

À chaque appel, NtQueryDirectoryFileEx 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 :

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 informer l’appelant de cette condition. Dans ce cas, l’appelant doit allouer une mémoire tampon plus importante et appeler à nouveau NtQueryDirectoryFileEx . 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, NtQueryDirectoryFileEx doit être appelé au moins deux fois pour énumérer le contenu d’un répertoire entier.

Lorsque vous appelez NtQueryDirectoryFileEx, vous pouvez voir des modifications apportées au répertoire qui se produisent en parallèle avec les 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 de status appropriée, telle que STATUS_NO_MORE_FILES.

Si NtQueryDirectoryFileEx est appelé plusieurs fois dans le même répertoire et qu’une autre opération modifie le contenu de ce répertoire, les modifications peuvent ou non être visibles, en fonction du moment des opérations.

NtQueryDirectoryFileEx 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.

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

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

Notes

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 dans 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 Utilisation des versions Nt et Zw des routines des services système natifs.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 10, version 1709
En-tête	ntifs.h
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (voir la section Remarques)