ReadConsoleOutput-Funktion

Artikel
10/23/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 klassischen Konsolendokument im Vergleich zum virtuellen Terminal .

Liest Zeichen- und Farbattributedaten aus einem rechteckigen Block von Zeichenzellen in einem Konsolenbildschirmpuffer, und die Funktion schreibt die Daten an einer bestimmten Stelle im Zielpuffer in einen rechteckigen Block.

Syntax

BOOL WINAPI ReadConsoleOutput(
  _In_    HANDLE      hConsoleOutput,
  _Out_   PCHAR_INFO  lpBuffer,
  _In_    COORD       dwBufferSize,
  _In_    COORD       dwBufferCoord,
  _Inout_ PSMALL_RECT lpReadRegion
);

Parameter

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

lpBuffer [out]
Ein Zeiger auf einen Zielpuffer, der die vom Konsolenbildschirmpuffer gelesenen Daten empfängt. 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 lpBuffer-Parameters in Zeichenzellen. Das X-Element der COORD-Struktur ist die Anzahl der Spalten. Das Y-Element ist die Anzahl der Zeilen.

dwBufferCoord [in]
Die Koordinaten der oberen linken Zelle im lpBuffer-Parameter , die die aus dem Konsolenbildschirmpuffer gelesenen Daten empfängt. Das X-Element der COORD-Struktur ist die Spalte, und das Y-Element ist die Zeile.

lpReadRegion [in, out]
Ein Zeiger auf eine SMALL_RECT Struktur. Bei Eingaben geben die Strukturmember die oberen linken und unteren rechten Koordinaten des Konsolenbildschirmpufferrechtecks an, aus dem die Funktion gelesen werden soll. Bei der Ausgabe geben die Strukturmember 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

ReadConsoleOutput behandelt den Konsolenbildschirmpuffer und den Zielpuffer als zweidimensionale Arrays (Spalten und Zeilen von Zeichenzellen). Das Rechteck, auf das der Parameter lpReadRegion verweist, gibt die Größe und Position des Blocks an, der aus dem Konsolenbildschirmpuffer gelesen werden soll. Ein Zielrechteck derselben Größe befindet sich mit der oberen linken Zelle an den Koordinaten des dwBufferCoord-Parameters im lpBuffer-Array . Daten, die aus den Zellen im Quellrechteck des Konsolenbildschirmpuffers gelesen werden, werden in die entsprechenden Zellen im Zielpuffer kopiert. Wenn sich die entsprechende Zelle außerhalb der Grenzen des Zielpufferrechtecks befindet (deren Dimensionen durch den dwBufferSize-Parameter angegeben werden), werden die Daten nicht kopiert.

Zellen im Zielpuffer, die Koordinaten entsprechen, die sich nicht innerhalb der Grenzen des Konsolenbildschirmpuffers befinden, bleiben unverändert. Mit anderen Worten: Dies sind die Zellen, für die keine Bildschirmpufferdaten gelesen werden können.

Bevor ReadConsoleOutput zurückgegeben wird, werden die Elemente der Struktur festgelegt, auf die der lpReadRegion-Parameter verweist, auf das tatsächliche Bildschirmpufferrechteck, dessen Zellen in den Zielpuffer kopiert wurden. Dieses Rechteck spiegelt die Zellen im Quellrechteck wider, für die eine entsprechende Zelle im Zielpuffer vorhanden ist, da ReadConsoleOutput die Abmessungen des Quellrechtecks annimmt, um die Grenzen des Konsolenbildschirmpuffers anzupassen.

Wenn das durch lpReadRegion angegebene Rechteck vollständig außerhalb der Grenzen des Konsolenbildschirmpuffers liegt oder das entsprechende Rechteck vollständig außerhalb der Grenzen des Zielpuffers positioniert wird, werden keine Daten kopiert. In diesem Fall gibt die Funktion mit den Membern der Struktur zurück, auf die der lpReadRegion-Parameter verweist, sodass das Rechte Element kleiner als der Linke ist, oder das Untere Element kleiner als der obere Member ist. Um den aktuellen Modus eines Konsoleneingabepuffers oder Bildschirmpuffers zu bestimmen, verwenden Sie die Funktion GetConsoleMode.

Die ReadConsoleOutput-Funktion hat keine Auswirkung auf die Cursorposition des Konsolenbildschirmpuffers. Der Inhalt des Konsolenbildschirmpuffers wird von der Funktion nicht geändert.

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 wird nicht empfohlen und verfügt nicht über eine virtuelle Terminalentsprechung. Diese Entscheidung richtet die Windows-Plattform absichtlich an andere Betriebssysteme aus, bei denen die einzelne Clientanwendung erwartet wird, dass sie sich ihren eigenen gezeichneten Zustand für eine weitere Manipulation merken wird. Anwendungen, die über plattformübergreifende Dienstprogramme und Transporte wie SSH remoting werden, funktionieren möglicherweise nicht wie erwartet, wenn Sie diese API verwenden.

Beispiele

Für ein Beispiel, 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	ConsoleApi.h (über WinCon.h, Windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll
Unicode- und ANSI-Namen	ReadConsoleOutputW (Unicode) und ReadConsoleOutputA (ANSI)