Función CreateConsoleScreenBuffer

Artículo
12/21/2023

Importante

En este documento se describe la funcionalidad de la plataforma de consola que ya no forma parte de nuestra hoja de ruta del ecosistema. No se recomienda usar este contenido en nuevos productos, pero seguiremos admitiendo los usos existentes para un 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 la consola clásica frente al terminal virtual.

Crea un búfer de pantalla de consola.

Sintaxis

HANDLE WINAPI CreateConsoleScreenBuffer(
  _In_             DWORD               dwDesiredAccess,
  _In_             DWORD               dwShareMode,
  _In_opt_   const SECURITY_ATTRIBUTES *lpSecurityAttributes,
  _In_             DWORD               dwFlags,
  _Reserved_       LPVOID              lpScreenBufferData
);

Parámetros

dwDesiredAccess [in]
Acceso al búfer de pantalla de la consola. Para obtener una lista de los derechos de acceso, consulte Seguridad y derechos de acceso del búfer de la consola.

dwShareMode [in]
Este parámetro puede ser cero, lo que indica que el búfer no se puede compartir, o puede ser uno o varios de los valores siguientes.

Valor	Significado
FILE_SHARE_READ 0x00000001	Otras operaciones abiertas se pueden realizar en el búfer de pantalla de la consola para el acceso de lectura.
FILE_SHARE_WRITE 0x00000002	Otras operaciones abiertas se pueden realizar en el búfer de pantalla de la consola para el acceso de escritura.

lpSecurityAttributes [in, opcional]
Puntero a una estructura de SECURITY_ATTRIBUTES que determina si el identificador devuelto se puede heredar de procesos secundarios. Si lpSecurityAttributes es NULL, el identificador no puede heredarse. El miembro lpSecurityDescriptor de la estructura especifica un descriptor de seguridad para el nuevo búfer de pantalla de la consola. Si lpSecurityAttributes es NULL, el búfer de pantalla de la consola obtiene un descriptor de seguridad predeterminado. Las ACL del descriptor de seguridad predeterminado para un búfer de consola proceden del token de suplantación o principal del creador.

dwFlags [in]
Tipo de búfer de pantalla de consola que se va a crear. El único tipo de búfer de pantalla admitido es CONSOLE_TEXTMODE_BUFFER.

lpScreenBufferData
Reservado; debe ser NULL.

Valor devuelto

Si la función es correcta, el valor devuelto es un identificador del nuevo búfer de pantalla de la consola.

Si se produce un error en la función, el valor devuelto es INVALID_HANDLE_VALUE. Para obtener información de error extendida, llame a GetLastError.

Comentarios

Una consola puede tener varios búferes de pantalla, pero solo un búfer de pantalla activo. Se puede acceder a los búferes de pantalla inactivos para leer y escribir, pero solo se muestra el búfer de pantalla activo. Para que el nuevo búfer de pantalla sea el búfer de pantalla activo, use la función SetConsoleActiveScreenBuffer.

El búfer de pantalla recién creado copiará algunas propiedades del búfer de pantalla activo en el momento en que se llame a esta función. El comportamiento es el siguiente:

Font : copiado del búfer de pantalla activo
Display Window Size : copiado del búfer de pantalla activo
Buffer Size : coincide con Display Window Size (NO copiado)
Default Attributes (colores): copiado del búfer de pantalla activo
Default Popup Attributes (colores): copiado del búfer de pantalla activo

El proceso de llamada puede usar el identificador devuelto en cualquier función que requiera un identificador para un búfer de pantalla de consola, sujeto a las limitaciones de acceso especificadas por el parámetro dwDesiredAccess.

El proceso de llamada puede usar la función DuplicateHandle para crear un identificador de búfer de pantalla duplicado que tenga un acceso o una herencia distintos del identificador original. Sin embargo, DuplicateHandle no se puede usar para crear un duplicado válido para un proceso diferente (excepto a través de la herencia).

Para cerrar el identificador de búfer de pantalla de la consola, usa la función CloseHandle.

Sugerencia

Esta API no se recomienda, pero tiene un terminal virtual aproximado equivalente en la secuencia del búfer de pantalla alternativo. Establecer el búfer de pantalla alternativo puede proporcionar a una aplicación un espacio aislado independiente para dibujar durante el tiempo de ejecución de la sesión y conservar al mismo tiempo el contenido que se mostraba desde el invocador de la aplicación. Así se conserva la información de dibujo para realizar una restauración simple en la salida del proceso.

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