LPHANDLER_FUNCTION fonction de rappel (winsvc.h)

Article
08/27/2023

Fonction de rappel définie par l’application utilisée avec la fonction RegisterServiceCtrlHandler . Un programme de service peut l’utiliser comme fonction de gestionnaire de contrôle d’un service particulier.

Le type LPHANDLER_FUNCTION définit un pointeur vers cette fonction. Le gestionnaire est un espace réservé pour le nom défini par l’application.

Cette fonction a été remplacée par la fonction de gestionnaire de contrôle HandlerEx utilisée avec la fonction RegisterServiceCtrlHandlerEx . Un service peut utiliser l’un ou l’autre gestionnaire de contrôle, mais le nouveau gestionnaire de contrôle prend en charge les données de contexte définies par l’utilisateur et les codes de contrôle étendus supplémentaires.

Syntaxe

LPHANDLER_FUNCTION LphandlerFunction;

void LphandlerFunction(
  DWORD dwControl
)
{...}

Paramètres

dwControl

Valeur de retour

None

Remarques

Lorsqu’un service est démarré, sa fonction ServiceMain doit immédiatement appeler la fonction RegisterServiceCtrlHandler pour spécifier une fonction Handler pour traiter les demandes de contrôle.

Le répartiteur de contrôle dans le thread main d’un processus de service appelle la fonction de gestionnaire de contrôle pour le service spécifié chaque fois qu’il reçoit une demande de contrôle du gestionnaire de contrôle de service. Après avoir traité la demande de contrôle, le gestionnaire de contrôle doit appeler la fonction SetServiceStatus si l’état du service change pour signaler ses nouvelles status au gestionnaire de contrôle de service.

La fonction de gestionnaire de contrôle est destinée à recevoir une notification et à retourner immédiatement. La fonction de rappel doit enregistrer ses paramètres et créer d’autres threads pour effectuer un travail supplémentaire. (Votre application doit s’assurer que ces threads se sont arrêtés avant d’arrêter le service.) En particulier, un gestionnaire de contrôle doit éviter les opérations susceptibles de bloquer, telles que la prise d’un verrou, car cela peut entraîner un interblocage ou entraîner l’arrêt de la réponse du système.

Lorsque le gestionnaire de contrôle de service envoie un code de contrôle à un service, il attend que la fonction de gestionnaire retourne avant d’envoyer des codes de contrôle supplémentaires à d’autres services. Le gestionnaire de contrôle doit retourner aussi rapidement que possible ; s’il ne retourne pas dans les 30 secondes, le SCM retourne une erreur. Si un service doit effectuer un traitement long lorsqu’il exécute le gestionnaire de contrôle, il doit créer un thread secondaire pour effectuer le traitement long, puis retourner à partir du gestionnaire de contrôle. Cela empêche le service de lier le répartiteur de contrôle et d’empêcher d’autres services de recevoir des codes de contrôle.

Le code de contrôle SERVICE_CONTROL_SHUTDOWN ne doit être traité que par les services qui doivent absolument propre pendant l’arrêt, car un temps limité (environ 20 secondes) est disponible pour l’arrêt du service. Une fois ce délai expiré, l’arrêt du système se poursuit, que l’arrêt du service soit terminé ou non. Notez que si le système est à l’état d’arrêt (non redémarré ou hors tension), le service continue à s’exécuter. Si votre service s’inscrit pour accepter SERVICE_CONTROL_SHUTDOWN, il doit gérer le code de contrôle et s’arrêter en temps voulu. Sinon, le service peut augmenter le temps nécessaire à l’arrêt du système, car le système doit attendre la durée totale autorisée pour l’arrêt du service avant que l’arrêt du système puisse se poursuivre.

Si le service a besoin de plus de temps pour propre, il doit envoyer STOP_PENDING status messages, ainsi qu’un indicateur d’attente, afin que le contrôleur de service sache combien de temps attendre avant de signaler au système que l’arrêt du service est terminé. Toutefois, pour empêcher un service d’arrêter l’arrêt, il existe une limite à la durée d’attente du contrôleur de service. Si le service est arrêté via le composant logiciel enfichable Services, la limite est de 125 secondes. Si le système d’exploitation redémarre, la limite de temps est spécifiée dans la valeur WaitToKillServiceTimeout de la clé de Registre suivante :

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control

Les services peuvent également utiliser la fonction SetConsoleCtrlHandler pour recevoir une notification d’arrêt. Cette notification est reçue lorsque les applications en cours d’exécution sont arrêtées, ce qui se produit avant l’arrêt des services.

Exemples

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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winsvc.h (inclure Windows.h)