Fonction ReadFileScatter (fileapi.h)

Article
01/10/2024

Lit les données d’un fichier et les stocke dans un tableau de mémoires tampons.

La fonction commence à lire les données du fichier à une position spécifiée par une structure CHEVAUCHEMENT . La fonction ReadFileScatter fonctionne de manière asynchrone.

Syntaxe

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

Paramètres

[in] hFile

Handle du fichier à lire.

Le handle de fichier doit être créé avec le GENERIC_READ droit 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 reçoit 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 GetSystemInfo.

Le tableau doit contenir suffisamment d’éléments pour représenter nNumberOfBytesToRead octets de données. Par exemple, s’il y a 40 Ko à lire 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 de mémoire système et doit être alignée sur une limite de taille de page de mémoire système. Le système lit une page de mémoire système de données dans chaque mémoire tampon.

La fonction stocke les données dans les mémoires tampons dans l’ordre séquentiel. Par exemple, il stocke les données dans la première mémoire tampon, puis dans la deuxième mémoire tampon, et ainsi de suite jusqu’à ce que chaque mémoire tampon soit remplie et que toutes les données soient stockées, ou que nNumberOfBytesToRead octets aient été lus.

[in] nNumberOfBytesToRead

Nombre total d’octets à lire à partir du fichier. 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 correspondre à un multiple de la taille de secteur du système de fichiers où se trouve le fichier.

lpReserved

Ce paramètre est réservé à une utilisation ultérieure et doit avoir la valeur NULL.

[in, out] lpOverlapped

Pointeur vers une structure de données CHEVAUCHEMENT .

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

La fonction ReadFileScatter commence à lire les données du fichier à une position spécifiée par les membres Offset et OffsetHigh de la structure OVERLAPPED .

La fonction ReadFileScatter peut retourner avant la fin de l’opération de lecture. Dans ce scénario, la fonction ReadFileScatter retourne la valeur 0 (zéro), et la fonction GetLastError renvoie la valeur ERROR_IO_PENDING. Cette opération asynchrone de ReadFileScatter permet au processus appelant de continuer pendant la fin de l’opération de lecture. Vous pouvez appeler les fonctions GetOverlappedResult, HasOverlappedIoCompleted ou GetQueuedCompletionStatus pour obtenir des informations sur la fin de l’opération de lecture. 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 ReadFileScatter tente de lire au-delà de la fin du fichier (EOF), l’appel à GetOverlappedResult pour cette opération retourne FALSE et GetLastError retourne ERROR_HANDLE_EOF.

Si la fonction retourne avant la fin de l’opération de lecture, la fonction retourne zéro (0) et 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 interrompre les applications prenant en charge les grandes adresses s’exécutant 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 à La mémoire tampon.

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, la fonction retourne les données de la vue traitée du fichier. Un descripteur de lecture traité affiche nécessairement la même vue d’un fichier pendant toute la durée du descripteur.

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