Funzione WriteFileGather (fileapi.h)

Articolo
01/10/2024

Recupera i dati da una matrice di buffer e scrive i dati in un file.

La funzione inizia a scrivere dati nel file in una posizione specificata da una struttura OVERLAPPED . La funzione WriteFileGather funziona in modo asincrono.

Sintassi

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

Parametri

[in] hFile

Handle per il file. L'handle di file deve essere creato con il diritto di accesso GENERIC_WRITE e i flag di 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 contengono 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 la funzione GetSystemInfo .

La matrice deve contenere elementi sufficienti per rappresentare i byte nNumberOfBytesToWrite . Ad esempio, se sono presenti 40 KB da scrivere 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 scrive una pagina di memoria di sistema dei dati da ogni buffer.

La funzione raccoglie i dati dai buffer in ordine sequenziale. Ad esempio, scrive i dati nel file dal primo buffer, quindi il secondo buffer e così via fino a quando non sono stati scritti byte nNumberOfBytesToWrite .

A causa dell'operazione asincrona di questa funzione, è necessario prendere precauzioni per garantire che questo parametro faccia sempre riferimento alla memoria valida per la durata delle scritture asincrone. Ad esempio, un errore di programmazione comune consiste nell'usare l'archiviazione stack locale e quindi consentire l'esecuzione per l'uscita dall'ambito.

[in] nNumberOfBytesToWrite

Numero totale di byte da scrivere. 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.

Se nNumberOfBytesToWrite è zero (0), la funzione esegue un'operazione di scrittura Null. Il comportamento di un'operazione di scrittura Null dipende dal file system sottostante. Se nNumberOfBytesToWrite non è zero (0) e la lunghezza e l'offset dei dati di posizione di scrittura oltre la fine corrente del file, la funzione WriteFileGather estende 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 WriteFileGather richiede una struttura OVERLAPPED valida. Il parametro lpOverlapped non può essere NULL.

La funzione WriteFileGather inizia a scrivere dati nel file in una posizione specificata dai membri Offset e OffsetHigh della struttura OVERLAPPED.

La funzione WriteFileGather può restituire prima del completamento dell'operazione di scrittura. In questo scenario la funzione WriteFileGather restituisce il valore zero (0) e la funzione GetLastError restituisce il valore ERROR_IO_PENDING. Questa operazione asincrona della funzione WriteFileGather consente al processo chiamante di continuare mentre l'operazione di scrittura viene completata.

È possibile chiamare la funzione GetOverlappedResult, HasOverlappedIoCompleted o GetQueuedCompletionStatus per ottenere informazioni sul completamento dell'operazione di scrittura. 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 la funzione viene restituita prima del completamento dell'operazione di scrittura, la funzione restituisce zero (0) e la funzione GetLastError restituisce ERROR_IO_PENDING.

Commenti

Questa funzione non è supportata per 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; questo 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.

Se parte del file specificato da hFile è bloccata da un altro processo e l'operazione di scrittura si sovrappone alla parte bloccata, la funzione WriteFileGather ha esito negativo.

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, l'operazione viene eseguita.

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