função de retorno de chamada LPHANDLER_FUNCTION (winsvc.h)

Artigo
03/08/2023

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)