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

Confira também

HandlerEx

RegisterServiceCtrlHandler

Função do manipulador do controle de serviço

Funções de serviço

ServiceMain

SetServiceStatus