Função RegisterServiceCtrlHandlerA (winsvc.h)

Artigo
08/27/2023

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

Essa função foi substituída pela função RegisterServiceCtrlHandlerEx . Um serviço pode usar qualquer função, mas a nova função dá suporte a dados de contexto definidos pelo usuário e a nova função de manipulador dá suporte a códigos de controle estendidos adicionais.

Sintaxe

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerA(
  [in] LPCSTR             lpServiceName,
  [in] LPHANDLER_FUNCTION lpHandlerProc
);

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.

Se o tipo de serviço for SERVICE_WIN32_OWN_PROCESS, a função não verificará se o nome especificado é válido, pois há apenas um serviço registrado no processo.

[in] lpHandlerProc

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

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 RegisterServiceCtrlHandler 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 Manipulador. 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 RegisterServiceCtrlHandler deve ser chamada antes da primeira chamada setServiceStatus porque RegisterServiceCtrlHandler 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.

Exemplos

Para obter um exemplo, consulte Escrevendo uma função ServiceMain.

Observação

O cabeçalho winsvc.h define RegisterServiceCtrlHandler 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