RegisterServiceCtrlHandlerExW, fonction (winsvc.h)

Article
03/13/2024

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

Syntaxe

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerExW(
  [in]           LPCWSTR               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 de service que le programme de contrôle de service a spécifié 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 immédiatement appeler la fonction RegisterServiceCtrlHandlerEx pour inscrire une fonction de gestionnaire de contrôle 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 appelant 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 retourne un handle de status de service que l’appelant doit utiliser afin qu’aucun autre service ne puisse définir ce service status par inadvertance. 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ôle 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 service status a changé, par exemple lorsque le service traite les contrôles d’arrêt ou d’arrêt. Si le service status n’a pas changé, il ne doit pas signaler status au gestionnaire de contrôle de service.

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

Notes

L’en-tête winsvc.h définit RegisterServiceCtrlHandlerEx comme 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. La combinaison 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