Funzione ControlServiceExA (winsvc.h)

Articolo
11/20/2024

Invia un codice di controllo a un servizio.

Sintassi

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

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 controllo servizi è a conoscenza dello stato corrente del servizio.
SERVICE_CONTROL_NETBINDADD 0x00000007	Notifica a un servizio di rete che è presente 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 la funzionalità Plug and Play.
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 la funzionalità Plug and Play.
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 la funzionalità Plug and Play.
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 la funzionalità Plug and Play.
SERVICE_CONTROL_PARAMCHANGE 0x00000006	Notifica a un servizio che i relativi 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 parametro 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.

[in] dwInfoLevel

Livello di informazioni per i parametri del controllo del servizio. Questo parametro deve essere impostato su SERVICE_CONTROL_STATUS_REASON_INFO (1).

[in, out] pControlParams

Puntatore ai parametri del controllo del servizio. Se dwInfoLevel è SERVICE_CONTROL_STATUS_REASON_INFO, questo membro è un puntatore a una struttura di SERVICE_CONTROL_STATUS_REASON_PARAMS.

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 ottenere informazioni estese 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 usando CreateService o OpenServiceoppure l'handle non è più valido.
ERROR_INVALID_PARAMETER	Il codice di controllo richiesto nel parametro dwControl non è definito oppure dwControl è SERVICE_CONTROL_STOP, ma il dwReason o pszComment membri della struttura SERVICE_CONTROL_STATUS_REASON_PARAMS non sono validi.
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 StartServiceCtrlDispatchero il thread che ha chiamato StartServiceCtrlDispatcher potrebbe essere bloccato in una funzione del gestore di controllo.
ERROR_SHUTDOWN_IN_PROGRESS	Il sistema viene arrestato.

Osservazioni

La funzione ControlServiceEx 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.

Gestione controllo servizi 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 quello successivo. Per questo motivo, una chiamata a ControlServiceEx blocca per 30 secondi se un servizio è occupato a gestire un codice di controllo. Se il servizio occupato non è ancora stato restituito dalla funzione del gestore quando scade il timeout, ControlServiceEx ha esito negativo con ERROR_SERVICE_REQUEST_TIMEOUT.

Per arrestare e avviare un servizio, è necessario un descrittore di sicurezza che consenta di farlo. Il descrittore di sicurezza predefinito consente al account LocalSysteme ai membri dei gruppi Administrators e Power Users di arrestare e avviare i servizi. Per modificare il descrittore di sicurezza di un servizio, vedere Modifica dell'elenco DI controllo di accesso per un servizio.

La funzione QueryServiceStatusEx restituisce una struttura SERVICE_STATUS_PROCESS la cui dwCurrentState e membri 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	Fermarsi	Altri controlli
FERMATA	(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, ControlServiceEx restituisce zero e getLastError restituisce ERROR_INVALID_SERVICE_CONTROL.
(b): Il servizio non è in uno stato in cui è possibile inviare un controllo, pertanto ControlServiceEx restituisce zero e GetLastError restituisce ERROR_SERVICE_CANNOT_ACCEPT_CTRL.
(c): Il servizio non è attivo, quindi ControlServiceEx restituisce zero e GetLastError restituisce ERROR_SERVICE_NOT_ACTIVE.

Nota

L'intestazione winsvc.h definisce ControlServiceEx come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows Vista [solo app desktop]
server minimo supportato	Windows Server 2008 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	winsvc.h (include Windows.h)
libreria	Advapi32.lib
dll	Advapi32.dll