Fonction WriteFileEx (fileapi.h)

Article
03/14/2023

Écrit les données dans le fichier ou le périphérique d’entrée/sortie (E/S) spécifié. Il signale son achèvement de manière asynchrone, appelant la routine d’achèvement spécifiée lorsque l’écriture est terminée ou annulée et que le thread appelant est dans un état d’attente pouvant être alerté.

Pour écrire des données dans un fichier ou un appareil de manière synchrone, utilisez la fonction WriteFile .

Syntaxe

BOOL WriteFileEx(
  [in]           HANDLE                          hFile,
  [in, optional] LPCVOID                         lpBuffer,
  [in]           DWORD                           nNumberOfBytesToWrite,
  [in, out]      LPOVERLAPPED                    lpOverlapped,
  [in]           LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

Paramètres

[in] hFile

Handle pour le fichier ou l’appareil d’E/S (par exemple, un fichier, un flux de fichiers, un disque physique, un volume, une mémoire tampon de console, un lecteur de bande, un socket, une ressource de communication, un maillot ou un canal).

Ce paramètre peut être n’importe quel handle ouvert avec l’indicateur FILE_FLAG_OVERLAPPED par la fonction CreateFile , ou un handle de socket retourné par le socket ou la fonction accept .

N’associez pas un port d’achèvement d’E/S à ce handle. Pour plus d'informations, consultez la section Notes.

Ce handle doit également avoir le droit d’accès GENERIC_WRITE . Pour plus d’informations sur les droits d’accès, consultez Sécurité des fichiers et droits d’accès.

[in, optional] lpBuffer

Pointeur vers la mémoire tampon contenant les données à écrire dans le fichier ou l’appareil.

Cette mémoire tampon doit rester valide pendant la durée de l’opération d’écriture. L’appelant ne doit pas utiliser cette mémoire tampon tant que l’opération d’écriture n’est pas terminée.

[in] nNumberOfBytesToWrite

Nombre d’octets à écrire dans le fichier ou l’appareil.

La valeur zéro spécifie une opération d’écriture null. Le comportement d’une opération d’écriture null dépend du système de fichiers sous-jacent.

Les opérations d’écriture de canal sur un réseau sont limitées à 65 535 octets par écriture. Pour plus d’informations sur les tuyaux, consultez la section Remarques.

[in, out] lpOverlapped

Pointeur vers une structure de données CHEVAUCHEMENT QUI fournit des données à utiliser pendant l’opération d’écriture (asynchrone) qui se chevauche.

Pour les fichiers qui prennent en charge les décalages d’octets, vous devez spécifier un décalage d’octets auquel commencer l’écriture dans le fichier. Vous spécifiez ce décalage en définissant les membres Offset et OffsetHigh de la structure OVERLAPPED . Pour les fichiers ou les appareils qui ne prennent pas en charge les décalages d’octets, Offset et OffsetHigh sont ignorés.

Pour écrire à la fin du fichier, spécifiez les membres Offset et OffsetHigh de la structure OVERLAPPED en tant que 0xFFFFFFFF. Sur le plan fonctionnel, cela équivaut à appeler précédemment la fonction CreateFile pour ouvrir hFile à l’aide d’un accès FILE_APPEND_DATA .

La fonction WriteFileEx ignore le membre hEvent de la structure OVERLAPPED. Une application est libre d’utiliser ce membre à ses propres fins dans le contexte d’un appel WriteFileEx . WriteFileEx signale l’achèvement de son opération d’écriture en appelant, ou en mettant en file d’attente un appel à, la routine d’achèvement pointée par lpCompletionRoutine, de sorte qu’elle n’a pas besoin d’un handle d’événement.

La fonction WriteFileEx utilise les membres Internal et InternalHigh de la structure OVERLAPPED . Vous ne devez pas modifier la valeur de ces membres.

La structure de données OVERLAPPED doit rester valide pendant toute la durée de l’opération d’écriture. Il ne doit pas s’agir d’une variable qui peut sortir de l’étendue pendant que l’opération d’écriture est en attente d’achèvement.

[in] lpCompletionRoutine

Pointeur vers une routine d’achèvement à appeler lorsque l’opération d’écriture est terminée et que le thread appelant est dans un état d’attente pouvant être alerté. Pour plus d’informations sur cette routine d’achèvement, consultez FileIOCompletionRoutine.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Si la fonction WriteFileEx réussit, le thread appelant a une opération d’E/S asynchrone en attente : opération d’écriture superposée dans le fichier. Lorsque cette opération d’E/S se termine et que le thread appelant est bloqué dans un état d’attente pouvant être alerté, le système d’exploitation appelle la fonction pointée par lpCompletionRoutine, et l’attente se termine avec un code de retour .WAIT_IO_COMPLETION

Si la fonction réussit et que l’opération d’écriture de fichier se termine, mais que le thread appelant n’est pas dans un état d’attente pouvant être alerté, le système met en file d’attente l’appel à *lpCompletionRoutine, en maintenant l’appel jusqu’à ce que le thread appelant passe à un état d’attente pouvant être alerté. Pour plus d’informations sur les états d’attente pouvant être alertés et les opérations d’entrée/sortie qui se chevauchent, consultez À propos de la synchronisation.

Remarques

Lorsque vous utilisez WriteFileEx, vous devez case activée GetLastError même lorsque la fonction retourne « success » à case activée pour les conditions qui sont des réussites mais qui ont un résultat que vous souhaiterez peut-être connaître. Par exemple, un dépassement de mémoire tampon lors de l’appel de WriteFileEx retourne TRUE, mais GetLastError signale le dépassement de capacité avec ERROR_MORE_DATA. Si l’appel de fonction réussit et qu’il n’existe aucune condition d’avertissement, GetLastError retourne ERROR_SUCCESS.

La fonction WriteFileEx échoue si le paramètre hFile est associé à un port d’achèvement d’E/S. Pour effectuer des écritures à l’aide de ce type de handle, utilisez la fonction WriteFile .

La fonction WriteFileEx peut échouer s’il y a trop de demandes d’E/S asynchrones en attente. En cas d’échec de ce type, GetLastError peut retourner ERROR_INVALID_USER_BUFFER ou ERROR_NOT_ENOUGH_MEMORY.

Pour annuler toutes les opérations d’E/S asynchrones en attente, utilisez l’une des fonctions suivantes :

CancelIo : cette fonction annule uniquement les opérations émises par le thread appelant pour le handle de fichier spécifié.
CancelIoEx : cette fonction annule toutes les opérations émises par les threads pour le handle de fichier spécifié.

Utilisez CancelSynchronousIo pour annuler les opérations d’E/S synchrones en attente.

Les opérations d’E/S qui sont annulées sont terminées avec l’erreur ERROR_OPERATION_ABORTED.

Si une partie du fichier spécifié par hFile est verrouillée par un autre processus et que l’opération d’écriture spécifiée chevauche la partie verrouillée, WriteFileEx échoue.

Lors de l’écriture dans un fichier, l’heure de la dernière écriture n’est pas entièrement mise à jour tant que tous les handles utilisés pour l’écriture n’ont pas été fermés. Par conséquent, pour garantir une heure exacte de la dernière écriture, fermez le handle de fichier immédiatement après l’écriture dans le fichier.

L’accès à la mémoire tampon de sortie pendant qu’une opération d’écriture utilise la mémoire tampon peut entraîner une altération des données écrites à partir de cette mémoire tampon. Les applications ne doivent pas écrire dans, réallouer ou libérer la mémoire tampon de sortie qu’une opération d’écriture utilise tant que l’opération d’écriture n’est pas terminée.

Notez que les horodatages peuvent ne pas être mis à jour correctement pour un fichier distant. Pour garantir des résultats cohérents, utilisez des E/S non déboguées.

Le système interprète zéro octet à écrire comme spécifiant une opération d’écriture null et WriteFile ne tronque pas le fichier ni ne l’étend. Pour tronquer ou étendre un fichier, utilisez la fonction SetEndOfFile .

Une application utilise les fonctions WaitForSingleObjectEx, WaitForMultipleObjectsEx, MsgWaitForMultipleObjectsEx, SignalObjectAndWait et SleepEx pour entrer dans un état d’attente pouvant être alerté. Pour plus d’informations sur les états d’attente pouvant être alertés et les opérations d’E/S qui se chevauchent, consultez À propos de la synchronisation.

Si vous écrivez directement dans un volume qui a un système de fichiers monté, vous devez d’abord obtenir un accès exclusif au volume. Sinon, vous risquez de provoquer une altération des données ou une instabilité du système, car les écritures de votre application peuvent entrer en conflit avec d’autres modifications provenant du système de fichiers et laisser le contenu du volume dans un état incohérent. Pour éviter ces problèmes, les modifications suivantes ont été apportées dans Windows Vista et versions ultérieures :

Une écriture sur un handle de volume réussit si le volume n’a pas de système de fichiers monté ou si l’une des conditions suivantes est remplie :
- Les secteurs à écrire sont des secteurs de démarrage.
- Secteurs à écrire pour résider en dehors de l’espace du système de fichiers.
- Vous avez explicitement verrouillé ou démonté le volume à l’aide de FSCTL_LOCK_VOLUME ou de FSCTL_DISMOUNT_VOLUME.
- Le volume n’a pas de système de fichiers réel. (En d’autres termes, il a un système de fichiers RAW monté.)
Une écriture sur un handle de disque réussit si l’une des conditions suivantes est remplie :
- Les secteurs à écrire ne se situent pas dans les étendues d’un volume.
- Les secteurs à écrire se trouvent dans un volume monté, mais vous avez explicitement verrouillé ou démonté le volume à l’aide de FSCTL_LOCK_VOLUME ou de FSCTL_DISMOUNT_VOLUME.
- Les secteurs à écrire se trouvent dans un volume qui n’a pas de système de fichiers monté autre que RAW.

Il existe des exigences strictes pour utiliser correctement les fichiers ouverts avec CreateFile à l’aide de FILE_FLAG_NO_BUFFERING. Pour plus d’informations, consultez Mise en mémoire tampon des fichiers.

Dans Windows 8 et Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.

Technologie	Prise en charge
Protocole Server Message Block (SMB) 3.0	Oui
Basculement transparent SMB 3.0 (TFO)	Oui
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO)	Oui
Système de fichiers du volume partagé de cluster (CsvFS)	Oui
Système de fichiers résilient (ReFS)	Oui

Opérations traitées

S’il existe une transaction liée au descripteur de fichier, l’écriture du fichier est traitée. Pour plus d’informations, consultez À propos de NTFS transactionnel.

Exemples

Pour obtenir un exemple, consultez Serveur de canal nommé à l’aide de routines d’achèvement.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	fileapi.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll