WriteFileGather, fonction (fileapi.h)

Article
01/10/2024

Récupère les données d’un tableau de mémoires tampons et les écrit dans un fichier.

La fonction commence à écrire des données dans le fichier à une position spécifiée par une structure CHEVAUCHEMENT . La fonction WriteFileGather fonctionne de manière asynchrone.

Syntaxe

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

Paramètres

[in] hFile

Descripteur du fichier. Le handle de fichier doit être créé avec le droit d’accès GENERIC_WRITE et les indicateurs FILE_FLAG_OVERLAPPED et FILE_FLAG_NO_BUFFERING . Pour plus d’informations, consultez Sécurité des fichiers et droits d’accès.

[in] aSegmentArray

Pointeur vers un tableau de mémoires tampons de structure FILE_SEGMENT_ELEMENT qui contiennent les données. Pour obtenir une description de cette union, consultez Remarques.

Chaque élément représente une page de données.

Notes

Pour déterminer la taille d’une page système, utilisez la fonction GetSystemInfo .

Le tableau doit contenir suffisamment d’éléments pour représenter nNumberOfBytesToWrite octets de données. Par exemple, s’il y a 40 Ko à écrire et que la taille de page est de 4 Ko, le tableau doit avoir 10 éléments.

Chaque mémoire tampon doit avoir au moins la taille d’une page mémoire système et doit être alignée sur une limite de taille de page mémoire système. Le système écrit une page de mémoire système de données à partir de chaque mémoire tampon.

La fonction collecte les données des mémoires tampons dans l’ordre séquentiel. Par exemple, il écrit des données dans le fichier à partir de la première mémoire tampon, puis de la deuxième mémoire tampon, et ainsi de suite jusqu’à ce que les octets nNumberOfBytesToWrite aient été écrits.

En raison de l’opération asynchrone de cette fonction, des précautions doivent être prises pour s’assurer que ce paramètre référence toujours la mémoire valide pendant la durée de vie des écritures asynchrones. Par instance, une erreur de programmation courante consiste à utiliser le stockage de la pile locale, puis à autoriser l’exécution à s’exécuter en dehors de l’étendue.

[in] nNumberOfBytesToWrite

Nombre total d’octets à écrire. Chaque élément d’aSegmentArray contient un segment d’une page de ce total. Étant donné que le fichier doit être ouvert avec FILE_FLAG_NO_BUFFERING, le nombre d’octets doit être un multiple de la taille de secteur du système de fichiers où se trouve le fichier.

Si nNumberOfBytesToWrite est égal à zéro (0), la fonction effectue une opération d’écriture null. Le comportement d’une opération d’écriture null dépend du système de fichiers sous-jacent. Si nNumberOfBytesToWrite n’est pas égal à zéro (0) et que le décalage et la longueur des données de place d’écriture au-delà de la fin actuelle du fichier, la fonction WriteFileGather étend le fichier.

lpReserved

Ce paramètre est réservé pour une utilisation ultérieure et doit être NULL.

[in, out] lpOverlapped

Pointeur vers une structure de données CHEVAUCHEMENT .

La fonction WriteFileGather nécessite une structure CHEVAUCHEMENT VALIDE . Le paramètre lpOverlapped ne peut pas être NULL.

La fonction WriteFileGather commence à écrire des données dans le fichier à une position spécifiée par les membres Offset et OffsetHigh de la structure OVERLAPPED .

La fonction WriteFileGather peut retourner avant la fin de l’opération d’écriture. Dans ce scénario, la fonction WriteFileGather retourne la valeur zéro (0) et la fonction GetLastError renvoie la valeur ERROR_IO_PENDING. Cette opération asynchrone de la fonction WriteFileGather permet au processus appelant de continuer pendant que l’opération d’écriture se termine.

Vous pouvez appeler la fonction GetOverlappedResult, HasOverlappedIoCompleted ou GetQueuedCompletionStatus pour obtenir des informations sur la fin de l’opération d’écriture. Pour plus d’informations, consultez E/S synchrones et asynchrones.

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 (0). Pour obtenir des informations détaillées sur l’erreur, appelez la fonction GetLastError.

Si la fonction retourne avant la fin de l’opération d’écriture, la fonction retourne zéro (0) et la fonction GetLastError retourne ERROR_IO_PENDING.

Remarques

Cette fonction n’est pas prise en charge pour les applications 32 bits par WOW64 sur les systèmes Itanium.

La structure FILE_SEGMENT_ELEMENT est définie comme suit :

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

L’affectation d’un pointeur au membre Buffer signe-étend la valeur si le code est compilé en 32 bits ; Cela peut arrêter les applications prenant en charge les grandes adresses qui s’exécutent sur des systèmes configurés avec un réglage de 4 gigaoctets ou s’exécutant sous WOW64 sur Windows 64 bits. Par conséquent, utilisez la macro PtrToPtr64 lors de l’affectation de pointeurs vers Buffer.

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

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 handle de fichier, l’opération est traitée.

Configuration requise


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