WriteConsole-Funktion

Artikel
07/12/2023

Schreibt eine Zeichenfolge in einen Konsolenbildschirm-Puffer, beginnend an der aktuellen Cursorposition.

Syntax

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

Parameter

hConsoleOutput [in]
Ein Handle für den Konsolenbildschirm-Puffer. Das Handle muss das Zugriffsrecht GENERIC_WRITE besitzen. Weitere Informationen finden Sie unter Sicherheit und Zugriffsrechte für Konsolenpuffer.

lpBuffer [in]
Ein Zeiger auf einen Puffer, der Zeichen enthält, die in den Konsolenbildschirm-Puffer geschrieben werden sollen. Es wird erwartet, dass es sich um ein Array von char für WriteConsoleA oder von wchar_t für WriteConsoleW handelt.

nNumberOfCharsToWrite [in]
Die Anzahl der zu schreibenden Zeichen. Wenn die Gesamtgröße der angegebenen Anzahl Zeichen den verfügbaren Heap überschreitet, schlägt die Funktion mit ERROR_NOT_ENOUGH_MEMORY fehl.

lpNumberOfCharsWritten [out, optional]
Ein Zeiger auf eine Variable, die die Anzahl der tatsächlich geschriebenen Zeichen empfängt.

lpReserved reserviert; muss NULL sein.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Die WriteConsole-Funktion schreibt Zeichen an der aktuellen Cursorposition in den Konsolenbildschirm-Puffer. Die Cursorposition wird mit dem Schreiben von Zeichen vorgerückt. Die SetConsoleCursorPosition-Funktion legt die aktuelle Cursorposition fest.

Zeichen werden unter Verwendung der Vordergrund- und Hintergrundfarbenattribute geschrieben, die dem Konsolenbildschirm-Puffer zugeordnet sind. Die SetConsoleTextAttribute-Funktion ändert diese Farben. Um die aktuellen Farbattribute und die aktuelle Cursorposition zu bestimmen, verwenden Sie GetConsoleScreenBufferInfo.

Alle Eingabemodi, die sich auf das Verhalten der WriteFile-Funktion auswirken, haben denselben Effekt auf WriteConsole. Zum Abrufen und Festlegen der Ausgabemodi eines Konsolenbildschirm-Puffers verwenden Sie die Funktionen GetConsoleMode und SetConsoleMode.

Diese Funktion verwendet entweder Unicodezeichen oder 8-Bit-Zeichen aus der aktuellen Codepage der Konsole. Die Codepage der Konsole wird zunächst standardmäßig auf die OEM-Codepage des Systems festgelegt. Um die Codepage der Konsole zu ändern, verwenden Sie die Funktionen SetConsoleCP oder SetConsoleOutputCP. Ältere Consumer können auch die chcp oder mode con cp select=-Befehle verwenden, aber sie werden für neue Entwicklungen nicht empfohlen.

WriteConsole schlägt fehl, wenn sie mit einem Standardhandle verwendet wird, das an eine Datei umgeleitet wird. Wenn eine Anwendung mehrsprachige Ausgaben verarbeitet, die umgeleitet werden können, stellen Sie fest, ob das Ausgabehandle ein Konsolenhandle ist (eine Methode besteht darin, die GetConsoleMode-Funktion aufzurufen und zu überprüfen, ob sie erfolgreich ist). Wenn das Handle ein Konsolenhandle ist, rufen Sie WriteConsole auf. Wenn das Handle kein Konsolenhandle ist, wird die Ausgabe umgeleitet, und Sie sollten WriteFile aufrufen, um die E/A auszuführen. Stellen Sie sicher, dass Sie eine Unicode-Nur-Text-Datei mit einer Bytereihenfolge-Marke versehen. Weitere Informationen finden Sie unter Verwenden von Bytereihenfolge-Marken.

Obwohl eine Anwendung WriteConsole im ANSI-Modus verwenden kann, um ANSI-Zeichen zu schreiben, unterstützen Konsolen keine „ANSI-Escapezeichen“ oder „virtuellen Terminal“sequenzen, sofern diese nicht aktiviert sind. Weitere Informationen, auch zur Anwendbarkeit von Betriebssystemversionen, finden Sie unter Virtuelle Konsolenterminalsequenzen.

Wenn virtuelle Terminal-Escapesequenzen nicht aktiviert sind, können Konsolenfunktionen entsprechende Funktionalitäten bereitstellen. Weitere Informationen finden Sie unter SetCursorPos, SetConsoleTextAttributeund GetConsoleCursorInfo.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Header	ConsoleApi.h (über WinCon.h, Windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll
Unicode- und ANSI-Namen	WriteConsoleW (Unicode) und WriteConsoleA (ANSI)