LPHANDLER_FUNCTION_EX fonction de rappel (winsvc.h)

Article
08/27/2023

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

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

Cette fonction remplace la fonction de gestionnaire de contrôle Handler utilisée avec la fonction RegisterServiceCtrlHandler . 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_EX LphandlerFunctionEx;

DWORD LphandlerFunctionEx(
  [in] DWORD dwControl,
  [in] DWORD dwEventType,
  [in] LPVOID lpEventData,
  [in] LPVOID lpContext
)
{...}

Paramètres

[in] dwControl

Code de contrôle. Ce paramètre peut prendre les valeurs suivantes.

Code de contrôle	Signification
SERVICE_CONTROL_CONTINUE 0x00000003	Avertit un service suspendu qu’il doit reprendre.
SERVICE_CONTROL_INTERROGATE 0x00000004	Avertit un service de signaler ses informations de status actuelles au gestionnaire de contrôle de service. Le gestionnaire doit simplement retourner NO_ERROR ; le SCM est conscient de l’état actuel du service.
SERVICE_CONTROL_NETBINDADD 0x00000007	Avertit un service réseau qu’il existe un nouveau composant pour la liaison. Le service doit être lié au nouveau composant. Les applications doivent utiliser Plug-and-Play fonctionnalité à la place.
SERVICE_CONTROL_NETBINDDISABLE 0x0000000A	Avertit un service réseau qu’une de ses liaisons a été désactivée. Le service doit relire ses informations de liaison et supprimer la liaison. Les applications doivent utiliser Plug-and-Play fonctionnalité à la place.
SERVICE_CONTROL_NETBINDENABLE 0x00000009	Avertit un service réseau qu’une liaison désactivée a été activée. Le service doit relire ses informations de liaison et ajouter la nouvelle liaison. Les applications doivent utiliser Plug-and-Play fonctionnalité à la place.
SERVICE_CONTROL_NETBINDREMOVE 0x00000008	Avertit un service réseau qu’un composant de liaison a été supprimé. Le service doit relire ses informations de liaison et se dissocier du composant supprimé. Les applications doivent utiliser Plug-and-Play fonctionnalité à la place.
SERVICE_CONTROL_PARAMCHANGE 0x00000006	Avertit un service que les paramètres de démarrage spécifiques au service ont changé. Le service doit relire ses paramètres de démarrage.
SERVICE_CONTROL_PAUSE 0x00000002	Avertit un service qu’il doit s’interrompre.
SERVICE_CONTROL_PRESHUTDOWN 0x0000000F	Avertit un service que le système s’arrêtera. Les services qui ont besoin de temps supplémentaire pour effectuer des tâches de nettoyage au-delà de la limite de temps à l’arrêt du système peuvent utiliser cette notification. Le gestionnaire de contrôle de service envoie cette notification aux applications qui s’y sont inscrites avant d’envoyer une notification SERVICE_CONTROL_SHUTDOWN aux applications qui se sont inscrites pour cette notification. Un service qui gère cette notification bloque l’arrêt du système jusqu’à ce que le service s’arrête ou que l’intervalle de délai d’attente avant arrêt spécifié jusqu’à SERVICE_PRESHUTDOWN_INFO expire. Étant donné que cela affecte l’expérience utilisateur, les services doivent utiliser cette fonctionnalité uniquement si cela est absolument nécessaire pour éviter une perte de données ou un temps de récupération important au prochain démarrage du système. Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge.
SERVICE_CONTROL_SHUTDOWN 0x00000005	Avertit un service que le système s’arrête afin qu’il puisse effectuer des tâches de nettoyage. Notez que les services qui s’inscrivent aux notifications SERVICE_CONTROL_PRESHUTDOWN ne peuvent pas recevoir cette notification, car ils se sont déjà arrêtés. Si un service accepte ce code de contrôle, il doit s’arrêter après avoir effectué ses tâches de nettoyage et retourner NO_ERROR. Une fois que le SCM a envoyé ce code de contrôle, il n’envoie pas d’autres codes de contrôle au service. Pour plus d’informations, consultez la section Remarques de cette rubrique.
SERVICE_CONTROL_STOP 0x00000001	Avertit un service qu’il doit s’arrêter. Si un service accepte ce code de contrôle, il doit s’arrêter à la réception et retourner NO_ERROR. Une fois que le SCM a envoyé ce code de contrôle, il n’envoie pas d’autres codes de contrôle au service. Windows XP : Si le service retourne NO_ERROR et continue de s’exécuter, il continue de recevoir des codes de contrôle. Ce comportement a changé à partir de Windows Server 2003 et de Windows XP avec SP2.

Ce paramètre peut également être l’un des codes de contrôle étendu suivants. Notez que ces codes de contrôle ne sont pas pris en charge par la fonction Handler .

Code de contrôle	Signification
SERVICE_CONTROL_DEVICEEVENT 0x0000000B	Avertit un service des événements d’appareil. (Le service doit s’être inscrit pour recevoir ces notifications à l’aide de la fonction RegisterDeviceNotification .) Les paramètres dwEventType et lpEventData contiennent des informations supplémentaires.
SERVICE_CONTROL_HARDWAREPROFILECHANGE 0x0000000C	Avertit un service que le profil matériel de l’ordinateur a changé. Le paramètre dwEventType contient des informations supplémentaires.
SERVICE_CONTROL_POWEREVENT 0x0000000D	Notifie un service des événements d’alimentation du système. Le paramètre dwEventType contient des informations supplémentaires. Si dwEventType est PBT_POWERSETTINGCHANGE, le paramètre lpEventData contient également des informations supplémentaires.
SERVICE_CONTROL_SESSIONCHANGE 0x0000000E	Notifie un service des événements de modification de session. Notez qu’un service n’est averti d’une ouverture de session utilisateur que s’il est entièrement chargé avant la tentative d’ouverture de session. Les paramètres dwEventType et lpEventData contiennent des informations supplémentaires.
SERVICE_CONTROL_TIMECHANGE 0x00000010	Avertit un service que l’heure système a changé. Le paramètre lpEventData contient des informations supplémentaires. Le paramètre dwEventType n’est pas utilisé. Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : Ce code de contrôle n’est pas pris en charge.
SERVICE_CONTROL_TRIGGEREVENT 0x00000020	Avertit un service inscrit pour un événement de déclencheur de service que l’événement s’est produit. Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : Ce code de contrôle n’est pas pris en charge.
SERVICE_CONTROL_USERMODEREBOOT 0x00000040	Avertit un service que l’utilisateur a lancé un redémarrage. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : Ce code de contrôle n’est pas pris en charge.

Ce paramètre peut également être un code de contrôle défini par l’utilisateur, comme décrit dans le tableau suivant.

Code de contrôle	Signification
Plage 128 à 255.	Le service définit l’action associée au code de contrôle.

[in] dwEventType

Type d’événement qui s’est produit. Ce paramètre est utilisé si dwControl est SERVICE_CONTROL_DEVICEEVENT, SERVICE_CONTROL_HARDWAREPROFILECHANGE, SERVICE_CONTROL_POWEREVENT ou SERVICE_CONTROL_SESSIONCHANGE. Sinon, c’est zéro.

Si dwControl est SERVICE_CONTROL_DEVICEEVENT, ce paramètre peut être l’une des valeurs suivantes :

Si dwControl est SERVICE_CONTROL_HARDWAREPROFILECHANGE, ce paramètre peut être l’une des valeurs suivantes :

Si dwControl est SERVICE_CONTROL_POWEREVENT, ce paramètre peut être l’une des valeurs spécifiées dans le paramètre wParam du message WM_POWERBROADCAST .

Si dwControl est SERVICE_CONTROL_SESSIONCHANGE, ce paramètre peut être l’une des valeurs spécifiées dans le paramètre wParam du message WM_WTSSESSION_CHANGE .

[in] lpEventData

Informations supplémentaires sur l’appareil, si nécessaire. Le format de ces données dépend de la valeur des paramètres dwControl et dwEventType .

Si dwControl est SERVICE_CONTROL_DEVICEEVENT, ces données correspondent au paramètre lParam que les applications reçoivent dans le cadre d’un message WM_DEVICECHANGE .

Si dwControl est SERVICE_CONTROL_POWEREVENT et que dwEventType est PBT_POWERSETTINGCHANGE, ces données sont un pointeur vers une structure POWERBROADCAST_SETTING .

Si dwControl est SERVICE_CONTROL_SESSIONCHANGE, ce paramètre est un pointeur vers une structure WTSSESSION_NOTIFICATION .

Si dwControl est SERVICE_CONTROL_TIMECHANGE, ces données sont un pointeur vers une structure SERVICE_TIMECHANGE_INFO .

[in] lpContext

Données définies par l’utilisateur transmises à partir de RegisterServiceCtrlHandlerEx. Lorsque plusieurs services partagent un processus, le paramètre lpContext peut aider à identifier le service.

Valeur retournée

La valeur de retour de cette fonction dépend du code de contrôle reçu.

La liste suivante identifie les règles pour cette valeur de retour :

En général, si votre service ne gère pas le contrôle, retournez ERROR_CALL_NOT_IMPLEMENTED. Toutefois, votre service doit retourner NO_ERROR pour SERVICE_CONTROL_INTERROGATE même si votre service ne le gère pas.
Si votre service gère SERVICE_CONTROL_STOP ou SERVICE_CONTROL_SHUTDOWN, retournez NO_ERROR.
Si votre service gère SERVICE_CONTROL_DEVICEEVENT, retournez NO_ERROR pour accorder la demande et un code d’erreur pour refuser la demande.
Si votre service gère SERVICE_CONTROL_HARDWAREPROFILECHANGE, retournez NO_ERROR pour accorder la demande et un code d’erreur pour refuser la demande.
Si votre service gère SERVICE_CONTROL_POWEREVENT, retournez NO_ERROR pour accorder la demande et un code d’erreur pour refuser la demande.
Pour tous les autres codes de contrôle gérés par votre service, retournez NO_ERROR.

Remarques

Lorsqu’un service est démarré, sa fonction ServiceMain doit immédiatement appeler la fonction RegisterServiceCtrlHandlerEx pour spécifier une fonction HandlerEx pour traiter les demandes de contrôle. Pour spécifier les codes de contrôle à accepter, utilisez les fonctions SetServiceStatus et RegisterDeviceNotification .

Le répartiteur de contrôle dans le thread main d’un service appelle la fonction de gestionnaire de contrôles 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 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ôles 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 ont été arrêtés avant d’arrêter le service.) En particulier, un gestionnaire de contrôles doit éviter les opérations qui peuvent être bloquées, telles que la prise d’un verrou, car cela peut entraîner un blocage ou entraîner l’arrêt de 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ôles doit revenir le plus rapidement possible ; s’il ne retourne pas dans les 30 secondes, le SCM retourne une erreur. Si un service doit effectuer un traitement long lorsque le service exécute le gestionnaire de contrôles, il doit créer un thread secondaire pour effectuer le traitement long, puis revenir à 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 le temps d’arrêt du service est limité (environ 20 secondes). 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 laissé à l’état d’arrêt (pas redémarré ou hors tension), le service continue de s’exécuter. Si votre service s’inscrit pour accepter SERVICE_CONTROL_SHUTDOWN, il doit gérer le code de contrôle et retourner NO_ERROR. Le renvoi d’une erreur pour ce code de contrôle et le fait de ne pas s’arrêter en temps opportun 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 messages status, 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

Veillez à gérer Plug-and-Play événements d’appareil aussi rapidement que possible ; sinon, le système risque de ne plus répondre. Si votre gestionnaire d’événements doit effectuer une opération qui peut bloquer l’exécution (par exemple, les E/S), il est préférable de démarrer un autre thread pour effectuer l’opération de manière asynchrone.

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.

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)