Funzione WriteConsole
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) |