Funzione ReadFileScatter (fileapi.h)

Articolo
01/10/2024

Legge i dati da un file e lo archivia in una matrice di buffer.

La funzione avvia la lettura dei dati dal file in una posizione specificata da una struttura OVERLAPPED . La funzione ReadFileScatter funziona in modo asincrono.

Sintassi

BOOL ReadFileScatter(
  [in]      HANDLE                  hFile,
  [in]      FILE_SEGMENT_ELEMENT [] aSegmentArray,
  [in]      DWORD                   nNumberOfBytesToRead,
            LPDWORD                 lpReserved,
  [in, out] LPOVERLAPPED            lpOverlapped
);

Parametri

[in] hFile

Handle per il file da leggere.

L'handle di file deve essere creato con la GENERIC_READ destra e i flag FILE_FLAG_OVERLAPPED e FILE_FLAG_NO_BUFFERING. Per altre informazioni, vedere Sicurezza file e diritti di accesso.

[in] aSegmentArray

Puntatore a una matrice di buffer struttura FILE_SEGMENT_ELEMENT che riceve i dati. Per una descrizione di questa unione, vedere Osservazioni.

Ogni elemento rappresenta una pagina di dati.

Nota

Per determinare le dimensioni di una pagina di sistema, usare GetSystemInfo.

La matrice deve contenere elementi sufficienti per rappresentare i byte nNumberOfBytesToRead . Ad esempio, se sono presenti 40 KB da leggere e le dimensioni della pagina sono 4 KB, la matrice deve avere 10 elementi.

Ogni buffer deve essere almeno la dimensione di una pagina di memoria di sistema e deve essere allineata a un limite di dimensioni della pagina di memoria di sistema. Il sistema legge una pagina di memoria di sistema dei dati in ogni buffer.

La funzione archivia i dati nei buffer in ordine sequenziale. Ad esempio, archivia i dati nel primo buffer, quindi nel secondo buffer e così via finché ogni buffer non viene riempito e tutti i dati vengono archiviati o nNumberOfBytesToRead sono stati letti.

[in] nNumberOfBytesToRead

Numero totale di byte da leggere dal file. Ogni elemento di aSegmentArray contiene un blocco a una pagina del totale. Poiché il file deve essere aperto con FILE_FLAG_NO_BUFFERING, il numero di byte deve essere un multiplo delle dimensioni del settore del file system in cui si trova il file.

lpReserved

Questo parametro è riservato per l'uso futuro e deve essere NULL.

[in, out] lpOverlapped

Puntatore a una struttura di dati OVERLAPPED .

La funzione ReadFileScatter richiede una struttura OVERLAPPED valida. Il parametro lpOverlapped non può essere NULL.

La funzione ReadFileScatter avvia la lettura dei dati dal file in una posizione specificata dai membri Offset e OffsetHigh della struttura OVERLAPPED.

La funzione ReadFileScatter può restituire prima del completamento dell'operazione di lettura. In questo scenario, la funzione ReadFileScatter restituisce il valore 0 (zero) e la funzione GetLastError restituisce il valore ERROR_IO_PENDING. Questa operazione asincrona di ReadFileScatter consente al processo chiamante di continuare mentre l'operazione di lettura viene completata. È possibile chiamare le funzioni GetOverlappedResult, HasOverlappedIoCompleted o GetQueuedCompletionStatus per ottenere informazioni sul completamento dell'operazione di lettura. Per altre informazioni, vedere I/O sincrona e asincrona.

Valore restituito

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

Se la funzione ha esito negativo, il valore restituito è zero (0). Per ottenere informazioni sull'errore estese, chiamare la funzione GetLastError .

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

Se la funzione viene restituita prima del completamento dell'operazione di lettura, la funzione restituisce zero (0) e GetLastError restituisce ERROR_IO_PENDING.

Commenti

Questa funzione non è supportata per le applicazioni a 32 bit da WOW64 nei sistemi basati su Itanium.

La struttura FILE_SEGMENT_ELEMENT è definita come segue:

typedef union _FILE_SEGMENT_ELEMENT {
    PVOID64 Buffer;
    ULONGLONG Alignment;
}FILE_SEGMENT_ELEMENT, *PFILE_SEGMENT_ELEMENT;

L'assegnazione di un puntatore al membro buffer estenderà il valore se il codice viene compilato come 32 bit; ciò può interrompere applicazioni con riconoscimento a indirizzi di grandi dimensioni in esecuzione nei sistemi configurati con Ottimizzazione a 4 Gigabyte o in esecuzione in WOW64 in Windows a 64 bit. Usare pertanto la macro PtrToPtr64 quando si assegnano puntatori a Buffer.

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ì

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.

Requisiti


Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	fileapi.h (includere Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll