Função StartServiceCtrlDispatcherA (winsvc.h)

Artigo
08/27/2023

Conecta o thread main de um processo de serviço ao gerenciador de controle de serviço, o que faz com que o thread seja o thread do dispatcher de controle de serviço para o processo de chamada.

Sintaxe

BOOL StartServiceCtrlDispatcherA(
  [in] const SERVICE_TABLE_ENTRYA *lpServiceStartTable
);

Parâmetros

[in] lpServiceStartTable

Um ponteiro para uma matriz de estruturas de SERVICE_TABLE_ENTRY que contém uma entrada para cada serviço que pode ser executada no processo de chamada. Os membros da última entrada na tabela devem ter valores NULL para designar o final da tabela.

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.

O código de erro a seguir pode ser definido 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_FAILED_SERVICE_CONTROLLER_CONNECT	Esse erro será retornado se o programa estiver sendo executado como um aplicativo de console e não como um serviço. Se o programa for executado como um aplicativo de console para fins de depuração, estrutura-o de modo que o código específico do serviço não seja chamado quando esse erro for retornado.
ERROR_INVALID_DATA	A tabela de expedição especificada contém entradas que não estão no formato adequado.
ERROR_SERVICE_ALREADY_RUNNING	O processo já chamou StartServiceCtrlDispatcher. Cada processo pode chamar StartServiceCtrlDispatcher apenas uma vez.

Comentários

Quando o gerenciador de controle de serviço inicia um processo de serviço, ele aguarda o processo chamar a função StartServiceCtrlDispatcher . O thread main de um processo de serviço deve fazer essa chamada o mais rápido possível depois que ela for iniciada (dentro de 30 segundos). Se StartServiceCtrlDispatcher for bem-sucedido, ele conectará o thread de chamada ao gerenciador de controle de serviço e não retornará até que todos os serviços em execução no processo entrem no estado SERVICE_STOPPED. O gerenciador de controle de serviço usa essa conexão para enviar solicitações de controle e início de serviço para o thread main do processo de serviço. O thread main atua como um dispatcher invocando a função HandlerEx apropriada para lidar com solicitações de controle ou criando um novo thread para executar a função ServiceMain apropriada quando um novo serviço é iniciado.

O parâmetro lpServiceTable contém uma entrada para cada serviço que pode ser executado no processo de chamada. Cada entrada especifica a função ServiceMain para esse serviço. Para serviços SERVICE_WIN32_SHARE_PROCESS, cada entrada deve conter o nome de um serviço. Esse nome é o nome do serviço especificado pela função CreateService quando o serviço foi instalado. Para serviços SERVICE_WIN32_OWN_PROCESS, o nome do serviço na entrada da tabela é ignorado.

Se um serviço for executado em seu próprio processo, o thread main do processo de serviço deverá chamar imediatamente StartServiceCtrlDispatcher. Todas as tarefas de inicialização são feitas na função ServiceMain do serviço quando o serviço é iniciado.

Se vários serviços compartilharem um processo e alguma inicialização comum em todo o processo precisar ser feita antes que qualquer função ServiceMain seja chamada, o thread main poderá fazer o trabalho antes de chamar StartServiceCtrlDispatcher, desde que leve menos de 30 segundos. Caso contrário, outro thread deve ser criado para fazer a inicialização em todo o processo, enquanto o thread main chama StartServiceCtrlDispatcher e se torna o dispatcher de controle de serviço. Qualquer inicialização específica do serviço ainda deve ser feita nas funções de main de serviço individuais.

Os serviços não devem tentar exibir uma interface do usuário diretamente. Para obter mais informações, consulte Serviços Interativos.

Exemplos

Para obter um exemplo, consulte Escrevendo a função principal de um programa de serviço.

Observação

O cabeçalho winsvc.h define StartServiceCtrlDispatcher 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 (inclua Windows.h)
Biblioteca	Advapi32.lib
DLL	Advapi32.dll