Funzione ReadFile (fileapi.h)
Legge i dati dal file o dal dispositivo di input/output (I/O) specificato. Le letture si verificano nella posizione specificata dal puntatore al file, se supportato dal dispositivo.
Questa funzione è progettata sia per le operazioni sincrone che asincrone. Per una funzione simile progettata esclusivamente per l'operazione asincrona, vedere ReadFileEx.
Sintassi
BOOL ReadFile(
[in] HANDLE hFile,
[out] LPVOID lpBuffer,
[in] DWORD nNumberOfBytesToRead,
[out, optional] LPDWORD lpNumberOfBytesRead,
[in, out, optional] LPOVERLAPPED lpOverlapped
);
Parametri
[in] hFile
Handle per il dispositivo (ad esempio, un file, un flusso di file, un disco fisico, un volume, un buffer della console, un'unità nastro, socket, risorsa di comunicazione, mailslot o pipe).
Il parametro hFile deve essere stato creato con accesso in lettura. Per altre informazioni, vedere Diritti di accesso generico e Diritti di accesso e sicurezza dei file.
Per le operazioni di lettura asincrone, hFile può essere qualsiasi handle aperto con il flag FILE_FLAG_OVERLAPPED dalla funzione CreateFile o un handle socket restituito dalla funzione socket o accept .
[out] lpBuffer
Puntatore al buffer che riceve i dati letti da un file o un dispositivo.
Questo buffer deve rimanere valido per la durata dell'operazione di lettura. Il chiamante non deve usare questo buffer fino al completamento dell'operazione di lettura.
[in] nNumberOfBytesToRead
Numero massimo di byte da leggere.
[out, optional] lpNumberOfBytesRead
Puntatore alla variabile che riceve il numero di byte letti quando si usa un parametro hFile sincrono. ReadFile imposta questo valore su zero prima di eseguire qualsiasi controllo del lavoro o degli errori. Usare NULL per questo parametro se si tratta di un'operazione asincrona per evitare risultati potenzialmente errati.
Questo parametro può essere NULL solo quando il parametro lpOverlapped non è NULL.
Windows 7: Questo parametro non può essere NULL.
Per altre informazioni, vedere la sezione Osservazioni.
[in, out, optional] lpOverlapped
È necessario un puntatore a una struttura OVERLAPPED se il parametro hFile è stato aperto con FILE_FLAG_OVERLAPPED; in caso contrario, può essere NULL.
Se hFile viene aperto con FILE_FLAG_OVERLAPPED, il parametro lpOverlapped deve puntare a una struttura OVERLAPPED valida e univoca. In caso contrario, la funzione può segnalare erroneamente che l'operazione di lettura è stata completata.
Per un hFile che supporta gli offset di byte, se si usa questo parametro è necessario specificare un offset di byte in corrispondenza del quale iniziare la lettura dal file o dal dispositivo. Questo offset viene specificato impostando i membri Offset e OffsetHigh della struttura OVERLAPPED . Per un hFile che non supporta gli offset di byte, Offset e OffsetHigh vengono ignorati.
Per altre informazioni sulle diverse combinazioni di lpOverlapped e FILE_FLAG_OVERLAPPED, vedere la sezione Osservazioni e la sezione Sincronizzazione e posizione file .
Valore restituito
Se la funzione ha esito positivo, il valore restituito è diverso da zero (TRUE).
Se la funzione ha esito negativo o viene completata in modo asincrono, il valore restituito è zero (FALSE). Per ottenere informazioni sull'errore estese, chiamare la funzione GetLastError .
Commenti
La funzione ReadFile restituisce quando si verifica una delle condizioni seguenti:
- Il numero di byte richiesti è in lettura.
- Un'operazione di scrittura viene completata sulla fine di scrittura della pipe.
- Viene usato un handle asincrono e la lettura avviene in modo asincrono.
- Si verifica un errore.
La funzione ReadFile potrebbe non riuscire con ERROR_INVALID_USER_BUFFER o ERROR_NOT_ENOUGH_MEMORY ogni volta che sono presenti troppe richieste di I/O asincrone in sospeso.
Per annullare tutte le operazioni di I/O asincrone in sospeso, usare:
- CancelIo: questa funzione annulla solo le operazioni eseguite dal thread chiamante per l'handle di file specificato.
- CancelIoEx: questa funzione annulla tutte le operazioni eseguite dai thread per l'handle di file specificato.
Usare CancelSynchronousIo per annullare le operazioni di I/O sincrone in sospeso.
Le operazioni di I/O annullate vengono completate con l'errore ERROR_OPERATION_ABORTED.
La funzione ReadFile potrebbe non riuscire con ERROR_NOT_ENOUGH_QUOTA, il che significa che il buffer del processo chiamante non può essere bloccato da pagina. Per altre informazioni, vedere SetProcessWorkingSetSize.
Se parte di un file è bloccata da un altro processo e l'operazione di lettura si sovrappone alla parte bloccata, questa funzione ha esito negativo.
L'accesso al buffer di input mentre un'operazione di lettura usa il buffer può causare il danneggiamento dei dati letti nel buffer. Le applicazioni non devono leggere, scrivere in, riallocare o liberare il buffer di input usato da un'operazione di lettura fino al completamento dell'operazione di lettura. Ciò può risultare particolarmente problematico quando si usa un handle di file asincrono. Altre informazioni relative agli handle di file sincroni e asincroni sono disponibili nella sezione Sincronizzazione e posizione file e nell'argomento di riferimento CreateFile .
I caratteri possono essere letti dal buffer di input della console usando ReadFile con un handle per l'input della console. La modalità console determina il comportamento esatto della funzione ReadFile . Per impostazione predefinita, la modalità console è ENABLE_LINE_INPUT, che indica che ReadFile deve essere letto fino a raggiungere un ritorno a capo. Se si preme CTRL+C, la chiamata ha esito positivo, ma GetLastError restituisce ERROR_OPERATION_ABORTED. Per altre informazioni, vedere CreateFile.
Quando si legge da un dispositivo di comunicazione, il comportamento di ReadFile è determinato dal timeout di comunicazione corrente impostato e recuperato usando le funzioni SetCommTimeouts e GetCommTimeouts . I risultati imprevedibili possono verificarsi se non si impostano i valori di timeout. Per altre informazioni sui timeout delle comunicazioni, vedere COMMTIMEOUTS.
Se ReadFile tenta di leggere da un oggetto mailslot con un buffer troppo piccolo, la funzione restituisce FALSE e GetLastError restituisce ERROR_INSUFFICIENT_BUFFER.
Esistono requisiti rigorosi per l'uso corretto dei file aperti con CreateFile usando il flag FILE_FLAG_NO_BUFFERING . Per informazioni dettagliate, vedere Buffering dei file.
Se hFile è stato aperto con FILE_FLAG_OVERLAPPED, sono effettive le condizioni seguenti:
- Il parametro lpOverlapped deve puntare a una struttura OVERLAPPED valida e univoca. In caso contrario, la funzione può segnalare erroneamente che l'operazione di lettura è stata completata.
- Il parametro lpNumberOfBytesRead deve essere impostato su NULL. Usare la funzione GetOverlappedResult per ottenere il numero effettivo di byte letti. Se il parametro hFile è associato a una porta di completamento I/O, è anche possibile ottenere il numero di byte letti chiamando la funzione GetQueuedCompletionStatus .
Sincronizzazione e posizione file
Se hFile viene aperto con FILE_FLAG_OVERLAPPED, è un handle di file asincrono; in caso contrario, è sincrona. Le regole per l'uso della struttura OVERLAPPED sono leggermente diverse per ognuna, come indicato in precedenza.- ReadFile può restituire prima del completamento dell'operazione di lettura. In questo scenario ReadFile restituisce FALSE e la funzione GetLastError restituisce ERROR_IO_PENDING, che consente al processo chiamante di continuare mentre il sistema completa l'operazione di lettura.
- Il parametro lpOverlapped non deve essere NULL e deve essere usato tenendo presente quanto segue:
- Anche se l'evento specificato nella struttura OVERLAPPED viene impostato e reimpostato automaticamente dal sistema, l'offset specificato nella struttura OVERLAPPED non viene aggiornato automaticamente.
- ReadFile reimposta l'evento su uno stato non firmato quando avvia l'operazione di I/O.
- L'evento specificato nella struttura OVERLAPPED viene impostato su uno stato segnalato al termine dell'operazione di lettura; fino a quel momento, l'operazione di lettura viene considerata in sospeso.
- Poiché l'operazione di lettura inizia all'offset specificato nella struttura OVERLAPPED e ReadFile può restituire prima che l'operazione di lettura a livello di sistema venga completata (lettura in sospeso), né l'offset né qualsiasi altra parte della struttura deve essere modificato, liberato o riutilizzato dall'applicazione fino a quando l'evento non viene segnalato (ovvero, la lettura viene completata).
- Se viene rilevata la fine del file (EOF) durante le operazioni asincrone, la chiamata a GetOverlappedResult per tale operazione restituisce FALSE e GetLastError restituisce ERROR_HANDLE_EOF.
- Se lpOverlapped è NULL, l'operazione di lettura inizia nella posizione del file corrente e ReadFile non restituisce finché l'operazione non viene completata e il sistema aggiorna il puntatore al file prima che ReadFile restituisca.
- Se lpOverlapped non è NULL, l'operazione di lettura inizia con l'offset specificato nella struttura OVERLAPPED e ReadFile non restituisce fino al completamento dell'operazione di lettura. Il sistema aggiorna l'offset OVERLAPPED e il puntatore al file prima della restituzione di ReadFile .
- Se lpOverlapped è NULL, quando un'operazione di lettura sincrona raggiunge la fine di un file, ReadFile restituisce TRUE e imposta su
*lpNumberOfBytesReadzero. - Se lpOverlapped non è NULL, quando un'operazione di lettura sincrona raggiunge la fine di un file, ReadFile restituisce FALSE e GetLastError restituisce ERROR_HANDLE_EOF.
Tubi
Se viene usata una pipe anonima e l'handle di scrittura è stato chiuso, quando ReadFile tenta di leggere usando l'handle di lettura corrispondente della pipe, la funzione restituisce FALSE e GetLastError restituisce ERROR_BROKEN_PIPE.Se una named pipe viene letta in modalità messaggio e il messaggio successivo è più lungo del parametro nNumberOfBytesToRead specificato, ReadFile restituisce FALSE e GetLastError restituisce ERROR_MORE_DATA. Il resto del messaggio può essere letto da una chiamata successiva alla funzione ReadFile o PeekNamedPipe .
Se il parametro lpNumberOfBytesRead è zero quando ReadFile restituisce TRUE su una pipe, l'altra estremità della pipe ha chiamato la funzione WriteFile con nNumberOfBytesToWrite impostata su zero.
Per altre informazioni sulle pipe, vedere Pipe.
Operazioni transazionate
Se è presente una transazione associata all'handle di file, la funzione restituisce i dati dalla visualizzazione transazionata del file. Un handle di lettura transazionato è garantito per visualizzare la stessa visualizzazione di un file per la durata dell'handle. Per altre informazioni, vedere Informazioni su NTFS transazionale.In Windows 8 e Windows Server 2012 questa funzione è supportata dalle tecnologie seguenti.
| Tecnologia | Supportato |
|---|---|
| Protocollo SMB (Server Message Block) 3.0 | Sì |
| Failover trasparente SMB 3.0 (TFO) | Sì |
| SMB 3.0 con condivisioni file con scalabilità orizzontale (SO) | Sì |
| File system del volume condiviso del cluster (CsvFS) | Sì |
| File system resiliente (ReFS) | Sì |
Esempi
Per un esempio di codice che illustra come testare la fine del file, vedere Test per la fine di un file. Per altri esempi, vedere Creazione e uso di un file temporaneo e apertura di un file per la lettura o la scrittura.
Requisiti
| Client minimo supportato | Windows XP [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2003 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | fileapi.h (includere Windows.h) |
| Libreria | Kernel32.lib |
| DLL | Kernel32.dll |