Fonction RegisterServiceCtrlHandlerA (winsvc.h)

Article
08/27/2023

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

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

Syntaxe

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerA(
  [in] LPCSTR             lpServiceName,
  [in] LPHANDLER_FUNCTION lpHandlerProc
);

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.

Si le type de service est SERVICE_WIN32_OWN_PROCESS, la fonction ne vérifie pas que le nom spécifié est valide, car il n’y a qu’un seul service inscrit dans le processus.

[in] lpHandlerProc

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

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 RegisterServiceCtrlHandler 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 Gestionnaire. 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 RegisterServiceCtrlHandler doit être appelée avant le premier appel SetServiceStatus, car RegisterServiceCtrlHandler retourne un status de service à utiliser pour qu’aucun autre service ne puisse définir par inadvertance ce service status. 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é.

Exemples

Pour obtenir un exemple, consultez Écriture d’une fonction ServiceMain.

Notes

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