HandlerRoutine-Rückruffunktion

Artikel
12/21/2023

Eine anwendungsdefinierte Funktion, die mit der SetConsoleCtrlHandler-Funktion verwendet wird. Ein Konsolenprozess verwendet diese Funktion zum Verarbeiten von Steuersignalen, die vom Prozess empfangen werden. Wenn das Signal empfangen wird, erstellt das System einen neuen Thread im Prozess, um die Funktion auszuführen.

Der Typ PHANDLER_ROUTINE definiert einen Zeiger auf diese Rückruffunktion. HandlerRoutine ist ein Platzhalter für den anwendungsdefinierten Funktionsnamen.

Syntax

BOOL WINAPI HandlerRoutine(
  _In_ DWORD dwCtrlType
);

Parameter

dwCtrlType [in]
Der Typ des vom Handler empfangenen Steuersignals. Dieser Parameter kann einen der folgenden Werte annehmen.

Wert	Bedeutung
CTRL_C_EVENT 0	Ein `STRG+C-Signal` wurde entweder von Tastatureingaben oder von einem Signal empfangen, das von der GenerateConsoleCtrlEvent-Funktion generiert wurde.
CTRL_BREAK_EVENT 1	Ein `STRG+BREAK-Signal` wurde entweder von der Tastatureingabe oder von einem von GenerateConsoleCtrlEvent generierten Signal empfangen.
CTRL_CLOSE_EVENT 2	Ein Signal, das das System an alle Prozesse sendet, die an eine Konsole angefügt sind, wenn der Benutzer die Konsole schließt (entweder durch Klicken auf "Schließen " im Fenstermenü des Konsolenfensters oder durch Klicken auf den Befehl "Aufgabe beenden" im Task-Manager).
CTRL_LOGOFF_EVENT 5	Ein Signal, dass das System an alle Konsolenprozesse sendet, wenn sich ein Benutzer abmeldet. Dieses Signal gibt nicht an, welcher Benutzer sich abmeldet, sodass keine Annahmen getroffen werden können. Beachten Sie, dass dieses Signal nur von Diensten empfangen wird. Interaktive Anwendungen werden bei der Abmeldung beendet, sodass sie nicht vorhanden sind, wenn das System dieses Signal sendet.
CTRL_SHUTDOWN_EVENT 6	Ein Signal, das das System sendet, wenn das System heruntergefahren wird. Interaktive Anwendungen sind nicht vorhanden, wenn das System dieses Signal sendet, daher kann es nur Dienste in dieser Situation empfangen werden. Dienste verfügen auch über einen eigenen Benachrichtigungsmechanismus für Herunterfahren-Ereignisse. Weitere Informationen finden Sie in Handles.

Rückgabewert

Wenn die Funktion das Steuersignal behandelt, sollte WAHR zurückgegeben werden. Wenn FALSCH zurückgegeben wird, wird die nächste Handlerfunktion in der Liste der Handler für diesen Prozess verwendet.

Hinweise

Da das System einen neuen Thread im Prozess zum Ausführen der Handlerfunktion erstellt, ist es möglich, dass die Handlerfunktion von einem anderen Thread im Prozess beendet wird. Achten Sie darauf, Threads im Prozess mit dem Thread für die Handlerfunktion zu synchronisieren.

Jeder Konsolenprozess verfügt über eine eigene Liste der HandlerRoutine-Funktionen . Anfänglich enthält die Handlerliste für jeden Prozess nur eine Standardhandlerfunktion, die ExitProcessaufruft. 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 WAHR zurückgibt. Wenn keiner der Handler WAHR zurückgibt, wird der Standardhandler aufgerufen.

Die CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT und CTRL_SHUTDOWN_EVENT Signale geben dem Prozess die Möglichkeit, vor der Kündigung zu säubern. Eine HandlerRoutine kann alle erforderlichen Säuberungen ausführen und dann eine der folgenden Aktionen ausführen:

Rufen Sie die ExitProcess-Funktion auf, um den Prozess zu beenden.
Zurückgeben von FALSCH Wenn keine der registrierten Handlerfunktionen WAHR zurückgibt, beendet der Standardhandler den Prozess.
Gibt „WAHR“ zurück. In diesem Fall werden keine anderen Handlerfunktionen aufgerufen, und das System beendet den Prozess.

Ein Prozess kann die SetProcessShutdownParameters-Funktion verwenden, um zu verhindern, dass das System während der Abmeldung oder beim Herunterfahren ein Dialogfeld für den Benutzer anzeigt. In diesem Fall beendet das System den Prozess, wenn HandlerRoutine WAHR zurückgibt oder wenn der Timeoutzeitraum verstrichen ist.

Wenn eine Konsolenanwendung als Dienst ausgeführt wird, empfängt sie einen geänderten Standardkonsolen-Steuerelementhandler. Dieser geänderte Handler ruft ExitProcess nicht auf, wenn die CTRL_LOGOFF_EVENT und CTRL_SHUTDOWN_EVENT Signale verarbeitet werden. Dadurch kann der Dienst weiterhin ausgeführt werden, nachdem der Benutzer sich ausgeloggt hat. Wenn der Dienst einen eigenen Konsolensteuerelementhandler installiert, wird dieser Handler vor dem Standardhandler aufgerufen. Wenn der installierte Handler ExitProcess beim Verarbeiten des CTRL_LOGOFF_EVENT Signals aufruft, wird der Dienst beendet, wenn sich der Benutzer abmeldet.

Beachten Sie, dass eine Drittanbieterbibliothek oder DLL einen Konsolensteuerungshandler für Ihre Anwendung installieren kann. In diesem Fall überschreibt dieser Handler den Standardhandler und kann dazu führen, dass die Anwendung beendet wird, wenn sich der Benutzer abmeldet.

Timeouts

Ereignis	Umstände	Timeout
`CTRL_CLOSE_EVENT`	beliebig	Systemparameter 5000ms
`CTRL_LOGOFF_EVENT`	Schnell (1)	Registrierungsschlüssel `CriticalAppShutdownTimeout` oder 500 ms
`CTRL_LOGOFF_EVENT`	Keine der oben genannten Antworten	Systemparameter, 5000ms
`CTRL_SHUTDOWN_EVENT`	Dienstprozess	Systemparameter 20000ms
`CTRL_SHUTDOWN_EVENT`	Schnell (1)	Registrierungsschlüssel `CriticalAppShutdownTimeout` oder 500 ms
`CTRL_SHUTDOWN_EVENT`	Keine der oben genannten Antworten	Systemparameter, 5000ms
`CTRL_C`, `CTRL_BREAK`	beliebig	Keine Zeitüberschreitung

[1]: "schnelle" Ereignisse werden nie verwendet, aber es gibt immer noch Code, um sie zu unterstützen.

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)