Funzione ZwReadFile (wdm.h)

Articolo
08/08/2023

La routine ZwReadFile legge i dati da un file aperto.

Sintassi

NTSYSAPI NTSTATUS ZwReadFile(
  [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 ZwCreateFile o ZwOpenFile.

[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, ZwReadFile restituisce un errore.

Se la chiamata a ZwCreateFile 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 ZwReadFile 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.

ZwReadFile aggiorna la posizione del file corrente aggiungendo il numero di byte letti al termine dell'operazione di lettura, se 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 ZwReadFile. 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

ZwReadFile restituisce STATUS_SUCCESS o il codice di errore NTSTATUS appropriato.

Commenti

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

Se la chiamata precedente a ZwCreateFile imposta il flag FILE_NO_INTERMEDIATE_BUFFERING nel parametro CreateOptions su ZwCreateFile, i parametri Length e ByteOffset su ZwReadFile devono essere multipli delle dimensioni del settore. Per altre informazioni, vedere ZwCreateFile.

ZwReadFile inizia la lettura dall'oggetto ByteOffset specificato o dalla posizione corrente del file 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, ZwReadFile 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.
ZwReadFile ha restituito STATUS_PENDING.

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

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

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

Analogamente, ZwReadFile 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 ZwReadFile nel contesto di un processo diverso da quello del sistema, l'APC potrebbe essere ritardato in modo indefinito o potrebbe non essere attivato a tutti.

Per altre informazioni sull'uso dei file, vedere Uso di file in un driver.

I chiamanti di ZwReadFile 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".

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	wdm.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(kmdf), BufAfterReqCompletedIoctlA(kmdf), BufAfterReqCompletedReadA(kmdf), BufAfterReqCompletedWriteA(kmdf), HwStorPortProhibitedDDDIs(storport), PowerIrpDDis(wdm)