ReadConsole-Funktion

Artikel
12/21/2023

Liest die Zeicheneingabe aus dem Konsoleneingabepuffer und entfernt sie aus dem Puffer.

Syntax

BOOL WINAPI ReadConsole(
  _In_     HANDLE  hConsoleInput,
  _Out_    LPVOID  lpBuffer,
  _In_     DWORD   nNumberOfCharsToRead,
  _Out_    LPDWORD lpNumberOfCharsRead,
  _In_opt_ LPVOID  pInputControl
);

Parameter

hConsoleInput [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 Puffer, der die vom Konsoleneingabepuffer gelesenen Daten empfängt.

nNumberOfCharsToRead [in]
Die Anzahl der zu lesenden Zeichen. Die Größe des Puffers, auf den der lpBuffer-Parameter verweist, sollte mindestens nNumberOfCharsToRead * sizeof(TCHAR) Byte sein.

lpNumberOfCharsRead [out]
Ein Zeiger auf eine Variable, die die Anzahl der tatsächlich gelesenen Zeichen empfängt.

pInputControl [in, optional]
Ein Zeiger auf eine CONSOLE_READCONSOLE_CONTROL-Struktur , die ein Steuerzeichen angibt, um das Ende des Lesevorgangs zu signalisieren. Dieser Parameter kann NULL sein.

Für diesen Parameter ist standardmäßig Unicode-Eingabe erforderlich. Legen Sie für den ANSI-Modus diesen Parameter auf NULL fest.

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

ReadConsole liest Tastatureingaben aus dem Eingabepuffer einer Konsole. Es verhält sich wie die ReadFile-Funktion , mit der Ausnahme, dass sie im Unicode-Modus (Breitzeichen) oder im ANSI-Modus gelesen werden kann. Verwenden Sie "ReadConsole" anstelle von ReadFile, um Anwendungen zu erhalten, die einen einzigen Satz von Quellen enthalten, die mit beiden Modi kompatibel sind. Obwohl ReadConsole nur mit einem Konsoleneingabepufferhandle verwendet werden kann, kann ReadFile mit anderen Handles (z. B. Dateien oder Rohren) verwendet werden. ReadConsole schlägt fehl, wenn sie mit einem Standardhandle verwendet wird, das umgeleitet wurde, um etwas anderes als ein Konsolenhandle zu sein.

Alle Eingabemodi, die sich auf das Verhalten von ReadFile auswirken, wirken sich auf ReadConsole gleich aus. Zum Abrufen und Festlegen der Eingabemodi eines Konsoleneingabe-Puffers verwenden Sie die Funktionen GetConsoleMode und SetConsoleMode.

Wenn der Eingabepuffer andere Eingabeereignisse als Tastaturereignisse (z. B. Mausereignisse oder Fensteränderungsereignisse) enthält, werden sie entfernt. Diese Ereignisse können nur mithilfe der ReadConsoleInput-Funktion gelesen werden.

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.

Der pInputControl-Parameter kann verwendet werden, um zwischengeschaltete Wakeups aus dem Lesevorgang als Reaktion auf ein in einer CONSOLE_READCONSOLE_CONTROL Struktur angegebenes Dateivervollständigungssteuer zeichen zu aktivieren. Dieses Feature erfordert die Aktivierung von Befehlserweiterungen, das Standardausgabehandle als Konsolenausgabehandle und als Unicode-Eingabe.

Windows Server 2003 und Windows XP/2000: Die Zwischenlesefunktion wird nicht unterstützt.

Der „Gekochte“ Modus tritt ein, wenn ENABLE_LINE_INPUT mit SetConsoleMode auf dem Konsoleneingabepunkt festgelegt wird. Im gekochten Modus stellt der Konsolenhost eine Bearbeitungszeile im Auftrag der Befehlszeilenanwendung bereit, und Aufrufe von ReadFile oder ReadConsole werden erst zurückgegeben, wenn die EINGABETASTE gedrückt wird.

Zwischenlesevorgang ist eine Erweiterung für dieses Verhalten im ReadConsole-Aufruf im „gekochten“ Lesemodus. Das Festlegen einer Kennzeichnung in dwCtrlWakeupMask in der CONSOLE_READCONSOLE_CONTROL-Struktur und übergeben Sie es an pinputControl, während es ReadConsole aufruft, führt dazu, dass der Lesevorgang nicht unbedingt auf eine Neueline wartet, sondern es auch auf ein angegebenes Zeichen zurückgibt.

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	ReadConsoleW (Unicode) und ReadConsoleA (ANSI)