Función ZwQueryDirectoryFile (ntifs.h)

Artículo
12/22/2024

La rutina ZwQueryDirectoryFile devuelve varias informaciones sobre los archivos del directorio especificados por un identificador de archivo determinado.

Sintaxis

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

Parámetros

[in] FileHandle

Identificador devuelto por ZwCreateFile o ZwOpenFile 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 de null nonull 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 se puede NULL. Debe ser NULL si el autor de la llamada esperará a que el FileHandle se establezca en el estado Signaled.

[in, optional] ApcRoutine

Una dirección de una rutina de APC opcional proporcionada por el autor de la llamada que se va a llamar cuando se completa la operación solicitada. Este parámetro es opcional y se puede 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 envía al objeto de finalización de E/S asociado.

Este parámetro es opcional y se puede 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, se devuelve el número de bytes escritos en el búfer de FileInformation 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 el FileInformationClass especificado.

[in] FileInformationClass

Tipo de información que se va a devolver sobre los archivos del directorio. Consulte el parámetro FileInformationClass de NtQueryDirectoryFileEx para obtener la lista de valores posibles.

[in] ReturnSingleEntry

Establézcalo en TRUE si solo se debe devolver una sola entrada, FALSE de lo contrario. Si este parámetro es TRUE, ZwQueryDirectoryFile devuelve solo la primera entrada que se encuentra.

[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 se incluyen en el examen del directorio los archivos cuyos nombres coinciden con la cadena FileName de .
Si FileName es null, todos los archivos se incluyen si ReturnSingleEntry es FALSE; Se incluye un archivo si ReturnSingleEntry es TRUE.

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

[in] RestartScan

Establézcalo en TRUE si el examen se inicia en la primera entrada del directorio. Establézcalo en FALSE si reanuda el examen desde una llamada anterior.

Cuando se llama a la rutina ZwQueryDirectoryFile para un identificador determinado, el parámetro RestartScan se trata como si se hubiera establecido en TRUE, independientemente de su valor. En las llamadas posteriores ZwQueryDirectoryFile, se respeta el valor del parámetro RestartScan.

Valor devuelto

La rutina ZwQueryDirectoryFile 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. ZwQueryDirectoryFile también devuelve el número de bytes escritos en el búfer FileInformation especificado en el miembro Information de IoStatusBlock. Consulte NtQueryDirectoryFileEx para obtener una lista de algunos códigos de error posibles.

Observaciones

La rutina ZwQueryDirectoryFile devuelve información sobre los archivos contenidos en el directorio representados por FileHandle.

Si se proporciona, FileName determina las entradas incluidas en el examen del directorio para todas las llamadas posteriores a ZwQueryDirectoryFile para un FileHandle determinado.

Si hay al menos una entrada coincidente, ZwQueryDirectoryFile 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 el más pequeño de lo siguiente:

Una entrada, si ReturnSingleEntry es TRUE y FileName es NULL.
Número de entradas que coinciden con la cadena de 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 ZwQueryDirectoryFile, 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 FileInformationbúfer de salida. La parte fija consta de todos los campos excepto la cadena final FileName. En la primera llamada, pero no en las llamadas posteriores, el sistema de E/S garantiza que el búfer sea lo suficientemente grande como para contener la parte fija de la estructura FILE_XXX adecuada_INFORMATION.
Escribe en el búfer de salida tanto de la cadena de FileName como se ajustará.
Devuelve un valor de estado adecuado, como STATUS_BUFFER_OVERFLOW.

En cada llamada, ZwQueryDirectoryFile devuelve tantos FILE_estructuras de_INFORMATION XXX (una por entrada de directorio) como se puede contener completamente en el búfer al que apunta FileInformation:

En la primera llamada, ZwQueryDirectoryFile 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 ninguna estructura, ZwQueryDirectoryFile 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 llamar a ZwQueryDirectoryFile de nuevo. 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, ZwQueryDirectoryFile debe llamarse al menos dos veces para enumerar el contenido de todo un directorio.

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

La llamada final a ZwQueryDirectoryFile 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 ZwQueryDirectoryFile 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.

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

Los autores de llamadas de ZwQueryDirectoryFile deben ejecutarse en IRQL = PASSIVE_LEVEL y con 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 ZwQueryDirectoryFile se produce en modo de usuario, debe usar el nombre "NtQueryDirectoryFile" en lugar de "ZwQueryDirectoryFile".

En el caso de las llamadas desde controladores en modo kernel, las NtXxx y Zwversiones de Xxx de una rutina de Servicios del sistema nativo de Windows 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 de NtXxx y ZwXxx de una rutina, vea Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows XP.
de la plataforma de destino de	Universal
encabezado de	ntifs.h (incluya Ntifs.h)
biblioteca de	NtosKrnl.lib
DLL de	NtosKrnl.exe
irQL	PASSIVE_LEVEL (consulte la sección Comentarios)
reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)