Funzione CreateConsoleScreenBuffer

Articolo
10/23/2023

Importante

Questo documento descrive le funzionalità della piattaforma della console che non fanno più parte della roadmap dell'ecosistema. Non è consigliabile usare questo contenuto nei nuovi prodotti, ma continueremo a supportare gli utilizzi esistenti per il futuro indefinito. La soluzione moderna preferita è incentrata sulle sequenze di terminale virtuale per garantire la massima compatibilità negli scenari multipiattaforma. Per altre informazioni su questa decisione di progettazione, vedere il documento relativo alla console classica e al terminale virtuale.

Crea un buffer dello schermo della console.

Sintassi

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

Parametri

dwDesiredAccess [in]
Accesso al buffer dello schermo della console. Per un elenco dei diritti di accesso, vedere Protezione del buffer della console e diritti di accesso.

dwShareMode [in]
Questo parametro può essere zero, a indicare che il buffer non può essere condiviso oppure può essere uno o più dei valori seguenti.

valore	Significato
FILE_SHARE_READ 0x00000001	È possibile eseguire altre operazioni aperte nel buffer dello schermo della console per l'accesso in lettura.
FILE_SHARE_WRITE 0x00000002	È possibile eseguire altre operazioni aperte nel buffer dello schermo della console per l'accesso in scrittura.

lpSecurityAttributes [in, facoltativo]
Puntatore a una struttura edizione StandardCURITY_ATTRIBUTES che determina se l'handle restituito può essere ereditato dai processi figlio. Se lpSecurityAttributes è NULL, l'handle non può essere ereditato. Il membro lpSecurityDescriptor della struttura specifica un descrittore di sicurezza per il nuovo buffer dello schermo della console. Se lpSecurityAttributes è NULL, il buffer dello schermo della console ottiene un descrittore di sicurezza predefinito. Gli elenchi di controllo di accesso nel descrittore di sicurezza predefinito per un buffer dello schermo della console provengono dal token primario o di rappresentazione dell'autore.

dwFlags [in]
Tipo di buffer dello schermo della console da creare. L'unico tipo di buffer dello schermo supportato è CONSOLE_TEXTMODE_BUFFER.

lpScreenBufferData
Riservati; deve essere NULL.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è un handle per il nuovo buffer dello schermo della console.

Se la funzione ha esito negativo, il valore restituito è INVALID_HANDLE_VALUE. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Osservazioni:

Una console può avere più buffer dello schermo, ma un solo buffer dello schermo attivo. È possibile accedere ai buffer dello schermo inattivi per la lettura e la scrittura, ma viene visualizzato solo il buffer dello schermo attivo. Per rendere il nuovo buffer dello schermo il buffer dello schermo attivo, usare la funzione SetConsoleActiveScreenBuffer.

Il buffer dello schermo appena creato copia alcune proprietà dal buffer dello schermo attivo al momento della chiamata di questa funzione. Il comportamento è il seguente:

Font - copiato dal buffer dello schermo attivo
Display Window Size - copiato dal buffer dello schermo attivo
Buffer Size - corrispondente a Display Window Size (NON copiato)
Default Attributes (colori): copiato dal buffer dello schermo attivo
Default Popup Attributes (colori): copiato dal buffer dello schermo attivo

Il processo chiamante può usare l'handle restituito in qualsiasi funzione che richiede un handle per un buffer dello schermo della console, soggetto alle limitazioni di accesso specificate dal parametro dwDesiredAccess .

Il processo chiamante può usare la funzione DuplicateHandle per creare un handle di buffer dello schermo duplicato con accesso o ereditabilità diversi dall'handle originale. Non è tuttavia possibile usare DuplicateHandle per creare un duplicato valido per un processo diverso,ad eccezione dell'ereditarietà.

Per chiudere l'handle del buffer dello schermo della console, usare la funzione CloseHandle.

Suggerimento

Questa API non è consigliata, ma ha un equivalente di terminale virtuale approssimativo nella sequenza di buffer dello schermo alternativo. L'impostazione del buffer dello schermo alternativo può fornire a un'applicazione uno spazio separato e isolato per il disegno nel corso del runtime di sessione mantenendo il contenuto visualizzato dall'invoker dell'applicazione. In questo modo vengono conservate le informazioni di disegno per un semplice ripristino all'uscita del processo.

Esempi

Per un esempio, vedere Lettura e scrittura di blocchi di caratteri e attributi.

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Intestazione	ConsoleApi2.h (tramite WinCon.h, includere Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll