Función ReadConsole

Artículo
12/21/2023

Lee la entrada de caracteres del búfer de entrada de la consola y la elimina del búfer.

Sintaxis

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

Parámetros

hConsoleInput [in]
Identificador del búfer de entrada de la consola. El identificador debe tener derecho de acceso de GENERIC_READ. Para obtener más información, consulte Seguridad y derechos de acceso del búfer de la consola.

lpBuffer [out]
Puntero a un búfer que recibe los datos leídos del búfer de entrada de la consola.

nNumberOfCharsToRead [in]
Número de caracteres que se va a leer. El tamaño del búfer al que apunta el parámetro lpBuffer debe ser de al menos nNumberOfCharsToRead * sizeof(TCHAR) bytes.

lpNumberOfCharsRead [out]
Puntero a una variable que recibe el número de caracteres leídos realmente.

pInputControl [in, optional]
Puntero a una estructura CONSOLE_READCONSOLE_CONTROL que especifica un carácter de control para indicar el final de la operación de lectura. Este parámetro puede ser NULL.

Este parámetro requiere la entrada Unicode de forma predeterminada. Para el modo ANSI, establezca este parámetro en NULL.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

ReadConsole lee la entrada de teclado desde el búfer de entrada de una consola. Se comporta como la función ReadFile, salvo que puede leerse en modo Unicode (carácter ancho) o ANSI. Para disponer de aplicaciones que mantengan un único conjunto de orígenes compatibles con ambos modos, utilice ReadConsole en lugar de ReadFile. A diferencia de ReadConsole, que solo se puede utilizar con un identificador de búfer de entrada de la consola, ReadFile se puede usar con otros identificadores (como archivos o canalizaciones). ReadConsole genera un error si se utiliza con un identificador estándar redirigido para ser algo distinto de un identificador de consola.

Todos los modos de entrada que afectan al comportamiento de ReadFile tienen el mismo efecto en ReadConsole. Para recuperar y establecer los modos de salida del búfer de entrada de una consola, utilice las funciones GetConsoleMode y SetConsoleMode.

Si el búfer de entrada contiene eventos de entrada que no son eventos de teclado (como eventos del mouse o de cambio de tamaño de ventana), se descartan. Esos eventos solo se pueden leer con la función ReadConsoleInput.

Esta función usa caracteres Unicode o caracteres de 8 bits de la página de códigos actual de la consola. La página de códigos de la consola tiene como valor predeterminado la página de códigos OEM del sistema. Para cambiar la página de códigos de la consola, use las funciones SetConsoleCP o SetConsoleOutputCP. Los consumidores heredados también pueden usar los comandos chcp o mode con cp select=, pero no se recomienda si va a desarrollar algo nuevo.

El parámetro pInputControl se puede utilizar para habilitar reactivaciones intermedias desde la lectura en respuesta a un carácter de control de finalización de archivos especificado en una estructura CONSOLE_READCONSOLE_CONTROL. Esta función requiere que las extensiones de comandos estén habilitadas, que el identificador de salida estándar sea un identificador de salida de la consola y que la entrada sea Unicode.

Windows Server 2003 y Windows XP/2000: no se admite la función de lectura intermedia.

En el modo cocinado, se establece ENABLE_LINE_INPUT con SetConsoleMode en el identificador de entrada de la consola. En este modo, el host de consola proporciona una línea de edición en nombre de la aplicación de línea de comandos y las llamadas a ReadFile o ReadConsole no devuelven resultados hasta que se presiona la tecla Entrar.

Lectura intermedia aumenta ese comportamiento en la llamada de ReadConsole en modo cocinado de lectura. Si se establece una marca en dwCtrlWakeupMask en la estructura CONSOLE_READCONSOLE_CONTROL y se pasa a pinputControl cuando llama a ReadConsole, la lectura no espera necesariamente una nueva línea y también devuelve resultados con el carácter especificado.

Requisitos


Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Encabezado	ConsoleApi.h (a través de WinCon.h, incluido Windows.h)
Biblioteca	Kernel32.lib
Archivo DLL	Kernel32.dll
Nombres Unicode y ANSI	ReadConsoleW (Unicode) y ReadConsoleA (ANSI)