Função SetServiceStatus (winsvc.h)

Artigo
03/13/2024

Atualizações as informações de status do gerenciador de controle de serviço para o serviço de chamada.

Sintaxe

BOOL SetServiceStatus(
  [in] SERVICE_STATUS_HANDLE hServiceStatus,
  [in] LPSERVICE_STATUS      lpServiceStatus
);

Parâmetros

[in] hServiceStatus

Um identificador para a estrutura de informações status para o serviço atual. Esse identificador é retornado pela função RegisterServiceCtrlHandlerEx .

[in] lpServiceStatus

Um ponteiro para a estrutura SERVICE_STATUS contém as informações mais recentes status para o serviço de chamada.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

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. Outros códigos de erro podem ser definidos pelas funções do Registro que são chamadas pelo gerenciador de controle de serviço.

Código de retorno	Descrição
ERROR_INVALID_DATA	A estrutura de status de serviço especificada é inválida.
ERROR_INVALID_HANDLE	O identificador especificado é inválido.

Comentários

Uma função ServiceMain primeiro chama a função RegisterServiceCtrlHandlerEx para obter o SERVICE_STATUS_HANDLE do serviço. Em seguida, ele chama imediatamente a função SetServiceStatus para notificar o gerenciador de controle de serviço de que sua status está SERVICE_START_PENDING. Durante a inicialização, o serviço pode fornecer status atualizadas para indicar que está progredindo, mas precisa de mais tempo. Um bug comum é que o serviço faça com que o thread main execute a inicialização enquanto um thread separado continua a chamar SetServiceStatus para impedir que o gerenciador de controle de serviço o marque como travado. No entanto, se o thread main for travado, a inicialização do serviço terminará em um loop infinito porque o thread de trabalho continuará relatando que o thread main está progredindo.

Depois de processar uma solicitação de controle, a função Manipulador do serviço deverá chamar SetServiceStatus se o serviço status mudar para relatar sua nova status para o gerenciador de controle de serviço. Só é necessário fazer isso quando o serviço está alterando o estado, como quando está processando controles de parada ou desligamento. Um serviço também pode usar essa função a qualquer momento de qualquer thread do serviço para notificar o gerenciador de controle de serviço de alterações de estado, como quando o serviço deve parar devido a um erro recuperável.

Um serviço só pode chamar essa função depois de chamar RegisterServiceCtrlHandlerEx para obter um identificador de status de serviço.

Se um serviço chamar SetServiceStatus com o membro dwCurrentState definido como SERVICE_STOPPED e o membro dwWin32ExitCode definido como um valor diferente de zero, a seguinte entrada será gravada no log de eventos do sistema:

   Event ID    = 7023
   Source      = Service Control Manager
   Type        = Error
   Description = <ServiceName> terminated with the following error:
                 <ExitCode>.

Veja a seguir as práticas recomendadas ao chamar essa função:

Inicialize todos os campos na estrutura SERVICE_STATUS, garantindo que haja valores válidos de dica de ponto marcar e espera para estados pendentes. Use dicas de espera razoáveis.
Não se registre para aceitar controles enquanto o status estiver SERVICE_START_PENDING ou o serviço puder falhar. Depois que a inicialização for concluída, aceite o código SERVICE_CONTROL_STOP.
Chame essa função com valores de ponto de verificação e dica de espera somente se o serviço estiver progredindo nas tarefas relacionadas ao início pendente, parar, pausar ou continuar a operação. Caso contrário, o SCM não poderá detectar se o serviço está travado.
Insira o estado interrompido com um código de saída apropriado se o ServiceMain falhar.
Se o status for SERVICE_STOPPED, execute toda a limpeza necessária e chame SetServiceStatus apenas uma vez. Essa função faz uma chamada LRPC para o SCM. A primeira chamada para a função no estado SERVICE_STOPPED fecha o identificador de contexto RPC e todas as chamadas subsequentes podem causar falha no processo.
Não tente executar nenhum trabalho adicional depois de chamar SetServiceStatus com SERVICE_STOPPED, pois o processo de serviço pode ser encerrado a qualquer momento.

Exemplos

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

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)
Biblioteca	Advapi32.lib
DLL	Advapi32.dll