Función FltQueryDirectoryFile (fltkernel.h)

Artículo
08/07/2023

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

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 la clase FileInformationClass especificada.

[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

Se establece en TRUE si solo se debe devolver una sola entrada; de lo contrario, false. 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 puede ser NULL.

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

[in] RestartScan

Se establece en TRUE si el examen se inicia en la primera entrada del directorio. Establezca 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.

Comentarios

FltQueryDirectoryFile devuelve información sobre los archivos contenidos 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, FileName y RestartScan. Si hay al menos una entrada coincidente, FltQueryDirectoryFile crea una estructura FILE_XXX_INFORMATION (vea 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 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 cabe en el 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 caber en el 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 FileName final. 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 FILE_XXX_INFORMATION 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 tantas estructuras FILE_XXX_INFORMATION (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, se debe llamar a FltQueryDirectoryFile 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 se llama a FltQueryDirectoryFile 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 llamadas posteriores, FltQueryDirectoryFile reanuda el examen del directorio dondequiera que se dejó en esta misma enumeración. Sin embargo, entre 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 FILE_XXX_INFORMATION que no es 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, vea Deshabilitar LAS API.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista
Plataforma de destino	Universal
Encabezado	fltkernel.h (incluya Fltkernel.h)
Library	FltMgr.lib
Archivo DLL	Fltmgr.sys
IRQL	PASSIVE_LEVEL (consulte la sección Comentarios)