Funzione SetServiceStatus (winsvc.h)

Articolo
08/27/2023

Aggiornamenti le informazioni sullo stato del gestore di controllo del servizio per il servizio chiamante.

Sintassi

BOOL SetServiceStatus(
  [in] SERVICE_STATUS_HANDLE hServiceStatus,
  [in] LPSERVICE_STATUS      lpServiceStatus
);

Parametri

[in] hServiceStatus

Handle per la struttura delle informazioni sullo stato per il servizio corrente. Questo handle viene restituito dalla funzione RegisterServiceCtrlHandlerEx .

[in] lpServiceStatus

Puntatore alla struttura SERVICE_STATUS contenente le informazioni sullo stato più recenti per il servizio chiamante.

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_INVALID_DATA	La struttura di stato del servizio specificata non è valida.
ERROR_INVALID_HANDLE	L'handle specificato non è valido.

Commenti

Una funzione ServiceMain chiama innanzitutto la funzione RegisterServiceCtrlHandlerEx per ottenere il SERVICE_STATUS_HANDLE del servizio. Chiama quindi immediatamente la funzione SetServiceStatus per notificare al gestore del controllo del servizio che il relativo stato è SERVICE_START_PENDING. Durante l'inizializzazione, il servizio può fornire lo stato aggiornato per indicare che sta effettuando progressi, ma richiede più tempo. Un bug comune è che il servizio abbia il thread principale che esegue l'inizializzazione mentre un thread separato continua a chiamare SetServiceStatus per impedire al gestore del controllo del servizio di contrassegnarlo come bloccato. Tuttavia, se il thread principale si blocca, l'avvio del servizio termina in un ciclo infinito perché il thread di lavoro continua a segnalare che il thread principale sta effettuando lo stato di avanzamento.

Dopo l'elaborazione di una richiesta di controllo, la funzione Handler del servizio deve chiamare SetServiceStatus se lo stato del servizio cambia per segnalare il nuovo stato al gestore di controllo del servizio. È necessario farlo solo quando il servizio cambia stato, ad esempio quando elabora i controlli di arresto o arresto. Un servizio può anche usare questa funzione in qualsiasi momento da qualsiasi thread del servizio per notificare al gestore di controllo del servizio le modifiche dello stato, ad esempio quando il servizio deve essere arrestato a causa di un errore ripristinabile.

Un servizio può chiamare questa funzione solo dopo che ha chiamato RegisterServiceCtrlHandlerEx per ottenere un handle di stato del servizio.

Se un servizio chiama SetServiceStatus con il membro dwCurrentState impostato su SERVICE_STOPPED e il membro dwWin32ExitCode impostato su un valore diverso da zero, la voce seguente viene scritta nel registro eventi di sistema:

   Event ID    = 7023
   Source      = Service Control Manager
   Type        = Error
   Description = <ServiceName> terminated with the following error:
                 <ExitCode>.

Di seguito sono riportate le procedure consigliate quando si chiama questa funzione:

Inizializzare tutti i campi nella struttura SERVICE_STATUS , assicurandosi che siano presenti valori di punto di controllo e hint di attesa validi per gli stati in sospeso. Usare hint di attesa ragionevoli.
Non eseguire la registrazione per accettare controlli mentre lo stato è SERVICE_START_PENDING o il servizio può arrestarsi in modo anomalo. Al termine dell'inizializzazione, accettare il codice SERVICE_CONTROL_STOP.
Chiamare questa funzione con valori checkpoint e hint di attesa solo se il servizio sta effettuando progressi nelle attività correlate all'operazione di avvio, arresto, sospensione o continuazione in sospeso. In caso contrario, SCM non è in grado di rilevare se il servizio è bloccato.
Immettere lo stato arrestato con un codice di uscita appropriato se ServiceMain ha esito negativo.
Se lo stato è SERVICE_STOPPED, eseguire tutte le operazioni di pulizia necessarie e chiamare SetServiceStatus una sola volta. Questa funzione effettua una chiamata LRPC a SCM. La prima chiamata alla funzione nello stato SERVICE_STOPPED chiude l'handle del contesto RPC ed eventuali chiamate successive possono causare l'arresto anomalo del processo.
Non tentare di eseguire operazioni aggiuntive dopo aver chiamato SetServiceStatus con SERVICE_STOPPED, perché il processo del servizio può essere terminato in qualsiasi momento.

Esempio

Per un esempio, vedere Scrittura di una funzione ServiceMain.

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