Función ReadConsoleOutputCharacter

Artículo
12/21/2023

Importante

En este documento se describe funcionalidad de la plataforma de consola que ya no forma parte de nuestro plan de desarrollo del ecosistema. No se recomienda usar este contenido en nuevos productos, pero seguiremos admitiendo los usos existentes para el futuro indefinido. Nuestra solución moderna preferida se centra en secuencias de terminal virtual para lograr la máxima compatibilidad en escenarios multiplataforma. Puede encontrar más información sobre esta decisión de diseño en nuestro documento de Comparación de consola clásica y terminal virtual.

Copia un número de caracteres de celdas consecutivas de un búfer de pantalla de consola, comenzando por la ubicación especificada.

Sintaxis

BOOL WINAPI ReadConsoleOutputCharacter(
  _In_  HANDLE  hConsoleOutput,
  _Out_ LPTSTR  lpCharacter,
  _In_  DWORD   nLength,
  _In_  COORD   dwReadCoord,
  _Out_ LPDWORD lpNumberOfCharsRead
);

Parámetros

hConsoleOutput [in]
Identificador del búfer de pantalla 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.

lpCharacter [out]
Puntero a un búfer que recibe los caracteres leídos del búfer de pantalla de consola.

nLength [in]
Número de celdas de caracteres del búfer de pantalla desde las que se va a leer. El tamaño del búfer al que apunta el parámetro lpCharacter debe ser nLength * sizeof(TCHAR).

dwReadCoord [in]
Coordenadas de la primera celda del búfer de pantalla de consola desde la que se va a leer, en caracteres. El miembro X de la estructura COORD es la columna. El miembro Y es la fila.

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

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

Si el número de caracteres que se va a leer se extiende más allá del final de la fila especificada del búfer de pantalla, se leen los caracteres en la fila siguiente. Si el número de caracteres que se va a leer se extiende más allá del final del búfer de pantalla de consola, se leen los caracteres hasta el final de este búfer.

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.

Sugerencia

Esta API no se recomienda y no tiene un equivalente de terminal virtual. Esta decisión alinea intencionadamente la plataforma Windows con otros sistemas operativos en los que se espera que la aplicación cliente individual recuerde su propio estado dibujado para su posterior manipulación. Es posible que las aplicaciones que se comunican remotamente a través de utilidades multiplataforma y los transportes como SSH no funcionen según lo previsto si se utiliza esta API.

Requisitos


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