Fonction ReadConsole

Article
12/22/2023

Lit les entrées de caractères dans la mémoire tampon d'entrée de console et les retire de la mémoire tampon.

Syntaxe

BOOL WINAPI ReadConsole(
  _In_     HANDLE  hConsoleInput,
  _Out_    LPVOID  lpBuffer,
  _In_     DWORD   nNumberOfCharsToRead,
  _Out_    LPDWORD lpNumberOfCharsRead,
  _In_opt_ LPVOID  pInputControl
);

Paramètres

hConsoleInput [entrée]
Un descripteur vers la mémoire tampon d’entrée de 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 qui reçoit les données lues à partir de la mémoire tampon d’entrée de console.

nNumberOfCharsToRead [entrée]
Le nombre de caractères à lire. La taille de la mémoire tampon indiquée par le paramètre lpBuffer doit être d'au moins nNumberOfCharsToRead * sizeof(TCHAR) octets.

lpNumberOfCharsRead [sortie]
Un pointeur sur une variable qui reçoit le nombre de caractères réellement lus.

pInputControl [entrée, facultatif]
Un pointeur vers une structure CONSOLE_READCONSOLE_CONTROL qui spécifie un caractère de contrôle pour signaler la fin de l’opération de lecture. Ce paramètre peut être NULL.

Ce paramètre nécessite une entrée Unicode par défaut. Pour le mode ANSI, définissez ce paramètre sur NUL.

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 ReadConsole lit l’entrée de clavier à partir de la mémoire tampon d’entrée d’une console. Elle se comporte comme la fonction ReadFile, sauf qu’elle peut lire en mode Unicode (caractère large) ou ANSI. Pour que les applications qui gèrent un seul ensemble de sources soient compatibles avec les deux modes, utilisez la fonction ReadConsole plutôt que ReadFile. Bien que la fonction ReadConsole ne puisse être utilisée qu'avec un gestionnaire de mémoire tampon d'entrée de console, la fonction ReadFile peut être utilisée avec d'autres gestionnaires (tels que des fichiers ou des pipes). La ReadConsole échoue si elle est utilisée avec un descripteur standard qui a été redirigé pour être autre chose qu’un descripteur de console.

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

Si la mémoire tampon d’entrée contient des événements d’entrée autres que les événements de clavier (tels que les événements de souris ou les événements de redimensionnement de fenêtre), ils sont ignorées. Ces événements ne peuvent être lus qu’à l’aide de la fonction ReadConsoleInput.

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.

Le paramètre pInputControl peut être utilisé pour activer les réveils intermédiaires de la lecture en réponse à un caractère de contrôle de fin de fichier spécifié dans une structure CONSOLE_READCONSOLE_CONTROL. Cette fonctionnalité nécessite que les extensions de commande soient activées, que le descripteur de sortie standard soit un descripteur de sortie de console et que l’entrée soit Unicode.

Windows Server 2003 et Windows XP/2000 : la fonctionnalité de lecture intermédiaire n’est pas prise en charge.

Le mode traité correspond à la définition de la structure ENABLE_LINE_INPUT avec la fonction SetConsoleMode sur le descripteur d’entrée de console. En mode traité, l’hôte de console fournit une ligne de modification au nom de l’application en ligne de commande et les appels à la fonction ReadFile ou ReadConsole ne renvoient pas tant que la touche Entrée n’est pas appuyée.

La lecture intermédiaire est une extension de ce comportement sur l’appel à la fonction ReadConsole en mode lecture traité. La définition d'un indicateur dans dwCtrlWakeupMask sur la structure CONSOLE_READCONSOLE_CONTROL et sa transmission à pinputControl lors de l'appel de la fonction ReadConsole feront que la lecture n'attendra pas nécessairement une nouvelle ligne, mais qu'elle renverra également sur un caractère spécifié.

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	ReadConsoleW (Unicode) et ReadConsoleA (ANSI)