LPHANDLER_FUNCTION_EX funzione di callback (winsvc.h)

Articolo
03/08/2023

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

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

Questa funzione sostituisce la funzione gestore del controllo Handler usata con la funzione RegisterServiceCtrlHandler . Un servizio può usare entrambi i gestori di controllo, ma il nuovo gestore di controllo supporta i dati di contesto definiti dall'utente e codici di controllo estesi aggiuntivi.

Sintassi

LPHANDLER_FUNCTION_EX LphandlerFunctionEx;

DWORD LphandlerFunctionEx(
  [in] DWORD dwControl,
  [in] DWORD dwEventType,
  [in] LPVOID lpEventData,
  [in] LPVOID lpContext
)
{...}

Parametri

[in] dwControl

Codice del controllo. Questo parametro può avere uno dei valori seguenti.

Codice di controllo	Significato
SERVICE_CONTROL_CONTINUE 0x00000003	Notifica a un servizio sospeso che deve riprendere.
SERVICE_CONTROL_INTERROGATE 0x00000004	Notifica a un servizio di segnalare le informazioni sullo stato correnti al gestore di controllo del servizio. Il gestore deve semplicemente restituire NO_ERROR; 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. Il servizio deve essere associato al nuovo componente. Le applicazioni devono usare invece Plug and Play funzionalità.
SERVICE_CONTROL_NETBINDDISABLE 0x0000000a	Notifica a un servizio di rete che una delle relative associazioni è stata disabilitata. Il servizio deve rileggere le informazioni di associazione e rimuovere l'associazione. Le applicazioni devono usare invece Plug and Play funzionalità.
SERVICE_CONTROL_NETBINDENABLE 0x00000009	Notifica a un servizio di rete che è stata abilitata un'associazione disabilitata. Il servizio deve rileggere le informazioni di associazione e aggiungere la nuova associazione. Le applicazioni devono usare invece Plug and Play funzionalità.
SERVICE_CONTROL_NETBINDREMOVE 0x00000008	Notifica a un servizio di rete che un componente per l'associazione è stato rimosso. Il servizio deve rileggere le informazioni di associazione e annullare l'associazione dal componente rimosso. Le applicazioni devono usare invece Plug and Play funzionalità.
SERVICE_CONTROL_PARAMCHANGE 0x00000006	Notifica a un servizio che i parametri di avvio specifici del servizio sono stati modificati. Il servizio deve rileggere i parametri di avvio.
SERVICE_CONTROL_PAUSE 0x00000002	Notifica a un servizio che deve essere sospeso.
SERVICE_CONTROL_PRESHUTDOWN 0x0000000F	Notifica a un servizio che il sistema verrà arrestato. I servizi che richiedono tempo aggiuntivo per eseguire attività di pulizia oltre la restrizione temporale stretta all'arresto del sistema possono usare questa notifica. Il gestore di controllo del servizio invia questa notifica alle applicazioni registrate prima di inviare una notifica di SERVICE_CONTROL_SHUTDOWN alle applicazioni registrate per tale notifica. Un servizio che gestisce questa notifica blocca l'arresto del sistema fino all'arresto del servizio o all'intervallo di timeout preshutdown specificato tramite SERVICE_PRESHUTDOWN_INFO scade. Poiché ciò influisce sull'esperienza utente, i servizi devono usare questa funzionalità solo se è assolutamente necessario per evitare perdite di dati o tempi di ripristino significativi all'avvio successivo del sistema. Windows Server 2003 e Windows XP: Questo valore non è supportato.
SERVICE_CONTROL_SHUTDOWN 0x00000005	Notifica a un servizio che il sistema sta arrestando in modo che il servizio possa eseguire attività di pulizia. Si noti che i servizi che si registrano per le notifiche di SERVICE_CONTROL_PRESHUTDOWN non possono ricevere questa notifica perché sono già stati arrestati. Se un servizio accetta questo codice di controllo, deve essere arrestato dopo l'esecuzione delle attività di pulizia e restituire NO_ERROR. Dopo che SCM invia questo codice di controllo, non invierà altri codici di controllo al servizio. Per altre informazioni, vedere la sezione Osservazioni di questo argomento.
SERVICE_CONTROL_STOP 0x00000001	Notifica a un servizio che deve essere arrestato. Se un servizio accetta questo codice di controllo, deve arrestarsi alla ricezione e restituire NO_ERROR. Dopo che SCM invia questo codice di controllo, non invierà altri codici di controllo al servizio. Windows XP: Se il servizio restituisce NO_ERROR e continua a essere eseguito, continua a ricevere i codici di controllo. Questo comportamento è cambiato a partire da Windows Server 2003 e Windows XP con SP2.

Questo parametro può anche essere uno dei codici di controllo estesi seguenti. Si noti che questi codici di controllo non sono supportati dalla funzione Handler .

Codice di controllo	Significato
SERVICE_CONTROL_DEVICEEVENT 0x0000000B	Notifica a un servizio di eventi del dispositivo. Il servizio deve essere registrato per ricevere queste notifiche usando la funzione RegisterDeviceNotification . I parametri dwEventType e lpEventData contengono informazioni aggiuntive.
SERVICE_CONTROL_HARDWAREPROFILECHANGE 0x0000000C	Notifica a un servizio che il profilo hardware del computer è stato modificato. Il parametro dwEventType contiene informazioni aggiuntive.
SERVICE_CONTROL_POWEREVENT 0x0000000D	Notifica a un servizio di eventi di alimentazione del sistema. Il parametro dwEventType contiene informazioni aggiuntive. Se dwEventType è PBT_POWERSETTINGCHANGE, il parametro lpEventData contiene anche informazioni aggiuntive.
SERVICE_CONTROL_SESSIONCHANGE 0x0000000E	Notifica a un servizio di eventi di modifica della sessione. Si noti che un servizio riceverà una notifica solo di un accesso utente se è completamente caricato prima che venga effettuato il tentativo di accesso. I parametri dwEventType e lpEventData contengono informazioni aggiuntive.
SERVICE_CONTROL_TIMECHANGE 0x00000010	Notifica a un servizio che l'ora di sistema è cambiata. Il parametro lpEventData contiene informazioni aggiuntive. Il parametro dwEventType non viene utilizzato. Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Questo codice di controllo non è supportato.
SERVICE_CONTROL_TRIGGEREVENT 0x00000020	Notifica a un servizio registrato per un evento trigger del servizio che l'evento si è verificato. Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Questo codice di controllo non è supportato.
SERVICE_CONTROL_USERMODEREBOOT 0x00000040	Notifica a un servizio che l'utente ha avviato un riavvio. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Questo codice di controllo non è supportato.

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.

[in] dwEventType

Tipo di evento che si è verificato. Questo parametro viene usato se dwControl è SERVICE_CONTROL_DEVICEEVENT, SERVICE_CONTROL_HARDWAREPROFILECHANGE, SERVICE_CONTROL_POWEREVENT o SERVICE_CONTROL_SESSIONCHANGE. In caso contrario, è zero.

Se dwControl è SERVICE_CONTROL_DEVICEEVENT, questo parametro può essere uno dei valori seguenti:

Se dwControl è SERVICE_CONTROL_HARDWAREPROFILECHANGE, questo parametro può essere uno dei valori seguenti:

Se dwControl è SERVICE_CONTROL_POWEREVENT, questo parametro può essere uno dei valori specificati nel parametro wParam del messaggio WM_POWERBROADCAST .

Se dwControl è SERVICE_CONTROL_SESSIONCHANGE, questo parametro può essere uno dei valori specificati nel parametro wParam del messaggio WM_WTSSESSION_CHANGE .

[in] lpEventData

Informazioni aggiuntive sul dispositivo, se necessario. Il formato di questi dati dipende dal valore dei parametri dwControl e dwEventType .

Se dwControl è SERVICE_CONTROL_DEVICEEVENT, questi dati corrispondono al parametro lParam ricevuto dalle applicazioni come parte di un messaggio di WM_DEVICECHANGE .

Se dwControl è SERVICE_CONTROL_POWEREVENT e dwEventType è PBT_POWERSETTINGCHANGE, questi dati sono un puntatore a una struttura POWERBROADCAST_SETTING .

Se dwControl è SERVICE_CONTROL_SESSIONCHANGE, questo parametro è un puntatore a una struttura WTSSESSION_NOTIFICATION .

Se dwControl è SERVICE_CONTROL_TIMECHANGE, questi dati sono un puntatore a una struttura SERVICE_TIMECHANGE_INFO .

[in] lpContext

Dati definiti dall'utente passati da RegisterServiceCtrlHandlerEx. Quando più servizi condividono un processo, il parametro lpContext consente di identificare il servizio.

Valore restituito

Il valore restituito per questa funzione dipende dal codice di controllo ricevuto.

L'elenco seguente identifica le regole per questo valore restituito:

In generale, se il servizio non gestisce il controllo, restituire ERROR_CALL_NOT_IMPLEMENTED. Tuttavia, il servizio deve restituire NO_ERROR per SERVICE_CONTROL_INTERROGATE anche se il servizio non lo gestisce.
Se il servizio gestisce SERVICE_CONTROL_STOP o SERVICE_CONTROL_SHUTDOWN, restituire NO_ERROR.
Se il servizio gestisce SERVICE_CONTROL_DEVICEEVENT, restituire NO_ERROR per concedere la richiesta e un codice di errore per negare la richiesta.
Se il servizio gestisce SERVICE_CONTROL_HARDWAREPROFILECHANGE, restituire NO_ERROR per concedere la richiesta e un codice di errore per negare la richiesta.
Se il servizio gestisce SERVICE_CONTROL_POWEREVENT, restituire NO_ERROR per concedere la richiesta e un codice di errore per negare la richiesta.
Per tutti gli altri codici di controllo gestiti dal servizio, restituire NO_ERROR.

Commenti

Quando un servizio viene avviato, la relativa funzione ServiceMain deve chiamare immediatamente la funzione RegisterServiceCtrlHandlerEx per specificare una funzione HandlerEx per elaborare le richieste di controllo. Per specificare i codici di controllo da accettare, usare le funzioni SetServiceStatus e RegisterDeviceNotification .

Il dispatcher di controllo nel thread principale di un servizio richiama la funzione del gestore di controllo per il servizio specificato ogni volta che riceve una richiesta di controllo dalla gestione controllo del servizio. Dopo aver elaborato la richiesta di controllo, il gestore del controllo deve chiamare SetServiceStatus se lo stato del servizio cambia per segnalare il nuovo stato alla gestione controllo del servizio.

La funzione del gestore di controllo è progettata per 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 di controllo del servizio invia un codice di controllo a un servizio, attende che la funzione del gestore restituisca prima di inviare codici di controllo aggiuntivi ad altri servizi. Il gestore di 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 di controlli, 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 di 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 essere assolutamente puliti 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 spento), il servizio continua a essere eseguito. Se il servizio esegue la registrazione per accettare SERVICE_CONTROL_SHUTDOWN, deve gestire il codice di controllo e restituire NO_ERROR. La restituzione di un errore per questo codice di controllo e non l'arresto tempestivo può aumentare il tempo necessario per arrestare il sistema, perché il sistema deve attendere l'intero periodo di tempo consentito per l'arresto del servizio prima che l'arresto del sistema possa continuare.

Se il servizio richiede più tempo per eseguire la pulizia, 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 il completamento dell'arresto del servizio. Tuttavia, per impedire a un servizio di arrestare l'arresto, esiste un limite alla durata di attesa del controller del servizio. 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

Assicurarsi di gestire Plug and Play eventi del dispositivo il più rapidamente possibile. In caso contrario, il sistema potrebbe non rispondere. Se il gestore eventi deve eseguire un'operazione che potrebbe bloccare l'esecuzione (ad esempio I/O), è consigliabile avviare un altro thread per eseguire l'operazione in modo asincrono.

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.

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)