Función FltQueryDirectoryFileEx (fltkernel.h)

Artículo
07/16/2024

fltQueryDirectoryFileEx devuelve varios tipos de información sobre los archivos del directorio especificados por un objeto de archivo determinado.

Sintaxis

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

Parámetros

Instance

Puntero opaco a la instancia del controlador de minifiltro que está iniciando esta E/S.

FileObject

Puntero al objeto de archivo que representa el directorio que se está consultando.

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.

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.

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.

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)	Si se establece esta marca, 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)	Si se establece esta marca, el examen debe iniciarse en una posición indizada especificada en el directorio. Esta marca solo se puede establecer si genera su propia IRP_MJ_DIRECTORY_CONTROL IRP; el índice se especifica en 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)	Si se establece esta marca, los filtros del sistema de archivos que realicen la virtualización de directorios o la expansión Just-In-Time simplemente deben pasar la solicitud al sistema de archivos y devolver entradas que están actualmente en el 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 de directorio porFileObject. Cuando varios subprocesos realizan consultas con el mismo FileObject, el acceso a la estructura FileObject por es un solo subproceso para evitar daños en el estado del cursor. Esta marca indica al sistema de archivos que no actualice porFileObject información de estado del cursor, lo que permite que varios subprocesos realicen consultas en paralelo mediante 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 compatibilidad con consultas de directorio asincrónica verdadera. 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.

FileName

Puntero a una estructura de UNICODE_STRING asignada por el autor de la llamada con la cadena Unicode 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 es NULL, se incluyen todos los archivos.

Si FileName no es null, solo se incluyen en el examen del directorio los archivos cuyos nombres coinciden con la cadena FileName de . Si se establece la marca de QueryFlagsResetScan, se omite el valor de FileName.

LengthReturned

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

Valor devuelto

fltQueryDirectoryFileEx devuelve STATUS_SUCCESS o un código de error adecuado. El conjunto de valores de estado de error que se pueden devolver es específico del sistema de archivos.

Observaciones

FltQueryDirectoryFileEx devuelve información sobre los archivos contenidos en el directorio representados por FileObject.

La primera llamada a FltQueryDirectoryFileEx 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 QueryFlags y FileName. Si hay al menos una entrada coincidente, FltQueryDirectoryFileEx crea una estructura 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 la marca de SL_RETURN_SINGLE_ENTRY se establece en QueryFlags 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 cabe en el búfer al que apunta FileInformation.
Número de entradas contenidas en el directorio.

En la primera llamada a FltQueryDirectoryFileEx, si la estructura creada para la primera entrada encontrada es 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 final FileName. El subsistema de E/S garantiza que el búfer es lo suficientemente grande como para contener la parte fija de la estructura_INFORMATION XXX adecuada FILE_(solo en la primera llamada y no en las llamadas posteriores). Cuando esto sucede, fltQueryDirectoryFileEx devuelve un valor de estado de STATUS_BUFFER_OVERFLOW. También en la primera llamada a fltQueryDirectoryFileEx, si no hay ningún archivo en el directorio FileObject que coincida con el parámetro fileName , FltQueryDirectoryFileEx devuelve STATUS_NO_SUCH_FILE.

En cada llamada, FltQueryDirectoryFileEx devuelve tantas estructuras de_INFORMATION XXX FILE_(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, fltQueryDirectoryFileEx 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 FltQueryDirectoryFileEx devuelve un búfer de salida vacío e informa de un valor de estado no error de STATUS_NO_MORE_FILES.

Nota: Cuando fltQueryDirectoryFileEx 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 fija en la primera llamada a FltQueryDirectoryFileEx. En las llamadas posteriores, FltQueryDirectoryFileEx reanuda el examen del directorio siempre que se quede en esta misma enumeración. Sin embargo, entre las llamadas a FltQueryDirectoryFileEx, las entradas de directorio reales pueden cambiar para que ya no estén sincronizadas con la enumeración original.

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

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