Funzione FltReadFile (fltkernel.h)

Articolo
02/26/2024

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 istanza opaca 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 da cui i dati devono essere letti. Questo oggetto file deve essere aperto. La chiamata a 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) 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.

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

[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 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, 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 di I/O sincrona. I driver minifilter che impostano questo flag devono anche impostare il flag di 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_CALLBACK tipizzata 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.

Commenti

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 associate 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 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 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, 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 viene eseguito un tentativo di lettura 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. Vale a dire, FltReadFile attende fino al completamento dell'operazione di lettura prima della restituzione. Questo valore è vero anche se l'oggetto file a cui Fa riferimento FileObject è stato aperto per L/O asincrona.

Se più thread chiamano FltReadFile 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, FltReadFile differisce da ZwReadFile.

Requisiti

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