Função RegisterServiceCtrlHandlerW (winsvc.h)

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 RegisterServiceCtrlHandlerW(
  [in] LPCWSTR            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 Handler.

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.

Observações

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 receber solicitações de controle para esse serviço. Para obter uma lista de códigos de controle possíveis, consultedo Manipulador de . 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 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.

Exemplos

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

Requisitos

Consulte também

CreateService

do Manipulador de

RegisterServiceCtrlHandlerEx

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

Funções de serviço

do ServiceMain

SetServiceStatus