Función WriteConsole

Artículo
07/12/2023

Escribe una cadena de caracteres en un búfer de pantalla de la consola a partir de la ubicación actual del cursor.

Sintaxis

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

Parámetros

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

lpBuffer [in]
Puntero a un búfer que contiene los caracteres que se van a escribir en el búfer de pantalla de la consola. Se espera que sea una matriz de char para WriteConsoleA o wchar_t para WriteConsoleW.

nNumberOfCharsToWrite [in]
El número de caracteres que se va a escribir. Si el tamaño total del número especificado de caracteres supera el montón disponible, se produce un error en la función con ERROR_NOT_ENOUGH_MEMORY.

lpNumberOfCharsWritten [out, opcional]
Puntero a una variable que recibe el número de caracteres escritos realmente.

lpReserved reservado; debe ser 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

La función WriteConsole escribe caracteres en el búfer de pantalla de la consola en la posición actual del cursor. La posición del cursor avanza a medida que se escriben caracteres. La función SetConsoleCursorPosition establece la posición actual del cursor.

Los caracteres se escriben con los atributos de color de primer plano y de fondo asociados al búfer de pantalla de la consola. La función SetConsoleTextAttribute cambia estos colores. Para determinar los atributos de color actuales y la posición actual del cursor, utilice GetConsoleScreenBufferInfo.

Todos los modos de entrada que afectan al comportamiento de la función WriteFile tienen el mismo efecto en WriteConsole. Para recuperar y establecer los modos de salida de un búfer de pantalla de la consola, use las funciones GetConsoleMode y SetConsoleMode.

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.

WriteConsole produce un error si se usa con un identificador estándar que se redirige a un archivo. Si una aplicación procesa una salida multilingüe que se puede redirigir, determine si el identificador de salida es un identificador de consola (un método consiste en llamar a la función GetConsoleMode y comprobar si se realiza correctamente). Si el identificador es un identificador de consola, llame a WriteConsole. Si el identificador no es un identificador de consola, la salida se redirige y debe llamar a WriteFile para realizar la E/S. Asegúrese de prefijar un archivo de texto sin formato Unicode con una marca de orden de bytes. Para obtener más información, consulte Uso de marcas de orden de bytes.

Aunque una aplicación puede usar WriteConsole en modo ANSI para escribir caracteres ANSI, las consolas no admiten secuencias de "escape ANSI" o de "terminal virtuales" a menos que estén habilitadas. Consulte Secuencias de terminal virtuales de la consola para obtener más información y para ver la aplicabilidad de la versión del sistema operativo.

Cuando las secuencias de escape de terminal virtuales no están habilitadas, las funciones de consola pueden proporcionar una funcionalidad equivalente. Para obtener más información, vea SetCursorPos, SetConsoleTextAttribute y GetConsoleCursorInfo.

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	WriteConsoleW (Unicode) y WriteConsoleA (ANSI)