Funzione FltReadFileEx (fltkernel.h)

Articolo
03/08/2024

FltReadFileEx legge i dati da un file, un flusso o un dispositivo aperti. Questa funzione estende FltReadFile per consentire l'uso facoltativo di un MDL per la lettura dei dati invece di un indirizzo del buffer mappato.

Sintassi

NTSTATUS FLTAPI FltReadFileEx(
  [in]            PFLT_INSTANCE                    InitiatingInstance,
  [in]            PFILE_OBJECT                     FileObject,
  [in, optional]  PLARGE_INTEGER                   ByteOffset,
  [in]            ULONG                            Length,
  [out]           PVOID                            Buffer,
  [in]            FLT_IO_OPERATION_FLAGS           Flags,
  [out, optional] PULONG                           BytesRead,
  [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 da cui devono essere letti i dati. L'oggetto file deve essere aperto. La chiamata a FltReadFileEx 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.

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 FltReadFileEx (e dei filtri ad altitudini più elevate) l'oggetto 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 .

[in] Length

Dimensione, in byte, del buffer a cui punta il parametro Buffer .

[out] Buffer

Puntatore a un buffer allocato dal chiamante che riceve i dati letti dal file. 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 lettura da eseguire.

Contrassegno	Significato
FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET	I driver minifilter possono impostare questo flag per specificare che FltReadFile non deve aggiornare il campo CurrentByteOffset dell'oggetto file.
FLTFL_IO_OPERATION_NON_CACHED	I driver minifilter possono impostare questo flag per specificare una lettura 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 lettura di paging.
FLTFL_IO_OPERATION_SYNCHRONOUS_PAGING	I driver minifilter possono impostare questo flag per specificare una lettura I/O sincrona di paging. I driver minifilter che impostano questo flag devono anche impostare il flag FLTFL_IO_OPERATION_PAGING. Disponibile a partire da Windows Vista.

[out, optional] BytesRead

Puntatore a una variabile allocata dal chiamante che riceve il numero di byte letti dal 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 lettura. Questo parametro è facoltativo e può essere NULL.

[in, optional] CallbackContext

Puntatore di contesto da passare a 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 intervallo di byte.

[in, optional] Mdl

MDL facoltativo che descrive la memoria in cui vengono letti i dati. Se in Buffer viene fornito un buffer, Mdl deve essere NULL.

Valore restituito

FltReadFileEx restituisce il valore NTSTATUS restituito dal file system.

Commenti

Un driver minifilter chiama FltReadFileEx per leggere i dati da un file aperto.

FltReadFileEx crea una richiesta di lettura e la invia 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 lettura.

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

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 viene effettuato un tentativo di lettura oltre la fine del file, FltReadFileEx restituisce un errore.

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

Se il valore del parametro CallbackRoutine è NULL, l'operazione di lettura viene eseguita in modo sincrono. Ovvero FltReadFileEx attende il completamento dell'operazione di lettura 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 FltReadFileEx 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 , FltReadFileEx differisce da ZwReadFile.

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