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 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

[1]: eventos "rápidos" nunca são usados, mas ainda há código para dar suporte a eles.

Requisitos

Confira também

Manipuladores de controle do console

Funções de Console

ExitProcess

GenerateConsoleCtrlEvent

GetProcessShutdownParameters

SetConsoleCtrlHandler

SetProcessShutdownParameters