Funzione ControlService (winsvc.h)
Invia un codice di controllo a un servizio.
Per specificare informazioni aggiuntive quando si arresta un servizio, usare la funzione ControlServiceEx .
Sintassi
BOOL ControlService(
[in] SC_HANDLE hService,
[in] DWORD dwControl,
[out] LPSERVICE_STATUS lpServiceStatus
);
Parametri
[in] hService
Handle per il servizio. Questo handle viene restituito dalla funzione OpenService o CreateService . I diritti di accesso necessari per questo handle dipendono dal codice dwControl richiesto.
[in] dwControl
Questo parametro può essere uno dei codici di controllo seguenti.
Questo valore può anche essere un codice di controllo definito dall'utente, come descritto nella tabella seguente.
| Codice di controllo | Significato |
|---|---|
|
Il servizio definisce l'azione associata al codice di controllo. L'handle hService deve avere il diritto di accesso SERVICE_USER_DEFINED_CONTROL . |
[out] lpServiceStatus
Puntatore a una struttura di SERVICE_STATUS che riceve le informazioni più recenti sullo stato del servizio. Le informazioni restituite riflettono lo stato più recente segnalato dal servizio al gestore di controllo del servizio.
La gestione controllo del servizio compila la struttura solo quando GetLastError restituisce uno dei codici di errore seguenti: NO_ERROR, ERROR_INVALID_SERVICE_CONTROL, ERROR_SERVICE_CANNOT_ACCEPT_CTRL o ERROR_SERVICE_NOT_ACTIVE. In caso contrario, la struttura non viene compilata.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è diverso da zero.
Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.
I codici di errore seguenti possono essere impostati dal gestore di controllo del servizio. Altri codici di errore possono essere impostati dalle funzioni del Registro di sistema chiamate dal gestore di controllo del servizio.
| Codice restituito | Descrizione |
|---|---|
|
L'handle non ha il diritto di accesso necessario. |
|
Il servizio non può essere arrestato perché altri servizi in esecuzione dipendono da esso. |
|
L'handle specificato non è stato ottenuto tramite CreateService o OpenService oppure l'handle non è più valido. |
|
Il codice di controllo richiesto non è definito. |
|
Il codice di controllo richiesto non è valido o non è accettabile per il servizio. |
|
Impossibile inviare il codice di controllo richiesto al servizio perché lo stato del servizio è SERVICE_STOPPED, SERVICE_START_PENDING o SERVICE_STOP_PENDING. |
|
Il servizio non è stato avviato. |
|
Il processo per il servizio è stato avviato, ma non ha chiamato StartServiceCtrlDispatcher o il thread che ha chiamato StartServiceCtrlDispatcher può essere bloccato in una funzione del gestore di controlli. |
|
Il sistema viene arrestato. |
Commenti
La funzione ControlService chiede a Service Control Manager (SCM) di inviare il codice di controllo richiesto al servizio. SCM invia il codice se il servizio ha specificato che accetterà il codice ed è in uno stato in cui è possibile inviare un codice di controllo.
SCM elabora le notifiche di controllo del servizio in modo seriale: attende che un servizio completi l'elaborazione di una notifica di controllo del servizio prima di inviare quella successiva. Per questo motivo, una chiamata a ControlService verrà bloccata per 30 secondi se un servizio è occupato nella gestione di un codice di controllo. Se il servizio occupato non è ancora stato restituito dalla relativa funzione del gestore alla scadenza del timeout, ControlService ha esito negativo con ERROR_SERVICE_REQUEST_TIMEOUT.
Per arrestare e avviare un servizio è necessario un descrittore di sicurezza che consenta di eseguire questa operazione. Il descrittore di sicurezza predefinito consente all'account LocalSystem e ai membri dei gruppi Administrators e Power Users di arrestare e avviare i servizi. Per modificare il descrittore di sicurezza di un servizio, vedere Modifying the DACL for a Service .To change the security descriptor of a service, see Modifying the DACL for a Service.
La funzione QueryServiceStatusEx restituisce una struttura SERVICE_STATUS_PROCESS i cui membri dwCurrentState e dwControlsAccepted indicano lo stato corrente e i controlli accettati da un servizio in esecuzione. Tutti i servizi in esecuzione accettano il codice di controllo SERVICE_CONTROL_INTERROGATE per impostazione predefinita. I driver non accettano codici di controllo diversi da SERVICE_CONTROL_STOP e SERVICE_CONTROL_INTERROGATE. Ogni servizio specifica gli altri codici di controllo accettati quando chiama la funzione SetServiceStatus per segnalarne lo stato. Un servizio deve sempre accettare questi codici quando è in esecuzione, indipendentemente da ciò che sta facendo.
Nella tabella seguente viene illustrata l'azione di Gestione controllo servizi in ognuno dei possibili stati del servizio.
| Stato del servizio | Stop | Altri controlli |
|---|---|---|
| STOPPED | (c) | (c) |
| STOP_PENDING | (b) | (b) |
| START_PENDING | (a) | (b) |
| CORSA | (a) | (a) |
| CONTINUE_PENDING | (a) | (a) |
| PAUSE_PENDING | (a) | (a) |
| PAUSA | (a) | (a) |
- (a)
- Se il servizio accetta questo codice di controllo, inviare la richiesta al servizio; in caso contrario, ControlService restituisce zero e GetLastError restituisce ERROR_INVALID_SERVICE_CONTROL.
- (b)
- Il servizio non è in uno stato in cui è possibile inviare un controllo, pertanto ControlService restituisce zero e GetLastError restituisce ERROR_SERVICE_CANNOT_ACCEPT_CTRL.
- (c)
- Il servizio non è attivo, pertanto ControlService restituisce zero e GetLastError restituisce ERROR_SERVICE_NOT_ACTIVE.
Esempio
Per un esempio, vedere Arresto di un servizio.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows XP [solo app desktop] |
| Server minimo supportato | Windows Server 2003 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | winsvc.h (include Windows.h) |
| Libreria | AdvApi32.lib |
| DLL | AdvApi32.dll |