Fonction WriteConsole

Article
07/12/2023

Écrit une chaîne de caractères dans une mémoire tampon d’écran de console en commençant à l’emplacement actuel du curseur.

Syntaxe

BOOL WINAPI WriteConsole(
  _In_             HANDLE  hConsoleOutput,
  _In_       const VOID    *lpBuffer,
  _In_             DWORD   nNumberOfCharsToWrite,
  _Out_opt_        LPDWORD lpNumberOfCharsWritten,
  _Reserved_       LPVOID  lpReserved
);

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]
Pointeur vers une mémoire tampon qui contient les caractères à écrire dans la mémoire tampon d’écran de console. Il doit s’agir d’un tableau de char pour WriteConsoleA ou de wchar_t pour WriteConsoleW.

nNumberOfCharsToWrite [entrée]
Nombre de caractères à écrire. Si la taille totale du nombre spécifié de caractères dépasse le tas disponible, la fonction échoue avec ERROR_NOT_ENOUGH_MEMORY.

lpNumberOfCharsWritten [sortie, facultatif]
Pointeur vers une variable qui reçoit le nombre de caractères réellement écrits.

lpReserved Réservé ; doit être NULL.

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

La fonction WriteConsole écrit des caractères dans la mémoire tampon d’écran de console, à la position actuelle du curseur. La position du curseur avance à mesure que des caractères sont écrits. La fonction SetConsoleCursorPosition définit la position actuelle du curseur.

Les caractères sont écrits en utilisant les attributs de couleur de premier plan et d’arrière-plan associés à la mémoire tampon d’écran de console. La fonction SetConsoleTextAttribute change ces couleurs. Pour déterminer les attributs de couleur actuels et la position actuelle du curseur, utilisez GetConsoleScreenBufferInfo.

Tous les modes d’entrée qui affectent le comportement de la fonction WriteFile ont le même effet sur WriteConsole. Pour récupérer et définir les modes de sortie d’une mémoire tampon d’écran de console, utilisez les fonctions GetConsoleMode et SetConsoleMode.

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.

WriteConsole échoue si elle est utilisée avec un handle standard qui est redirigé vers un fichier. Si une application traite une sortie multilingue qui peut être redirigée, déterminez si le handle de sortie est un handle de console (une méthode consiste à appeler la fonction GetConsoleMode et à vérifier si elle a réussi). Si le handle est un handle de console, appelez WriteConsole. Si le handle n’est pas un handle de console, la sortie est redirigée et vous devez appeler WriteFile pour effectuer les E/S. Veillez à faire précéder un fichier texte brut Unicode par une marque d’ordre des octets. Pour plus d’informations, consultez Utilisation des marques d’ordre des octets.

Bien qu’une application puisse utiliser WriteConsole en mode ANSI pour écrire des caractères ANSI, les consoles ne prennent pas en charge les séquences « échappement ANSI » ou « terminal virtuel », sauf si elles sont activées. Pour plus d’informations et l’applicabilité selon la version du système d’exploitation, consultez Séquences de terminal virtuel de la console.

Quand les séquences d’échappement du terminal virtuel ne sont pas activées, les fonctions de la console peuvent fournir des fonctionnalités équivalentes. Pour plus d’informations, consultez SetCursorPos, SetConsoleTextAttribute et GetConsoleCursorInfo.

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	ConsoleApi.h (via WinCon.h, inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll
Noms Unicode et ANSI	WriteConsoleW (Unicode) et WriteConsoleA (ANSI)