SetConsoleCtrlHandler (funzione)

Articolo
12/13/2023

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

HandlerRoutine [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_QUERYENDedizione Standard SSION fornisce alle applicazioni grafiche con un message pump. È anche possibile usare questa funzione da un'applicazione grafica, ma non esiste alcuna garanzia che arrivi prima della notifica da WM_QUERYENDedizione Standard SSION.

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 a AttachConsole, AllocConsole o FreeConsole reimposta la tabella dei gestori di controllo nel processo client sullo stato iniziale. I gestori devono essere registrati di nuovo quando cambia la sessione della console collegata.

Per i processi della console, le combinazioni di tasti CTRL+C e CTRL+BREAK vengono in genere considerate come 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_PROCESedizione StandardD_INPUT per il buffer di input di una 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 viene eseguito il debug di un processo della console 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_CLOedizione Standard_EVENT, CTRL_LOGOFF_EVENT e CTRL_SHUTDOWN_EVENT segnala quando l'utente chiude la console, si disconnette o arresta il sistema in modo che il processo abbia la possibilità di eseguire la pulizia prima della chiusura. 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 della finestra WM_QUERYENDedizione Standard SSION e WM_ENDedizione Standard SSION 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