ReadConsoleOutput-Funktion

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.

Beispiele

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

Anforderungen

Siehe auch

Konsolenfunktionen

Ausgabefunktionen für die Konsolen auf niedriger Ebene

ReadConsoleOutputAttribute

ReadConsoleOutputCharacter

SetConsoleCP

SetConsoleOutputCP

SMALL_RECT

WriteConsoleOutput

CHAR_INFO

COORD