Funzione FltReadFile (fltkernel.h)

Articolo
02/06/2025

FltReadFile legge i dati da un file, un flusso o un dispositivo aperti.

Sintassi

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

Parametri

[in] InitiatingInstance

Puntatore a istanze opache 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 da cui devono essere letti i dati. Questo oggetto file deve essere attualmente aperto. La chiamata di FltReadFile 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 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.

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 FltReadFile (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.

[in] Length

Dimensioni, 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.

[in] Flags

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

Bandiera	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 minifiltro 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 minifiltro 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 PFLT_COMPLETED_ASYNC_IO_CALLBACKtipizzata da chiamare al termine dell'operazione di lettura. 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

FltReadFile restituisce il valore NTSTATUS restituito dal file system.

Osservazioni

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

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

FltReadFile esegue operazioni di I/O non memorizzate in 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 FltReadFile:

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 si tenta di leggere oltre la fine del file, FltReadFile 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. Ciò significa che FltReadFile attende il completamento dell'operazione di lettura 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 FltReadFile 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, FltReadFile differisce da ZwReadFile.