SetConsoleCtrlHandler-FunktionSetConsoleCtrlHandler function

Fügt eine von der Anwendung definierte HandlerRoutine-Funktion zur Liste der Handlerfunktionen für den aufrufenden Prozess hinzu oder entfernt sie aus dieser.Adds or removes an application-defined HandlerRoutine function from the list of handler functions for the calling process.

Wenn keine Handlerfunktion angegeben wird, legt die Funktion ein vererbbares Attribut fest, das bestimmt, ob der aufrufende Prozess STRG+C-Signale ignoriert.If no handler function is specified, the function sets an inheritable attribute that determines whether the calling process ignores CTRL+C signals.

SyntaxSyntax

BOOL WINAPI SetConsoleCtrlHandler(
  _In_opt_ PHANDLER_ROUTINE HandlerRoutine,
  _In_     BOOL             Add
);

ParameterParameters

HandlerRoutine [in, optional]HandlerRoutine [in, optional]
Ein Zeiger auf die von der Anwendung definierte HandlerRoutine-Funktion, die hinzugefügt oder entfernt werden soll.A pointer to the application-defined HandlerRoutine function to be added or removed. Dieser Parameter kann NULL sein.This parameter can be NULL.

Add [in]Add [in]
Wenn dieser Parameter TRUE ist, wird der Handler hinzugefügt. Ist er FALSE, wird der Handler entfernt.If this parameter is TRUE, the handler is added; if it is FALSE, the handler is removed.

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.If the HandlerRoutine parameter is NULL, a TRUE value causes the calling process to ignore CTRL+C input, and a FALSE value restores normal processing of CTRL+C input. Dieses Attribut zum Ignorieren oder Verarbeiten von STRG+C wird von untergeordneten Prozessen geerbt.This attribute of ignoring or processing CTRL+C is inherited by child processes.

RückgabewertReturn value

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.If the function succeeds, the return value is nonzero.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null.If the function fails, the return value is zero. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.To get extended error information, call GetLastError.

BemerkungenRemarks

Diese Funktion bietet eine ähnliche Benachrichtigung für Konsolenanwendungen und-Dienste, wie sie WM_QUERYENDSESSION für grafische Anwendungen mit einem Nachrichtensystem bereitstellt.This function provides a similar notification for console application and services that WM_QUERYENDSESSION provides for graphical applications with a message pump. 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.You could also use this function from a graphical application, but there is no guarantee it would arrive before the notification from WM_QUERYENDSESSION.

Für jeden Konsolenprozess gibt es eine eigene Liste mit anwendungsdefinierten HandlerRoutine-Funktionen, die STRG+C- und STRG+UNTBR-Signale verarbeiten.Each console process has its own list of application-defined HandlerRoutine functions that handle CTRL+C and CTRL+BREAK signals. 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.The handler functions also handle signals generated by the system when the user closes the console, logs off, or shuts down the system. Anfänglich enthält die Handlerliste für jeden Prozess nur eine Standardhandlerfunktion, die die ExitProcess-Funktion aufruft.Initially, the handler list for each process contains only a default handler function that calls the ExitProcess function. 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.A console process adds or removes additional handler functions by calling the SetConsoleCtrlHandler function, which does not affect the list of handler functions for other processes. 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.When a console process receives any of the control signals, its handler functions are called on a last-registered, first-called basis until one of the handlers returns TRUE. Wenn keiner der Handler TRUE zurückgibt, wird der Standardhandler aufgerufen.If none of the handlers returns TRUE, the default handler is called.

Für Konsolenprozesse werden die Tastenkombinationen STRG+C und STRG+UNTBR normalerweise als Signale (STRG_C_EVENT und STRG_BREAK_EVENT) behandelt.For console processes, the CTRL+C and CTRL+BREAK key combinations are typically treated as signals (CTRL_C_EVENT and CTRL_BREAK_EVENT). 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.When a console window with the keyboard focus receives CTRL+C or CTRL+BREAK, the signal is typically passed to all processes sharing that console.

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:CTRL+BREAK is always treated as a signal, but typical CTRL+C behavior can be changed in three ways that prevent the handler functions from being called:

  • 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.The SetConsoleMode function can disable the ENABLE_PROCESSED_INPUT mode for a console's input buffer, so CTRL+C is reported as keyboard input rather than as a signal.
  • Das Aufrufen von SetConsoleCtrlHandler mit den Argumenten NULL und TRUE bewirkt, dass der aufrufende Prozess STRG+C-Signale ignoriert.Calling SetConsoleCtrlHandler with the NULL and TRUE arguments causes the calling process to ignore CTRL+C signals. Dieses Attribut wird von untergeordneten Prozessen geerbt, kann jedoch von jedem Prozess aktiviert oder deaktiviert werden, ohne dass vorhandene Prozesse davon betroffen sind.This attribute is inherited by child processes, but it can be enabled or disabled by any process without affecting existing processes.
  • Wenn ein Konsolenprozess debuggt wird und STRG+C-Signale nicht deaktiviert wurden, generiert das System eine DBG_CONTROL_C-Ausnahme.If a console process is being debugged and CTRL+C signals have not been disabled, the system generates a DBG_CONTROL_C exception. Diese Ausnahme wird nur zum Nutzen des Debuggers ausgelöst, und eine Anwendung sollte niemals einen Ausnahmehandler verwenden, um sie zu verarbeiten.This exception is raised only for the benefit of the debugger, and an application should never use an exception handler to deal with it. Wenn der Debugger die Ausnahme behandelt, wird das STRG+C-Signal von einer Anwendung nicht bemerkt, mit einer Ausnahme: Warnungsfähige Wartebedingungen werden beendet.If the debugger handles the exception, an application will not notice the CTRL+C, with one exception: alertable waits will terminate. Wenn der Debugger die Ausnahme unverarbeitet übergibt, wird STRG+C an den Konsolenprozess übergeben und als Signal behandelt, wie zuvor erörtert.If the debugger passes the exception on unhandled, CTRL+C is passed to the console process and treated as a signal, as previously discussed.

Ein Konsolenprozess kann die Funktion GenerateConsoleCtrlEvent verwenden, um ein STRG+C- oder STRG+BREAK-Signal an eine Konsolenprozessgruppe zu senden.A console process can use the GenerateConsoleCtrlEvent function to send a CTRL+C or CTRL+BREAK signal to a console process group.

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.The system generates CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT, and CTRL_SHUTDOWN_EVENT signals when the user closes the console, logs off, or shuts down the system so that the process has an opportunity to clean up before termination. Konsolenfunktionen oder beliebige C-Laufzeitfunktionen, die Konsolenfunktionen aufrufen, funktionieren möglicherweise nicht zuverlässig, während eins dieser zuvor erwähnten Signale verarbeitet wird.Console functions, or any C run-time functions that call console functions, may not work reliably during processing of any of the three signals mentioned previously. Dies hat den Grund, dass möglicherweise einige oder alle ihrer internen Routinen zur Konsolenbereinigung aufgerufen wurden, bevor der Prozesssignalhandler ausgeführt wird.The reason is that some or all of the internal console cleanup routines may have been called before executing the process signal handler.

Windows 7, Windows 8, Windows 8.1 und Windows 10:Windows 7, Windows 8, Windows 8.1 and 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.If a console application loads the gdi32.dll or user32.dll library, the HandlerRoutine function that you specify when you call SetConsoleCtrlHandler does not get called for the CTRL_LOGOFF_EVENT and CTRL_SHUTDOWN_EVENT events. Das Betriebssystem erkennt Prozesse, die gdi32.dll oder user32.dll laden, als Windows-Anwendungen und nicht als Konsolenanwendungen.The operating system recognizes processes that load gdi32.dll or user32.dll as Windows applications rather than console applications. 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.This behavior also occurs for console applications that do not call functions in gdi32.dll or user32.dll directly, but do call functions such as Shell functions that do in turn call functions in gdi32.dll or user32.dll.

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.To receive events when a user signs out or the device shuts down in these circumstances, create a hidden window in your console application, and then handle the WM_QUERYENDSESSION and WM_ENDSESSION window messages that the hidden window receives. Sie können ein ausgeblendetes Fenster erstellen, indem Sie die Methode CreateWindowEx mit auf 0 festgelegtem Parameter dwExStyle aufrufen.You can create a hidden window by calling the CreateWindowEx method with the dwExStyle parameter set to 0.

BeispieleExamples

Ein Beispiel finden Sie unter Registrieren einer Steuerelementhandler-Funktion.For an example, see Registering a Control Handler Function.

AnforderungenRequirements

   
Unterstützte Mindestversion (Client)Minimum supported client Windows 2000 Professional [nur Desktop-Apps]Windows 2000 Professional [desktop apps only]
Unterstützte Mindestversion (Server)Minimum supported server Windows 2000 Server [nur Desktop-Apps]Windows 2000 Server [desktop apps only]
HeaderHeader ConsoleApi.h (über WinCon.h, Windows.h einschließen)ConsoleApi.h (via WinCon.h, include Windows.h)
BibliothekLibrary Kernel32.libKernel32.lib
DLLDLL Kernel32.dllKernel32.dll
Unicode- und ANSI-NameUnicode and ANSI names

Siehe auchSee also

Konsolen-BearbeitungssteuerelementeConsole Control Handlers

KonsolenfunktionenConsole Functions

ExitProcessExitProcess

GenerateConsoleCtrlEventGenerateConsoleCtrlEvent

GetConsoleModeGetConsoleMode

HandlerRoutineHandlerRoutine

SetConsoleModeSetConsoleMode