Función FltWriteFile (fltkernel.h)

Artículo
11/16/2023

FltWriteFile se usa para escribir datos en un archivo, secuencia o dispositivo abiertos.

Sintaxis

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

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 en el que se van a escribir los datos. Este objeto de archivo debe estar abierto actualmente. Llamar a FltWriteFile 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.
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 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 FltWriteFile (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 .

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.

Antes de Windows 8, las constantes especiales FILE_WRITE_TO_END_OF_FILE y FILE_USE_FILE_POINTER_POSITION no se admiten para este parámetro.

[in] Length

Tamaño, en bytes, del búfer al que apunta el parámetro Buffer .

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

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

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

Comentarios

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

FltWriteFile hace que se envíe una solicitud de escritura 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 escritura.

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

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 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, FltWriteFile espera hasta que se complete la operación de escritura antes de volver. 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 FltWriteFile 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, FltWriteFile difiere de ZwWriteFile.