Compartilhar via

Função StartServiceA (winsvc.h)

  • Artigo

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 do OpenService ou CreateService e deve ter o acesso SERVICE_START correto. Para obter mais informações, consulte de Direitos de Acesso e Segurança do Serviço.

[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 de retorno

Se a função for bem-sucedida, o valor retornado não será 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 SERVICE_START correto.
ERROR_INVALID_HANDLE
 O identificador é 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 pôde ser 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 StartServiceCtrlDispatcherou o thread que chamou StartServiceCtrlDispatcher pode ser bloqueado em uma função de manipulador de controle.

Observações

Quando um serviço de driver é iniciado, a função StartService não retorna até que o driver do dispositivo tenha terminado 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 já poderá existir. A função StartService não aguarda a primeira atualização de 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 ServiceMain thread 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 está definido como SERVICE_START_PENDING.
  • Os controles aceitos são definidos como nenhum (zero).
  • O valor do CheckPoint é definido como zero.
  • O tempo de WaitHint é definido como 2 segundos.
O processo de chamada pode determinar se o novo serviço terminou 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 será bloqueado 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.

Nota

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 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

ControlService

CreateService

DeleteService

openservice

QueryServiceDynamicInformation

queryServiceStatusEx

Funções de serviço

de inicialização do serviço

do ServiceMain