Funzione ReadFileEx (fileapi.h)

Articolo
08/23/2023

Legge i dati dal file o dal dispositivo di input/output (I/O) specificato. Segnala lo stato di completamento in modo asincrono, chiamando la routine di completamento specificata quando la lettura viene completata o annullata e il thread chiamante è in uno stato di attesa avvisabile.

Per leggere i dati da un file o da un dispositivo in modo sincrono, usare la funzione ReadFile .

Sintassi

BOOL ReadFileEx(
  [in]            HANDLE                          hFile,
  [out, optional] LPVOID                          lpBuffer,
  [in]            DWORD                           nNumberOfBytesToRead,
  [in, out]       LPOVERLAPPED                    lpOverlapped,
  [in]            LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

Parametri

[in] hFile

Handle per il file o il dispositivo di I/O, ad esempio un file, un flusso di file, un disco fisico, un volume, un buffer della console, un'unità nastro, un socket, una risorsa di comunicazione, un file o una pipe.

Questo parametro può essere qualsiasi handle aperto con il flag FILE_FLAG_OVERLAPPED dalla funzione CreateFile o un handle socket restituito dal socket o dalla funzione accept .

Questo handle deve avere anche il diritto di accesso GENERIC_READ . Per altre informazioni sui diritti di accesso, vedere Diritti di accesso e sicurezza dei file.

[out, optional] lpBuffer

Puntatore a un buffer che riceve i dati letti dal file o dal dispositivo.

Questo buffer deve rimanere valido per la durata dell'operazione di lettura. L'applicazione non deve usare questo buffer fino al completamento dell'operazione di lettura.

[in] nNumberOfBytesToRead

Numero di byte da leggere.

[in, out] lpOverlapped

Puntatore a una struttura di dati OVERLAPPED che fornisce dati da utilizzare durante l'operazione di lettura del file asincrona (sovrapposta).

Per i file che supportano gli offset di byte, è necessario specificare un offset di byte in corrispondenza del quale iniziare la lettura dal file. Per specificare questo offset, impostare i membri Offset e OffsetHigh della struttura OVERLAPPED . Per i file o i dispositivi che non supportano gli offset di byte, Offset e OffsetHigh vengono ignorati.

La funzione ReadFileEx ignora il membro hEvent della struttura OVERLAPPED. Un'applicazione è gratuita per l'uso di tale membro ai propri scopi nel contesto di una chiamata ReadFileEx . ReadFileEx segnala il completamento dell'operazione di lettura chiamando o accodando una chiamata a, la routine di completamento a cui punta lpCompletionRoutine, quindi non è necessario un handle eventi.

La funzione ReadFileEx usa i membri Internal e InternalHigh della struttura OVERLAPPED. Un'applicazione non deve impostare questi membri.

La struttura dei dati OVERLAPPED deve rimanere valida per la durata dell'operazione di lettura. Non deve essere una variabile che può uscire dall'ambito mentre l'operazione di lettura è in attesa di completamento.

[in] lpCompletionRoutine

Puntatore alla routine di completamento da chiamare al termine dell'operazione di lettura e il thread chiamante si trova in uno stato di attesa avvisabile. Per altre informazioni sulla routine di completamento, vedere FileIOCompletionRoutine.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Se la funzione ha esito positivo, il thread chiamante ha un'operazione di I/O asincrona in sospeso: l'operazione di lettura sovrapposta dal file. Al termine di questa operazione di I/O e il thread chiamante viene bloccato in uno stato di attesa avvisabile, il sistema chiama la funzione a cui punta lpCompletionRoutine e lo stato di attesa viene completato con un codice restituito di WAIT_IO_COMPLETION.

Se la funzione ha esito positivo e l'operazione di lettura file viene completata, ma il thread chiamante non è in uno stato di attesa avvisabile, il sistema accoda la chiamata di routine di completamento, tenendo premuta la chiamata fino a quando il thread chiamante non entra in uno stato di attesa di avviso. Per informazioni sulle attese di avviso e sulle operazioni di input/output sovrapposte, vedere Informazioni sulla sincronizzazione.

Se ReadFileEx tenta di leggere oltre la fine del file (EOF), la chiamata a GetOverlappedResult per tale operazione restituisce FALSE e GetLastError restituisce ERROR_HANDLE_EOF.

Commenti

Quando si usa ReadFileEx , è consigliabile controllare GetLastError anche quando la funzione restituisce "esito positivo" per verificare le condizioni che sono "riuscite" ma che hanno un risultato che potrebbe essere utile conoscere. Ad esempio, un overflow del buffer quando si chiama ReadFileEx restituirà TRUE, ma GetLastError segnala l'overflow con ERROR_MORE_DATA. Se la chiamata di funzione ha esito positivo e non sono presenti condizioni di avviso, GetLastError restituirà ERROR_SUCCESS.

La funzione ReadFileEx potrebbe non riuscire se sono presenti troppe richieste di I/O asincrone in sospeso. In caso di errore di questo tipo, GetLastError può restituire ERROR_INVALID_USER_BUFFER o ERROR_NOT_ENOUGH_MEMORY.

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.

Se parte del file specificato da hFile è bloccata da un altro processo e l'operazione di lettura specificata in una chiamata a ReadFileEx si sovrappone alla parte bloccata, la chiamata a ReadFileEx ha esito negativo.

Quando si tenta di leggere i dati da un oggetto mailslot il cui buffer è troppo piccolo, ReadFileEx restituisce FALSE e GetLastError restituisce ERROR_INSUFFICIENT_BUFFER.

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.

Un'applicazione usa le funzioni MsgWaitForMultipleObjectsEx, WaitForSingleObjectEx, WaitForMultipleObjectsEx e SleepEx per immettere uno stato di attesa avvisabile. Per altre informazioni sulle attese di avviso e sull'input/output sovrapposto, vedere Informazioni sulla sincronizzazione.

Esistono requisiti rigorosi per l'uso corretto dei file aperti con CreateFile usando FILE_FLAG_NO_BUFFERING. Per informazioni dettagliate, vedere Buffering dei file.

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 di scalabilità orizzontale (SO)	Sì
File system del volume condiviso cluster (CsvFS)	Sì
Resilient File System (ReFS)	Sì

Operazioni transazionate

Se è presente una transazione associata all'handle di file, la funzione restituisce i dati dalla vista transazionale del file. È garantito che un handle di lettura transazionato mostri la stessa visualizzazione di un file per la durata dell'handle. Per altre informazioni, vedere Informazioni su NTFS transazionale.

Esempio

Per un esempio, vedere Named Pipe Server Using Completion Routines.For an example, see Named Pipe Server Using Completion Routines.

Requisiti

Requisito	Valore
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 (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll