WriteConsoleOutput-Funktion

Artikel
12/15/2023

Wichtig

In diesem Dokument werden Konsolenplattformfunktionen beschrieben, die nicht mehr Teil unserer Ökosystem-Roadmap sind. Wir empfehlen nicht, diesen Inhalt in neuen Produkten zu verwenden, aber wir werden weiterhin vorhandene Nutzungen für die unbegrenzte Zukunft unterstützen. Unsere bevorzugte moderne Lösung konzentriert sich auf virtuelle Terminalsequenzen für maximale Kompatibilität in plattformübergreifenden Szenarien. Weitere Informationen zu dieser Designentscheidung finden Sie in unserem Dokument klassische Konsole im Vergleich zum virtuellen Terminal.

Schreibt Zeichen- und Farbattributedaten in einen angegebenen rechteckigen Block von Zeichenzellen in einem Konsolenbildschirmpuffer. Die zu schreibenden Daten stammen aus einem entsprechend großen rechteckigen Block an einer bestimmten Stelle im Quellpuffer.

Syntax

BOOL WINAPI WriteConsoleOutput(
  _In_          HANDLE      hConsoleOutput,
  _In_    const CHAR_INFO   *lpBuffer,
  _In_          COORD       dwBufferSize,
  _In_          COORD       dwBufferCoord,
  _Inout_       PSMALL_RECT lpWriteRegion
);

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]
Die Daten, die in den Konsolenbildschirmpuffer geschrieben werden sollen. Dieser Zeiger wird als Ursprung eines zweidimensionalen Arrays von CHAR_INFO Strukturen behandelt, deren Größe durch den dwBufferSize-Parameter angegeben wird.

dwBufferSize [in]
Die Größe des Puffers, auf den der lpBuffer-Parameter in Zeichenzellen verweist. Das X-Mitglied der COORD-Struktur ist die Anzahl der Spalten. Das Y-Mitglied ist die Anzahl der Zeilen.

dwBufferCoord [in]
Die Koordinaten der oberen linken Zelle im Puffer, auf die der lpBuffer-Parameter verweist. Das X-Mitglied der COORD-Struktur ist die Spalte, und das Y-Mitglied ist die Zeile.

lpWriteRegion [in, out]
Ein Zeiger auf eine SMALL_RECT Struktur. Bei Eingaben geben die Strukturmitglieder die oberen linken und unteren rechten Koordinaten des Konsolenbildschirmpufferrechtecks an, in das geschrieben werden soll. Bei Ausgaben geben die Strukturmitglieder das tatsächliche Rechteck an, das verwendet wurde.

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

WriteConsoleOutput behandelt den Quellpuffer und den Zielbildschirmpuffer als zweidimensionale Arrays (Spalten und Zeilen von Zeichenzellen). Das Rechteck, auf das der lpWriteRegion-Parameter verweist, gibt die Größe und Position des Blocks an, in den im Konsolenbildschirmpuffer geschrieben werden soll. Ein Rechteck derselben Größe befindet sich mit der linken oberen Zelle an den Koordinaten des dwBufferCoord-Parameters im lpBuffer-Array. Daten aus den Zellen, die sich im Schnittpunkt dieses Rechtecks befinden, und das Quellpufferrechteck (dessen Dimensionen durch den dwBufferSize-Parameter angegeben werden) werden in das Zielrechteck geschrieben.

Zellen im Zielrechteck, deren entsprechender Quellspeicherort sich außerhalb der Grenzen des Quellpufferrechtecks befindet, bleiben vom Schreibvorgang unberührt. Mit anderen Worten: Dies sind die Zellen, für die keine Daten geschrieben werden können.

Bevor WriteConsoleOutput zurückgegeben wird, legt es die Mitglieder von lpWriteRegion auf das tatsächliche Bildschirmpufferrechteck fest, das vom Schreibvorgang betroffen ist. Dieses Rechteck gibt die Zellen im Zielrechteck wieder, für die eine entsprechende Zelle im Quellpuffer vorhanden ist, da WriteConsoleOutput die Abmessungen des Zielrechtecks an die Grenzen des Konsolenbildschirmpuffers ausklammert.

Wenn das durch lpWriteRegion angegebene Rechteck vollständig außerhalb der Grenzen des Konsolenbildschirmpuffers liegt oder das entsprechende Rechteck vollständig außerhalb der Grenzen des Quellpuffers positioniert wird, werden keine Daten geschrieben. In diesem Fall kehrt die Funktion mit den Mitgliedern der Struktur zurück, auf die der lpWriteRegion-Parameter verweist, sodass das Rechte Mitglied kleiner als das Linke ist oder das Untere Mitglied kleiner als das Obere ist. Um die Größe des Konsolenbildschirmpuffers zu bestimmen, verwenden Sie die Funktion GetConsoleScreenBufferInfo.

WriteConsoleOutput hat keine Auswirkung auf die Cursorposition.

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.

Tipp

Diese API verfügt über eine virtuelle Terminal-Entsprechung in den Sequenzen Textformatierung und Cursorpositionierung. Bewegen Sie den Cursor an die Einfügeposition, wenden Sie die gewünschte Formatierung an, und schreiben Sie den Text aus. Virtuelle Terminalsequenzen werden für alle neuen und laufenden Entwicklungen empfohlen.

Beispiele

Für ein Beispiel siehe Lesen und Schreiben von Zeichen- und Attributblöcken.

Anforderungen


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