Fonction WriteConsoleOutput

Article
12/15/2023

Important

Ce document décrit les fonctionnalités de la plateforme de console qui ne font plus partie de notre feuille de route de l’é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 terminal virtuel pour une compatibilité maximale dans les scénarios multiplateformes. Vous trouverez plus d’informations sur cette décision de conception dans notre document console classique versus terminal virtuel.

Écrit les données d’attribut de caractère et de couleur dans un bloc rectangulaire spécifié de cellules de caractères dans une mémoire tampon d’écran de console. Les données à écrire sont extraites d’un bloc rectangulaire de taille correspondante à un emplacement spécifié dans la mémoire tampon source.

Syntaxe

BOOL WINAPI WriteConsoleOutput(
  _In_          HANDLE      hConsoleOutput,
  _In_    const CHAR_INFO   *lpBuffer,
  _In_          COORD       dwBufferSize,
  _In_          COORD       dwBufferCoord,
  _Inout_       PSMALL_RECT lpWriteRegion
);

Paramètres

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

lpBuffer [entrée]
Les données à écrire dans 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]
Taille de la mémoire tampon pointée par le paramètre lpBuffer, dans les 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]
Coordonnées de la cellule supérieure gauche dans la mémoire tampon pointée par le paramètre lpBuffer. Le membre X de la structure COORD est la colonne et le membre Y est la ligne.

lpWriteRegion [entrée, sortie]
Un pointeur vers une structure SMALL_RECT. Lors de l’entrée, les membres de la structure spécifient les coordonnées supérieure gauche et inférieure droite du rectangle de mémoire tampon de l’écran de console dans lequel écrire. En sortie, les membres de la structure spécifient le rectangle réellement utilisé.

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.

Notes

WriteConsoleOutput traite la mémoire tampon source et la mémoire tampon de l’écran de destination en tant que tableaux à deux dimensions (colonnes et lignes de cellules de caractères). Le rectangle pointé par le paramètre lpWriteRegion spécifie la taille et l’emplacement du bloc à écrire dans la mémoire tampon de l’écran de la console. Un rectangle 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 des cellules qui se trouvent à l’intersection de ce rectangle et du rectangle de mémoire tampon source (dont les dimensions sont spécifiées par le paramètre dwBufferSize) sont écrites dans le rectangle de destination.

Les cellules du rectangle de destination dont l’emplacement source correspondant se trouve en dehors des limites du rectangle de mémoire tampon source ne sont pas affectées par l’opération d’écriture. En d’autres termes, il s’agit des cellules pour lesquelles aucune donnée n’est disponible pour être écrite.

Avant que la fonction WriteConsoleOutput envoie son retour, elle définit les membres de lpWriteRegion sur le rectangle de mémoire tampon d’écran réel affecté par l’opération d’écriture. Ce rectangle reflète les cellules du rectangle de destination pour lesquelles il existait une cellule correspondante dans la mémoire tampon source, car WriteConsoleOutput extrait les dimensions du rectangle de destination aux limites de la mémoire tampon d’écran de la console.

Si le rectangle spécifié par lpWriteRegion se trouve complètement en dehors des limites de la mémoire tampon de l’écran de console, ou si le rectangle correspondant est positionné complètement en dehors des limites de la mémoire tampon source, aucune donnée n’est écrite. Dans ce cas, la fonction renvoie les membres de la structure pointées par le paramètre lpWriteRegion 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 d’écran de console, utilisez la fonction GetConsoleScreenBufferInfo.

WriteConsoleOutput n’a aucun effet sur la position du curseur.

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 a un équivalent au terminal virtuel dans les séquences de mise en forme du texte et de positionnement de curseur. Déplacez le curseur vers l’emplacement à insérer, appliquez la mise en forme souhaitée et écrivez le texte. Les séquences de terminal virtuel sont recommandées pour tout développement nouveau et continu.

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, inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll
Noms Unicode et ANSI	WriteConsoleOutputW (Unicode) et WriteConsoleOutputA (ANSI)