Funzione di callback HandlerRoutine

Articolo
10/23/2023

Funzione definita dall'applicazione usata con la funzione SetConsoleCtrlHandler. Un processo della console usa questa funzione per gestire i segnali di controllo ricevuti dal processo. Quando il segnale viene ricevuto, il sistema crea un nuovo thread nel processo per eseguire la funzione.

Il tipo PHANDLER_ROUTINE definisce un puntatore a questa funzione di callback. HandlerRoutine è un segnaposto per il nome della funzione definita dall'applicazione.

Sintassi

BOOL WINAPI HandlerRoutine(
  _In_ DWORD dwCtrlType
);

Parametri

dwCtrlType [in]
Tipo di segnale di controllo ricevuto dal gestore. Questo parametro può avere uno dei valori seguenti.

Valore	Significato
CTRL_C_EVENT 0	È stato ricevuto un `segnale CTRL+C`, dall'input della tastiera o da un segnale generato dalla funzione GenerateConsoleCtrlEvent.
CTRL_BREAK_EVENT 1	È stato ricevuto un `segnale CTRL`+`BREAK`, dall'input della tastiera o da un segnale generato da GenerateConsoleCtrlEvent.
CTRL_CLO edizione Standard_EVENT 2	Segnale che il sistema invia a tutti i processi collegati a una console quando l'utente chiude la console (facendo clic su Chiudi nel menu della finestra della console o facendo clic sul comando Termina attività da Gestione attività).
CTRL_LOGOFF_EVENT 5	Segnale che il sistema invia a tutti i processi della console quando un utente si disconnette. Questo segnale non indica quale utente sta disconnettendo, quindi non è possibile fare ipotesi. Si noti che questo segnale viene ricevuto solo dai servizi. Le applicazioni interattive vengono terminate alla disconnessione, quindi non sono presenti quando il sistema invia questo segnale.
CTRL_SHUTDOWN_EVENT 6	Segnale che il sistema invia quando il sistema viene arrestato. Le applicazioni interattive non sono presenti nel momento in cui il sistema invia questo segnale, pertanto può essere ricevuto solo come servizi in questa situazione. I servizi hanno anche un proprio meccanismo di notifica per gli eventi di arresto. Per altre informazioni, vedere Gestore.

Valore restituito

Se la funzione gestisce il segnale di controllo, deve restituire TRUE. Se restituisce FAL edizione Standard, viene utilizzata la funzione del gestore successiva nell'elenco dei gestori per questo processo.

Osservazioni:

Poiché il sistema crea un nuovo thread nel processo per eseguire la funzione del gestore, è possibile che la funzione del gestore venga terminata da un altro thread nel processo. Assicurarsi di sincronizzare i thread nel processo con il thread per la funzione del gestore.

Ogni processo della console ha un proprio elenco di funzioni HandlerRoutine . Inizialmente, questo elenco contiene solo una funzione del gestore predefinita che chiama ExitProcess. Un processo della console aggiunge o rimuove ulteriori funzioni gestore chiamando la funzione SetConsoleCtrlHandler, che non influisce sull'elenco di funzioni gestore per altri processi. Quando un processo della console riceve uno dei segnali di controllo, le funzioni del gestore vengono chiamate in base all'ultima registrazione, prima chiamata fino a quando uno dei gestori non restituisce TRUE. Se nessuno dei gestori restituisce TRUE, viene chiamato il gestore predefinito.

I segnali CTRL_CLO edizione Standard_EVENT, CTRL_LOGOFF_EVENT e CTRL_SHUTDOWN_EVENT offrono al processo l'opportunità di eseguire la pulizia prima della chiusura. Un HandlerRoutine può eseguire qualsiasi pulizia necessaria, quindi eseguire una delle azioni seguenti:

Chiamare la funzione ExitProcess per terminare il processo.
Restituisce FAL edizione Standard. Se nessuna delle funzioni del gestore registrato restituisce TRUE, il gestore predefinito termina il processo.
Restituisce TRUE. In questo caso, non vengono chiamate altre funzioni del gestore e il sistema termina il processo.

Un processo può usare la funzione SetProcessShutdownParameters per impedire al sistema di visualizzare una finestra di dialogo all'utente durante l'accesso o l'arresto. In questo caso, il sistema termina il processo quando HandlerRoutine restituisce TRUE o quando scade il periodo di timeout.

Quando un'applicazione console viene eseguita come servizio, riceve un gestore di controllo della console predefinito modificato. Questo gestore modificato non chiama ExitProcess durante l'elaborazione dei segnali CTRL_LOGOFF_EVENT e CTRL_SHUTDOWN_EVENT. Ciò consente al servizio di continuare l'esecuzione dopo che l'utente si disconnette. Se il servizio installa il proprio gestore di controllo della console, questo gestore viene chiamato prima del gestore predefinito. Se il gestore installato chiama ExitProcess durante l'elaborazione del segnale CTRL_LOGOFF_EVENT , il servizio viene chiuso quando l'utente si disconnette.

Si noti che una libreria o una DLL di terze parti può installare un gestore di controllo della console per l'applicazione. In tal caso, questo gestore esegue l'override del gestore predefinito e può causare l'uscita dell'applicazione quando l'utente si disconnette.

Timeout

Event	Circostanze	Timeout
`CTRL_CLOSE_EVENT`	qualsiasi	parametro `SPI_GETHUNGAPPTIMEOUT`di sistema , 5000 ms
`CTRL_LOGOFF_EVENT`	quick[1]	Chiave `CriticalAppShutdownTimeout` del Registro di sistema o 500 ms
`CTRL_LOGOFF_EVENT`	nessuno dei precedenti	parametro `SPI_GETWAITTOKILLTIMEOUT`di sistema , 5000 ms
`CTRL_SHUTDOWN_EVENT`	processo del servizio	parametro `SPI_GETWAITTOKILLSERVICETIMEOUT`di sistema , 20000 ms
`CTRL_SHUTDOWN_EVENT`	quick[1]	Chiave `CriticalAppShutdownTimeout` del Registro di sistema o 500 ms
`CTRL_SHUTDOWN_EVENT`	nessuno dei precedenti	parametro `SPI_GETWAITTOKILLTIMEOUT`di sistema , 5000 ms
`CTRL_C`, `CTRL_BREAK`	qualsiasi	nessun timeout

[1]: gli eventi "rapidi" non vengono mai usati, ma c'è ancora codice per supportarli.

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Intestazione	ConsoleApi.h (tramite WinCon.h, con Windows.h)