Função de retorno de chamada HandlerRoutine
Uma função definida pelo aplicativo usada com a função SetConsoleCtrlHandler. Um processo de console usa essa função para lidar com sinais de controle recebidos pelo processo. Quando o sinal é recebido, o sistema cria um novo thread no processo para executar a função.
O tipo PHANDLER_ROUTINE define um ponteiro para essa função de retorno de chamada. HandlerRoutine é um espaço reservado para o nome da função definida pelo aplicativo.
Sintaxe
BOOL WINAPI HandlerRoutine(
_In_ DWORD dwCtrlType
);
Parâmetros
dwCtrlType [in]
O tipo de sinal de controle recebido pelo manipulador. Esse parâmetro pode usar um dos valores a seguir.
| Valor | Significado |
|---|---|
| CTRL_C_EVENT 0 | Um sinal CTRL+C foi recebido da entrada do teclado ou de um sinal gerado pela função GenerateConsoleCtrlEvent. |
| CTRL_BREAK_EVENT 1 | Um sinal CTRL+BREAK foi recebido da entrada do teclado ou de um sinal gerado por GenerateConsoleCtrlEvent. |
| CTRL_CLOSE_EVENT 2 | Um sinal que o sistema envia a todos os processos conectados a um console quando o usuário fecha o console (ao clicar em Fechar no menu da janela do console ou ao clicar no comando do botão Finalizar Tarefa do Gerenciador de Tarefas). |
| CTRL_LOGOFF_EVENT 5 | Um sinal que o sistema envia a todos os processos do console quando um usuário faz logoff. Esse sinal não indica qual usuário está fazendo logoff, portanto, nenhuma pressuposição pode ser feita. Observe que esse sinal é recebido somente pelos serviços. Os aplicativos interativos são encerrados no logoff, portanto, eles não estão presentes quando esse sinal é enviado pelo sistema. |
| CTRL_SHUTDOWN_EVENT 6 | Um sinal que o sistema envia quando o sistema está sendo desligado. Aplicativos interativos não estão presentes no momento em que o sistema envia esse sinal, portanto, ele é recebido somente por serviços nesta situação. Os serviços também têm o próprio mecanismo de notificação para eventos de desligamento. Para obter mais informações, confira Manipulador. |
Valor retornado
Se a função manipula o sinal de controle, ela deve retornar TRUE. Se ela retornar FALSE, a próxima função de manipulador na lista de manipuladores para esse processo será usada.
Comentários
Uma vez que o sistema cria um novo thread no processo para executar a função de manipulador, a função de manipulador pode ser encerrada por outro thread no processo. Sincronize os threads no processo com o thread para a função de manipulador.
Cada processo de console tem a própria lista de funções HandlerRoutine. Inicialmente, a lista contém somente uma função de manipulador padrão que chama 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 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.
Os sinais CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT e CTRL_SHUTDOWN_EVENT oferecem ao processo a oportunidade de realizar a limpeza antes do término. Um HandlerRoutine pode realizar a limpeza necessária e, em seguida, executar uma das seguintes ações:
- Chamar a função ExitProcess para encerrar o processo.
- Retorna FALSE. Se nenhuma das funções de manipulador registradas retornar TRUE, o manipulador padrão encerrará o processo.
- Retorna TRUE. Nesse caso, nenhuma outra função de manipulador é chamada e o sistema encerra o processo.
Um processo pode usar a função SetProcessShutdownParameters para impedir que o sistema exiba uma caixa de diálogo ao usuário durante o logoff ou desligamento. Nesse caso, o sistema encerra o processo quando HandlerRoutine retorna TRUE ou ao expirar o período de tempo limite.
Quando um aplicativo de console é executado como serviço, ele recebe um manipulador de controle de console padrão modificado. Esse manipulador modificado não chama ExitProcess ao processar os sinais CTRL_LOGOFF_EVENT e CTRL_SHUTDOWN_EVENT. Isso permite que o serviço continue em execução depois que o usuário fizer logoff. Se o serviço instalar o próprio manipulador de controle de console, esse manipulador será chamado antes do manipulador padrão. Se o manipulador instalado chamar ExitProcess ao processar o sinal CTRL_LOGOFF_EVENT, o serviço será encerrado quando o usuário fizer logoff.
Observe que uma biblioteca ou DLL de terceiros pode instalar um manipulador de controle de console para seu aplicativo. Nesse caso, esse manipulador substituirá o manipulador padrão e poderá fazer com que o aplicativo seja encerrado quando o usuário fizer logoff.
Tempos limite
| Evento | Circunstâncias | Tempo limite |
|---|---|---|
CTRL_CLOSE_EVENT |
qualquer | parâmetro do sistema SPI_GETHUNGAPPTIMEOUT, 5000 ms |
CTRL_LOGOFF_EVENT |
rápido[1] | chave do registro CriticalAppShutdownTimeout ou 500 ms |
CTRL_LOGOFF_EVENT |
nenhuma das opções acima | parâmetro do sistema SPI_GETWAITTOKILLTIMEOUT, 5000 ms |
CTRL_SHUTDOWN_EVENT |
serviço/processo | parâmetro do sistema SPI_GETWAITTOKILLSERVICETIMEOUT, 20000 ms |
CTRL_SHUTDOWN_EVENT |
rápido[1] | chave do registro CriticalAppShutdownTimeout ou 500 ms |
CTRL_SHUTDOWN_EVENT |
nenhuma das opções acima | parâmetro do sistema SPI_GETWAITTOKILLTIMEOUT, 5000 ms |
CTRL_C, CTRL_BREAK |
qualquer | sem tempo limite |
[1]: eventos "rápidos" nunca são usados, mas ainda há código para dar suporte a eles.
Requisitos
| Cliente mínimo com suporte | Windows 2000 Professional [somente aplicativos para desktop] |
| 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) |