Funzione ControlServiceExA (winsvc.h)

Articolo
08/27/2023

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 al 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 del controllo del servizio. L'handle hService deve avere il diritto di accesso SERVICE_INTERROGATE. Si noti che questo controllo non è in genere utile perché SCM è a conoscenza dello 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 la funzionalità Plug and Play.
SERVICE_CONTROL_NETBINDDISABLE 0x0000000a	Notifica a un servizio di rete che uno dei relativi binding è stato disabilitato. 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 è stato rimosso un 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_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 sospendere. L'handle hService deve avere il diritto di accesso SERVICE_PAUSE_CONTINUE.
SERVICE_CONTROL_STOP 0x00000001	Notifica a un servizio che deve arrestarsi. L'handle hService deve avere il diritto di accesso SERVICE_STOP. Dopo aver inviato la richiesta di arresto a un servizio, non è necessario 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 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 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 dispone del diritto di accesso richiesto.
ERROR_DEPENDENT_SERVICES_RUNNING	Impossibile arrestare il servizio perché altri servizi in esecuzione dipendono da esso.
ERROR_INVALID_HANDLE	L'handle specificato non è stato ottenuto usando CreateService o OpenService oppure l'handle non è più valido.
ERROR_INVALID_PARAMETER	Il codice di controllo richiesto nel parametro dwControl non è definito o dwControl è SERVICE_CONTROL_STOP ma i membri dwReason o pszComment della struttura di 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 StartServiceCtrlDispatcher o il thread denominato StartServiceCtrlDispatcher può essere bloccato in una funzione del gestore di controllo.
ERROR_SHUTDOWN_IN_PROGRESS	Il sistema sta arrestando.

Commenti

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.

SCM elabora le notifiche di controllo del servizio in modo seriale: attende che un servizio completi l'elaborazione di una notifica del controllo del servizio prima di inviare quello successivo. A causa di questo, 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 richiede un descrittore di sicurezza che consente 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 Modifica dell'elenco dati per un servizio.

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 SCM in ognuno dei possibili stati del servizio.

Stato del servizio	Stop	Altri controlli
STOPPED	(c)	(c)
STOP_PENDING	(b)	(b)
START_PENDING	(a)	(b)
RUNNING	(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, quindi 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 di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti


Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winsvc.h (include Windows.h)
Libreria	Advapi32.lib
DLL	Advapi32.dll