Función ReadConsoleOutput

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.

Lee datos de atributos de colores y caracteres de un bloque rectangular de celdas de caracteres en un búfer de pantalla de consola y la función escribe los datos en un bloque rectangular en una ubicación especificada en el búfer de destino.

Sintaxis

BOOL WINAPI ReadConsoleOutput(
  _In_    HANDLE      hConsoleOutput,
  _Out_   PCHAR_INFO  lpBuffer,
  _In_    COORD       dwBufferSize,
  _In_    COORD       dwBufferCoord,
  _Inout_ PSMALL_RECT lpReadRegion
);

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.

lpBuffer [out]
Puntero a un búfer de destino que recibe los datos leídos del búfer de pantalla de consola. Este puntero se trata como el origen de una matriz bidimensional de estructuras CHAR_INFO cuyo tamaño especifica el parámetro dwBufferSize.

dwBufferSize [in]
Tamaño del parámetro lpBuffer en celdas de caracteres. El miembro X de la estructura COORD es el número de columnas. El miembro Y es el número de filas.

dwBufferCoord [in]
Coordenadas de la celda superior izquierda en el parámetro lpBuffer que recibe los datos leídos del búfer de pantalla de consola. El miembro X de la estructura COORD es la columna. El miembro Y es la fila.

lpReadRegion [in, out]
Puntero a una estructura SMALL_RECT. Durante la entrada, los miembros de la estructura especifican las coordenadas superior izquierda e inferior derecha del rectángulo del búfer de pantalla de consola desde el que se va a leer la función.. En la salida, los miembros de la estructura especifican el rectángulo real que se usó.

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

ReadConsoleOutput trata el búfer de pantalla de consola y el búfer de destino como matrices bidimensionales (columnas y filas de celdas de caracteres). El rectángulo al que apunta el parámetro lpReadRegion especifica el tamaño y la ubicación del bloque que se va a leer desde el búfer de pantalla de consola. Un rectángulo de destino del mismo tamaño se ubica con su celda superior izquierda en las coordenadas del parámetro dwBufferCoord en la matriz lpBuffer. Los datos leídos de las celdas del rectángulo de origen del búfer de pantalla de consola se copian en las celdas correspondientes del búfer de destino. Si la celda correspondiente está fuera de los límites del rectángulo del búfer de destino (cuyas dimensiones especifica el parámetro dwBufferSize), los datos no se copian.

Las celdas del búfer de destino correspondientes a las coordenadas que no están dentro de los límites del búfer de pantalla de consola se mantienen sin cambios. En otras palabras, estas son las celdas que se quedan sin datos del búfer de pantalla disponibles para su lectura.

Antes de devolver resultados, ReadConsoleOutput establece los miembros de la estructura a los que apunta el parámetro lpReadRegion en el rectángulo real del búfer de pantalla cuyas celdas se han copiado en el búfer de destino. Este rectángulo refleja las celdas del rectángulo de origen para las que existía una celda correspondiente en el búfer de destino, ya que ReadConsoleOutput recorta las dimensiones del rectángulo de origen para ajustarse a los límites del búfer de pantalla de consola.

Si el rectángulo que especifica lpReadRegion se encuentra completamente fuera de los límites del búfer de pantalla de consola, o si el rectángulo correspondiente se coloca íntegramente fuera de los límites del búfer de destino, no se copia ningún dato. En este caso, la función vuelve con los miembros de la estructura a los que apunta el parámetro lpReadRegion establecido, de forma que el miembro Right es menor que Left, o el miembro Bottom es menor que Top. Para determinar el tamaño del búfer de pantalla de la consola, utilice la función GetConsoleScreenBufferInfo.

La función ReadConsoleOutput no afecta a la posición del cursor del búfer de pantalla de consola ni cambia el contenido del búfer de pantalla de consola.

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 transportes, como SSH, no funcionen según lo previsto si se usa esta API.

Ejemplos

Para ver un ejemplo, consulte Lectura y escritura de bloques de caracteres y atributos.

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	ReadConsoleOutputW (Unicode) y ReadConsoleOutputA (ANSI)