Fonction RegisterServiceCtrlHandlerExA (winsvc.h)

Article
08/27/2023

Inscrit une fonction pour gérer les demandes de contrôle de service étendu.

Syntaxe

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerExA(
  [in]           LPCSTR                lpServiceName,
  [in]           LPHANDLER_FUNCTION_EX lpHandlerProc,
  [in, optional] LPVOID                lpContext
);

Paramètres

[in] lpServiceName

Nom du service exécuté par le thread appelant. Il s’agit du nom du service spécifié par le programme de contrôle de service dans la fonction CreateService lors de la création du service.

[in] lpHandlerProc

Pointeur vers la fonction de gestionnaire à inscrire. Pour plus d’informations, consultez HandlerEx.

[in, optional] lpContext

Toutes les données définies par l’utilisateur. Ce paramètre, qui est passé à la fonction de gestionnaire, peut aider à identifier le service lorsque plusieurs services partagent un processus.

Valeur retournée

Si la fonction réussit, la valeur de retour est un service status handle.

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

Les codes d’erreur suivants peuvent être définis par le gestionnaire de contrôle de service.

Code de retour	Description
ERROR_NOT_ENOUGH_MEMORY	La mémoire disponible est insuffisante pour convertir un paramètre de chaîne ANSI en Unicode. Cette erreur ne se produit pas pour les paramètres de chaîne Unicode.
ERROR_SERVICE_NOT_IN_EXE	L’entrée de service a été spécifiée incorrectement lorsque le processus a appelé la fonction StartServiceCtrlDispatcher .

Remarques

La fonction ServiceMain d’un nouveau service doit appeler immédiatement la fonction RegisterServiceCtrlHandlerEx pour inscrire une fonction de gestionnaire de contrôles auprès du répartiteur de contrôle. Cela permet au répartiteur de contrôle d’appeler la fonction spécifiée lorsqu’il reçoit des demandes de contrôle pour ce service. Pour obtenir la liste des codes de contrôle possibles, consultez HandlerEx. Les threads du processus d’appel peuvent utiliser le service status handle retourné par cette fonction pour identifier le service dans les appels suivants à la fonction SetServiceStatus.

La fonction RegisterServiceCtrlHandlerEx doit être appelée avant le premier appel SetServiceStatus, car RegisterServiceCtrlHandlerEx renvoie un handle de service status que l’appelant doit utiliser afin qu’aucun autre service ne puisse définir par inadvertance ce status de service. En outre, le gestionnaire de contrôles doit être en place pour recevoir les demandes de contrôle au moment où le service spécifie les contrôles qu’il accepte via la fonction SetServiceStatus .

Lorsque la fonction de gestionnaire de contrôles est appelée avec une demande de contrôle, le service doit appeler SetServiceStatus pour signaler status au gestionnaire de contrôle de service uniquement si le status de service a changé, par exemple lorsque le service traite les contrôles d’arrêt ou d’arrêt. Si le status de service n’a pas changé, le service ne doit pas signaler status au gestionnaire de contrôle de service.

Le handle status service n’a pas besoin d’être fermé.

Notes

L’en-tête winsvc.h définit RegisterServiceCtrlHandlerEx comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

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)
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll