Funzione NtReadFile

Legge i dati da un file aperto.

Questa funzione è l'equivalente in modalità utente alla funzione ZwReadFile documentata in Windows Driver Kit (WDK).

Sintassi

NTSTATUS NtReadFile(
  _In_     HANDLE           FileHandle,
  _In_opt_ HANDLE           Event,
  _In_opt_ PIO_APC_ROUTINE  ApcRoutine,
  _In_opt_ PVOID            ApcContext,
  _Out_    PIO_STATUS_BLOCK IoStatusBlock,
  _Out_    PVOID            Buffer,
  _In_     ULONG            Length,
  _In_opt_ PLARGE_INTEGER   ByteOffset,
  _In_opt_ PULONG           Key
);

Parametri

FileHandle [in]

Handle all'oggetto file. Questo handle viene creato da una chiamata riuscita a NtCreateFile o NtOpenFile.

Evento [in, facoltativo]

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.

ApcRoutine [in, facoltativo]

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

ApcContext [in, facoltativo]

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

IoStatusBlock [out]

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.

Buffer [out]

Puntatore a un buffer allocato dal chiamante che riceve i dati letti dal file.

Lunghezza [in]

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

ByteOffset [in, facoltativo]

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.

Chiave [in, facoltativa]

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. Per altre informazioni, vedere NtCreateFile.

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.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Universale
Intestazione	Wdm.h (include Wdm.h, Ntddk.h o Ntifs.h)
Libreria	Ntdll.lib
DLL	Ntdll.dll (modalità utente)

Vedi anche

KeInitializeEvent

NtCreateFile

NtQueryInformationFile

NtSetInformationFile

NtWriteFile