Funzione FltWriteFile (fltkernel.h)

Articolo
11/16/2023

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

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 di istanza opaco per l'istanza del driver minifilter 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 a cui devono essere scritti i dati. Questo oggetto file deve essere aperto. La chiamata a FltWriteFile quando l'oggetto file non è ancora aperto o non è più aperto (ad esempio, in una routine di callback di pre-creazione o post-pulizia) causa l'asserzione del sistema in una compilazione selezionata. Questo parametro è obbligatorio e non può essere NULL.

[in, optional] ByteOffset

Puntatore a una variabile allocata del 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 CurrentByteOffset dell'oggetto file.

Se il file è stato aperto per I/O sincrono (FO_SYNCHRONOUS_IO è impostato nel campo Flags dell'oggetto file), il chiamante può impostare ByteOffset-LowPart su FILE_USE_FILE_POINTER_POSITION e ByteOffset-HighPart>> su -1 per avere l'I/O eseguito nel campo CurrentByteOffset dell'oggetto file. Se il file non è stato aperto per L/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, ovvero eseguire una scrittura di accodamento.

Se ByteOffset non è specificato:

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

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

Nota: il file system aggiorna ancora CurrentByteOffset in questo caso. Filter Manager salva il valore CurrentByteOffset prima di inviare lo stack di I/O e ripristinarlo quando restituisce l'I/O. Dal punto di vista del chiamante di FltWriteFile (e filtri a altitudini superiori) il CurrrentByteOffset non viene aggiornato. Ma i filtri sotto il chiamante visualizzano il valore CurrentByteOffset aggiornato nei callback post-lettura/scrittura.

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

Se l'oggetto file a cui fa riferimento FileObject è stato aperto per 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 che contiene i dati da scrivere nel file. Se il file viene aperto per I/O non crittografato, 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 flag che specificano il tipo di operazione di scrittura da eseguire.

Contrassegno	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 minifilter possono impostare questo flag per specificare una scrittura non memorizzata, anche se l'oggetto file non è stato aperto con FILE_NO_INTERMEDIATE_BUFFERING.
FLTFL_IO_OPERATION_PAGING	I driver minifilter 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. I driver minifilter che impostano questo flag devono anche impostare il flag di 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_CALLBACK tipizzata 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.

Commenti

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

FltWriteFile causa l'invio di una richiesta di scrittura alle istanze del driver minifilter associate 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 incached se uno dei seguenti è true:

Il chiamante imposta il flag FLTFL_IO_OPERATION_NON_CACHED nel parametro Flags .
L'oggetto file è stato aperto per I/O non incached. In genere, questa operazione viene eseguita specificando il flag FILE_NO_INTERMEDIATE_BUFFERING CreateOptions nella chiamata precedente a FltCreateFile, FltCreateFileEx o ZwCreateFile.

I/O non incached 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, chiamare FltAllocatePoolAlignedWithTag.
Offset di byte che il parametro ByteOffset punta a deve essere un multiplo nonnegative delle dimensioni del settore del volume.
La lunghezza specificata nel parametro Length deve essere un multiplo nonnegative 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. Ovvero, FltWriteFile attende fino al completamento dell'operazione di scrittura prima di restituire. Questo valore è vero anche se l'oggetto file a cui Fa riferimento FileObject è stato aperto per L/O asincrona.

Se più thread chiamano FltWriteFile per lo stesso oggetto file e l'oggetto file è stato aperto per I/O sincrono, Filter Manager non tenta di serializzare I/O nel file. In questo senso, FltWriteFile differisce da ZwWriteFile.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	fltkernel.h (includere Fltkernel.h)
Libreria	FltMgr.lib
DLL	Fltmgr.sys
IRQL	PASSIVE_LEVEL