Función FltReadFile (fltkernel.h)

FltReadFile lee los datos de un archivo, secuencia o dispositivo abiertos.

Sintaxis

NTSTATUS FLTAPI FltReadFile(
  [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
);

Parámetros

[in] InitiatingInstance

Puntero de instancia opaco para la instancia del controlador de minifiltro a la que se va a 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 FltReadFile 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 activada. 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 FltReadFile (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.

[in] Flags

Máscara de bits de marcas que especifican el tipo de operación de lectura que se va a realizar.

[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.

Valor devuelto

FltReadFile devuelve el valor NTSTATUS devuelto por el sistema de archivos.

Comentarios

Un controlador de minifiltro llama a FltReadFile para leer datos de un archivo abierto.

FltReadFile 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.

FltReadFile 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 FltReadFile:

• 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, FltReadFile 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, FltReadFile 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 FltReadFile 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, FltReadFile difiere de ZwReadFile.

Requisitos

Consulte también

FILE_OBJECT

FltAllocatePoolAlignedWithTag

FltCreateFile

FltCreateFileEx

FltWriteFile

ObReferenceObjectByHandle

PFLT_COMPLETED_ASYNC_IO_CALLBACK

ZwCreateFile

ZwReadFile

ZwWriteFile