Función NtQueryDirectoryFileEx (ntifs.h)

Artículo
03/10/2023

La rutina NtQueryDirectoryFileEx devuelve varios tipos de información sobre los archivos del directorio especificados por un identificador de archivo determinado.

Sintaxis

__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
);

Parámetros

[in] FileHandle

Identificador devuelto por NtCreateFile o NtOpenFile para el objeto de archivo que representa el directorio para el que se solicita información. El objeto de archivo debe haberse abierto para E/S asincrónica si el autor de la llamada especifica un valor distinto de NULL para Event o ApcRoutine.

[in, optional] Event

Identificador opcional para un evento creado por el autor de la llamada. Si se proporciona este parámetro, el autor de la llamada se colocará en un estado de espera hasta que se complete la operación solicitada y el evento especificado se establezca en el estado Signaled. Este parámetro es opcional y puede ser NULL. Debe ser NULL si el autor de la llamada esperará a que FileHandle se establezca en el estado Signaled.

[in, optional] ApcRoutine

Dirección de una rutina de APC opcional proporcionada por el autor de la llamada que se llamará cuando se complete la operación solicitada. Este parámetro es opcional y puede ser NULL. Si hay un objeto de finalización de E/S asociado al objeto de archivo, este parámetro debe ser NULL.

[in, optional] ApcContext

Puntero opcional a un área de contexto determinada por el autor de la llamada si el autor de la llamada proporciona un APC o si un objeto de finalización de E/S está asociado al objeto de archivo. Cuando se completa la operación, este contexto se pasa al APC, si se especificó uno o se incluye como parte del mensaje de finalización que el Administrador de E/S publica en el objeto de finalización de E/S asociado.

Este parámetro es opcional y puede ser NULL. Debe ser NULL si ApcRoutine es NULL y no hay ningún objeto de finalización de E/S asociado al objeto de archivo.

[out] IoStatusBlock

Puntero a una estructura de IO_STATUS_BLOCK que recibe el estado de finalización final e información sobre la operación. Para llamadas correctas que devuelven datos, el número de bytes escritos en el búfer FileInformation se devuelve en el miembro Information de la estructura.

[out] FileInformation

Puntero a un búfer de salida que recibe la información deseada sobre el archivo. La estructura de la información devuelta en el búfer se define mediante el parámetro FileInformationClass .

[in] Length

Tamaño, en bytes, del búfer al que apunta FileInformation. El autor de la llamada debe establecer este parámetro según la clase FileInformationClass especificada.

FileInformationClass

Tipo de información que se va a devolver sobre los archivos del directorio. Tipo de información que se va a devolver sobre los archivos del directorio. FileInformationClass puede ser uno de los siguientes valores de FILE_INFORMATION_CLASS .

Valor	Significado
FileDirectoryInformation (1)	Devuelve una estructura de FILE_DIRECTORY_INFORMATION para cada archivo.
FileFullDirectoryInformation (2)	Devuelve una estructura de FILE_FULL_DIR_INFORMATION para cada archivo.
FileBothDirectoryInformation (3)	Devuelve una estructura de FILE_BOTH_DIR_INFORMATION para cada archivo.
FileNamesInformation (12)	Devuelve una estructura de FILE_NAMES_INFORMATION para cada archivo.
FileObjectIdInformation (29)	Devuelve una estructura de FILE_OBJECTID_INFORMATION para cada archivo que tiene un identificador de objeto en el volumen. Esta clase de información solo es válida para el directorio especial "\$Extend\$ObjId:$O:$INDEX_ALLOCATION" en volúmenes NTFS.
FileQuotaInformation (32)	Devuelve una única estructura de FILE_QUOTA_INFORMATION para cada usuario del volumen que tiene cuotas aplicadas. Esta clase de información solo es válida para el directorio especial "\$Extend\$Quota:$Q:$INDEX_ALLOCATION" en volúmenes NTFS.
FileReparsePointInformation (33)	Devuelve una única estructura de FILE_REPARSE_POINT_INFORMATION para cada archivo que tiene un punto de reanálisis en el volumen. Esta clase de información solo es válida para el directorio especial "\$Extend\$Reparse:$R:$INDEX_ALLOCATION" en volúmenes NTFS y ReFS.
FileIdBothDirectoryInformation (37)	Devuelve una estructura de FILE_ID_BOTH_DIR_INFORMATION para cada archivo.
FileIdFullDirectoryInformation (38)	Devuelve una estructura de FILE_ID_FULL_DIR_INFORMATION para cada archivo.
FileIdGlobalTxDirectoryInformation (50)	Devuelve una estructura de FILE_ID_GLOBAL_TX_DIR_INFORMATION para cada archivo.
FileIdExtdDirectoryInformation (60)	Devuelve una estructura de FILE_ID_EXTD_DIR_INFORMATION para cada archivo.
FileIdExtdBothDirectoryInformation (63)	Devuelve una estructura de FILE_ID_EXTD_BOTH_DIR_INFORMATION para cada archivo.

[in] QueryFlags

Una o varias de las marcas contenidas en SL_QUERY_DIRECTORY_MASK. Los valores posibles se especifican en la tabla siguiente.

Valor	Significado
SL_RESTART_SCAN (0x00000001)	El examen se iniciará en la primera entrada del directorio. Si no se establece esta marca, el examen se reanudará desde donde finalizó la última consulta.
SL_RETURN_SINGLE_ENTRY (0x00000002)	Normalmente, el búfer de retorno se empaqueta con tantas entradas de directorio coincidentes que caben. Si se establece esta marca, el sistema de archivos devolverá solo una entrada de directorio a la vez. Esto hace que la operación sea menos eficaz.
SL_INDEX_SPECIFIED (0x00000004)	El examen debe iniciarse en una posición indizada especificada en el directorio. Esta marca solo se puede establecer si genera su propio IRP de IRP_MJ_DIRECTORY_CONTROL; el índice se especifica en el IRP. La forma en que se especifica la posición varía de sistema de archivos a sistema de archivos.
SL_RETURN_ON_DISK_ENTRIES_ONLY (0x00000008)	Cualquier filtro del sistema de archivos que realice la virtualización de directorios o la expansión Just-In-Time simplemente debe pasar la solicitud al sistema de archivos y devolver entradas que están actualmente en disco. No todos los sistemas de archivos admiten esta marca.
SL_NO_CURSOR_UPDATE_QUERY (0x00000010)	Los sistemas de archivos mantienen la información del cursor del directorio per-FileObject. Cuando varios subprocesos realizan consultas con el mismo FileObject, el acceso a la estructura per-FileObject es un único subproceso para evitar daños en el estado del cursor. Esta marca indica al sistema de archivos que no actualice la información de estado del cursor por FileObject, lo que permite que varios subprocesos realicen consultas en paralelo con el mismo identificador. Se comporta como si SL_RESTART_SCAN se especifica en cada llamada. Si se da un patrón de comodín en la siguiente llamada, la operación no recogerá dónde finalizó la última consulta. Esto permite la verdadera compatibilidad con consultas de directorio asincrónica. Si se usa esta marca dentro de una transacción TxF, se producirá un error en la operación. No todos los sistemas de archivos admiten esta marca.

[in, optional] FileName

Puntero opcional a una cadena Unicode asignada por el autor de la llamada que contiene el nombre de un archivo (o varios archivos, si se usan caracteres comodín) dentro del directorio especificado por FileHandle. Este parámetro es opcional:

Si FileName no es NULL, solo los archivos cuyos nombres coinciden con la cadena FileName se incluyen en el examen del directorio.
Si FileName es NULL:
- Si SL_RETURN_SINGLE_ENTRY no se establece en QueryFlags, se incluyen todos los archivos.
- Si se establece SL_RETURN_SINGLE_ENTRY, solo se incluye un archivo.

FileName se usa como una expresión de búsqueda y se captura en la primera llamada a NtQueryDirectoryFileEx para un identificador determinado. Las llamadas posteriores a NtQueryDirectoryFileEx usarán la expresión de búsqueda establecida en la primera llamada. Se omitirá el parámetro FileName pasado a llamadas posteriores.

Valor devuelto

NtQueryDirectoryFileEx devuelve STATUS_SUCCESS o un estado de error adecuado. El conjunto de valores de estado de error que se pueden devolver es específico del sistema de archivos. NtQueryDirectoryFileEx también devuelve el número de bytes escritos realmente en el búfer FileInformation especificado en el miembro Information de IoStatusBlock. Algunos posibles códigos de error y motivos pueden ser los siguientes:

Código de retorno	Significado
STATUS_BUFFER_OVERFLOW	El búfer de salida no es lo suficientemente grande como para devolver el nombre de archivo completo.
STATUS_BUFFER_TOO_SMALL	El búfer de salida no es lo suficientemente grande como para al menos la estructura base identificada por FileInformationClass.
STATUS_INVALID_INFO_CLASS	Se especificó una clase FileInformationClass no válida o la clase de información solo es válida para una condición especial (por ejemplo, válida solo para un directorio especial).
STATUS_INVALID_PARAMETER	Uno de los parámetros no es válido para el sistema de archivos.

Comentarios

NtQueryDirectoryFileEx devuelve información sobre los archivos contenidos en el directorio representado por FileHandle.

Si se proporciona, FileName determina las entradas que se incluyen en el directorio buscan todas las llamadas posteriores a NtQueryDirectoryFileEx para un fileHandle determinado.

Si hay al menos una entrada coincidente, NtQueryDirectoryFileEx crea una estructura FILE_XXX_INFORMATION para cada entrada y las almacena en el búfer.

Suponiendo que se encuentre al menos una entrada de directorio coincidente, el número de entradas para las que se devuelve información es la más pequeña de las siguientes:

Una entrada, si SL_RETURN_SINGLE_ENTRY se establece en QueryFlags y FileName es NULL.
Número de entradas que coinciden con la cadena FileName , si FileName no es NULL. Si la cadena no contiene caracteres comodín, puede haber como máximo una entrada coincidente.
Número de entradas cuya información se ajusta al búfer especificado.
Número de entradas contenidas en el directorio.

En la primera llamada a NtQueryDirectoryFileEx, si la estructura que crea para la primera entrada encontrada es demasiado grande para caber en el búfer de salida, esta rutina hace lo siguiente:

Escribe la parte fija de la estructura en el búfer de salida de FileInformation. La parte fija consta de todos los campos excepto la cadena FileName final. En la primera llamada, pero no en las llamadas posteriores, el sistema de E/S garantiza que el búfer es lo suficientemente grande como para contener la parte fija de la estructura FILE_XXX_INFORMATION adecuada.
Escribe en el búfer de salida tanto como se ajuste a la cadena FileName .
Devuelve un valor de estado adecuado, como STATUS_BUFFER_OVERFLOW.

En cada llamada, NtQueryDirectoryFileEx devuelve tantas estructuras FILE_XXX_INFORMATION (una por entrada de directorio) como se puede contener completamente en el búfer al que apunta FileInformation:

En la primera llamada, NtQueryDirectoryFileEx devuelve STATUS_SUCCESS solo si el búfer de salida contiene al menos una estructura completa.
En las llamadas posteriores, si el búfer de salida no contiene estructuras, NtQueryDirectoryFileEx devuelve STATUS_SUCCESS pero establece IoStatusBlock-Information> = 0 para notificar al autor de la llamada de esta condición. En este caso, el autor de la llamada debe asignar un búfer mayor y volver a llamar a NtQueryDirectoryFileEx . No se notifica información sobre las entradas restantes. Por lo tanto, excepto en los casos enumerados anteriormente en los que solo se devuelve una entrada, se debe llamar a NtQueryDirectoryFileEx al menos dos veces para enumerar el contenido de un directorio completo.

Al llamar a NtQueryDirectoryFileEx, es posible que vea los cambios realizados en el directorio que se producen en paralelo con las llamadas a NtQueryDirectoryFileEx . Este comportamiento depende de la implementación del sistema de archivos subyacente.

La llamada final a NtQueryDirectoryFileEx devuelve un búfer de salida vacío e informa de un valor de estado adecuado, como STATUS_NO_MORE_FILES.

Si se llama a NtQueryDirectoryFileEx varias veces en el mismo directorio y alguna otra operación cambia el contenido de ese directorio, es posible que se vean los cambios o no, en función del tiempo de las operaciones.

NtQueryDirectoryFileEx devuelve cero en cualquier miembro de una estructura FILE_XXX_INFORMATION que no es compatible con el sistema de archivos.

Los autores de llamadas de NtQueryDirectoryFileEx deben ejecutarse en IRQL = PASSIVE_LEVEL y con las API de kernel especiales habilitadas.

Para obtener información sobre otras rutinas de consulta de información de archivos, vea Objetos de archivo.

Nota

Si la llamada a la función NtQueryDirectoryFileEx se produce en modo kernel, debe usar el nombre "ZwQueryDirectoryFileEx" en lugar de "NtQueryDirectoryFileEx".

En el caso de las llamadas desde controladores en modo kernel, las versiones NtXxx y ZwXxx de una rutina de Windows Native System Services pueden comportarse de forma diferente en la forma en que controlan e interpretan los parámetros de entrada. Para obtener más información sobre la relación entre las versiones NtXxx y ZwXxx de una rutina, vea Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 10, versión 1709
Encabezado	ntifs.h
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (consulte la sección Comentarios)