Fonction ReadFileEx (fileapi.h)
Lit les données du fichier ou du 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 la lecture est terminée ou annulée et que le thread appelant est dans un état d’attente pouvant être alerté.
Pour lire les données d’un fichier ou d’un appareil de manière synchrone, utilisez la fonction ReadFile .
Syntaxe
BOOL ReadFileEx(
[in] HANDLE hFile,
[out, optional] LPVOID lpBuffer,
[in] DWORD nNumberOfBytesToRead,
[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 .
Ce handle doit également avoir le droit d’accès GENERIC_READ . Pour plus d’informations sur les droits d’accès, consultez Sécurité des fichiers et droits d’accès.
[out, optional] lpBuffer
Pointeur vers une mémoire tampon qui reçoit les données lues à partir du fichier ou de l’appareil.
Cette mémoire tampon doit rester valide pendant toute la durée de l’opération de lecture. L’application ne doit pas utiliser cette mémoire tampon tant que l’opération de lecture n’est pas terminée.
[in] nNumberOfBytesToRead
Nombre d'octets à lire.
[in, out] lpOverlapped
Pointeur vers une structure de données CHEVAUCHEMENT QUI fournit des données à utiliser pendant l’opération de lecture de fichier 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 à partir duquel commencer la lecture à partir du 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.
La fonction ReadFileEx 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 ReadFileEx . ReadFileEx signale l’achèvement de son opération de lecture 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 ReadFileEx utilise les membres Internal et InternalHigh de la structure OVERLAPPED. Une application ne doit pas définir ces membres.
La structure de données OVERLAPPED doit rester valide pendant toute la durée de l’opération de lecture. Il ne doit pas s’agir d’une variable qui peut sortir de l’étendue pendant que l’opération de lecture est en attente d’achèvement.
[in] lpCompletionRoutine
Pointeur vers la routine d’achèvement à appeler lorsque l’opération de lecture est terminée et que le thread appelant est dans un état d’attente pouvant être alerté. Pour plus d’informations sur la 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 réussit, le thread appelant a une opération d’E/S asynchrone en attente : l’opération de lecture qui se chevauche à partir du 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 appelle la fonction pointée par lpCompletionRoutine, et l’état d’attente se termine avec un code de retour de WAIT_IO_COMPLETION.
Si la fonction réussit et que l’opération de lecture 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 de routine d’achèvement, en maintenant l’appel jusqu’à ce que le thread appelant passe à un état d’attente pouvant être alerté. Pour plus d’informations sur les attentes pouvant être alertées et les opérations d’entrée/sortie qui se chevauchent, consultez À propos de la synchronisation.
Si ReadFileEx tente de lire au-delà de la fin du fichier (EOF), l’appel à GetOverlappedResult pour cette opération retourne FALSE et GetLastError renvoie ERROR_HANDLE_EOF.
Remarques
Lorsque vous utilisez ReadFileEx, 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 dont vous souhaitez peut-être connaître le résultat. Par exemple, un dépassement de mémoire tampon lors de l’appel de ReadFileEx 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 ReadFileEx peut échouer s’il y a trop de demandes d’E/S asynchrones en attente. En cas d’échec, 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 descripteur de fichier spécifié.
- CancelIoEx : cette fonction annule toutes les opérations émises par les threads pour le descripteur de fichier spécifié.
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 de lecture spécifiée dans un appel à ReadFileEx chevauche la partie verrouillée, l’appel à ReadFileEx échoue.
Lorsque vous tentez de lire des données à partir d’un maillot dont la mémoire tampon est trop petite, ReadFileEx renvoie FALSE et GetLastError renvoie ERROR_INSUFFICIENT_BUFFER.
L’accès à la mémoire tampon d’entrée pendant qu’une opération de lecture utilise la mémoire tampon peut entraîner une altération des données lues dans cette mémoire tampon. Les applications ne doivent pas lire, écrire dans, réallouer ou libérer la mémoire tampon d’entrée qu’une opération de lecture utilise tant que l’opération de lecture n’est pas terminée.
Une application utilise les fonctions MsgWaitForMultipleObjectsEx, WaitForSingleObjectEx, WaitForMultipleObjectsEx et SleepEx pour entrer dans un état d’attente pouvant être alerté. Pour plus d’informations sur les attentes pouvant être alertées et les entrées/sorties qui se chevauchent, consultez À propos de la synchronisation.
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, 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. 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 |