Função SetConsoleCtrlHandler

Artigo
07/12/2023

Adiciona ou remove uma função HandlerRoutine definida pelo aplicativo da lista de funções de manipulador para o processo autor da chamada.

Se nenhuma função de manipulador for especificada, a função definirá um atributo herdável que determina se o processo autor da chamada ignora o sinais CTRL+C.

Sintaxe

BOOL WINAPI SetConsoleCtrlHandler(
  _In_opt_ PHANDLER_ROUTINE HandlerRoutine,
  _In_     BOOL             Add
);

Parâmetros

HandlerRoutine [in, opcional]
Um ponteiro para a função HandlerRoutine definida pelo aplicativo a ser adicionada ou removida. Este parâmetro pode ser NULL.

Add [in]
Se o parâmetro for TRUE, o manipulador será adicionado; se for FALSE, o manipulador será removido.

Se o parâmetro HandlerRoutine for NULL, um valor TRUE fará com que o processo autor da chamada ignore a entrada CTRL+C e um valor FALSE restaurará o processamento normal da entrada CTRL+C. Esse atributo de ignorar ou processar CTRL+C é herdado por processos filho.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Essa função fornece a aplicativos de console e serviços uma notificação semelhante à que WM_QUERYENDSESSION fornece para aplicativos gráficos com uma bomba de mensagens. Você também pode usar essa função em um aplicativo gráfico, mas não há nenhuma garantia de que ela chegue antes da notificação de WM_QUERYENDSESSION.

Cada processo do console tem a própria lista de funções HandlerRoutine definidas pelo aplicativo que lidam com os sinais CTRL+C e CTRL+BREAK. As funções de manipulador também lidam com os sinais gerados pelo sistema quando o usuário fecha o console, faz logoff ou desliga o sistema. Inicialmente, a lista de manipuladores para cada processo contém somente uma função de manipulador padrão que chama a função ExitProcess. Um processo de console adiciona ou remove funções de manipulador adicionais chamando a função SetConsoleCtrlHandler, o que não afeta a lista de funções de manipulador para outros processos. Quando um processo de console recebe qualquer um dos sinais de controle, suas funções de manipulador são chamadas com base no último registrado, primeiro chamado, até que um dos manipuladores retorne TRUE. Se nenhum dos manipuladores retornar TRUE, o manipulador padrão será chamado.

Chamar AttachConsole, AllocConsole ou FreeConsole redefinirá a tabela de manipuladores de controle no processo do cliente para o estado inicial. Os manipuladores precisam ser registrados novamente quando a sessão de console anexada é alterada.

Para processos do console, as combinações de teclas CTRL+C e CTRL+BREAK normalmente são tratadas como sinais (CTRL_C_EVENT e CTRL_BREAK_EVENT). Quando uma janela do console com foco do teclado recebe CTRL+C ou CTRL+BREAK, o sinal normalmente é passado para todos os processos que compartilham esse console.

CTRL+BREAK sempre é tratado como um sinal, mas o comportamento padrão de CTRL+C pode ser alterado de três maneiras que impedem que as funções do manipulador sejam chamadas:

A função SetConsoleMode pode desabilitar o modo ENABLE_PROCESSED_INPUT para o buffer de entrada de um console, portanto CTRL+C é relatado como entrada de teclado, e não como um sinal.
Chamar SetConsoleCtrlHandler com os argumentos NULL e TRUE faz com que o processo autor da chamada ignore os sinais CTRL+C. Esse atributo é herdado por processos filho, mas pode ser habilitado ou desabilitado por qualquer processo sem afetar os processos existentes.
Se um processo do console estiver sendo depurado e os sinais CTRL+C não tiverem sido desabilitados, o sistema vai gerar uma exceção para DBG_CONTROL_C. Essa exceção é gerada apenas para o benefício do depurador, e um aplicativo nunca deve usar um manipulador de exceção para lidar com ela. Se o depurador tratar a exceção, um aplicativo não notará CTRL+C, com uma exceção: as esperas passíveis alerta serão encerradas. Se o depurador passar a exceção sem tratamento, CTRL+C será passado para o processo do console e tratado como um sinal, conforme discutido anteriormente.

Um processo do console pode usar a função GenerateConsoleCtrlEvent para enviar um sinal CTRL+C ou CTRL+BREAK a um grupo de processos do console.

O sistema gera os sinais CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT e CTRL_SHUTDOWN_EVENT quando o usuário fecha o console, faz logoff ou desliga o sistema para que o processo tenha a oportunidade de fazer a limpeza antes do encerramento. As funções de console ou qualquer função do runtime C que chama funções de console podem não funcionar de maneira confiável durante o processamento de qualquer um dos três sinais mencionados anteriormente. O motivo é que algumas das rotinas de limpeza do console interno (ou todas elas) podem ter sido chamadas antes da execução do manipulador de sinal do processo.

Windows 7, Windows 8, Windows 8.1 e Windows 10:

Se um aplicativo de console carregar a biblioteca gdi32.dll ou user32.dll, a função HandlerRoutine que você especifica ao chamar SetConsoleCtrlHandler não será chamada para os eventos CTRL_LOGOFF_EVENT e CTRL_SHUTDOWN_EVENT. O sistema operacional reconhece processos que carregam gdi32.dll ou user32.dll como aplicativos do Windows em vez de aplicativos de console. Esse comportamento também ocorre para aplicativos de console que não chamam funções em gdi32.dll ou user32.dll diretamente, mas chamam funções como Funções de shell que, por sua vez, chamam funções em gdi32.dll ou user32.dll.

Para receber eventos quando um usuário sai ou o dispositivo é desligado nessas circunstâncias, crie uma janela oculta no aplicativo de console e manipule as mensagens de janela WM_QUERYENDSESSION e WM_ENDSESSION que a janela oculta recebe. Você pode criar uma janela oculta chamando o método CreateWindowEx com o parâmetro dwExStyle definido como 0. Um exemplo disso é incluído com o exemplo de manipulador básico vinculado abaixo.

Exemplos

Para ver um exemplo, confira Registrar uma função de manipulador de controle.

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Cabeçalho	ConsoleApi.h (via WinCon.h, inclui o Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll
Nomes Unicode e ANSI