Fonction ReadConsoleOutput

Article
12/22/2023

Important

Ce document décrit les fonctionnalités de la plateforme de la console qui ne font plus partie de la feuille de route de notre écosystème. Nous vous déconseillons d’utiliser ce contenu dans de nouveaux produits, mais nous continuerons à prendre en charge des utilisations existantes pour l’avenir indéterminé. Notre solution moderne préférée se concentre sur les séquences de terminaux virtuels pour une compatibilité maximale dans les scénarios multiplateformes. Vous trouverez plus d’informations sur cette décision de conception dans notre document sur les consoles classiques et les terminaux virtuels.

Lit les données relatives aux caractères et aux attributs de couleur à partir d'un bloc rectangulaire de cellules de caractères dans une mémoire tampon de l'écran de la console, et la fonction écrit les données dans un bloc rectangulaire à un emplacement spécifié dans la mémoire tampon de destination.

Syntaxe

BOOL WINAPI ReadConsoleOutput(
  _In_    HANDLE      hConsoleOutput,
  _Out_   PCHAR_INFO  lpBuffer,
  _In_    COORD       dwBufferSize,
  _In_    COORD       dwBufferCoord,
  _Inout_ PSMALL_RECT lpReadRegion
);

Paramètres

hConsoleOutput [entrée]
Un descripteur vers la mémoire tampon de l’écran de la console. Le descripteur doit avoir le droit d’accès GENERIC_READ. Pour plus d’informations, consultez Sécurité de la mémoire tampon et droits d’accès d’une console.

lpBuffer [sortie]
Un pointeur vers une mémoire tampon de destination qui reçoit les données lues à partir de la mémoire tampon de l’écran de la console. Ce pointeur est traité comme l’origine d’un tableau à deux dimensions de structures CHAR_INFO dont la taille est spécifiée par le paramètre dwBufferSize.

dwBufferSize [entrée]
La taille de la mémoire tampon pointée par le paramètre lpBuffer, en cellules de caractères. Le membre X de la structure COORD est le nombre de colonnes ; le membre Y est le nombre de lignes.

dwBufferCoord [entrée]
Les coordonnées de la cellule supérieure gauche du paramètre lpBuffer qui reçoit les données lues à partir de la mémoire tampon de l'écran de la console. Le membre X de la structure COORD est la colonne et le membre Y est la ligne.

lpReadRegion [entrée, sortie]
Un pointeur vers une structure SMALL_RECT. En entrée, les membres de la structure spécifient les coordonnées supérieure gauche et inférieure droite du rectangle de la mémoire tampon de l'écran de la console à partir duquel la fonction doit être lue. En sortie, les membres de la structure spécifient le rectangle réellement utilisé.

Valeur renvoyé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.

Notes

La fonction ReadConsoleOutput traite la mémoire tampon de l’écran de la console et la mémoire tampon de destination en tant que tableaux à deux dimensions (colonnes et lignes de cellules de caractères). Le rectangle pointé par le paramètre lpReadRegion spécifie la taille et l’emplacement du bloc à lire à partir de la mémoire tampon de l’écran de la console. Un rectangle de destination de la même taille est positionné avec sa cellule supérieure gauche aux coordonnées du paramètre dwBufferCoord dans le tableau lpBuffer. Les données lues dans les cellules du rectangle source de la mémoire tampon de l'écran de la console sont copiées dans les cellules correspondantes de la mémoire tampon de destination. Si la cellule correspondante se trouve en dehors des limites du rectangle de la mémoire tampon de destination (dont les dimensions sont spécifiées par le paramètre dwBufferSize), les données ne sont pas copiées.

Les cellules de la mémoire tampon de destination correspondant à des coordonnées qui ne se trouvent pas dans les limites de la mémoire tampon de l'écran de la console restent inchangées. En d'autres termes, il s'agit des cellules pour lesquelles aucune donnée de la mémoire tampon de l'écran ne peut être lue.

Avant que la fonction ReadConsoleOutput ne soit renvoyée, elle définit les membres de la structure indiquée par le paramètre lpReadRegion en fonction du rectangle de la mémoire tampon de l'écran dont les cellules ont été copiées dans la mémoire tampon de destination. Ce rectangle reflète les cellules du rectangle source pour lesquelles il existait une cellule correspondante dans la mémoire tampon de destination, car la fonction ReadConsoleOutput réduit les dimensions du rectangle source pour l'adapter aux limites de la mémoire tampon de l'écran de la console.

Si le rectangle spécifié par le paramètre lpReadRegion se trouve complètement en dehors des limites de la mémoire tampon de l’écran de la console, ou si le rectangle correspondant est positionné complètement en dehors des limites de la mémoire tampon de destination, aucune donnée n’est copiée. Dans ce cas, la fonction renvoie les membres de la structure pointées par le paramètre lpReadRegion défini de sorte que le membre Droite soit inférieur au membre Gauche, ou que le membre Bas soit inférieur au membre Haut. Pour déterminer la taille de la mémoire tampon de l’écran de la console, utilisez la fonction GetConsoleScreenBufferInfo.

La fonction ReadConsoleOutput n’a aucun effet sur la position du curseur de la mémoire tampon de l’écran de la console. Le contenu de la mémoire tampon de l’écran de la console n’est pas modifié par la fonction.

Cette fonction utilise des caractères Unicode ou des caractères 8 bits de la page de codes actuelle de la console. Par défaut, la page de codes de la console est initialement définie sur la page de codes OEM du système. Pour changer la page de codes de la console, utilisez les fonctions SetConsoleCP ou SetConsoleOutputCP. Les consommateurs existants peuvent également utiliser les commandes chcp ou mode con cp select=, mais ce n’est pas recommandé pour un nouveau développement.

Conseil

Cette API n’est pas recommandée et n’a pas d’équivalent de terminal virtuel. Cette décision aligne intentionnellement la plateforme Windows avec d’autres systèmes d’exploitation où l’application cliente individuelle est censée mémoriser son propre état dessiné pour une manipulation supplémentaire. La communication à distance des applications via des utilitaires multiplateformes et des transports comme SSH peut ne pas fonctionner comme prévu si vous utilisez cette API.

Exemples

Pour obtenir un exemple, consultez Lecture et écriture de blocs de caractères et d’attributs.

Spécifications


Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
En-tête	ConsoleApi2.h (via WinCon.h, include Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll
Noms Unicode et ANSI	ReadConsoleOutputW (Unicode) et ReadConsoleOutputA (ANSI)