Fonction de rappel HandlerRoutine

Article
12/22/2023

Une fonction définie par l’application et utilisée avec la fonction SetConsoleCtrlHandler. Un processus de console utilise cette fonction pour gérer les signaux de contrôle reçus par le processus. Lorsque le signal est reçu, le système crée un thread dans le processus pour exécuter la fonction.

Le type PHANDLER_ROUTINE définit un pointeur vers cette fonction de rappel. HandlerRoutine est un espace réservé pour le nom de la fonction définie par l’application.

Syntaxe

BOOL WINAPI HandlerRoutine(
  _In_ DWORD dwCtrlType
);

Paramètres

dwCtrlType [entrée]
Le type de signal de contrôle reçu par le gestionnaire. Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
CTRL_C_EVENT 0	Un signal `CTRL`+`C` a été reçu, à partir de l’entrée de clavier ou d’un signal généré par la fonction GenerateConsoleCtrlEvent.
CTRL_BREAK_EVENT 1	Un signal `CTRL`+`BREAK` a été reçu, à partir de l’entrée de clavier ou d’un signal généré par la fonction GenerateConsoleCtrlEvent.
CTRL_CLOSE_EVENT 2	Un signal que le système envoie à tous les processus attachés à une console lorsque l'utilisateur ferme la console (soit en cliquant sur Fermer dans le menu de la fenêtre de console, soit en cliquant sur la commande du bouton Arrêter la tâche dans le Gestionnaire de tâches).
CTRL_LOGOFF_EVENT 5	Un signal que le système envoie à tous les processus de console lorsqu'un utilisateur se déconnecte. Ce signal n’indique pas quel utilisateur ferme une session, donc aucune hypothèse ne peut être faite. Notez que ce signal est reçu uniquement par les services. Les applications interactives sont arrêtées lors de la fermeture de session, de sorte qu’elles ne sont pas présentes lorsque le système envoie ce signal.
CTRL_SHUTDOWN_EVENT 6	Un signal que le système envoie quand le système s’arrête. Les applications interactives ne sont pas présentes au moment où le système envoie ce signal, qui ne peut donc être reçu que par les services dans cette situation. Les services ont également leur propre mécanisme de notification pour les événements d’arrêt. Pour plus d’informations, consultez la section Gestionnaire.

Valeur retournée

Si la fonction gère le signal de contrôle, elle doit renvoyer VRAI. Si elle renvoie FAUX, la fonction de gestionnaire suivante dans la liste des gestionnaires pour ce processus est utilisée.

Notes

Étant donné que le système crée un thread dans le processus pour exécuter la fonction de gestionnaire, il est possible que la fonction de gestionnaire soit arrêtée par un autre thread du processus. Veillez à synchroniser les threads dans le processus avec le thread de la fonction de gestionnaire.

Chaque processus de console possède sa propre liste de fonctions HandlerRoutine. À la base, cette liste ne contient qu'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 renvoie VRAI. Si aucun des gestionnaires ne renvoie VRAI, le gestionnaire par défaut est appelé.

Les signaux CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT et CTRL_SHUTDOWN_EVENT donnent l’occasion de nettoyer avant l’arrêt. Un HandlerRoutine peut effectuer tout nettoyage nécessaire, puis entreprendre l'une des actions suivantes :

Appelez la fonction ExitProcess pour terminer le processus.
Renvoie FAUX. Si aucune des fonctions de gestionnaire enregistrées ne renvoie VRAI, le gestionnaire par défaut termine le processus.
Renvoie VRAI. Dans ce cas, aucune autre fonction de gestionnaire n’est appelée et le système termine le processus.

Un processus peut utiliser la fonction SetProcessShutdownParameters pour empêcher le système d’afficher une boîte de dialogue à l’utilisateur pendant la déconnexion ou l’arrêt. Dans ce cas, le système met fin au processus lorsque HandlerRoutine renvoie VRAI ou lorsque le délai d’attente s’écoule.

Lorsqu’une application de console est exécutée en tant que service, elle reçoit un gestionnaire de contrôle de console par défaut modifié. Ce gestionnaire modifié n’appelle pas ExitProcess lors du traitement des signaux CTRL_LOGOFF_EVENT et CTRL_SHUTDOWN_EVENT. Cela permet au service de continuer à s'exécuter après la déconnexion de l'utilisateur. Si le service installe son propre gestionnaire de contrôle de console, ce gestionnaire est appelé avant le gestionnaire par défaut. Si le gestionnaire installé appelle ExitProcess lors du traitement du signal CTRL_LOGOFF_EVENT, le service se ferme lorsque l’utilisateur se déconnecte.

Notez qu’une bibliothèque ou une DLL tierce peut installer un gestionnaire de contrôle de console pour votre application. Si c’est le cas, ce gestionnaire remplace le gestionnaire par défaut et peut entraîner la fermeture de l’application lorsque l’utilisateur se déconnecte.

Délais d'attente

Event	Circumstances	Délai d'expiration
`CTRL_CLOSE_EVENT`	any	paramètre du système `SPI_GETHUNGAPPTIMEOUT`, 5000ms
`CTRL_LOGOFF_EVENT`	quick[1]	Clé de Registre `CriticalAppShutdownTimeout` ou 500ms
`CTRL_LOGOFF_EVENT`	aucune des propositions ci-dessus	paramètre du système `SPI_GETWAITTOKILLTIMEOUT`, 5000ms
`CTRL_SHUTDOWN_EVENT`	processus de service	paramètre du système `SPI_GETWAITTOKILLSERVICETIMEOUT`, 20000ms
`CTRL_SHUTDOWN_EVENT`	quick[1]	Clé de Registre `CriticalAppShutdownTimeout` ou 500ms
`CTRL_SHUTDOWN_EVENT`	aucune des propositions ci-dessus	paramètre du système `SPI_GETWAITTOKILLTIMEOUT`, 5000ms
`CTRL_C`, `CTRL_BREAK`	any	Aucun délai d’expiration

[1] : Les événements « quick » ne sont jamais utilisés, mais il existe toujours du code pour les prendre en charge.

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)