GetStdHandle-Funktion

Ruft ein Handle für das angegebene Standardgerät ab (Standardeingabe, Standardausgabe oder Standardfehler).

Syntax

HANDLE WINAPI GetStdHandle(
  _In_ DWORD nStdHandle
);

Parameter

nStdHandle [in]
Das Standardgerät. Dieser Parameter kann einen der folgenden Werte annehmen.

Rückgabewert

Wenn die Funktion erfolgreich ausgeführt wird, ist der Rückgabewert ein Handle für das angegebene Gerät oder ein umgeleitetes Handle, das durch einen vorhergehenden Aufruf von SetStdHandle festgelegt wurde. Das Handle verfügt über die Zugriffsrechte GENERIC_READ und GENERIC_WRITE, es sei denn, die Anwendung hat SetStdHandle verwendet, um ein Standardhandle mit geringeren Zugriffsrechten festzulegen.

Wenn die Funktion fehlschlägt, ist der Rückgabewert INVALID_HANDLE_VALUE. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Wenn eine Anwendung nicht über zugeordnete Standardhandles verfügt, wie etwa ein Dienst, der auf einem interaktiven Desktop ausgeführt wird und diese nicht umgeleitet hat, ist der Rückgabewert NULL.

Hinweise

Von GetStdHandle zurückgegebene Handles können von Anwendungen verwendet werden, die aus der Konsole lesen oder in die Konsole schreiben müssen. Beim Erstellen einer Konsole ist das Standardeingabehandle ein Handle für den Eingabepuffer der Konsole, und die Standardausgabe- und Standardfehlerhandles sind Handles für den aktiven Bildschirmpuffer der Konsole. Diese Handles können von den Funktionen ReadFile und WriteFile oder von jeder Konsolenfunktion verwendet werden, die auf den Konsoleneingabepuffer oder einen Bildschirmpuffer zugreift (beispielsweise die Funktionen ReadConsoleInput, WriteConsole oder GetConsoleScreenBufferInfo).

Die Standardhandles eines Prozesses können durch einen Aufruf von SetStdHandle umgeleitet werden. In diesem Fall gibt GetStdHandle das umgeleitete Handle zurück. Wenn die Standardhandles umgeleitet wurden, können Sie den CONIN$-Wert in einem Aufruf der Funktion CreateFile angeben, um ein Handle zum Eingabespeicher einer Konsole abzurufen. In ähnlicher Weise können Sie den CONOUT$-Wert angeben, um ein Handle für den aktiven Bildschirmpuffer einer Konsole abzurufen.

Die Standardhandles eines Prozesses beim Eintritt in die main-Methode werden durch die Konfiguration des /SUBSYSTEM-Flags vorgeschrieben, das dem Linker zum Zeitpunkt des Erstellens der Anwendung übergeben wurde. Für die Angabe von /SUBSYSTEM:CONSOLE ist es erforderlich, dass das Betriebssystem die Handles beim Start mit einer Konsolensitzung füllt, falls die Tabelle der Standardhandles nicht bereits mithilfe von Vererbung durch das übergeordnete Element aufgefüllt wurde. Im Gegensatz dazu impliziert /SUBSYSTEM:WINDOWS, dass die Anwendung keine Konsole benötigt und von den Standardhandles wahrscheinlich keinen Gebrauch machen wird. Weitere Informationen zur Handlevererbung finden Sie in der Dokumentation zu STARTF_USESTDHANDLES.

Einige Anwendungen werden außerhalb der Grenzen ihres deklarierten Subsystems betrieben; beispielsweise kann eine /SUBSYSTEM:WINDOWS-Anwendung die Standardhandles zu Protokollierungs- oder Debuggingzwecken überprüfen/verwenden, aber zugleich normal mit einer grafischen Benutzeroberfläche ausgeführt werden. Diese Anwendungen müssen den Zustand von Standardhandles beim Start sorgfältig überprüfen und AttachConsole, AllocConsole sowie FreeConsole verwenden, um bei Bedarf eine Konsole hinzuzufügen bzw. zu entfernen.

Einige Anwendungen können sogar ihr Verhalten je nach dem Typ des geerbten Handles ändern. Die Unterscheidung des Typs zwischen Konsole, Pipe, Datei und anderen kann mithilfe von GetFileType durchgeführt werden.

Entfernen des Handles

Es ist nicht erforderlich, CloseHandle zu verwenden, wenn das aus GetStdHandle abgerufene Handle abgeschlossen ist. Der zurückgegebene Wert ist einfach eine Kopie des in der Prozesstabelle gespeicherten Werts. Der Prozess selbst wird im Allgemeinen als Besitzer dieser Handles und ihrer Lebensdauer betrachtet. Jedes Handle wird bei der Erstellung in der Tabelle platziert, je nach den Festlegungen bezüglich Vererbung und Start des CreateProcess-Aufrufs, und wird wieder freigegeben, wenn der Prozess zerstört wird.

Eine manuelle Beeinflussung der Lebensdauer dieser Handles kann für eine Anwendung wünschenswert sein, die absichtlich versucht, sie zu ersetzen oder andere Teile des Prozesses an ihrer Verwendung zu hindern. Da ein HANDLE durch Ausführen von Code zwischengespeichert werden kann, nimmt dieser Code nicht notwendigerweise Änderungen auf, die über SetStdHandle vorgenommen wurden. Wenn Sie das Handle explizit über CloseHandle schließen, wird es prozessweit geschlossen, und bei der nächsten Verwendung eines zwischengespeicherten Verweises tritt ein Fehler auf.

Eine Anleitung zum Ersetzen eines Standardhandles in der Prozesstabelle besteht darin, das vorhandene HANDLE mit GetStdHandle aus der Tabelle abzurufen, mit SetStdHandle ein neues HANDLE zu platzieren, das mit CreateFile (oder einer ähnlichen Funktion) geöffnet wird, und dann das abgerufene Handle zu schließen.

Die als Handles in der Prozesstabelle durch die Funktion GetStdHandle oder SetStdHandle gespeicherten Werte werden nicht überprüft. Die Überprüfung erfolgt zum Zeitpunkt des tatsächlichen Lese-/Schreibvorgangs, z. B. ReadFile oder WriteFile.

Verhalten beim Zuordnen/Trennen

Beim Zuordnen zu einer neuen Konsole werden Standardhandles immer durch Konsolenhandles ersetzt, es sei denn, während der Prozesserstellung wurde STARTF_USESTDHANDLES angegeben.

Wenn der vorhandene Wert des Standardhandles NULL ist oder der vorhandene Wert des Standardhandles wie ein Konsolen-Pseudohandle aussieht, wird das Handle durch ein Konsolenhandle ersetzt.

Wenn ein übergeordnetes Element sowohl CREATE_NEW_CONSOLE als auch STARTF_USESTDHANDLES verwendet, um einen Konsolenprozess zu erstellen, werden Standardhandles nicht ersetzt, es sei denn, der vorhandene Wert des Standardhandles ist NULL, oder es handelt sich um ein Konsolen-Pseudohandle.

Beispiele

Ein Beispiel finden Sie unter Lesen von Eingabepufferereignissen.

Anforderungen

Siehe auch

Konsolenfunktionen

Konsolenhandles

CreateFile

GetConsoleScreenBufferInfo

ReadConsoleInput

ReadFile

SetStdHandle

WriteConsole

WriteFile