Função RegisterServiceCtrlHandlerExA (winsvc.h)

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.

Valor de retorno

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.

Observações

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 receber 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 definir inadvertidamente esse status de serviço. 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 o status para o gerenciador de controle de serviço somente se o status do serviço tiver sido alterado, como quando o serviço estiver processando controles de parada ou desligamento. Se o status do serviço não tiver sido alterado, o serviço não deverá relatar o status ao gerenciador de controle de serviço.

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

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2003 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	winsvc.h (incluir Windows.h)
biblioteca	Advapi32.lib
de DLL	Advapi32.dll

Consulte também

CreateService

HandlerEx

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

Funções de serviço

do ServiceMain

SetServiceStatus