Función FltReadFileEx (fltkernel.h)

FltReadFileEx lee datos de un archivo abierto, secuencia o dispositivo. Esta función extiende fltReadFile para permitir el uso opcional de una MDL para los datos de lectura 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 va a enviar la operación. La instancia debe adjuntarse al volumen donde reside el archivo. Este parámetro es necesario 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 se aserte en una compilación activada. Este parámetro es necesario y no puede ser NULL.

[in, optional] ByteOffset

Puntero a una variable asignada por el autor de la llamada que especifica el desplazamiento inicial de bytes 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 CurrentByteOff set del objeto de archivo.

• Si el archivo se abrió para E/S sincrónica (FO_SYNCHRONOUS_IO se establece en el campo marcas de del objeto de archivo), el autor de la llamada puede establecer ByteOffset->LowPart FILE_USE_FILE_POINTER_POSITION y >>High Part -1 para que la E/S del objeto de archivo se realice en el campo CurrentByteOff set 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 la 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 de CurrentByteOffset antes de enviar la E/S a la pila y restaurarlo cuando se devuelve la E/S. Desde la perspectiva del autor de la llamada de fltReadFileEx (y filtros a alturas más altas), el CurrrentByteOffset no se actualiza. Pero los filtros debajo del autor de la llamada ven el valor actualizado CurrentByteOffset 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 buffer parámetro.

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

[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, este parámetro se omite. 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_CALLBACKpara llamar cuando se complete 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 al CallbackRoutine si hay uno presente. Este parámetro es opcional y puede ser NULL. Si callbackRoutine es NULL, este parámetro se omite.

[in, optional] Key

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 Búfer , mdl debe ser NULL.

Valor devuelto

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

Observaciones

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 anteriormente no reciben la solicitud de lectura.

FltReadFileEx realiza E/S sin almacenamiento en caché si se cumple alguna de las siguientes opciones:

• El autor de la llamada 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, FltCreateFileExo 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 buffer debe alinearse de acuerdo con el requisito de alineación del dispositivo de almacenamiento subyacente. Para asignar este búfer alineado, llame a FltAllocatePoolAlignedWithTag.

• El desplazamiento de bytes al que apunta el ByteOffset parámetro 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 volver. Esto es cierto incluso si el objeto de archivo que FileObject apunta a 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. En este sentido, fltReadFileEx difiere de ZwReadFile.

El parámetro mdl se proporciona como una comodidad cuando un minifiltro ya tiene una MDL disponible. MdL se usa directamente y se puede evitar el paso adicional de asignar una dirección para búfer.

Requisitos

Consulte también

FILE_OBJECT

FltAllocatePoolAlignedWithTag

FltCreateFile

FltCreateFileEx

fltWriteFile de

obReferenceObjectByHandle

PFLT_COMPLETED_ASYNC_IO_CALLBACK

ZwCreateFile

ZwReadFile

ZwWriteFile