SetServiceStatus, fonction (winsvc.h)

Article
03/13/2024

Mises à jour les informations de status du gestionnaire de contrôle de service pour le service appelant.

Syntaxe

BOOL SetServiceStatus(
  [in] SERVICE_STATUS_HANDLE hServiceStatus,
  [in] LPSERVICE_STATUS      lpServiceStatus
);

Paramètres

[in] hServiceStatus

Handle de la structure d’informations status pour le service actuel. Ce handle est retourné par la fonction RegisterServiceCtrlHandlerEx .

[in] lpServiceStatus

Pointeur vers la structure SERVICE_STATUS contient les dernières informations status pour le service appelant.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

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. D’autres codes d’erreur peuvent être définis par les fonctions de Registre appelées par le gestionnaire de contrôle de service.

Code de retour	Description
ERROR_INVALID_DATA	La structure de status de service spécifiée n’est pas valide.
ERROR_INVALID_HANDLE	Le handle spécifié n’est pas valide.

Remarques

Une fonction ServiceMain appelle d’abord la fonction RegisterServiceCtrlHandlerEx pour obtenir les SERVICE_STATUS_HANDLE du service. Ensuite, il appelle immédiatement la fonction SetServiceStatus pour informer le gestionnaire de contrôle de service que son status est SERVICE_START_PENDING. Pendant l’initialisation, le service peut fournir des status mis à jour pour indiquer qu’il progresse, mais qu’il a besoin de plus de temps. Un bogue courant est que le service a la main thread d’effectuer l’initialisation tandis qu’un thread distinct continue d’appeler SetServiceStatus pour empêcher le gestionnaire de contrôle de service de marquer comme étant bloqué. Toutefois, si le thread main se bloque, le démarrage du service se termine dans une boucle infinie, car le thread de travail continue de signaler que le thread main progresse.

Après avoir traité une demande de contrôle, la fonction Handler du service doit appeler SetServiceStatus si le service status change pour signaler ses nouvelles status au gestionnaire de contrôle de service. Il est nécessaire de le faire uniquement lorsque le service change d’état, par exemple lorsqu’il traite les contrôles d’arrêt ou d’arrêt. Un service peut également utiliser cette fonction à tout moment à partir de n’importe quel thread du service pour informer le gestionnaire de contrôle de service des modifications d’état, par exemple quand le service doit s’arrêter en raison d’une erreur récupérable.

Un service peut appeler cette fonction uniquement après avoir appelé RegisterServiceCtrlHandlerEx pour obtenir un status de service.

Si un service appelle SetServiceStatus avec le membre dwCurrentState défini sur SERVICE_STOPPED et le membre dwWin32ExitCode défini sur une valeur différente de zéro, l’entrée suivante est écrite dans le journal des événements système :

   Event ID    = 7023
   Source      = Service Control Manager
   Type        = Error
   Description = <ServiceName> terminated with the following error:
                 <ExitCode>.

Voici les meilleures pratiques lors de l’appel de cette fonction :

Initialisez tous les champs de la structure SERVICE_STATUS, en vous assurant qu’il existe des valeurs d’indicateur de case activée et d’attente valides pour les états en attente. Utilisez des indicateurs d’attente raisonnables.
Ne vous inscrivez pas pour accepter les contrôles pendant que le status est SERVICE_START_PENDING ou que le service peut se bloquer. Une fois l’initialisation terminée, acceptez le code SERVICE_CONTROL_STOP.
Appelez cette fonction avec des valeurs de point de contrôle et d’indicateur d’attente uniquement si le service progresse sur les tâches liées à l’opération de démarrage, d’arrêt, de pause ou de poursuite en attente. Sinon, SCM ne peut pas détecter si votre service est suspendu.
Entrez l’état arrêté avec un code de sortie approprié en cas d’échec de ServiceMain .
Si le status est SERVICE_STOPPED, effectuez tous les nettoyages nécessaires et appelez SetServiceStatus une seule fois. Cette fonction effectue un appel LRPC au SCM. Le premier appel à la fonction dans l’état SERVICE_STOPPED ferme le handle de contexte RPC et tous les appels suivants peuvent provoquer le blocage du processus.
N’essayez pas d’effectuer un travail supplémentaire après avoir appelé SetServiceStatus avec SERVICE_STOPPED, car le processus de service peut être arrêté à tout moment.

Exemples

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

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