SetConsoleCtrlHandler (funzione)
Aggiunge o rimuove una funzione HandlerRoutine definita dall'applicazione nell'elenco di funzioni di gestione per il processo chiamante.
Se non viene specificata alcuna funzione gestore, la funzione imposta un attributo ereditabile che determina se il processo chiamante ignora i segnali CTRL+C.
Sintassi
BOOL WINAPI SetConsoleCtrlHandler(
_In_opt_ PHANDLER_ROUTINE HandlerRoutine,
_In_ BOOL Add
);
Parametri
GestoreRoutine [in, facoltativo]
Un puntatore alla funzione HandlerRoutine definita dall'applicazione da aggiungere o rimuovere. Questo parametro può essere NULL.
Aggiungi [in]
Se questo parametro è TRUE, il gestore viene aggiunto; se è FALSE, il gestore viene rimosso.
Se il parametro HandlerRoutine è NULL, il valore TRUE fa in modo che il processo chiamante ignori l'input CTRL+C e il valore FALSE ripristina la normale elaborazione dell'input CTRL+C. Questo attributo che determina se CTRL+C viene ignorato o elaborato viene ereditato dai processi figlio.
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.
Osservazioni
Questa funzione fornisce una notifica simile per applicazioni console e servizi che WM_QUERYENDSESSION fornisce applicazioni grafiche con una pompa di messaggi. È anche possibile usare questa funzione da un'applicazione grafica, ma non vi è alcuna garanzia che venga inviata prima della notifica da WM_QUERYENDSESSION.
Ogni processo della console dispone di un elenco specifico di funzioni HandlerRoutine definite dall'applicazione che gestiscono i segnali CTRL+C e CTRL+BREAK. Le funzioni gestore gestiscono anche i segnali generati dal sistema quando l'utente chiude la console, si disconnette o arresta il sistema. Inizialmente, l'elenco dei gestori per ogni processo contiene solo una funzione gestore predefinita che chiama la funzione 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, vengono chiamate le relative funzioni gestore, partendo dall'ultima registrata, finché uno dei gestori non restituisce TRUE. Se nessuno dei gestori restituisce TRUE, viene chiamato il gestore predefinito.
La chiamata di AttachConsole, AllocConsole o FreeConsole reimposta la tabella dei gestori di controllo nel processo client allo stato iniziale. I gestori devono essere registrati di nuovo quando la sessione della console associata cambia.
Per i processi della console, le combinazioni di tasti CTRL+C e CTRL+BREAK vengono in genere considerate segnali (CTRL_C_EVENT e CTRL_BREAK_EVENT). Quando una finestra della console con lo stato attivo della tastiera riceve CTRL+C o CTRL+INTERR, il segnale viene generalmente passato a tutti i processi che condividono tale console.
CTRL+INTERR viene sempre considerato come segnale, ma è possibile modificare il comportamento tipico di CTRL+C in tre modi che impediscono la chiamata delle funzioni gestore:
- La funzione SetConsoleMode può disabilitare la modalità ENABLE_PROCESSED_INPUT per il buffer di input della console, quindi CTRL+C viene segnalato come input da tastiera anziché come segnale.
- Se si chiama SetConsoleCtrlHandler con gli argomenti NULL e TRUE, il processo chiamante ignora i segnali CTRL+C. Questo attributo viene ereditato dai processi figlio, ma può essere abilitato o disabilitato da qualsiasi processo senza influire sui processi esistenti.
- Se un processo della console viene eseguito il debug e i segnali CTRL+C non sono stati disabilitati, il sistema genera un'eccezione DBG_CONTROL_C . Questa eccezione viene generata solo a vantaggio del debugger e un'applicazione non deve mai usare un gestore di eccezioni per gestirla. Se l'eccezione viene gestita dal debugger, un'applicazione non noterà la combinazione CTRL+C, con un'eccezione: le attese con avvisi vengono terminate. Se il debugger imposta l'eccezione su non gestita, CTRL+C viene passato al processo della console e considerato come un segnale, come indicato in precedenza.
Un processo della console può usare la funzione GenerateConsoleCtrlEvent per inviare un segnale CTRL+C o CTRL+INTERR a un gruppo di processi della console.
Il sistema genera CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT e CTRL_SHUTDOWN_EVENT segnali quando l'utente chiude la console, registra o arresta il sistema in modo che il processo abbia la possibilità di pulire prima della terminazione. Le funzioni della console, o qualsiasi funzione di runtime C che chiama funzioni della console, potrebbero non funzionare in modo affidabile durante l'elaborazione di uno dei tre segnali citati in precedenza. Questo perché alcune o tutte le routine di pulitura della console interna potrebbero essere state chiamate prima dell'esecuzione del gestore di segnale del processo.
Windows 7, Windows 8, Windows 8.1 e Windows 10:
Se un'applicazione console carica la libreria gdi32.dll o user32.dll, la funzione HandlerRoutine specificata quando si chiama SetConsoleCtrlHandler non viene chiamata per gli eventi CTRL_LOGOFF_EVENT e CTRL_SHUTDOWN_EVENT . Il sistema operativo riconosce i processi che caricano gdi32.dll o user32.dll come applicazioni Windows anziché come applicazioni console. Questo comportamento si verifica anche per le applicazioni console che non chiamano direttamente le funzioni in gdi32.dll o user32.dll, ma chiamano funzioni come le funzioni Shell che a loro volta chiamano le funzioni in gdi32.dll o user32.dll.
Per ricevere eventi quando un utente si disconnette o il dispositivo si arresta in queste circostanze, creare una finestra nascosta nell'applicazione console e quindi gestire i messaggi di WM_QUERYENDSESSION e WM_ENDSESSION finestra ricevuti dalla finestra nascosta. È possibile creare una finestra nascosta chiamando il metodo CreateWindowEx con il parametro dwExStyle impostato su 0. Un esempio di questo è incluso nell'esempio di gestore di base collegato di seguito.
Esempi
Un esempio è disponibile in Registrazione di una funzione gestore di controllo.
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) |
| Libreria | Kernel32.lib |
| DLL | Kernel32.dll |
| Nomi Unicode e ANSI |