Funzione NtReadFile (ntifs.h)

Articolo
07/11/2023

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 all'oggetto file. Questo handle viene creato da una chiamata riuscita a NtCreateFile o NtOpenFile.

[in, optional] Event

Facoltativamente, un handle a un oggetto evento da impostare sullo stato segnalato dopo il completamento dell'operazione di lettura. I driver di dispositivo e intermedio devono impostare questo parametro su NULL.

[in, optional] ApcRoutine

Questo parametro è riservato. I driver di dispositivo e intermedio devono impostare questo puntatore su NULL.

[in, optional] ApcContext

Questo parametro è riservato. I driver di dispositivo e intermedio 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

Dimensioni, in byte, del buffer a cui punta il buffer.

[in, optional] ByteOffset

Puntatore a una variabile che specifica l'offset di byte iniziale nel file in cui verrà avviata l'operazione di lettura. Se viene eseguito un tentativo di lettura oltre la fine del file, NtReadFile restituisce un errore.

Se la chiamata a NtCreateFile imposta uno dei flag CreateOptions FILE_SYNCHRONOUS_IO_ALERT o FILE_SYNCHRONOUS_IO_NONALERT, gestione I/O mantiene la posizione del file corrente. In tal caso, il chiamante di NtReadFile può specificare che l'offset di posizione del file corrente viene usato anziché un valore ByteOffset esplicito. Questa specifica può essere effettuata usando uno dei metodi seguenti:

Specificare un puntatore a un valore 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 del file corrente aggiungendo il numero di byte letti al termine dell'operazione di lettura, se si usa la posizione del file corrente gestita da I/O Manager.

Anche quando gestione I/O mantiene la posizione del file corrente, il chiamante può reimpostare questa posizione passando un valore ByteOffset esplicito a NtReadFile. Questa operazione modifica automaticamente la posizione del file corrente 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 atomico di ricerca e lettura.

[in, optional] Key

I driver di dispositivo e intermedio devono impostare questo puntatore su NULL.

Valore restituito

NtReadFile restituisce STATUS_SUCCESS o il codice di errore NTSTATUS appropriato.

Commenti

I chiamanti di NtReadFile devono avere già chiamato NtCreateFile con il valore FILE_READ_DATA o GENERIC_READ impostato nel parametro DesiredAccess .

Se la chiamata precedente a NtCreateFile imposta il flag di FILE_NO_INTERMEDIATE_BUFFERING nel parametro CreateOptions su NtCreateFile, i parametri Length e ByteOffset su NtReadFile devono essere multipli delle dimensioni del settore.

NtReadFile inizia la lettura dall'oggetto ByteOffset specificato o dalla posizione del file corrente nel buffer specificato. Termina l'operazione di lettura in una delle condizioni seguenti:

Il buffer è pieno perché il numero di byte specificati dal parametro 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 più dati nel file da trasferire nel buffer.

Se il chiamante ha aperto il file con il flag SYNC impostato in DesiredAccess, il thread chiamante può sincronizzare al completamento dell'operazione di lettura aspettando l'handle file, FileHandle. L'handle viene segnalato ogni volta che viene completata un'operazione di I/O rilasciata nell'handle. Tuttavia, il chiamante non deve attendere un handle aperto per l'accesso al 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 l'handle del file solo se vengono soddisfatte tutte e tre le condizioni seguenti:

L'handle è stato aperto per l'accesso asincrono, ovvero non è stato specificato alcun flag FILE_SYNCHRONOUS_IO_XXX .
L'handle viene usato per un'unica operazione di I/O alla volta.
NtReadFile ha restituito STATUS_PENDING.

Un driver deve chiamare NtReadFile nel contesto del processo di sistema se esistono alcune delle condizioni seguenti:

Il driver ha creato l'handle di file che passa a NtReadFile.
NtReadFile notificherà il driver di completamento di I/O tramite un evento creato dal driver.
NtReadFile notificherà il driver del completamento di I/O tramite una routine di callback APC che il driver passa a NtReadFile.

I gestori di file ed eventi sono validi solo nel contesto del processo in cui vengono creati gli handle. Pertanto, per evitare i fori di sicurezza, il driver deve creare qualsiasi file o handle di eventi che passa a NtReadFile nel contesto del processo di sistema anziché il contesto del processo in cui si trova il driver.

Analogamente, NtReadFile deve essere chiamato nel contesto del processo di sistema se notifica il driver di completamento di I/O tramite un APC, perché le API vengono sempre attivate nel contesto del thread che genera la richiesta di I/O. Se il driver chiama NtReadFile nel contesto di un processo diverso da quello del sistema, l'APC potrebbe essere ritardato in modo indefinito oppure potrebbe non essere attivato in modo indefinito.

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 dai driver in modalità kernel, le versioni NtXxx e ZwXxx 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 Uso di nt e zw versioni delle routine di Servizi di sistema nativo.

Requisiti

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, HwStorPortProhibitedDDDIs, PowerIrpDDis