Función FltWriteFileEx (fltkernel.h)

Artículo
02/26/2024

FltWriteFileEx se usa para escribir datos en un archivo abierto, secuencia o dispositivo. Esta función extiende FltWriteFile para permitir el uso opcional de una MDL para escribir datos en lugar de una dirección de búfer asignada.

Sintaxis

NTSTATUS FLTAPI FltWriteFileEx(
  [in]            PFLT_INSTANCE                    InitiatingInstance,
  [in]            PFILE_OBJECT                     FileObject,
  [in, optional]  PLARGE_INTEGER                   ByteOffset,
  [in]            ULONG                            Length,
  [in]            PVOID                            Buffer,
  [in]            FLT_IO_OPERATION_FLAGS           Flags,
  [out, optional] PULONG                           BytesWritten,
  [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 obligatorio y no puede ser NULL.

[in] FileObject

Puntero a un FILE_OBJECT para el archivo en el que se van a escribir los datos. Este objeto de archivo debe estar abierto actualmente. Llamar a FltWriteFileEx 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 Marcas 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.
El autor de la llamada puede establecer ByteOffset-LowPart> en FILE_WRITE_TO_END_OF_FILE y ByteOffset-HighPart> en -1 para iniciar la escritura al final del archivo (es decir, realizar una escritura anexada).

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 de 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 FltWriteFileEx (y filtros a mayor altitud), 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 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 .

Si el objeto de archivo al que apunta FileObject se abrió para E/S asincrónica, este parámetro es necesario y no puede ser NULL.

FltWriteFileEx no admite la marca FILE_WRITE_TO_END_OF_FILE.

[in] Length

Tamaño, en bytes, del búfer al que apunta el parámetro Buffer . Si se proporciona una MDL en Mdl, Length es el tamaño de los datos que describe MDL.

[in] Buffer

Puntero a un búfer que contiene los datos que se van a escribir en el archivo. Si el archivo se abre para E/S no almacenado en caché, este búfer debe alinearse de acuerdo con el requisito de alineación del dispositivo de almacenamiento subyacente. Los controladores de minifiltro pueden asignar este búfer alineado llamando a FltAllocatePoolAlignedWithTag.

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 escritura 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 FltWriteFileEx no actualizará el campo CurrentByteOffset del objeto de archivo.
FLTFL_IO_OPERATION_NON_CACHED	Los controladores de minifiltro pueden establecer esta marca para especificar una escritura 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 escritura de paginación.
FLTFL_IO_OPERATION_SYNCHRONOUS_PAGING	Los controladores de minifiltro pueden establecer esta marca para especificar una escritura 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. Esta marca está disponible a partir de Windows Vista.

[out, optional] BytesWritten

Puntero a una variable asignada por el autor de la llamada que recibe el número de bytes escritos en el 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_CALLBACK para llamar cuando se complete la operación de escritura. Este parámetro es opcional y puede ser NULL.

[in, optional] CallbackContext

Puntero de contexto que se va a pasar a la rutina en 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

Una clave opcional asociada a un bloqueo de objeto de archivo.

[in, optional] Mdl

MdL opcional que describe los datos que se van a escribir. Si se proporciona un búfer en buffer, Mdl debe ser NULL.

Valor devuelto

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

Comentarios

Un controlador de minifiltro llama a FltWriteFileEx para escribir datos en un archivo abierto.

FltWriteFileEx hace que se envíe una solicitud de escritura a las instancias del controlador de minifiltro asociadas debajo de la instancia de inicio y al sistema de archivos. La instancia especificada y las instancias adjuntas encima no reciben la solicitud de escritura.

FltWriteFileEx realiza una E/S no almacenada en caché si se cumple alguna de las siguientes condiciones:

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 la E/S no almacenada 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 FltWriteFileEx:

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 búfer alineado, llame a FltAllocatePoolAlignedWithTag.
El 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 el valor del parámetro CallbackRoutine no es NULL, la operación de escritura se realiza de forma asincrónica.

Si el valor del parámetro CallbackRoutine es NULL, la operación de escritura se realiza de forma sincrónica. Es decir, FltWriteFileEx espera hasta que se complete la operación de escritura 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 FltWriteFileEx 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, FltWriteFileEx difiere de ZwWriteFile.

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