Funzione FltWriteFileEx (fltkernel.h)

Articolo
02/26/2024

FltWriteFileEx viene usato per scrivere dati in un file, un flusso o un dispositivo aperto. Questa funzione estende FltWriteFile per consentire l'uso facoltativo di un MDL per la scrittura di dati anziché un indirizzo del buffer mappato.

Sintassi

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

Parametri

[in] InitiatingInstance

Puntatore di istanza opaco per l'istanza del driver minifilter a cui inviare l'operazione. L'istanza deve essere collegata al volume in cui si trova 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. L'oggetto file deve essere aperto. La chiamata a FltWriteFileEx quando l'oggetto file non è ancora aperto o non è più aperto (ad esempio, in una routine di callback di pre-creazione o post-pulizia) fa sì che il sistema asserisce 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 dei 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 operazioni di I/O sincrone (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 fare in modo che l'I/O venga eseguito nel campo CurrentByteOffset dell'oggetto file. Se il file non è stato aperto per operazioni di I/O sincrone, 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 ByteOffset non è specificato:

Se il file non è stato aperto per operazioni di I/O sincrone, si tratta di un errore.
In caso contrario, l'I/O viene eseguito in 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 passi 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 lo ripristina quando l'I/O viene restituito. Dal punto di vista del chiamante di FltWriteFileEx (e dei filtri ad altitudini più elevate) il CurrrentByteOffset non viene aggiornato. Ma i filtri sotto il chiamante vedono il valore CurrentByteOffset aggiornato 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 a cui punta FileObject è stato aperto per l'I/O asincrono, questo parametro è obbligatorio e non può essere NULL.

FltWriteFileEx non supporta il flag FILE_WRITE_TO_END_OF_FILE.

[in] Length

Dimensione, in byte, del buffer a cui punta il parametro Buffer . Se un MDL viene fornito in Mdl, Length è la dimensione dei dati descritti da MDL.

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

Se in Mdl viene fornito un MDL, buffer deve essere NULL.

[in] Flags

Maschera di bit 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 FltWriteFileEx 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 nella cache, 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 di paging. I driver minifilter 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 tipizzata PFLT_COMPLETED_ASYNC_IO_CALLBACK da chiamare al termine dell'operazione di scrittura. Questo parametro è facoltativo e può essere NULL.

[in, optional] CallbackContext

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

[in, optional] Key

Chiave facoltativa associata a un blocco di oggetti file.

[in, optional] Mdl

MDL facoltativo che descrive i dati da scrivere. Se viene fornito un buffer nel buffer, Mdl deve essere NULL.

Valore restituito

FltWriteFileEx restituisce il valore NTSTATUS restituito dal file system.

Commenti

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

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

FltWriteFileEx 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 Flags .
L'oggetto file è stato aperto per operazioni di I/O non memorizzate nella cache. In genere, questa operazione viene eseguita specificando il flag FILE_NO_INTERMEDIATE_BUFFERING_____CreateOptions nella chiamata precedente a FltCreateFile, FltCreateFileEx o ZwCreateFile.

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

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.
L'offset di byte a cui punta il parametro ByteOffset 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. Ovvero FltWriteFileEx attende il completamento dell'operazione di scrittura prima della restituzione. Ciò vale anche se l'oggetto file a cui punta FileObject è stato aperto per l'I/O asincrona.

Se più thread chiamano FltWriteFileEx 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. In questo senso , FltWriteFileEx differisce da ZwWriteFile.

Il parametro Mdl viene fornito per praticità quando un minifilter dispone già di un MDL disponibile. Il linguaggio MDL viene usato direttamente e il passaggio aggiuntivo di mapping di un indirizzo per Buffer può essere evitato.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8
Piattaforma di destinazione	Universale
Intestazione	fltkernel.h (include Fltkernel.h)
Libreria	FltMgr.lib
DLL	Fltmgr.sys
IRQL	PASSIVE_LEVEL