Funzione ControlService (winsvc.h)

Articolo
03/08/2023

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.

Codice di controllo	Significato
SERVICE_CONTROL_CONTINUE 0x00000003	Notifica a un servizio sospeso che deve riprendere. L'handle hService deve avere il diritto di accesso SERVICE_PAUSE_CONTINUE .
SERVICE_CONTROL_INTERROGATE 0x00000004	Notifica a un servizio che deve segnalare le informazioni sullo stato correnti al gestore di controllo del servizio. L'handle hService deve avere il diritto di accesso SERVICE_INTERROGATE . Si noti che questo controllo non è in genere utile perché Gestione configurazione server riconosce lo stato corrente del servizio.
SERVICE_CONTROL_NETBINDADD 0x00000007	Notifica a un servizio di rete che esiste un nuovo componente per l'associazione. L'handle hService deve avere il diritto di accesso SERVICE_PAUSE_CONTINUE . Tuttavia, questo codice di controllo è stato deprecato; usare invece Plug and Play funzionalità.
SERVICE_CONTROL_NETBINDDISABLE 0x0000000a	Notifica a un servizio di rete che una delle relative associazioni è stata disabilitata. L'handle hService deve avere il diritto di accesso SERVICE_PAUSE_CONTINUE . Tuttavia, questo codice di controllo è stato deprecato; usare invece Plug and Play funzionalità.
SERVICE_CONTROL_NETBINDENABLE 0x00000009	Notifica a un servizio di rete che è stata abilitata un'associazione disabilitata. L'handle hService deve avere il diritto di accesso SERVICE_PAUSE_CONTINUE . Tuttavia, questo codice di controllo è stato deprecato; usare invece Plug and Play funzionalità.
SERVICE_CONTROL_NETBINDREMOVE 0x00000008	Notifica a un servizio di rete che un componente per l'associazione è stato rimosso. L'handle hService deve avere il diritto di accesso SERVICE_PAUSE_CONTINUE . Tuttavia, questo codice di controllo è stato deprecato; usare invece Plug and Play funzionalità.
SERVICE_CONTROL_PARAMCHANGE 0x00000006	Notifica a un servizio che i parametri di avvio sono stati modificati. L'handle hService deve avere il diritto di accesso SERVICE_PAUSE_CONTINUE .
SERVICE_CONTROL_PAUSE 0x00000002	Notifica a un servizio che deve essere sospeso. L'handle hService deve avere il diritto di accesso SERVICE_PAUSE_CONTINUE .
SERVICE_CONTROL_STOP 0x00000001	Notifica a un servizio che deve essere arrestato. L'handle hService deve avere il diritto di accesso SERVICE_STOP . Dopo aver inviato la richiesta di arresto a un servizio, non è consigliabile inviare altri controlli al servizio.

Questo valore può anche essere un codice di controllo definito dall'utente, come descritto nella tabella seguente.

Codice di controllo	Significato
Intervallo da 128 a 255	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
ERROR_ACCESS_DENIED	L'handle non ha il diritto di accesso necessario.
ERROR_DEPENDENT_SERVICES_RUNNING	Il servizio non può essere arrestato perché altri servizi in esecuzione dipendono da esso.
ERROR_INVALID_HANDLE	L'handle specificato non è stato ottenuto tramite CreateService o OpenService oppure l'handle non è più valido.
ERROR_INVALID_PARAMETER	Il codice di controllo richiesto non è definito.
ERROR_INVALID_SERVICE_CONTROL	Il codice di controllo richiesto non è valido o non è accettabile per il servizio.
ERROR_SERVICE_CANNOT_ACCEPT_CTRL	Impossibile inviare il codice di controllo richiesto al servizio perché lo stato del servizio è SERVICE_STOPPED, SERVICE_START_PENDING o SERVICE_STOP_PENDING.
ERROR_SERVICE_NOT_ACTIVE	Il servizio non è stato avviato.
ERROR_SERVICE_REQUEST_TIMEOUT	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.
ERROR_SHUTDOWN_IN_PROGRESS	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