Fonction ControlServiceExA (winsvc.h)

Article
11/20/2024

Envoie un code de contrôle à un service.

Syntaxe

BOOL ControlServiceExA(
  [in]      SC_HANDLE hService,
  [in]      DWORD     dwControl,
  [in]      DWORD     dwInfoLevel,
  [in, out] PVOID     pControlParams
);

Paramètres

[in] hService

Handle vers le service. Ce handle est retourné par la fonction OpenService ou CreateService. Les droits d’accès requis pour ce handle dépendent du code dwControl demandé.

[in] dwControl

Ce paramètre peut être l’un des codes de contrôle suivants.

Code de contrôle	Signification
SERVICE_CONTROL_CONTINUE 0x00000003	Avertit un service suspendu qu’il doit reprendre. Le handle hService doit disposer du droit d’accès SERVICE_PAUSE_CONTINUE.
SERVICE_CONTROL_INTERROGATE 0x00000004	Avertit un service qu’il doit signaler ses informations d’état actuelles au gestionnaire de contrôle de service. Le handle hService doit disposer du droit d’accès SERVICE_INTERROGATE. Notez que ce contrôle n’est généralement pas utile, car le SCM est conscient de l’état actuel du service.
SERVICE_CONTROL_NETBINDADD 0x00000007	Avertit un service réseau qu’il existe un nouveau composant pour la liaison. Le handle hService doit disposer du droit d’accès SERVICE_PAUSE_CONTINUE. Toutefois, ce code de contrôle a été déprécié ; utilisez plutôt la fonctionnalité Plug-and-Play.
SERVICE_CONTROL_NETBINDDISABLE 0x0000000A	Avertit un service réseau que l’une de ses liaisons a été désactivée. Le handle hService doit disposer du droit d’accès SERVICE_PAUSE_CONTINUE. Toutefois, ce code de contrôle a été déprécié ; utilisez plutôt la fonctionnalité Plug-and-Play.
SERVICE_CONTROL_NETBINDENABLE 0x00000009	Avertit un service réseau qu’une liaison désactivée a été activée. Le handle hService doit disposer du droit d’accès SERVICE_PAUSE_CONTINUE. Toutefois, ce code de contrôle a été déprécié ; utilisez plutôt la fonctionnalité Plug-and-Play.
SERVICE_CONTROL_NETBINDREMOVE 0x00000008	Avertit un service réseau qu’un composant pour la liaison a été supprimé. Le handle hService doit disposer du droit d’accès SERVICE_PAUSE_CONTINUE. Toutefois, ce code de contrôle a été déprécié ; utilisez plutôt la fonctionnalité Plug-and-Play.
SERVICE_CONTROL_PARAMCHANGE 0x00000006	Avertit un service que ses paramètres de démarrage ont changé. Le handle hService doit disposer du droit d’accès SERVICE_PAUSE_CONTINUE.
SERVICE_CONTROL_PAUSE 0x00000002	Avertit un service qu’il doit suspendre. Le handle hService doit disposer du droit d’accès SERVICE_PAUSE_CONTINUE.
SERVICE_CONTROL_STOP 0x00000001	Avertit un service qu’il doit s’arrêter. Le handle hService doit disposer du droit d’accès SERVICE_STOP. Après avoir envoyé la demande d’arrêt à un service, vous ne devez pas envoyer d’autres contrôles au service.

Ce paramètre peut également être un code de contrôle défini par l’utilisateur, comme décrit dans le tableau suivant.

Code de contrôle	Signification
Plage de 128 à 255	Le service définit l’action associée au code de contrôle. Le handle hService doit disposer du droit d’accès SERVICE_USER_DEFINED_CONTROL.

[in] dwInfoLevel

Niveau d’informations pour les paramètres de contrôle de service. Ce paramètre doit être défini sur SERVICE_CONTROL_STATUS_REASON_INFO (1).

[in, out] pControlParams

Pointeur vers les paramètres de contrôle de service. Si dwInfoLevel est SERVICE_CONTROL_STATUS_REASON_INFO, ce membre est un pointeur vers une structure SERVICE_CONTROL_STATUS_REASON_PARAMS.

Valeur de retour

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’erreur étendues, 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.

Retourner le code	Description
ERROR_ACCESS_DENIED	Le handle n’a pas le droit d’accès requis.
ERROR_DEPENDENT_SERVICES_RUNNING	Impossible d’arrêter le service, car d’autres services en cours d’exécution dépendent de celui-ci.
ERROR_INVALID_HANDLE	Le handle spécifié n’a pas été obtenu à l’aide de createService ou OpenService, ou le handle n’est plus valide.
ERROR_INVALID_PARAMETER	Le code de contrôle demandé dans le paramètre dwControl n’est pas défini, ou dwControl est SERVICE_CONTROL_STOP, mais les dwReason ou pszComment membres de la structure SERVICE_CONTROL_STATUS_REASON_PARAMS ne sont pas valides.
ERROR_INVALID_SERVICE_CONTROL	Le code de contrôle demandé n’est pas valide ou il est inacceptable pour le service.
ERROR_SERVICE_CANNOT_ACCEPT_CTRL	Le code de contrôle demandé ne peut pas être envoyé au service, car l’état du service est SERVICE_STOPPED, SERVICE_START_PENDING ou SERVICE_STOP_PENDING.
ERROR_SERVICE_NOT_ACTIVE	Le service n’a pas été démarré.
ERROR_SERVICE_REQUEST_TIMEOUT	Le processus pour le service a été démarré, mais il n’a pas appelé StartServiceCtrlDispatcher, ou le thread qui a appelé StartServiceCtrlDispatcher peut être bloqué dans une fonction de gestionnaire de contrôles.
ERROR_SHUTDOWN_IN_PROGRESS	Le système s’arrête.

Remarques

La fonction ControlServiceEx demande au gestionnaire de contrôle de service (SCM) d’envoyer le code de contrôle demandé au service. Le SCM envoie le code si le service a spécifié qu’il acceptera le code et se trouve dans un état dans lequel un code de contrôle peut être envoyé à celui-ci.

Le SCM traite les notifications de contrôle de service de manière série : il attend qu’un service termine le traitement d’une notification de contrôle de service avant d’envoyer le suivant. En raison de cela, un appel à ControlServiceEx bloque pendant 30 secondes si un service est occupé à gérer un code de contrôle. Si le service occupé n’a toujours pas retourné à partir de sa fonction de gestionnaire lorsque le délai d’expiration expire, ControlServiceEx échoue avec ERROR_SERVICE_REQUEST_TIMEOUT.

Pour arrêter et démarrer un service, vous devez disposer d’un descripteur de sécurité qui vous permet de le faire. Le descripteur de sécurité par défaut permet au compte LocalSystemet aux membres des groupes Administrateurs et Utilisateurs Power d’arrêter et de démarrer des services. Pour modifier le descripteur de sécurité d’un service, consultez Modification de la liste dacl pour un service.

La fonction QueryServiceStatusEx retourne une structure SERVICE_STATUS_PROCESS dont dwCurrentState et membres dwControlsAccepted indiquent l’état actuel et les contrôles acceptés par un service en cours d’exécution. Tous les services en cours d’exécution acceptent le code de contrôle SERVICE_CONTROL_INTERROGATE par défaut. Les pilotes n’acceptent pas les codes de contrôle autres que SERVICE_CONTROL_STOP et SERVICE_CONTROL_INTERROGATE. Chaque service spécifie les autres codes de contrôle qu’il accepte lorsqu’il appelle la fonction SetServiceStatus pour signaler son état. Un service doit toujours accepter ces codes lorsqu’il est en cours d’exécution, peu importe ce qu’il fait.

Le tableau suivant montre l’action du SCM dans chacun des états de service possibles.

État du service	Arrêter	Autres contrôles
ARRÊTÉ	(c)	(c)
STOP_PENDING	(b)	(b)
START_PENDING	(a)	(b)
COURSE	(a)	(a)
CONTINUE_PENDING	(a)	(a)
PAUSE_PENDING	(a)	(a)
PAUSE	(a)	(a)

(a): Si le service accepte ce code de contrôle, envoyez la demande au service ; sinon, ControlServiceEx retourne zéro et GetLastError retourne ERROR_INVALID_SERVICE_CONTROL.
(b): Le service n’est pas dans un état dans lequel un contrôle peut être envoyé. Par conséquent, ControlServiceEx retourne zéro et GetLastError retourne ERROR_SERVICE_CANNOT_ACCEPT_CTRL.
(c): Le service n’est pas actif. Par conséquent, ControlServiceEx retourne zéro et GetLastError retourne ERROR_SERVICE_NOT_ACTIVE.

Note

L’en-tête winsvc.h définit ControlServiceEx 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 Vista [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2008 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	winsvc.h (inclure Windows.h)
bibliothèque	Advapi32.lib
DLL	Advapi32.dll