Función FltReadFileEx (fltkernel.h)
FltReadFileEx lee datos de un archivo, secuencia o dispositivo abiertos. Esta función extiende FltReadFile para permitir el uso opcional de mdl para leer datos en lugar de una dirección de búfer asignada.
Sintaxis
NTSTATUS FLTAPI FltReadFileEx(
[in] PFLT_INSTANCE InitiatingInstance,
[in] PFILE_OBJECT FileObject,
[in, optional] PLARGE_INTEGER ByteOffset,
[in] ULONG Length,
[out] PVOID Buffer,
[in] FLT_IO_OPERATION_FLAGS Flags,
[out, optional] PULONG BytesRead,
[in, optional] PFLT_COMPLETED_ASYNC_IO_CALLBACK CallbackRoutine,
[in, optional] PVOID CallbackContext,
[in, optional] PULONG Key,
[in, optional] PMDL Mdl
);
Parámetros
[in] InitiatingInstance
Puntero de instancia opaco para la instancia del controlador de minifiltro a la que se enviará la operación. La instancia debe adjuntarse al volumen donde reside el archivo. Este parámetro es obligatorio y no puede ser NULL.
[in] FileObject
Puntero a un FILE_OBJECT para el archivo desde el que se van a leer los datos. Este objeto de archivo debe estar abierto actualmente. Llamar a FltReadFileEx cuando el objeto de archivo aún no está abierto o ya no está abierto (por ejemplo, en una rutina de devolución de llamada anterior o posterior a la limpieza) hace que el sistema aserte en una compilación comprobada. Este parámetro es obligatorio y no puede ser NULL.
[in, optional] ByteOffset
Puntero a una variable asignada por el autor de la llamada que especifica el desplazamiento de bytes inicial dentro del archivo donde se va a iniciar la operación de lectura.
Si se especifica ByteOffset , la E/S se realiza en ese desplazamiento, independientemente del valor actual del campo CurrentByteOffset del objeto de archivo.
- Si el archivo se abrió para E/S sincrónica (FO_SYNCHRONOUS_IO se establece en el campo Flags del objeto de archivo), el autor de la llamada puede establecer ByteOffset-LowPart> en FILE_USE_FILE_POINTER_POSITION y ByteOffset-HighPart> en -1 para que la E/S del objeto de archivo se realice en el campo CurrentByteOffset del objeto de archivo.
- Si el archivo no se abrió para E/S sincrónica, el uso de FILE_USE_FILE_POINTER_POSITION es un error.
Si no se especifica ByteOffset :
- Si el archivo no se abrió para E/S sincrónica, se trata de un error.
- De lo contrario, la E/S se realiza en currentByteOffset del objeto de archivo.
Si el objeto de archivo se abrió para E/S sincrónica, el campo CurrentByteOffset se actualiza a menos que el autor de la llamada pase la marca FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET.
- Nota: el sistema de archivos sigue actualizando CurrentByteOffset en este caso. El Administrador de filtros guarda el valor CurrentByteOffset antes de enviar la E/S a la pila y lo restaura cuando se devuelve la E/S. Desde la perspectiva del autor de la llamada de FltReadFileEx (y filtros a una altitud superior), el CurrrentByteOffset no se actualiza. Pero los filtros debajo del autor de la llamada ven el valor currentByteOffset actualizado en sus devoluciones de llamada posteriores a la lectura y escritura.
Si el objeto de archivo no se abrió para E/S sincrónica, el campo CurrentByteOffset no se actualiza independientemente del estado del parámetro ByteOffset .
[in] Length
Tamaño, en bytes, del búfer al que apunta el parámetro Buffer .
[out] Buffer
Puntero a un búfer asignado por el autor de la llamada que recibe los datos leídos del archivo. Si se proporciona una MDL en Mdl, El búfer debe ser NULL.
[in] Flags
Máscara de bits de marcas que especifican el tipo de operación de lectura que se va a realizar.
| Marca | Significado |
|---|---|
| FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET | Los controladores de minifiltro pueden establecer esta marca para especificar que FltReadFile no debe actualizar el campo CurrentByteOffset del objeto de archivo. |
| FLTFL_IO_OPERATION_NON_CACHED | Los controladores de minifiltro pueden establecer esta marca para especificar una lectura no almacenada en caché, incluso si el objeto de archivo no se abrió con FILE_NO_INTERMEDIATE_BUFFERING. |
| FLTFL_IO_OPERATION_PAGING | Los controladores de minifiltro pueden establecer esta marca para especificar una lectura de paginación. |
| FLTFL_IO_OPERATION_SYNCHRONOUS_PAGING | Los controladores de minifiltro pueden establecer esta marca para especificar una lectura de E/S de paginación sincrónica. Los controladores de minifiltro que establecen esta marca también deben establecer la marca FLTFL_IO_OPERATION_PAGING. Disponible a partir de Windows Vista. |
[out, optional] BytesRead
Puntero a una variable asignada por el autor de la llamada que recibe el número de bytes leídos del archivo. Si CallbackRoutine no es NULL, se omite este parámetro. De lo contrario, este parámetro es opcional y puede ser NULL.
[in, optional] CallbackRoutine
Puntero a una rutina de devolución de llamada con tipo PFLT_COMPLETED_ASYNC_IO_CALLBACK para llamar cuando se completa la operación de lectura. Este parámetro es opcional y puede ser NULL.
[in, optional] CallbackContext
Puntero de contexto que se va a pasar a CallbackRoutine si hay uno presente. Este parámetro es opcional y puede ser NULL. Si CallbackRoutine es NULL, se omite este parámetro.
[in, optional] Key
Una clave opcional asociada a un bloqueo de intervalo de bytes.
[in, optional] Mdl
MdL opcional que describe la memoria donde se leen los datos. Si se proporciona un búfer en buffer , Mdl debe ser NULL.
Valor devuelto
FltReadFileEx devuelve el valor NTSTATUS devuelto por el sistema de archivos.
Comentarios
Un controlador de minifiltro llama a FltReadFileEx para leer datos de un archivo abierto.
FltReadFileEx crea una solicitud de lectura y la envía a las instancias del controlador de minifiltro adjuntas debajo de la instancia de inicio y al sistema de archivos. La instancia especificada y las instancias adjuntas encima no reciben la solicitud de lectura.
FltReadFileEx realiza E/S sin almacenamiento en caché si se cumple alguna de las siguientes condiciones:
El llamador establece la marca FLTFL_IO_OPERATION_NON_CACHED en el parámetro Flags .
El objeto de archivo se abrió para E/S sin almacenamiento en caché. Normalmente, esto se hace especificando la marca FILE_NO_INTERMEDIATE_BUFFERING CreateOptions en la llamada anterior a FltCreateFile, FltCreateFileEx o ZwCreateFile.
La E/S no almacenada en caché impone las siguientes restricciones en los valores de parámetro pasados a FltReadFileEx:
El búfer al que apunta el parámetro Buffer debe alinearse de acuerdo con el requisito de alineación del dispositivo de almacenamiento subyacente. Para asignar este tipo de búfer alineado, llame a FltAllocatePoolAlignedWithTag.
Desplazamiento de bytes al que apunta el parámetro ByteOffset debe ser un múltiplo no negativo del tamaño del sector del volumen.
La longitud especificada en el parámetro Length debe ser un múltiplo no negativo del tamaño del sector del volumen.
Si se intenta leer más allá del final del archivo, FltReadFileEx devuelve un error.
Si el valor del parámetro CallbackRoutine no es NULL, la operación de lectura se realiza de forma asincrónica.
Si el valor del parámetro CallbackRoutine es NULL, la operación de lectura se realiza de forma sincrónica. Es decir, FltReadFileEx espera hasta que se complete la operación de lectura antes de devolver. Esto es cierto incluso si el objeto de archivo al que apunta FileObject se abrió para E/S asincrónica.
Si varios subprocesos llaman a FltReadFileEx para el mismo objeto de archivo y el objeto de archivo se abrió para E/S sincrónica, el administrador de filtros no intenta serializar E/S en el archivo. A este respecto, FltReadFileEx difiere de ZwReadFile.
El parámetro Mdl se proporciona como una comodidad cuando un minifiltro ya tiene un MDL disponible. MdL se usa directamente y se puede evitar el paso adicional de asignación de una dirección para el búfer .
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows 8 |
| Plataforma de destino | Universal |
| Encabezado | fltkernel.h (incluya Fltkernel.h) |
| Library | FltMgr.lib |
| Archivo DLL | Fltmgr.sys |
| IRQL | PASSIVE_LEVEL |