RegisterServiceCtrlHandlerExA, fonction (winsvc.h)
Inscrit une fonction pour gérer les demandes de contrôle de service étendues.
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 que le programme de contrôle de service 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 quand plusieurs services partagent un processus.
Valeur de retour
Si la fonction réussit, la valeur de retour est un handle d’état de service.
Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations d’erreur étendues, appelez GetLastError.
Les codes d’erreur suivants peuvent être définis par le gestionnaire de contrôle de service.
| Retourner le code | Description |
|---|---|
|
La mémoire insuffisante est disponible 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. |
|
L’entrée de service a été spécifiée de manière incorrecte 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 handle d’état du service 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 d’état de service pour que l’appelant puisse utiliser pour qu’aucun autre service ne puisse définir par inadvertance cet état 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ôle est appelée avec une demande de contrôle, le service doit appeler SetServiceStatus pour signaler l’état au gestionnaire de contrôle de service uniquement si l’état du service a changé, par exemple lorsque le service traite les contrôles d’arrêt ou d’arrêt. Si l’état du service n’a pas changé, le service ne doit pas signaler l’état au gestionnaire de contrôle de service.
Le handle d’état du service n’a pas besoin d’être fermé.
Note
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. 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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows XP [applications de bureau uniquement] |
| serveur minimum pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| plateforme cible | Windows |
| d’en-tête | winsvc.h (inclure Windows.h) |
| bibliothèque | Advapi32.lib |
| DLL | Advapi32.dll |