Funzione FltWriteFile (fltkernel.h)

Articolo
02/06/2025

FltWriteFile viene usato per scrivere dati in un file, un flusso o un dispositivo aperto.

Sintassi

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

Parametri

[in] InitiatingInstance

Puntatore a un'istanza opaca per l'istanza del driver minifiltro a cui deve essere inviata l'operazione. L'istanza deve essere collegata al volume in cui risiede il file. Questo parametro è obbligatorio e non può essere NULL.

[in] FileObject

Puntatore a un FILE_OBJECT per il file in cui devono essere scritti i dati. Questo oggetto file deve essere attualmente aperto. La chiamata a FltWriteFile quando l'oggetto file non è ancora aperto o non è più aperto (ad esempio, in una routine di callback pre-creazione o post-pulizia) fa sì che il sistema asseri in una compilazione controllata. Questo parametro è obbligatorio e non può essere NULL.

[in, optional] ByteOffset

Puntatore a una variabile allocata dal chiamante che specifica l'offset di byte iniziale all'interno del file in cui deve iniziare l'operazione di lettura.

Se viene specificato ByteOffset, l'I/O viene eseguito in corrispondenza di tale offset, indipendentemente dal valore corrente del campo CurrentByteOff set dell'oggetto file.

Se il file è stato aperto per l'I/O sincrono (FO_SYNCHRONOUS_IO è impostato nel campo Flag dell'oggetto file), il chiamante può impostare ByteOffset->LowPart per FILE_USE_FILE_POINTER_POSITION e ByteOffset->HighPart per -1 per eseguire l'I/O nel campo CurrentByteOff set dell'oggetto file. Se il file non è stato aperto per l'I/O sincrono, l'uso di FILE_USE_FILE_POINTER_POSITION è un errore.
Il chiamante può impostare ByteOffset->LowPart su FILE_WRITE_TO_END_OF_FILE e ByteOffset->HighPart su -1 per avviare la scrittura alla fine del file (ad esempio, eseguire una scrittura di accodamento).

Se non viene specificato ByteOffset:

Se il file non è stato aperto per l'I/O sincrono, si tratta di un errore.
In caso contrario, l'I/O viene eseguito nel CurrentByteOffset dell'oggetto file.

Se l'oggetto file è stato aperto per operazioni di I/O sincrone, il campo CurrentByteOffset viene aggiornato a meno che il chiamante non superi il flag FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET.

Nota: il file system aggiorna ancora CurrentByteOffset in questo caso. Gestione filtri salva il valore CurrentByteOffset prima di inviare l'I/O verso il basso nello stack e ripristinarlo quando viene restituito l'I/O. Dal punto di vista del chiamante di FltWriteFile (e filtri ad altitudini più elevate) il CurrrentByteOffset non viene aggiornato. Ma i filtri sotto il chiamante visualizzano il valore aggiornato CurrentByteOffset nei callback post-lettura/scrittura.

Se l'oggetto file non è stato aperto per operazioni di I/O sincrone, il campo CurrentByteOffset non viene aggiornato indipendentemente dallo stato del parametro ByteOffset.

Se l'oggetto file che FileObject punta a è stato aperto per l'I/O asincrono, questo parametro è obbligatorio e non può essere NULL.

Prima di Windows 8, le costanti speciali FILE_WRITE_TO_END_OF_FILE e FILE_USE_FILE_POINTER_POSITION non sono supportate per questo parametro.

[in] Length

Dimensioni, in byte, del buffer a cui punta il parametro buffer.

[in] Buffer

Puntatore a un buffer contenente i dati da scrivere nel file. Se il file viene aperto per le operazioni di I/O non memorizzate nella cache, questo buffer deve essere allineato in base al requisito di allineamento del dispositivo di archiviazione sottostante. I driver minifilter possono allocare un buffer allineato chiamando FltAllocatePoolAlignedWithTag.

[in] Flags

Maschera di bit di flag che specifica il tipo di operazione di scrittura da eseguire.

Bandiera	Significato
FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET	I driver minifilter possono impostare questo flag per specificare che fltWriteFile non aggiornerà il campo currentByteOffset dell'oggetto file.
FLTFL_IO_OPERATION_NON_CACHED	I driver minifiltro possono impostare questo flag per specificare una scrittura non memorizzata nella cache, anche se l'oggetto file non è stato aperto con FILE_NO_INTERMEDIATE_BUFFERING.
FLTFL_IO_OPERATION_PAGING	I driver minifiltro possono impostare questo flag per specificare una scrittura di paging.
FLTFL_IO_OPERATION_SYNCHRONOUS_PAGING	I driver minifilter possono impostare questo flag per specificare una scrittura di I/O sincrona di paging. I driver minifiltro che impostano questo flag devono anche impostare il flag FLTFL_IO_OPERATION_PAGING. Questo flag è disponibile a partire da Windows Vista.

[out, optional] BytesWritten

Puntatore a una variabile allocata dal chiamante che riceve il numero di byte scritti nel file. Se callbackRoutine non è NULL, questo parametro viene ignorato. In caso contrario, questo parametro è facoltativo e può essere NULL.

[in, optional] CallbackRoutine

Puntatore a una routine di callback PFLT_COMPLETED_ASYNC_IO_CALLBACKtipizzata da chiamare al termine dell'operazione di scrittura. Questo parametro è facoltativo e può essere NULL.

[in, optional] CallbackContext

Puntatore di contesto da passare al CallbackRoutine se presente. Questo parametro è facoltativo e può essere NULL. Se callbackRoutine è NULL, questo parametro viene ignorato.

Valore restituito

FltWriteFile restituisce il valore NTSTATUS restituito dal file system.

Osservazioni

Un driver minifilter chiama FltWriteFile per scrivere dati in un file aperto.

FltWriteFile fa sì che una richiesta di scrittura venga inviata alle istanze del driver minifilter collegate sotto l'istanza di avvio e al file system. L'istanza specificata e le istanze associate sopra non ricevono la richiesta di scrittura.

FltWriteFile esegue operazioni di I/O non memorizzate nella cache se una delle condizioni seguenti è vera:

Il chiamante imposta il flag FLTFL_IO_OPERATION_NON_CACHED nel parametro flag.
L'oggetto file è stato aperto per le operazioni di I/O non memorizzate nella cache. In genere, questa operazione viene eseguita specificando il flag CreateOptions FILE_NO_INTERMEDIATE_BUFFERING nella chiamata precedente a FltCreateFile, FltCreateFileExo ZwCreateFile.

L'I/O non memorizzato nella cache impone le restrizioni seguenti sui valori dei parametri passati a FltWriteFile:

Il buffer a cui punta il parametro buffer deve essere allineato in base al requisito di allineamento del dispositivo di archiviazione sottostante. Per allocare un buffer allineato di questo tipo, chiamare FltAllocatePoolAlignedWithTag.
Offset di byte che il parametro ByteOffset punta deve essere un multiplo non negativo delle dimensioni del settore del volume.
La lunghezza specificata nel parametro Length deve essere un multiplo non negativo delle dimensioni del settore del volume.

Se il valore del parametro CallbackRoutine non è NULL, l'operazione di scrittura viene eseguita in modo asincrono.

Se il valore del parametro callbackRoutine è NULL, l'operazione di scrittura viene eseguita in modo sincrono. Ciò significa che FltWriteFile attende il completamento dell'operazione di scrittura prima della restituzione. Questo vale anche se l'oggetto file che FileObject punta a è stato aperto per l'I/O asincrona.

Se più thread chiamano FltWriteFile per lo stesso oggetto file e l'oggetto file è stato aperto per operazioni di I/O sincrone, Gestione filtri non tenta di serializzare I/O nel file. A questo proposito, FltWriteFile differisce da ZwWriteFile.