Fonction SetConsoleCtrlHandler

Article
07/12/2023

Ajoute ou supprime une fonction HandlerRoutine définie par l’application dans la liste des fonctions de gestionnaire pour le processus appelant.

Si aucune fonction de gestionnaire n’est spécifiée, la fonction définit un attribut pouvant être hérité qui détermine si le processus appelant ignore les signaux CTRL+C.

Syntaxe

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

Paramètres

HandlerRoutine [entrée, facultatif]
Pointeur vers la fonction HandlerRoutine définie par l’application à ajouter ou à supprimer. Ce paramètre peut être NULL.

Add [entrée]
Si ce paramètre est TRUE, le gestionnaire est ajouté ; si la valeur est FALSE, le gestionnaire est supprimé.

Si le paramètre HandlerRoutine est NULL, une valeur TRUE fait que le processus appelant ignore l’entrée CTRL+C, et une valeur FALSE restaure le traitement normal de CTRL+C. Cet attribut pour ignorer ou traiter CTRL+C est hérité par les processus enfants.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Notes

Cette fonction fournit une notification similaire pour l’application console et les services qui sont fournis par WM_QUERYENDSESSION pour les applications graphiques avec une pompe de messages. Vous pouvez également utiliser cette fonction à partir d’une application graphique, mais il n’y a aucune garantie qu’elle arrive avant la notification de WM_QUERYENDSESSION.

Chaque processus de console a sa propre liste de fonctions HandlerRoutine définies par l’application qui gèrent les signaux CTRL+C et CTRL+BREAK. Les fonctions du gestionnaire gèrent également les signaux générés par le système quand l’utilisateur ferme la console, se déconnecte ou arrête le système. À la base, la liste de gestionnaires de chaque processus contient seulement une fonction de gestionnaire par défaut qui appelle la fonction ExitProcess. Un processus de console ajoute ou supprime des fonctions de gestionnaire supplémentaires en appelant la fonction SetConsoleCtrlHandler, qui n’affecte pas la liste des fonctions de gestionnaire pour d’autres processus. Quand un processus de console reçoit un des signaux de contrôle, ses fonctions de gestionnaire sont appelées selon le principe « dernier enregistré, premier appelé », jusqu’à ce qu’un des gestionnaires retourne TRUE. Si aucun des gestionnaires ne retourne TRUE, le gestionnaire par défaut est appelé.

Le fait d’appeler AttachConsole, AllocConsole ou FreeConsole rétablit l’état initial de la table des gestionnaires de contrôles dans le processus client. Vous devez réinscrire les gestionnaires quand la session de console attachée change.

Pour les processus de la console, les combinaisons de touches Ctrl+C et Ctrl+Pause sont généralement traitées comme des signaux (CTRL_C_EVENT et CTRL_BREAK_EVENT). Quand une fenêtre de console avec le focus au clavier reçoit CTRL+C ou CTRL+BREAK, le signal est généralement passé à tous les processus qui partagent cette console.

CTRL+BREAK est toujours traitée comme un signal, mais le comportement habituel de CTRL+C peut être changé de trois façons qui empêchent l’appel des fonctions du gestionnaire :

La fonction SetConsoleMode peut désactiver le mode ENABLE_PROCESSED_INPUT pour la mémoire tampon d’entrée d’une console. Ctrl+C est donc signalé comme étant une entrée du clavier plutôt qu’un signal.
L’appel de SetConsoleCtrlHandler avec les arguments NULL et TRUE fait que le processus appelant ignore les signaux CTRL+C. Cet attribut est hérité par les processus enfants, mais il peut être activé ou désactivé par n’importe quel processus sans affecter les processus existants.
Si un processus de console est en cours de débogage et que les signaux CTRL+C n’ont pas été désactivés, le système génère une exception DBG_CONTROL_C. Cette exception est déclenchée seulement à destination du débogueur, et une application ne doit jamais utiliser un gestionnaire d’exceptions pour le gérer. Si le débogueur gère l’exception, une application ne va pas détecter le CTRL+C, à une exception près : les attentes susceptibles de déclencher des alertes vont se terminer. Si le débogueur passe l’exception en « non géré », CTRL+C est passé au processus de console et est traité en tant que signal, comme indiqué précédemment.

Un processus de console peut utiliser la fonction GenerateConsoleCtrlEvent pour envoyer un signal CTRL+C ou CTRL+BREAK à un groupe de processus de console.

Le système génère des signaux CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT et CTRL_SHUTDOWN_EVENT quand l’utilisateur ferme la console, ferme une session ou arrête le système afin que le processus puisse être nettoyé avant l’arrêt. Les fonctions de console, ou les fonctions du runtime C qui appellent des fonctions de console, risquent de ne pas fonctionner de façon fiable lors du traitement des trois signaux mentionnés précédemment. La raison en est que tout ou partie des routines de nettoyage de la console interne peuvent avoir été appelées avant l’exécution du gestionnaire de signaux du processus.

Windows 7, Windows 8, Windows 8.1 et Windows 10 :

Si une application console charge la bibliothèque gdi32.dll ou user32.dll, la fonction HandlerRoutine que vous spécifiez quand vous appelez SetConsoleCtrlHandler n’est pas appelée pour les événements CTRL_LOGOFF_EVENT et CTRL_SHUTDOWN_EVENT. Le système d’exploitation reconnaît les processus qui chargent gdi32.dll ou user32.dll en tant qu’applications Windows et non pas en tant qu’applications console. Ce comportement se produit également pour les applications console qui n’appellent pas directement des fonctions dans gdi32.dll ou user32.dll, mais qui appellent des fonctions comme des fonctions Shell qui appellent à leur tour des fonctions dans gdi32.dll ou user32.dll.

Pour recevoir des événements quand un utilisateur se déconnecte ou que l’appareil s’arrête dans ces circonstances, créez une fenêtre masquée dans votre application console, puis gérez les messages de fenêtre WM_QUERYENDSESSION et WM_ENDSESSION que la fenêtre masquée reçoit. Vous pouvez créer une fenêtre masquée en appelant la méthode CreateWindowEx avec le paramètre dwExStyle défini sur 0. Vous trouverez un exemple de ceci dans l’exemple de gestionnaire de base (lien ci-dessous).

Exemples

Pour obtenir un exemple, consultez Inscription d’une fonction de gestionnaire de contrôle.

Spécifications


Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
En-tête	ConsoleApi.h (via WinCon.h, inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll
Noms Unicode et ANSI