Função RegisterServiceCtrlHandlerExA (winsvc.h)

Artigo
03/04/2024

Registra uma função para lidar com solicitações de controle de serviço estendidas.

Sintaxe

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerExA(
  [in]           LPCSTR                lpServiceName,
  [in]           LPHANDLER_FUNCTION_EX lpHandlerProc,
  [in, optional] LPVOID                lpContext
);

Parâmetros

[in] lpServiceName

O nome do serviço executado pelo thread de chamada. Esse é o nome do serviço especificado pelo programa de controle de serviço na função CreateService ao criar o serviço.

[in] lpHandlerProc

Um ponteiro para a função de manipulador a ser registrada. Para obter mais informações, consulte HandlerEx.

[in, optional] lpContext

Todos os dados definidos pelo usuário. Esse parâmetro, que é passado para a função de manipulador, pode ajudar a identificar o serviço quando vários serviços compartilham um processo.

Retornar valor

Se a função for bem-sucedida, o valor retornado será um identificador de status de serviço.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Os códigos de erro a seguir podem ser definidos pelo gerenciador de controle de serviço.

Código de retorno	Descrição
ERROR_NOT_ENOUGH_MEMORY	Não há memória suficiente disponível para converter um parâmetro de cadeia de caracteres ANSI em Unicode. Esse erro não ocorre para parâmetros de cadeia de caracteres Unicode.
ERROR_SERVICE_NOT_IN_EXE	A entrada de serviço foi especificada incorretamente quando o processo chamou a função StartServiceCtrlDispatcher .

Comentários

A função ServiceMain de um novo serviço deve chamar imediatamente a função RegisterServiceCtrlHandlerEx para registrar uma função de manipulador de controle com o dispatcher de controle. Isso permite que o dispatcher de controle invoque a função especificada quando recebe solicitações de controle para esse serviço. Para obter uma lista de códigos de controle possíveis, consulte HandlerEx. Os threads do processo de chamada podem usar o identificador de status de serviço retornado por essa função para identificar o serviço em chamadas subsequentes para a função SetServiceStatus.

A função RegisterServiceCtrlHandlerEx deve ser chamada antes da primeira chamada SetServiceStatus porque RegisterServiceCtrlHandlerEx retorna um identificador de status de serviço para o chamador usar para que nenhum outro serviço possa inadvertidamente definir esse serviço status. Além disso, o manipulador de controle deve estar em vigor para receber solicitações de controle até que o serviço especifique os controles que aceita por meio da função SetServiceStatus .

Quando a função do manipulador de controle é invocada com uma solicitação de controle, o serviço deve chamar SetServiceStatus para relatar status ao gerenciador de controle de serviço somente se o serviço status tiver sido alterado, como quando o serviço está processando controles de parada ou desligamento. Se o serviço status não tiver sido alterado, o serviço não deverá relatar status ao gerenciador de controle de serviço.

O identificador de status de serviço não precisa ser fechado.

Observação

O cabeçalho winsvc.h define RegisterServiceCtrlHandlerEx como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

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 (incluir Windows.h)
Biblioteca	Advapi32.lib
DLL	Advapi32.dll