Funzione WriteFileEx (fileapi.h)

Articolo
02/29/2024

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

Per scrivere dati in un file o in un dispositivo in modo sincrono, usare la funzione WriteFile .

Sintassi

BOOL WriteFileEx(
  [in]           HANDLE                          hFile,
  [in, optional] LPCVOID                         lpBuffer,
  [in]           DWORD                           nNumberOfBytesToWrite,
  [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 .

Non associare una porta di completamento I/O a questo handle. Per altre informazioni, vedere la sezione Osservazioni.

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

[in, optional] lpBuffer

Puntatore al buffer contenente i dati da scrivere nel file o nel dispositivo.

Questo buffer deve rimanere valido per la durata dell'operazione di scrittura. Il chiamante non deve usare questo buffer fino al completamento dell'operazione di scrittura.

[in] nNumberOfBytesToWrite

Numero di byte da scrivere nel file o nel dispositivo.

Il valore zero specifica un'operazione di scrittura Null. Il comportamento di un'operazione di scrittura Null dipende dal file system sottostante.

Le operazioni di scrittura tramite pipe in una rete sono limitate a 65.535 byte per scrittura. Per altre informazioni sulle pipe, vedere la sezione Osservazioni.

[in, out] lpOverlapped

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

Per i file che supportano gli offset di byte, è necessario specificare un offset di byte in corrispondenza del quale iniziare a scrivere nel 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.

Per scrivere alla fine del file, specificare sia i membri Offset che OffsetHigh della struttura OVERLAPPED come 0xFFFFFFFF. Ciò equivale funzionalmente alla chiamata precedente della funzione CreateFile per aprire hFile usando FILE_APPEND_DATA l'accesso.

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

La funzione WriteFileEx utilizza i membri Internal e InternalHigh della struttura OVERLAPPED. Non è consigliabile modificare il valore di questi membri.

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

[in] lpCompletionRoutine

Puntatore a una routine di completamento da chiamare quando l'operazione di scrittura è stata completata e il thread chiamante si trova in uno stato di attesa di avviso. Per altre informazioni su questa 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 WriteFileEx ha esito positivo, il thread chiamante ha un'operazione di I/O asincrona in sospeso: l'operazione di scrittura sovrapposta al file. Al termine dell'operazione di I/O e il thread chiamante viene bloccato in uno stato di attesa avvisabile, il sistema operativo chiama la funzione a cui punta lpCompletionRoutine e l'attesa viene completata con un codice restituito di WAIT_IO_COMPLETION.

Se la funzione ha esito positivo e l'operazione di scrittura file termina, ma il thread chiamante non è in uno stato di attesa di avviso, il sistema accoda la chiamata a *lpCompletionRoutine, tenendo premuta la chiamata fino a quando il thread chiamante non entra in uno stato di attesa di avviso. Per altre informazioni sugli stati di attesa di avviso e sulle operazioni di input/output sovrapposte, vedere Informazioni sulla sincronizzazione.

Commenti

Quando si usa WriteFileEx , è consigliabile controllare GetLastError anche quando la funzione restituisce "success" per verificare le condizioni che hanno esito positivo , ma si potrebbe voler sapere di qualche risultato. Ad esempio, un overflow del buffer quando si chiama WriteFileEx 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 WriteFileEx avrà esito negativo se il parametro hFile è associato a una porta di completamento I/O. Per eseguire operazioni di scrittura usando questo tipo di handle, usare la funzione WriteFile .

La funzione WriteFileEx 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 scrittura specificata si sovrappone alla parte bloccata, WriteFileEx ha esito negativo.

Quando si scrive in un file, l'ora dell'ultima scrittura non viene aggiornata completamente fino a quando non vengono chiusi tutti gli handle utilizzati per la scrittura. Pertanto, per garantire un'ora dell'ultima scrittura accurata, chiudere l'handle di file immediatamente dopo la scrittura nel file.

L'accesso al buffer di output mentre un'operazione di scrittura usa il buffer può causare il danneggiamento dei dati scritti da tale buffer. Le applicazioni non devono scrivere in, riallocare o liberare il buffer di output usato da un'operazione di scrittura fino al completamento dell'operazione di scrittura.

Si noti che i timestamp potrebbero non essere aggiornati correttamente per un file remoto. Per garantire risultati coerenti, usare l'I/O non memorizzato nel buffer.

Il sistema interpreta zero byte da scrivere come specificare un'operazione di scrittura Null e WriteFile non tronca o estende il file. Per troncare o estendere un file, usare la funzione SetEndOfFile .

Un'applicazione usa le funzioni WaitForSingleObjectEx, WaitForMultipleObjectsEx, MsgWaitForMultipleObjectsEx, SignalObjectAndWait e SleepEx per immettere uno stato di attesa di avviso. Per altre informazioni sugli stati di attesa avvisibili e sulle operazioni di I/O sovrapposte, vedere Informazioni sulla sincronizzazione.

Se si scrive direttamente in un volume con un file system montato, è innanzitutto necessario ottenere l'accesso esclusivo al volume. In caso contrario, si rischia di causare il danneggiamento dei dati o l'instabilità del sistema, perché le scritture dell'applicazione potrebbero entrare in conflitto con altre modifiche provenienti dal file system e lasciare il contenuto del volume in uno stato incoerente. Per evitare questi problemi, sono state apportate le modifiche seguenti in Windows Vista e versioni successive:

Un handle di scrittura su un handle di volume avrà esito positivo se il volume non dispone di un file system montato o se una delle condizioni seguenti è vera:
- I settori da scrivere in sono settori d'avvio.
- I settori da scrivere in risiedono all'esterno dello spazio del file system.
- Il volume è stato bloccato o smontato in modo esplicito usando FSCTL_LOCK_VOLUME o FSCTL_DISMOUNT_VOLUME.
- Il volume non ha alcun file system effettivo. In altre parole, ha un file system RAW montato.
Se una delle condizioni seguenti è vera, una scrittura su un handle del disco avrà esito positivo:
- I settori da scrivere in non rientrano nelle dimensioni di un volume.
- I settori da scrivere in un volume montato, ma il volume è stato bloccato o smontato in modo esplicito utilizzando FSCTL_LOCK_VOLUME o FSCTL_DISMOUNT_VOLUME.
- I settori da scrivere per rientrare in un volume senza file system montato diverso da RAW.

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, viene eseguita la transazione di scrittura del file. 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