Función FltQueryDirectoryFile (fltkernel.h)

Artículo
12/21/2024

La rutina FltQueryDirectoryFile devuelve varios tipos de información sobre los archivos del directorio especificado por un objeto de archivo determinado. Use FltQueryDirectoryFileEx para un mayor control de consultas.

Sintaxis

NTSTATUS FLTAPI FltQueryDirectoryFile(
  [in]            PFLT_INSTANCE          Instance,
  [in]            PFILE_OBJECT           FileObject,
  [out]           PVOID                  FileInformation,
  [in]            ULONG                  Length,
  [in]            FILE_INFORMATION_CLASS FileInformationClass,
  [in]            BOOLEAN                ReturnSingleEntry,
  [in, optional]  PUNICODE_STRING        FileName,
  [in]            BOOLEAN                RestartScan,
  [out, optional] PULONG                 LengthReturned
);

Parámetros

[in] Instance

Puntero opaco a la instancia del controlador de filtro que inicia la E/S.

[in] FileObject

Puntero al objeto de archivo que representa el directorio que se va a examinar.

[out] FileInformation

Puntero a un búfer 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, FltQueryDirectoryFile devuelve solo la primera entrada que se encuentra.

[in, optional] FileName

Puntero 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 FileObject. Este parámetro es opcional y se puede NULL.

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, se incluyen todos los archivos. Si RestartScan es FALSE, se omite el valor de FileName.

[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. El autor de la llamada debe establecer este parámetro en TRUE al llamar a FltQueryDirectoryFile por primera vez.

[out, optional] LengthReturned

Recibe el número de bytes escritos realmente en el búfer FileInformation especificado.

Valor devuelto

fltQueryDirectoryFile devuelve STATUS_SUCCESS o un estado de error adecuado. Tenga en cuenta que el conjunto de valores de estado de error que se pueden devolver es específico del sistema de archivos.

Observaciones

FltQueryDirectoryFile devuelve información sobre los archivos que se encuentran en el directorio representado por FileObject.

La primera llamada a FltQueryDirectoryFile determina el conjunto de entradas que se incluirán en el examen del directorio para todas las llamadas posteriores, en función de los valores de ReturnSingleEntry, FileNamey RestartScan. Si hay al menos una entrada coincidente, FltQueryDirectoryFile crea una estructura de FILE_XXX_INFORMATION (consulte la tabla anterior) para cada entrada a su vez y almacena la estructura 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 ReturnSingleEntry es TRUE y FileName es NULL.
Número de entradas que coinciden con la cadena de FileName, si fileName no es NULL. (Tenga en cuenta que 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 FltQueryDirectoryFile, si la estructura creada para la primera entrada encontró demasiado grande para ajustarse al búfer de salida, solo se devuelve la parte fija de la estructura. La parte fija consta de todos los campos de la estructura, excepto la cadena final FileName. En la primera llamada, pero no en las posteriores, el sistema de E/S garantiza que el búfer es lo suficientemente grande como para contener la parte fija de la estructura_INFORMATION FILE_XXX adecuada. Cuando esto sucede, fltQueryDirectoryFile devuelve un valor de estado adecuado, como STATUS_BUFFER_OVERFLOW. También en la primera llamada a fltQueryDirectoryFile, si no hay ningún archivo en el directorio FileObject que coincida con el parámetro FileName, FltQueryDirectoryFile devuelve un valor de estado adecuado, como STATUS_NO_SUCH_FILE.

En cada llamada, FltQueryDirectoryFile 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. Siempre que el búfer de salida contenga al menos una estructura completa, el valor de estado devuelto se STATUS_SUCCESS. 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, fltQueryDirectoryFile debe llamarse al menos dos veces para enumerar el contenido de un directorio completo (por ejemplo, cuando el parámetro FileName contiene uno o varios caracteres comodín o es NULL).

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

Nota

Cuando fltQueryDirectoryFile se llama varias veces en el mismo directorio, es posible que el número de entradas para las que se devuelva información será menor de lo esperado. Esto se debe a que el conjunto de entradas que se van a incluir en el examen del directorio se ha corregido en la primera llamada a FltQueryDirectoryFile. En las llamadas posteriores, FltQueryDirectoryFile reanuda el examen del directorio siempre que se haya dejado en esta misma enumeración. Sin embargo, entre las llamadas a FltQueryDirectoryFile, las entradas de directorio reales pueden cambiar para que ya no estén sincronizadas con la enumeración original.

fltQueryDirectoryFile devuelve cero en cualquier miembro de una estructura de_INFORMATION XXX FILE_que no sea compatible con el sistema de archivos.

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

Los autores de llamadas de FltQueryDirectoryFile deben ejecutarse en IRQL = PASSIVE_LEVEL y con las API habilitadas. Para obtener más información, consulte Deshabilitación de las API.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows Vista
de la plataforma de destino de	Universal
encabezado de	fltkernel.h (incluya Fltkernel.h)
biblioteca de	FltMgr.lib
DLL de	Fltmgr.sys
irQL	PASSIVE_LEVEL (consulte la sección Comentarios)