Fonction ControlServiceExA (winsvc.h)
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 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.
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 |
---|---|
|
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. |
[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 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 |
---|---|
|
Le handle n’a pas le droit d’accès requis. |
|
Impossible d’arrêter le service, car d’autres services en cours d’exécution en dépendent. |
|
Le handle spécifié n’a pas été obtenu à l’aide de CreateService ou d’OpenService, ou le handle n’est plus valide. |
|
Le code de contrôle demandé dans le paramètre dwControl n’est pas défini ou dwControl est SERVICE_CONTROL_STOP, mais les membres dwReason ou pszComment de la structure SERVICE_CONTROL_STATUS_REASON_PARAMS ne sont pas valides. |
|
Le code de contrôle demandé n'est pas valide ou est inacceptable pour le service. |
|
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. |
|
Le service n'a pas été démarré. |
|
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. |
|
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 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 à ControlServiceEx bloque 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, ControlServiceEx é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 dacl pour 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) |
RUNNING | (a) | (a) |
CONTINUE_PENDING | (a) | (a) |
PAUSE_PENDING | (a) | (a) |
EN SUSPENS | (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’étant pas dans un état dans lequel un contrôle peut lui être envoyé, ControlServiceEx retourne zéro et GetLastError renvoie ERROR_SERVICE_CANNOT_ACCEPT_CTRL.
- (c)
- Le service n’étant pas actif, ControlServiceEx retourne zéro et GetLastError retourne ERROR_SERVICE_NOT_ACTIVE.
Notes
L’en-tête winsvc.h définit ControlServiceEx en tant qu’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. La combinaison 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.
Configuration requise
Client minimal pris en charge | Windows Vista [applications de bureau uniquement] |
Serveur minimal pris en charge | Windows Server 2008 [applications de bureau uniquement] |
Plateforme cible | Windows |
En-tête | winsvc.h (inclure Windows.h) |
Bibliothèque | Advapi32.lib |
DLL | Advapi32.dll |
Voir aussi
SERVICE_CONTROL_STATUS_REASON_PARAMS