Funzione WriteConsole

Articolo
07/12/2023

Scrive una stringa di caratteri in un buffer dello schermo della console iniziando dalla posizione corrente del cursore.

Sintassi

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

Parametri

hConsoleOutput [in]
Handle per il buffer dello schermo della console. L'handle deve avere il diritto di accesso GENERIC_WRITE . Per altre informazioni, vedere Sicurezza dei buffer della console e diritti di accesso.

lpBuffer [in]
Puntatore a un buffer che contiene caratteri da scrivere nel buffer dello schermo della console. È previsto che sia una matrice di char per WriteConsoleA o wchar_t per WriteConsoleW.

nNumberOfCharsToWrite [in]
Numero di caratteri da scrivere. Se la dimensione totale del numero specificato di caratteri supera l'heap disponibile, la funzione ha esito negativo con ERROR_NOT_ENOUGH_MEMORY.

lpNumberOfCharsWritten [out, facoltativo]
Puntatore a una variabile che riceve il numero di caratteri effettivamente scritti.

lpReserved riservato; deve essere NULL.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

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

Osservazioni:

La funzione WriteConsole scrive i caratteri nel buffer dello schermo della console in corrispondenza della posizione corrente del cursore. La posizione del cursore viene spostata man mano che i caratteri vengono scritti. La funzione SetConsoleCursorPosition imposta la posizione corrente del cursore.

I caratteri vengono scritti usando gli attributi del colore di primo piano e di sfondo associati al buffer dello schermo della console. La funzione SetConsoleTextAttribute modifica questi colori. Per determinare gli attributi di colore correnti e la posizione corrente del cursore, usare GetConsoleScreenBufferInfo.

Tutte le modalità di input che influiscono sul comportamento della funzione WriteFile hanno lo stesso effetto su WriteConsole. Per recuperare e impostare le modalità di output di un buffer dello schermo della console, usare le funzioni GetConsoleMode e SetConsoleMode.

Questa funzione usa i caratteri Unicode o i caratteri a 8 bit dalla tabella codici corrente della console. Inizialmente il valore predefinito della tabella codici della console è la tabella codici OEM del sistema. Per modificare la tabella codici della console usare le funzioni SetConsoleCP o SetConsoleOutputCP. I consumer legacy possono anche usare i comandichcp o mode con cp select= ma non è consigliabile per il nuovo sviluppo.

WriteConsole ha esito negativo se viene usata con un handle standard che viene reindirizzato a un file. Se un'applicazione elabora l'output multilingue che può essere reindirizzato, determinare se l'handle di output è un handle della console (un metodo consiste nel chiamare la funzione GetConsoleMode e verificare se l'operazione ha esito positivo). Se l'handle è un handle della console, chiamare WriteConsole. Se l'handle non è un handle della console, l'output viene reindirizzato ed è necessario chiamare WriteFile per eseguire le funzioni di I/O. Assicurarsi di anteporre un prefisso a un file di testo normale Unicode con un indicatore dell'ordine dei byte. Per altre informazioni, vedere Using Byte Order Marks (Uso degli indicatori dell'ordine dei byte).

Sebbene un'applicazione possa usare WriteConsole in modalità ANSI per scrivere caratteri ANSI, le console non supportano le sequenze di "escape ANSI" o "terminale virtuale", a meno che non siano abilitate. Per altre informazioni e per l'applicabilità della versione del sistema operativo, vedere Sequenze del terminale virtuale della console.

Quando le sequenze di escape del terminale virtuale non sono abilitate, le funzioni della console possono fornire funzionalità equivalenti. Per altre informazioni, vedere SetCursorPos, SetConsoleTextAttribute e GetConsoleCursorInfo.

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Intestazione	ConsoleApi.h (tramite WinCon.h, con Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll
Nomi Unicode e ANSI	WriteConsoleW (Unicode) e WriteConsoleA (ANSI)