FltQueryDirectoryFileEx, fonction (fltkernel.h)

Article
07/16/2024

FltQueryDirectoryFileEx retourne différents types d’informations sur les fichiers du répertoire spécifié par un objet de fichier donné.

Syntaxe

NTSTATUS FLTAPI FltQueryDirectoryFileEx(
  PFLT_INSTANCE          Instance,
  PFILE_OBJECT           FileObject,
  PVOID                  FileInformation,
  ULONG                  Length,
  FILE_INFORMATION_CLASS FileInformationClass,
  ULONG                  QueryFlags,
  PUNICODE_STRING        FileName,
  PULONG                 LengthReturned
);

Paramètres

Instance

Pointeur opaque vers l’instance de pilote minifilter qui lance cette E/S.

FileObject

Pointeur vers l’objet de fichier qui représente le répertoire interrogé.

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 .

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. Consultez le paramètre FileInformationClass de NtQueryDirectoryFileEx pour obtenir la liste des valeurs possibles.

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)	Si cet indicateur est défini, 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)	Si cet indicateur est défini, 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 du système de fichiers au système de fichiers.
SL_RETURN_ON_DISK_ENTRIES_ONLY (0x00000008)	Si cet indicateur est défini, tous les filtres de système de fichiers qui effectuent la virtualisation du répertoire ou l’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 gèrent les informations de curseur de répertoire parFileObject. Lorsque plusieurs threads effectuent des requêtes à l’aide de la même FileObject, l’accès à la structure FileObject parest 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 parFileObject informations d’état du curseur, 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.

FileName

Pointeur vers une structure UNICODE_STRING allouée par l’appelant avec la chaîne Unicode 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 est NULL, tous les fichiers sont inclus.

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 l’indicateur QueryFlagsResetScan est défini, la valeur de FileName est ignorée.

LengthReturned

Reçoit le nombre d’octets réellement écrits dans la mémoire tampon FileInformation donnée.

Valeur de retour

FltQueryDirectoryFileEx retourne STATUS_SUCCESS ou un code d’erreur approprié. L’ensemble de valeurs d’état d’erreur qui peuvent être retournées est spécifique au système de fichiers.

Remarques

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

Le premier appel à FltQueryDirectoryFileEx détermine l’ensemble d’entrées à inclure dans l’analyse du répertoire pour tous les appels suivants, en fonction des valeurs de QueryFlags et FileName. S’il existe au moins une entrée correspondante, FltQueryDirectoryFileEx 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 l’indicateur de SL_RETURN_SINGLE_ENTRY est défini dans QueryFlags 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 pointée par FileInformation.
Nombre d’entrées contenues dans le répertoire.

Lors du premier appel à FltQueryDirectoryFileEx, si la structure créée pour la première entrée trouvée est 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 . Le sous-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 (uniquement lors du premier appel et non sur les appels suivants). Lorsque cela se produit, FltQueryDirectoryFileEx retourne une valeur d’état de STATUS_BUFFER_OVERFLOW. Lors du premier appel à FltQueryDirectoryFileEx, s’il n’existe aucun fichier dans le répertoire FileObject qui correspond au paramètre FileName, FltQueryDirectoryFileEx retourne STATUS_NO_SUCH_FILE.

Lors de chaque appel, FltQueryDirectoryFileEx 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. Ainsi, sauf dans les cas répertoriés ci-dessus où une seule entrée est retournée, FltQueryDirectoryFileEx 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 à FltQueryDirectoryFileEx retourne une mémoire tampon de sortie vide et signale une valeur d’état non-erreur de STATUS_NO_MORE_FILES.

Remarque : Lorsque FltQueryDirectoryFileEx 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 à FltQueryDirectoryFileEx. Dans les appels suivants, FltQueryDirectoryFileEx reprend l’analyse du répertoire où qu’elle se soit arrêtée dans cette même énumération. Toutefois, entre les appels à FltQueryDirectoryFileEx, les entrées de répertoire réelles peuvent changer afin qu’elles ne soient plus synchronisées avec l’énumération d’origine.

FltQueryDirectoryFileEx retourne zéro dans un membre d’une structure_INFORMATION XXX FILE_qui n’est pas prise en charge par le système de fichiers.

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