Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
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 que le programme de contrôle de service spécifié 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 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 RegisterServiceCtrlHandler 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 gestionnaire. 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 RegisterServiceCtrlHandler doit être appelée avant le premier appel SetServiceStatus, car RegisterServiceCtrlHandler 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é.
Exemples
Pour obtenir un exemple, consultez Écriture d’une fonction ServiceMain.
Note
L’en-tête winsvc.h définit RegisterServiceCtrlHandler 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 |