SetConsoleCtrlHandler-Funktion
Fügt eine von der Anwendung definierte HandlerRoutine-Funktion zur Liste der Handlerfunktionen für den aufrufenden Prozess hinzu oder entfernt sie aus dieser.
Wenn keine Handlerfunktion angegeben wird, legt die Funktion ein vererbbares Attribut fest, das bestimmt, ob der aufrufende Prozess STRG+C-Signale ignoriert.
Syntax
BOOL WINAPI SetConsoleCtrlHandler(
_In_opt_ PHANDLER_ROUTINE HandlerRoutine,
_In_ BOOL Add
);
Parameter
HandlerRoutine [in, optional]
Ein Zeiger auf die von der Anwendung definierte HandlerRoutine-Funktion, die hinzugefügt oder entfernt werden soll. Dieser Parameter kann NULL sein.
Hinzufügen [in]
Wenn dieser Parameter TRUE ist, wird der Handler hinzugefügt. Ist er FALSE, wird der Handler entfernt.
Wenn der HandlerRoutine-Parameter NULL ist, bewirkt der Wert TRUE, dass der aufrufende Prozess die Eingabe von STRG+C ignoriert, während beim Wert FALSE die normale Verarbeitung der Eingabe von STRG+C wiederhergestellt wird. Dieses Attribut zum Ignorieren oder Verarbeiten von STRG+C wird von untergeordneten Prozessen geerbt.
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
Diese Funktion bietet eine ähnliche Benachrichtigung für Konsolenanwendungen und -dienste, wie sie WM_QUERYENDSESSION für grafische Anwendungen mit einem Nachrichtensystem bereitstellt. Sie könnten diese Funktion auch aus einer grafischen Anwendung heraus verwenden, es ist aber nicht sichergestellt, dass sie vor der Benachrichtigung von WM_QUERYENDSESSION eingehen würde.
Für jeden Konsolenprozess gibt es eine eigene Liste mit anwendungsdefinierten HandlerRoutine-Funktionen, die STRG+C- und STRG+UNTBR-Signale verarbeiten. Die Handlerfunktionen verarbeiten außerdem Signale, die vom System generiert werden, wenn der Benutzer die Konsole schließt, sich abmeldet oder das System herunterfährt. Anfänglich enthält die Handlerliste für jeden Prozess nur eine Standardhandlerfunktion, die die ExitProcess-Funktion aufruft. Ein Konsolenprozess fügt zusätzliche Handlerfunktionen hinzu oder entfernt diese, indem er die Funktion SetConsoleCtrlHandler aufruft, was sich nicht auf die Liste der Handlerfunktionen für andere Prozesse auswirkt. Wenn ein Konsolenprozess eins der Steuersignale empfängt, werden seine Handlerfunktionen der Reihe nach beginnend mit der zuletzt registrierten aufgerufen, bis einer der Handler TRUE zurückgibt. Wenn keiner der Handler TRUE zurückgibt, wird der Standardhandler aufgerufen.
Durch Aufrufen von AttachConsole, AllocConsole oder FreeConsole wird die Tabelle der Steuerelementhandler im Clientprozess auf den Ausgangszustand zurückgesetzt. Handler müssen erneut registriert werden, wenn sich die angefügte Konsolensitzung ändert.
Für Konsolenprozesse werden die Tastenkombinationen STRG+C und STRG+UNTBR normalerweise als Signale (CTRL_C_EVENT und CTRL_BREAK_EVENT) behandelt. Wenn ein Konsolenfenster mit Tastaturfokus STRG+C oder STRG+UNTBR empfängt, wird das Signal normalerweise an alle Prozesse übergeben, die die betreffende Konsole gemeinsam verwenden.
STRG+UNTBR wird immer als Signal behandelt, aber das Verhalten von STRG+C kann normalerweise auf drei Arten geändert werden, die das Aufrufen der Handlerfunktionen verhindern:
- Die Funktion SetConsoleMode kann den Modus ENABLE_PROCESSED_INPUT für den Eingabepuffer einer Konsole deaktivieren, sodass STRG+C als Tastatureingabe statt als Signal gemeldet wird.
- Das Aufrufen von SetConsoleCtrlHandler mit den Argumenten NULL und TRUE bewirkt, dass der aufrufende Prozess STRG+C-Signale ignoriert. Dieses Attribut wird von untergeordneten Prozessen geerbt, kann jedoch von jedem Prozess aktiviert oder deaktiviert werden, ohne dass vorhandene Prozesse davon betroffen sind.
- Wenn ein Konsolenprozess debuggt wird und STRG+C-Signale nicht deaktiviert wurden, generiert das System eine DBG_CONTROL_C-Ausnahme. Diese Ausnahme wird nur zum Nutzen des Debuggers ausgelöst, und eine Anwendung sollte niemals einen Ausnahmehandler verwenden, um sie zu verarbeiten. Wenn der Debugger die Ausnahme behandelt, wird das STRG+C-Signal von einer Anwendung nicht bemerkt, mit einer Ausnahme: Warnungsfähige Wartebedingungen werden beendet. Wenn der Debugger die Ausnahme unverarbeitet übergibt, wird STRG+C an den Konsolenprozess übergeben und als Signal behandelt, wie zuvor erörtert.
Ein Konsolenprozess kann die Funktion GenerateConsoleCtrlEvent verwenden, um ein STRG+C- oder STRG+BREAK-Signal an eine Konsolenprozessgruppe zu senden.
Das System generiert CTRL_CLOSE_EVENT-, CTRL_LOGOFF_EVENT- und CTRL_SHUTDOWN_EVENT-Signale, wenn der Benutzer die Konsole schließt, sich abmeldet oder das System herunterfährt, sodass der Prozess Gelegenheit hat, vor der Beendigung aufzuräumen. Konsolenfunktionen oder beliebige C-Laufzeitfunktionen, die Konsolenfunktionen aufrufen, funktionieren möglicherweise nicht zuverlässig, während eins dieser zuvor erwähnten Signale verarbeitet wird. Dies hat den Grund, dass möglicherweise einige oder alle ihrer internen Routinen zur Konsolenbereinigung aufgerufen wurden, bevor der Prozesssignalhandler ausgeführt wird.
Windows 7, Windows 8, Windows 8.1 und Windows 10:
Wenn eine Konsolenanwendung die gdi32.dll- oder user32.dll-Bibliothek lädt, wird die HandlerRoutine-Funktion, die Sie beim Aufrufen von SetConsoleCtrlHandler angeben, für die Ereignisse CTRL_LOGOFF_EVENT und CTRL_SHUTDOWN_EVENT nicht aufgerufen. Das Betriebssystem erkennt Prozesse, die gdi32.dll oder user32.dll laden, als Windows-Anwendungen und nicht als Konsolenanwendungen. Dieses Verhalten tritt auch bei Konsolenanwendungen auf, die keine Funktionen in gdi32.dll oder user32.dll direkt aufrufen, sondern Funktionen wie etwa Shellfunktionen aufrufen, die ihrerseits Funktionen in gdi32.dll oder user32.dll aufrufen.
Zum Empfangen von Ereignissen, wenn sich ein Benutzer abmeldet oder das Gerät unter diesen Umständen heruntergefahren wird, erstellen Sie ein verborgenes Fenster in Ihrer Konsolenanwendung, und verarbeiten Sie dann die Fensternachrichten WM_QUERYENDSESSION und WM_ENDSESSION, die vom verborgenen Fenster empfangen werden. Sie können ein ausgeblendetes Fenster erstellen, indem Sie die Methode CreateWindowEx mit auf 0 festgelegtem Parameter dwExStyle aufrufen. Ein Beispiel hierfür ist im unten verlinkten Beispiel für einen einfachen Handler enthalten.
Beispiele
Ein Beispiel finden Sie unter Registrieren einer Steuerelementhandler-Funktion.
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 |