Fonction NtQueryDirectoryFile (ntifs.h)

Article
02/26/2024

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

Syntaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryDirectoryFile(
  [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,
  [in]           FILE_INFORMATION_CLASS FileInformationClass,
  [in]           BOOLEAN                ReturnSingleEntry,
  [in, optional] PUNICODE_STRING        FileName,
  [in]           BOOLEAN                RestartScan
);

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 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. S’il existe un objet d’achèvement d’E/S associé à l’objet fichier, ce paramètre doit avoir la valeur 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 passé à l’APC, le cas échéant, ou est inclus dans le message d’achèvement que le Gestionnaire d’E/S publie dans 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 fichier.

[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 Informations de la structure.

[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 du FichierInformationClass donné.

[in] FileInformationClass

Type d’informations à retourner sur les fichiers dans le répertoire. Type d’informations à retourner sur les fichiers dans le 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 sinon. Si ce paramètre a la valeur TRUE, NtQueryDirectoryFile retourne uniquement la première entrée trouvée.

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

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

[in] RestartScan

Définissez sur TRUE si l’analyse doit démarrer à la première entrée dans le répertoire. Définissez sur FALSE si vous reprenez l’analyse d’un appel précédent.

Lorsque la routine NtQueryDirectoryFile est appelée pour un handle particulier, le paramètre RestartScan est traité comme s’il était défini sur TRUE, quelle que soit sa valeur. Lors des appels NtQueryDirectoryFile suivants, la valeur du paramètre RestartScan est respectée.

Valeur retournée

La routine NtQueryDirectoryFileretourne 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. NtQueryDirectoryFileretourne également le nombre d’octets réellement écrits dans la mémoire tampon FileInformation donnée dans le membre Informationd’IoStatusblock. Pour obtenir la liste des codes d’erreur possibles, consultez NtQueryDirectoryFileEx .

Remarques

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

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

S’il existe au moins une entrée correspondante, NtQueryDirectoryFile 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 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 s’intègrent dans la mémoire tampon spécifiée.
Nombre d’entrées contenues dans le répertoire.

Lors du premier appel à NtQueryDirectoryFile, si la structure créée pour la première entrée trouvée est trop grande pour tenir dans la mémoire tampon de sortie, la routine écrit la partie fixe de la structure dans la mémoire tampon de sortie. La routine écrit ensuite dans la mémoire tampon de sortie autant de chaîne FileName que vous le souhaitez. (La partie fixe de la structure 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.) Dans ce cas, NtQueryDirectoryFile retourne une valeur status appropriée, telle que STATUS_BUFFER_OVERFLOW.

À chaque appel, NtQueryDirectoryFile 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, NtQueryDirectoryFile 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, NtQueryDirectoryFile 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 importante et appeler à nouveau NtQueryDirectoryFile . 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, NtQueryDirectoryFile doit être appelé au moins deux fois pour énumérer le contenu d’un répertoire entier.

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

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

Si NtQueryDirectoryFile est appelé plusieurs fois sur 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.

NtQueryDirectoryFileretourne 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 NtQueryDirectoryFile 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 NtQueryDirectoryFile se produit en mode utilisateur, vous devez utiliser le nom « NtQueryDirectoryFile » au lieu de « ZwQueryDirectoryFile ».

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 XP
Plateforme cible	Universal
En-tête	ntifs.h (inclure Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (voir la section Remarques)
Règles de conformité DDI	HwStorPortProhibitedDDIs, PowerIrpDDis