Fonction ReadFile (fileapi.h)

Article
11/08/2024

Lit les données à partir du fichier ou de l’appareil d’entrée/sortie (E/S) spécifié. Les lectures se produisent à la position spécifiée par le pointeur de fichier si elle est prise en charge par l’appareil.

Cette fonction est conçue pour les opérations synchrones et asynchrones. Pour une fonction similaire conçue uniquement pour une opération asynchrone, consultez ReadFileEx.

Syntaxe

BOOL ReadFile(
  [in]                HANDLE       hFile,
  [out]               LPVOID       lpBuffer,
  [in]                DWORD        nNumberOfBytesToRead,
  [out, optional]     LPDWORD      lpNumberOfBytesRead,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

Paramètres

[in] hFile

Handle sur l’appareil (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).

Le paramètre hFile doit avoir été créé avec accès en lecture. Pour plus d’informations, consultez droits d’accès génériques et sécurité des fichiers et droits d’accès.

Pour les opérations de lecture asynchrones, hFile peut être n’importe quel handle ouvert avec l’indicateur de FILE_FLAG_OVERLAPPED par la fonction CreateFile , ou un handle de socket retourné par la de socket ou accepter fonction.

[out] lpBuffer

Pointeur vers la mémoire tampon qui reçoit les données lues à partir d’un fichier ou d’un appareil.

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

[in] nNumberOfBytesToRead

Nombre maximal d’octets à lire.

[out, optional] lpNumberOfBytesRead

Pointeur vers la variable qui reçoit le nombre d’octets lus lors de l’utilisation d’un paramètre hFile synchrone. ReadFile définit cette valeur sur zéro avant d’effectuer une vérification de travail ou d’erreur. Utilisez NULL pour ce paramètre s’il s’agit d’une opération asynchrone pour éviter les résultats potentiellement erronés.

Ce paramètre peut être NULL uniquement lorsque le paramètre lpOverlapped n’est pas NULL.

Windows 7 : Ce paramètre ne peut pas être NULL.

Pour plus d’informations, consultez la section Remarques.

[in, out, optional] lpOverlapped

Un pointeur vers une structure SUPERPOSÉE est nécessaire si le paramètre hFile a été ouvert avec FILE_FLAG_OVERLAPPED; sinon, il peut être NULL.

Si hFile est ouvert avec FILE_FLAG_OVERLAPPED, le paramètre lpOverlapped doit pointer vers une structure SE CHEVAUCHE R, sinon la fonction peut signaler de manière incorrecte que l’opération de lecture est terminée.

Pour un hFile prenant en charge les décalages d’octets, si vous utilisez ce paramètre, vous devez spécifier un décalage d’octet à partir duquel commencer la lecture à partir du fichier ou de l’appareil. Ce décalage est spécifié en définissant le offset et les membres OffsetHigh de la structure SE CHEVAUCHER. Pour un hFile qui ne prend pas en charge les décalages d’octets, offset et offsetHigh sont ignorés.

Pour plus d’informations sur différentes combinaisons de lpOverlapped et de FILE_FLAG_OVERLAPPED, consultez la section Remarques et la section Synchronisation et position de fichier.

Valeur de retour

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

Si la fonction échoue ou se termine de façon asynchrone, la valeur de retour est égale à zéro (FALSE). Pour obtenir des informations d’erreur étendues, appelez la fonction GetLastError.

Note

Le code GetLastErrorERROR_IO_PENDING n’est pas un échec ; elle désigne l’opération de lecture en attente d’achèvement de manière asynchrone. Pour plus d’informations, consultez Remarques.

Remarques

La fonction ReadFile retourne quand l’une des conditions suivantes se produit :

Le nombre d’octets demandés est lu.
Une opération d’écriture se termine sur la fin d’écriture du canal.
Un handle asynchrone est utilisé et la lecture se produit de façon asynchrone.
Une erreur se produit.

La fonction ReadFile peut échouer avec ERROR_INVALID_USER_BUFFER ou ERROR_NOT_ENOUGH_MEMORY chaque fois qu’il y a trop de requêtes d’E/S asynchrones en attente.

Pour annuler toutes les opérations d’E/S asynchrones en attente, utilisez :

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.

Opérations d’E/S annulées avec l’erreur ERROR_OPERATION_ABORTED.

La fonction ReadFile peut échouer avec ERROR_NOT_ENOUGH_QUOTA, ce qui signifie que la mémoire tampon du processus appelant n’a pas pu être verrouillée sur les pages. Pour plus d’informations, consultez SetProcessWorkingSetSize.

Si une partie d’un fichier est verrouillée par un autre processus et que l’opération de lecture chevauche la partie verrouillée, cette fonction échoue.

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. Cela peut être particulièrement problématique lors de l’utilisation d’un handle de fichier asynchrone. Vous trouverez des informations supplémentaires sur les handles de fichiers synchrones et asynchrones dans la section synchronisation et position de fichier et dans la rubrique de référence CreateFile.

Les caractères peuvent être lus à partir de la mémoire tampon d’entrée de la console à l’aide de readFile avec un handle d’entrée de console. Le mode console détermine le comportement exact de la fonction ReadFile. Par défaut, le mode console est ENABLE_LINE_INPUT, ce qui indique que ReadFile doit lire jusqu’à ce qu’elle atteigne un retour chariot. Si vous appuyez sur Ctrl+C, l’appel réussit, mais GetLastError retourne ERROR_OPERATION_ABORTED. Pour plus d’informations, consultez CreateFile.

Lors de la lecture à partir d’un appareil de communication, le comportement de ReadFile est déterminé par le délai d’attente de communication actuel défini et récupéré à l’aide des fonctions SetCommTimeouts et GetCommTimeouts. Des résultats imprévisibles peuvent se produire si vous ne parvenez pas à définir les valeurs de délai d’attente. Pour plus d’informations sur les délais de communication, consultez COMMTIMEOUTS.

Si ReadFile tente de lire à partir d’un maillot dont la mémoire tampon est trop petite, la fonction retourne faux et GetLastError retourne ERROR_INSUFFICIENT_BUFFER.

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

Si hFile a été ouvert avec FILE_FLAG_OVERLAPPED, les conditions suivantes sont en vigueur :

Le paramètre lpOverlapped doit pointer vers une structure SE CHEVAUCHER, sinon la fonction peut signaler de manière incorrecte que l’opération de lecture est terminée.
Le paramètre lpNumberOfBytesRead doit être défini sur NULL. Utilisez la fonction GetOverlappedResult pour obtenir le nombre réel d’octets lus. Si le paramètre hFile est associé à un port d’achèvement d’E/S, vous pouvez également obtenir le nombre d’octets lus en appelant la fonction GetQueuedCompletionStatus.

Synchronisation et position de fichier

Si hFile est ouvert avec FILE_FLAG_OVERLAPPED, il s’agit d’un handle de fichier asynchrone ; sinon, il est synchrone. Les règles d’utilisation de la structure de QUI SE CHEVAUCHENT sont légèrement différentes pour chacune d’elles, comme indiqué précédemment.

Note

Si un fichier ou un appareil est ouvert pour les E/S asynchrones, les appels suivants aux fonctions telles que ReadFile à l’aide de ce handle retournent généralement immédiatement, mais peuvent également se comporter de manière synchrone en ce qui concerne l’exécution bloquée. Pour plus d’informations, consultez E/S de disque asynchrone s’affiche comme synchrone sur Windows.

Considérations relatives à l’utilisation de handles de fichiers asynchrones :

readFile peut retourner avant la fin de l’opération de lecture. Dans ce scénario, ReadFile retourne FALSE et la fonction GetLastError retourne ERROR_IO_PENDING, ce qui permet au processus appelant de continuer pendant que le système termine l’opération de lecture.
Le paramètre
lpOverlapped ne doit pas être NULL et doit être utilisé avec les faits suivants à l’esprit :
- Bien que l’événement spécifié dans la structure de SE CHEVAUCHER soit défini et réinitialisé automatiquement par le système, le décalage spécifié dans la structure SUPERPOSÉE n’est pas automatiquement mis à jour.
- ReadFile réinitialise l’événement à un état non signé lorsqu’il démarre l’opération d’E/S.
- L’événement spécifié dans la structure de SE CHEVAUCHER est défini sur un état signalé lorsque l’opération de lecture est terminée ; jusqu’à ce stade, l’opération de lecture est considérée comme en attente.
- Étant donné que l’opération de lecture commence au décalage spécifié dans la structure SE CHEVAUCHER et que ReadFile peut retourner avant la fin de l’opération de lecture au niveau du système (lecture en attente), ni le décalage ni toute autre partie de la structure ne doit être modifié, libéré ou réutilisé par l’application jusqu’à ce que l’événement soit signalé (autrement dit, la lecture est terminée).
- Si la fin du fichier (EOF) est détectée pendant les opérations asynchrones, l’appel à GetOverlappedResult pour cette opération retourne FALSE et GetLastError retourne ERROR_HANDLE_EOF.

Considérations relatives à l’utilisation de handles de fichiers synchrones :

Si lpOverlapped est NULL, l’opération de lecture commence à la position de fichier actuelle et ReadFile ne retourne pas tant que l’opération n’est pas terminée, et que le système met à jour le pointeur de fichier avant ReadFile retourne.
Si lpOverlapped n’est pas NULL, l’opération de lecture commence au décalage spécifié dans la structure SE CHEVAUCHER et ReadFile ne retourne pas tant que l’opération de lecture n’est pas terminée. Le système met à jour le décalage de superposé et le pointeur de fichier avant de retourner ReadFile.
Si lpOverlapped est NULL, lorsqu’une opération de lecture synchrone atteint la fin d’un fichier, ReadFile retourne TRUE et définit *lpNumberOfBytesRead sur zéro.
Si lpOverlapped n’est pas NULL, quand une opération de lecture synchrone atteint la fin d’un fichier, ReadFile retourne FALSE et GetLastError retourne ERROR_HANDLE_EOF.

Pour plus d’informations, consultez CreateFile et d’E/S synchrones et asynchrones.

Tuyaux

Si un canal anonyme est utilisé et que le handle d’écriture a été fermé, lorsque ReadFile tente de lire à l’aide du handle de lecture correspondant du canal, la fonction retourne FALSE et GetLastError retourne ERROR_BROKEN_PIPE.

Si un canal nommé est lu en mode message et que le message suivant est plus long que le paramètre nNumberOfBytesToRead spécifie, ReadFile retourne FALSE et GetLastError retourne ERROR_MORE_DATA. Le reste du message peut être lu par un appel ultérieur à l'ReadFile ou fonction PeekNamedPipe.

Si le paramètre lpNumberOfBytesRead est égal à zéro lorsque ReadFile retourne TRUE sur un canal, l’autre extrémité du canal appelé fonction WriteFile avec nNumberOfBytesToWrite défini sur zéro.

Pour plus d’informations sur les canaux, consultez Pipes.

Opérations transactionnelles

S’il existe une transaction liée au handle de fichier, la fonction retourne les données de la vue transactionnelle du fichier. Un handle de lecture transactionné est garanti pour afficher la même vue d’un fichier pendant la durée du handle. Pour plus d’informations, consultez About Transactional NTFS.

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

Technologie	Supporté
Protocole SMB (Server Message Block) 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
Cluster Shared Volume File System (CsvFS)	Oui
Système de fichiers résilient (ReFS)	Oui

Exemples

Pour obtenir un exemple de code qui vous montre comment tester la fin du fichier, consultez Test de la fin d’un fichier. Pour obtenir d’autres exemples, consultez Création et utilisation d’un fichier temporaire et Ouverture d’un fichier pour la lecture ou l’écriture.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau \| Applications UWP]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau \| Applications UWP]
plateforme cible	Windows
d’en-tête	fileapi.h (include Windows.h)
bibliothèque	Kernel32.lib
DLL	Kernel32.dll