Função StartServiceA (winsvc.h)

Artigo
08/27/2023

Inicia um serviço.

Sintaxe

BOOL StartServiceA(
  [in]           SC_HANDLE hService,
  [in]           DWORD     dwNumServiceArgs,
  [in, optional] LPCSTR    *lpServiceArgVectors
);

Parâmetros

[in] hService

Um identificador para o serviço. Esse identificador é retornado pela função OpenService ou CreateService e deve ter o acesso SERVICE_START correto. Para obter mais informações, consulte Segurança do serviço e Direitos de Acesso.

[in] dwNumServiceArgs

O número de cadeias de caracteres na matriz lpServiceArgVectors . Se lpServiceArgVectors for NULL, esse parâmetro poderá ser zero.

[in, optional] lpServiceArgVectors

As cadeias de caracteres terminadas em nulo a serem passadas para a função ServiceMain para o serviço como argumentos. Se não houver argumentos, esse parâmetro poderá ser NULL. Caso contrário, o primeiro argumento (lpServiceArgVectors[0]) é o nome do serviço, seguido por quaisquer argumentos adicionais (lpServiceArgVectors[1] por meio de lpServiceArgVectors[dwNumServiceArgs-1]).

Os serviços de driver não recebem esses argumentos.

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. Outras podem ser definidas pelas funções do Registro que são chamadas pelo gerenciador de controle de serviço.

Código de retorno	Descrição
ERROR_ACCESS_DENIED	O identificador não tem o acesso de SERVICE_START correto.
ERROR_INVALID_HANDLE	O manipulador é inválido.
ERROR_PATH_NOT_FOUND	Não foi possível encontrar o arquivo binário de serviço.
ERROR_SERVICE_ALREADY_RUNNING	Uma instância do serviço já está em execução.
ERROR_SERVICE_DATABASE_LOCKED	O banco de dados está bloqueado.
ERROR_SERVICE_DEPENDENCY_DELETED	O serviço depende de um serviço que não existe ou foi marcado para exclusão.
ERROR_SERVICE_DEPENDENCY_FAIL	O serviço depende de outro serviço que não foi iniciado.
ERROR_SERVICE_DISABLED	O serviço foi desabilitado.
ERROR_SERVICE_LOGON_FAILED	O serviço não foi iniciado devido a uma falha de logon. Esse erro ocorrerá se o serviço estiver configurado para ser executado em uma conta que não tenha o direito de "Fazer logon como serviço".
ERROR_SERVICE_MARKED_FOR_DELETE	O serviço foi marcado para exclusão.
ERROR_SERVICE_NO_THREAD	Não foi possível criar um thread para o serviço.
ERROR_SERVICE_REQUEST_TIMEOUT	O processo para o serviço foi iniciado, mas ele não chamou StartServiceCtrlDispatcher ou o thread que chamou StartServiceCtrlDispatcher pode ser bloqueado em uma função de manipulador de controle.

Comentários

Quando um serviço de driver é iniciado, a função StartService não retorna até que o driver do dispositivo termine de inicializar.

Quando um serviço é iniciado, o SCM (Service Control Manager) gera o processo de serviço, se necessário. Se o serviço especificado compartilhar um processo com outros serviços, o processo necessário poderá já existir. A função StartService não aguarda a primeira atualização status do novo serviço, pois pode demorar um pouco. Em vez disso, ele retorna quando o SCM recebe a notificação do dispatcher de controle de serviço de que o thread ServiceMain para esse serviço foi criado com êxito.

O SCM define os seguintes valores de status padrão antes de retornar de StartService:

O estado atual do serviço é definido como SERVICE_START_PENDING.
Os controles aceitos são definidos como nenhum (zero).
O valor do CheckPoint é definido como zero.
O tempo WaitHint é definido como 2 segundos.

O processo de chamada pode determinar se o novo serviço concluiu sua inicialização chamando a função QueryServiceStatus periodicamente para consultar o status do serviço.

Um serviço não pode chamar StartService durante a inicialização. O motivo é que o SCM bloqueia o banco de dados de controle de serviço durante a inicialização, portanto, uma chamada para StartService será bloqueada. Depois que o serviço relatar ao SCM que ele foi iniciado com êxito, ele poderá chamar StartService.

Assim como acontece com ControlService, StartService bloqueará por 30 segundos se qualquer serviço estiver ocupado tratando um código de controle. Se o serviço ocupado ainda não tiver retornado de sua função de manipulador quando o tempo limite expirar, StartService falhará com ERROR_SERVICE_REQUEST_TIMEOUT. Isso ocorre porque o SCM processa apenas uma notificação de controle de serviço por vez.

Exemplos

Para obter um exemplo, consulte Iniciando um serviço.

Observação

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


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