Funzione FltReadFileEx (fltkernel.h)
FltReadFileEx legge i dati da un file, un flusso o un dispositivo aperti. Questa funzione estende FltReadFile per consentire l'uso facoltativo di un file MDL per leggere i dati anziché 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 a un'istanza opaca 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 FltReadFileEx quando l'oggetto file non è ancora aperto o non è più aperto (ad esempio, in una routine di callback 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 operazioni di I/O sincrone, 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 FltReadFileEx (e filtri a 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. Se viene specificato un MDL in Mdl, buffer deve essere NULL.
[in] Flags
Maschera di bit di flag che specificano 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.
[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 viene fornito un buffer in Buffer , Mdl deve essere NULL.
Valore restituito
FltReadFileEx restituisce il valore NTSTATUS restituito dal file system.
Osservazioni
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 è true una delle condizioni seguenti:
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 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.
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, 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. Ciò significa che FltReadFileEx 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 FltReadFileEx per lo stesso oggetto file e l'oggetto file è stato aperto per operazioni di I/O sincrone, il gestore 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 minifiltro 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.
Fabbisogno
| 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 |