LPHANDLER_FUNCTION funzione di callback (winsvc.h)

Articolo
03/08/2023

Funzione callback definita dall'applicazione usata con la funzione RegisterServiceCtrlHandler . Un programma di servizio può usarlo come funzione del gestore del controllo di un servizio specifico.

Il tipo LPHANDLER_FUNCTION definisce un puntatore a questa funzione. Il gestore è un segnaposto per il nome definito dall'applicazione.

Questa funzione è stata sostituita dalla funzione gestore del controllo HandlerEx usata con la funzione RegisterServiceCtrlHandlerEx . Un servizio può usare entrambi i gestori di controllo, ma il nuovo gestore di controllo supporta i dati di contesto definiti dall'utente e altri codici di controllo estesi.

Sintassi

LPHANDLER_FUNCTION LphandlerFunction;

void LphandlerFunction(
  DWORD dwControl
)
{...}

Parametri

dwControl

Valore restituito

nessuno

Osservazioni

Quando viene avviato un servizio, la funzione ServiceMain deve chiamare immediatamente la funzione RegisterServiceCtrlHandler per specificare una funzione gestore per elaborare le richieste di controllo.

Il dispatcher di controllo nel thread principale di un processo di servizio richiama la funzione del gestore del controllo per il servizio specificato ogni volta che riceve una richiesta di controllo dal gestore del controllo del servizio. Dopo l'elaborazione della richiesta di controllo, il gestore del controllo deve chiamare la funzione SetServiceStatus se lo stato del servizio cambia per segnalare il nuovo stato al gestore del controllo del servizio.

La funzione del gestore del controllo è destinata a ricevere la notifica e restituire immediatamente. La funzione di callback deve salvare i parametri e creare altri thread per eseguire operazioni aggiuntive. L'applicazione deve assicurarsi che tali thread siano usciti prima di arrestare il servizio. In particolare, un gestore di controllo deve evitare operazioni che potrebbero bloccare, ad esempio l'esecuzione di un blocco, perché ciò potrebbe causare un deadlock o causare l'arresto della risposta del sistema.

Quando il gestore del controllo del servizio invia un codice di controllo a un servizio, attende che la funzione del gestore venga restituita prima di inviare codici di controllo aggiuntivi ad altri servizi. Il gestore del controllo deve restituire il più rapidamente possibile; se non restituisce entro 30 secondi, SCM restituisce un errore. Se un servizio deve eseguire un'elaborazione lunga quando il servizio esegue il gestore del controllo, deve creare un thread secondario per eseguire l'elaborazione lunga e quindi restituire dal gestore del controllo. Ciò impedisce al servizio di legare il dispatcher del controllo e impedire ad altri servizi di ricevere codici di controllo.

Il codice di controllo SERVICE_CONTROL_SHUTDOWN deve essere elaborato solo dai servizi che devono assolutamente pulire durante l'arresto, perché è disponibile un tempo limitato (circa 20 secondi) per l'arresto del servizio. Dopo questa scadenza, l'arresto del sistema procede indipendentemente dal fatto che l'arresto del servizio sia stato completato. Si noti che se il sistema viene lasciato nello stato di arresto (non riavviato o disattivato), il servizio continua a essere eseguito. Se il servizio esegue la registrazione per accettare SERVICE_CONTROL_SHUTDOWN, deve gestire il codice di controllo e arrestarlo in modo tempestivo. In caso contrario, il servizio può aumentare il tempo necessario per arrestare il sistema, perché il sistema deve attendere il tempo completo consentito per l'arresto del servizio prima che l'arresto del sistema possa procedere.

Se il servizio richiede più tempo per pulire, deve inviare STOP_PENDING messaggi di stato, insieme a un hint di attesa, in modo che il controller del servizio sappia quanto tempo attendere prima di segnalare al sistema che l'arresto del servizio è stato completato. Tuttavia, per impedire a un servizio di arrestare l'arresto, esiste un limite per quanto tempo il controller di servizio attenderà. Se il servizio viene arrestato tramite lo snap-in Servizi, il limite è di 125 secondi. Se il sistema operativo viene riavviato, il limite di tempo viene specificato nel valore WaitToKillServiceTimeout della chiave del Registro di sistema seguente:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control

I servizi possono anche usare la funzione SetConsoleCtrlHandler per ricevere la notifica di arresto. Questa notifica viene ricevuta quando le applicazioni in esecuzione vengono arrestate, che si verificano prima dell'arresto dei servizi.

Esempio

Per un esempio, vedere Scrittura di una funzione gestore di controllo.

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)