WriteConsoleOutput-Funktion
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) |