Funzione NtReadFile (ntifs.h)
La routine NtReadFile legge i dati da un file aperto.
Sintassi
__kernel_entry NTSYSCALLAPI NTSTATUS NtReadFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[out] PVOID Buffer,
[in] ULONG Length,
[in, optional] PLARGE_INTEGER ByteOffset,
[in, optional] PULONG Key
);
Parametri
[in] FileHandle
Handle per l'oggetto file. Questo handle viene creato da una chiamata riuscita a NtCreateFile o NtOpenFile.
[in, optional] Event
Facoltativamente, un handle per un oggetto evento da impostare sullo stato segnalato al termine dell'operazione di lettura. I driver intermedi e del dispositivo devono impostare questo parametro su NULL.
[in, optional] ApcRoutine
Questo parametro è riservato. I driver intermedi e del dispositivo devono impostare questo puntatore su NULL.
[in, optional] ApcContext
Questo parametro è riservato. I driver intermedi e del dispositivo devono impostare questo puntatore su NULL.
[out] IoStatusBlock
Puntatore a una struttura IO_STATUS_BLOCK che riceve lo stato di completamento finale e informazioni sull'operazione di lettura richiesta. Il membro Information riceve il numero di byte effettivamente letti dal file.
[out] Buffer
Puntatore a un buffer allocato dal chiamante che riceve i dati letti dal file.
[in] Length
Dimensione, in byte, del buffer a cui punta Buffer.
[in, optional] ByteOffset
Puntatore a una variabile che specifica l'offset di byte iniziale nel file in cui inizierà l'operazione di lettura. Se si tenta di leggere oltre la fine del file, NtReadFile restituisce un errore.
Se la chiamata a NtCreateFile impostata una delle CreateOptions flag FILE_SYNCHRONOUS_IO_ALERT o FILE_SYNCHRONOUS_IO_NONALERT, gestione I/O mantiene la posizione corrente del file. In tal caso, il chiamante di NtReadFile può specificare che venga utilizzato l'offset di posizione del file corrente anziché un valore ByteOff set esplicito. Questa specifica può essere effettuata utilizzando uno dei metodi seguenti:
- Specificare un puntatore a un valore di LARGE_INTEGER con il membro HighPart impostato su -1 e il membro LowPart impostato sul valore definito dal sistema FILE_USE_FILE_POINTER_POSITION.
- Passare un puntatore NULL per ByteOffset.
NtReadFile aggiorna la posizione corrente del file aggiungendo il numero di byte letti al termine dell'operazione di lettura, se usa la posizione corrente del file gestita da I/O Manager.
Anche quando gestione I/O mantiene la posizione corrente del file, il chiamante può reimpostare questa posizione passando un valore di ByteOff set esplicito a NtReadFile. In questo modo la posizione corrente del file viene modificata automaticamente in tale valore ByteOffset, esegue l'operazione di lettura e quindi aggiorna la posizione in base al numero di byte effettivamente letti. Questa tecnica fornisce al chiamante il servizio atomic seek-and-read.
[in, optional] Key
I driver intermedi e del dispositivo devono impostare questo puntatore su NULL.
Valore restituito
NtReadFile restituisce STATUS_SUCCESS o il codice di errore NTSTATUS appropriato.
Osservazioni
I chiamanti di NtReadFile devono aver già chiamato NtCreateFile con il valore FILE_READ_DATA o GENERIC_READ impostato nel parametro DesiredAccess.
Se la chiamata precedente a NtCreateFile impostare il flag di FILE_NO_INTERMEDIATE_BUFFERING nel parametro CreateOptions su NtCreateFile, i parametri Length e ByteOffset per NtReadFile devono essere multipli delle dimensioni del settore.
NtReadFile inizia la lettura dall'ByteOffset specificato o dalla posizione corrente del file nell'bufferspecificato. Termina l'operazione di lettura in una delle condizioni seguenti:
- Il buffer è pieno perché il numero di byte specificato dal parametro length Length è stato letto. Pertanto, non è possibile inserire più dati nel buffer senza un overflow.
- La fine del file viene raggiunta durante l'operazione di lettura, quindi non sono presenti altri dati nel file da trasferire nel buffer.
Se il chiamante ha aperto il file con il flag SYNCHRONIZE impostato in DesiredAccess, il thread chiamante può eseguire la sincronizzazione con il completamento dell'operazione di lettura attendendo l'handle di file, FileHandle. L'handle viene segnalato ogni volta che viene completata un'operazione di I/O eseguita sull'handle. Tuttavia, il chiamante non deve attendere un handle aperto per l'accesso ai file sincrono (FILE_SYNCHRONOUS_IO_NONALERT o FILE_SYNCHRONOUS_IO_ALERT). In questo caso, NtReadFile attende per conto del chiamante e non restituisce fino al completamento dell'operazione di lettura. Il chiamante può attendere in modo sicuro sull'handle di file solo se vengono soddisfatte tutte e tre le condizioni seguenti:
- L'handle è stato aperto per l'accesso asincrono, ovvero nessuna delle FILE_SYNCHRONOUS_IO_XXX flag è stata specificata.
- L'handle viene usato per una sola operazione di I/O alla volta.
- NtReadFile restituito STATUS_PENDING.
Un driver deve chiamare NtReadFile nel contesto del processo di sistema se esistono una delle condizioni seguenti:
- Il driver ha creato l'handle di file passato a NtReadFile.
- NtReadFile informerà il driver del completamento di I/O tramite un evento creato dal driver.
- NtReadFile informerà il driver del completamento di I/O tramite una routine di callback APC che il driver passa a NtReadFile.
Gli handle di file ed eventi sono validi solo nel contesto del processo in cui vengono creati gli handle. Pertanto, per evitare problemi di sicurezza, il driver deve creare qualsiasi handle di file o evento passato a NtReadFile nel contesto del processo di sistema anziché nel contesto del processo in cui si trova il driver.
Analogamente, NtReadFile deve essere chiamato nel contesto del processo di sistema se notifica al driver di completamento di I/O tramite un APC, perché le API vengono sempre attivate nel contesto del thread che emette la richiesta di I/O. Se il driver chiama NtReadFile nel contesto di un processo diverso da quello di sistema, l'APC potrebbe essere ritardato a tempo indeterminato o potrebbe non essere attivato affatto.
Per altre informazioni sull'uso dei file, vedere Uso di file in un driver.
I chiamanti di NtReadFile devono essere in esecuzione in IRQL = PASSIVE_LEVEL e con API kernel speciali abilitate.
Se la chiamata a questa funzione si verifica in modalità utente, è necessario usare il nome "NtReadFile" anziché "ZwReadFile".
Per le chiamate da driver in modalità kernel, le NtXxx e ZwXxx versioni di una routine di Windows Native System Services possono comportarsi in modo diverso nel modo in cui gestiscono e interpretano i parametri di input. Per altre informazioni sulla relazione tra le versioni NtXxx e ZwXxx di una routine, vedere Using Nt and Zw Versions of the Native System Services Routines.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows 2000 |
| piattaforma di destinazione | Universale |
| intestazione | ntifs.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| libreria | NtosKrnl.lib |
| dll | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (vedere la sezione Osservazioni) |
| regole di conformità DDI | BufAfterReqCompletedIntIoctlA, BufAfterReqCompletedIoctlA, BufAfterReqCompletedReadA, BufAfterReqCompletedWriteA, HwStorPortProhibitedDDIs, PowerIrpDDis |