ZwQueryDirectoryFile, fonction (ntifs.h)

Article
12/21/2024

La routine ZwQueryDirectoryFile retourne diverses informations sur les fichiers du répertoire spécifié par un handle de fichier donné.

Syntaxe

NTSYSAPI NTSTATUS ZwQueryDirectoryFile(
  [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 ZwCreateFile ou ZwOpenFile 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 de NULL nonpour 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. Il doit être NULL si ApcRoutine est 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.

[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, ZwQueryDirectoryFile retourne uniquement la première entrée trouvée.

[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 est NULL, tous les fichiers sont inclus si ReturnSingleEntry est FALSE; un fichier est inclus si ReturnSingleEntry est TRUE.

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

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

Lorsque la routine ZwQueryDirectoryFile 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 de ZwQueryDirectoryFile suivants, la valeur du paramètre RestartScan est respectée.

Valeur de retour

La routine ZwQueryDirectoryFile 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. ZwQueryDirectoryFile retourne également le nombre d’octets réellement écrits dans la mémoire tampon FileInformation donnée dans le membre Information de IoStatusBlock. Consultez NtQueryDirectoryFileEx pour obtenir la liste de certains codes d’erreur possibles.

Remarques

La routine ZwQueryDirectoryFile 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 à ZwQueryDirectoryFile pour un FileHandledonné.

S’il existe au moins une entrée correspondante, ZwQueryDirectoryFile 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 ReturnSingleEntry est TRUE et FileName est NULL.
Nombre d’entrées qui correspondent à la chaîne FileName , si nom_fichier 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 à ZwQueryDirectoryFile, 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.

Sur chaque appel, ZwQueryDirectoryFile retourne autant de structures_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, ZwQueryDirectoryFile 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, ZwQueryDirectoryFile 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 ZwQueryDirectoryFile à nouveau. 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, ZwQueryDirectoryFile doit être appelée au moins deux fois pour énumérer le contenu d’un répertoire entier.

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

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

Si ZwQueryDirectoryFile 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.

ZwQueryDirectoryFile 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 ZwQueryDirectoryFile 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 ZwQueryDirectoryFile 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 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 XP.
plateforme cible	Universel
d’en-tête	ntifs.h (include Ntifs.h)
bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (voir la section Remarques)
règles de conformité DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)