função de retorno de chamada LPHANDLER_FUNCTION (winsvc.h)
Uma função de retorno de chamada definida pelo aplicativo usada com a função RegisterServiceCtrlHandler . Um programa de serviço pode usá-lo como a função de manipulador de controle de um serviço específico.
O tipo LPHANDLER_FUNCTION define um ponteiro para essa função. Manipulador é um espaço reservado para o nome definido pelo aplicativo.
Essa função foi substituída pela função manipuladora de controle HandlerEx usada com a função RegisterServiceCtrlHandlerEx . Um serviço pode usar qualquer manipulador de controle, mas o novo manipulador de controle dá suporte a dados de contexto definidos pelo usuário e códigos de controle estendidos adicionais.
Sintaxe
LPHANDLER_FUNCTION LphandlerFunction;
void LphandlerFunction(
DWORD dwControl
)
{...}
Parâmetros
dwControl
Valor retornado
Nenhum
Comentários
Quando um serviço é iniciado, sua função ServiceMain deve chamar imediatamente a função RegisterServiceCtrlHandler para especificar uma função Handler para processar solicitações de controle.
O dispatcher de controle no thread main de um processo de serviço invoca a função de manipulador de controle para o serviço especificado sempre que recebe uma solicitação de controle do gerenciador de controle de serviço. Depois de processar a solicitação de controle, o manipulador de controle deverá chamar a função SetServiceStatus se o estado do serviço for alterado para relatar seu novo status ao gerenciador de controle de serviço.
A função de manipulador de controle destina-se a receber notificação e retornar imediatamente. A função de retorno de chamada deve salvar seus parâmetros e criar outros threads para executar trabalho adicional. (Seu aplicativo deve garantir que esses threads tenham sido encerrados antes de interromper o serviço.) Em particular, um manipulador de controle deve evitar operações que possam bloquear, como tomar um bloqueio, porque isso pode resultar em um deadlock ou fazer com que o sistema pare de responder.
Quando o gerenciador de controle de serviço envia um código de controle para um serviço, ele aguarda o retorno da função de manipulador antes de enviar códigos de controle adicionais para outros serviços. O manipulador de controle deve retornar o mais rápido possível; se ele não retornar dentro de 30 segundos, o SCM retornará um erro. Se um serviço precisar fazer processamento longo quando o serviço estiver executando o manipulador de controle, ele deverá criar um thread secundário para executar o processamento demorado e retornar do manipulador de controle. Isso impede que o serviço acione o dispatcher de controle e impeça que outros serviços recebam códigos de controle.
O código de controle SERVICE_CONTROL_SHUTDOWN só deve ser processado por serviços que devem absolutamente limpo durante o desligamento, pois há um tempo limitado (cerca de 20 segundos) disponível para desligamento do serviço. Depois que esse tempo expirar, o desligamento do sistema continuará independentemente de o desligamento do serviço ser concluído. Observe que, se o sistema for deixado no estado de desligamento (não reiniciado ou desligado), o serviço continuará a ser executado. Se o serviço se registrar para aceitar SERVICE_CONTROL_SHUTDOWN, ele deverá lidar com o código de controle e parar em tempo hábil. Caso contrário, o serviço poderá aumentar o tempo necessário para desligar o sistema, pois o sistema deve aguardar o tempo total permitido para o desligamento do serviço antes que o desligamento do sistema possa continuar.
Se o serviço exigir mais tempo para limpo, ele deverá enviar STOP_PENDING status mensagens, juntamente com uma dica de espera, para que o controlador de serviço saiba quanto tempo aguardar antes de relatar ao sistema que o desligamento do serviço está concluído. No entanto, para impedir que um serviço interrompa o desligamento, há um limite para quanto tempo o controlador de serviço aguardará. Se o serviço estiver sendo desligado por meio do snap-in Serviços, o limite será de 125 segundos. Se o sistema operacional estiver sendo reinicializado, o limite de tempo será especificado no valor WaitToKillServiceTimeout da seguinte chave do Registro:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control
Os serviços também podem usar a função SetConsoleCtrlHandler para receber notificação de desligamento. Essa notificação é recebida quando os aplicativos em execução estão sendo desligados, o que ocorre antes que os serviços sejam desligados.
Exemplos
Para obter um exemplo, consulte Escrevendo uma função de manipulador de controle.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | winsvc.h (inclua Windows.h) |