Partager via


Fonction ControlService (winsvc.h)

Envoie un code de contrôle à un service.

Pour spécifier des informations supplémentaires lors de l’arrêt d’un service, utilisez la fonction ControlServiceEx .

Syntaxe

BOOL ControlService(
  [in]  SC_HANDLE        hService,
  [in]  DWORD            dwControl,
  [out] LPSERVICE_STATUS lpServiceStatus
);

Paramètres

[in] hService

Handle du 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 en pause qu’il doit reprendre. Le handle hService doit avoir le droit d’accès SERVICE_PAUSE_CONTINUE .
SERVICE_CONTROL_INTERROGATE
0x00000004
Avertit un service qu’il doit signaler ses informations de status actuelles au gestionnaire de contrôle de service. Le handle hService doit avoir le 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 avoir le droit d’accès SERVICE_PAUSE_CONTINUE . Toutefois, ce code de contrôle a été déprécié ; utilisez Plug-and-Play fonctionnalité à la place.
SERVICE_CONTROL_NETBINDDISABLE
0x0000000A
Avertit un service réseau qu’une de ses liaisons a été désactivée. Le handle hService doit avoir le droit d’accès SERVICE_PAUSE_CONTINUE . Toutefois, ce code de contrôle a été déprécié ; utilisez Plug-and-Play fonctionnalité à la place.
SERVICE_CONTROL_NETBINDENABLE
0x00000009
Avertit un service réseau qu’une liaison désactivée a été activée. Le handle hService doit avoir le droit d’accès SERVICE_PAUSE_CONTINUE . Toutefois, ce code de contrôle a été déprécié ; utilisez Plug-and-Play fonctionnalité à la place.
SERVICE_CONTROL_NETBINDREMOVE
0x00000008
Avertit un service réseau qu’un composant de liaison a été supprimé. Le handle hService doit avoir le droit d’accès SERVICE_PAUSE_CONTINUE . Toutefois, ce code de contrôle a été déprécié ; utilisez Plug-and-Play fonctionnalité à la place.
SERVICE_CONTROL_PARAMCHANGE
0x00000006
Avertit un service que ses paramètres de démarrage ont changé. Le handle hService doit avoir le droit d’accès SERVICE_PAUSE_CONTINUE .
SERVICE_CONTROL_PAUSE
0x00000002
Avertit un service qu’il doit suspendre. Le handle hService doit avoir le droit d’accès SERVICE_PAUSE_CONTINUE .
SERVICE_CONTROL_STOP
0x00000001
Avertit un service qu’il doit s’arrêter. Le handle hService doit avoir le 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.

 

Cette valeur 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 128 à 255
Le service définit l’action associée au code de contrôle. Le handle hService doit avoir le droit d’accès SERVICE_USER_DEFINED_CONTROL .

[out] lpServiceStatus

Pointeur vers une structure de SERVICE_STATUS qui reçoit les dernières informations status de service. Les informations retournées reflètent les status les plus récents que le service a signalés au gestionnaire de contrôle de service.

Le gestionnaire de contrôle de service remplit la structure uniquement lorsque GetLastError retourne l’un des codes d’erreur suivants : NO_ERROR, ERROR_INVALID_SERVICE_CONTROL, ERROR_SERVICE_CANNOT_ACCEPT_CTRL ou ERROR_SERVICE_NOT_ACTIVE. Sinon, la structure n’est pas renseignée.

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_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 en dépendent.
ERROR_INVALID_HANDLE
Le handle spécifié n’a pas été obtenu à l’aide de CreateService ou d’OpenService, ou le handle n’est plus valide.
ERROR_INVALID_PARAMETER
Le code de contrôle demandé n’est pas défini.
ERROR_INVALID_SERVICE_CONTROL
Le code de contrôle demandé n'est pas valide ou 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 du 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 ControlService 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 lui être envoyé.

Le SCM traite les notifications de contrôle de service en série : il attend qu’un service termine le traitement d’une notification de contrôle de service avant d’en envoyer la suivante. Pour cette raison, un appel à ControlService est bloqué pendant 30 secondes si un service est occupé à gérer un code de contrôle. Si le service occupé n’est toujours pas retourné par sa fonction de gestionnaire à l’expiration du délai d’expiration, ControlService échoue avec ERROR_SERVICE_REQUEST_TIMEOUT.

Pour arrêter et démarrer un service, un descripteur de sécurité vous permet de le faire. Le descripteur de sécurité par défaut permet au compte LocalSystem et aux membres des groupes Administrateurs et Utilisateurs avec pouvoir d’arrêter et de démarrer les services. Pour modifier le descripteur de sécurité d’un service, consultez Modification de la liste de contrôle d’accès d’un service.

La fonction QueryServiceStatusEx retourne une structure SERVICE_STATUS_PROCESS dont les membres dwCurrentState et 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 ses status. 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
STOPPED (c) (c)
STOP_PENDING (b) (b)
START_PENDING (a) (b)
EXÉCUTION (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, ControlService retourne zéro et GetLastError retourne ERROR_INVALID_SERVICE_CONTROL.
(b)
Le service n’étant pas dans un état dans lequel un contrôle peut lui être envoyé, ControlService retourne zéro et GetLastError retourne ERROR_SERVICE_CANNOT_ACCEPT_CTRL.
(c)
Le service n’étant pas actif, ControlService retourne zéro et GetLastError retourne ERROR_SERVICE_NOT_ACTIVE.

Exemples

Pour obtenir un exemple, consultez Arrêt d’un service.

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

Voir aussi

ControlServiceEx

CreateService

OpenService

QueryServiceStatusEx

SERVICE_STATUS

Demandes de contrôle de service

Fonctions de service

SetServiceObjectSecurity

SetServiceStatus