Compartilhar via


Função ControlService (winsvc.h)

Envia um código de controle para um serviço.

Para especificar informações adicionais ao parar um serviço, use a função ControlServiceEx .

Sintaxe

BOOL ControlService(
  [in]  SC_HANDLE        hService,
  [in]  DWORD            dwControl,
  [out] LPSERVICE_STATUS lpServiceStatus
);

Parâmetros

[in] hService

Um identificador para o serviço. Esse identificador é retornado pela função OpenService ou CreateService . Os direitos de acesso necessários para esse identificador dependem do código dwControl solicitado.

[in] dwControl

Esse parâmetro pode ser um dos seguintes códigos de controle.

Código de controle Significado
SERVICE_CONTROL_CONTINUE
0x00000003
Notifica um serviço em pausa de que ele deve ser retomado. O identificador hService deve ter o direito de acesso SERVICE_PAUSE_CONTINUE .
SERVICE_CONTROL_INTERROGATE
0x00000004
Notifica um serviço de que ele deve relatar suas informações de status atuais ao gerenciador de controle de serviço. O identificador hService deve ter o direito de acesso SERVICE_INTERROGATE .

Observe que esse controle geralmente não é útil, pois o SCM está ciente do estado atual do serviço.

SERVICE_CONTROL_NETBINDADD
0x00000007
Notifica um serviço de rede de que há um novo componente para associação. O identificador hService deve ter o direito de acesso SERVICE_PAUSE_CONTINUE . No entanto, esse código de controle foi preterido; use Plug and Play funcionalidade.
SERVICE_CONTROL_NETBINDDISABLE
0x0000000A
Notifica um serviço de rede de que uma de suas associações foi desabilitada. O identificador hService deve ter o direito de acesso SERVICE_PAUSE_CONTINUE . No entanto, esse código de controle foi preterido; use Plug and Play funcionalidade.
SERVICE_CONTROL_NETBINDENABLE
0x00000009
Notifica um serviço de rede de que uma associação desabilitada foi habilitada. O identificador hService deve ter o direito de acesso SERVICE_PAUSE_CONTINUE . No entanto, esse código de controle foi preterido; use Plug and Play funcionalidade.
SERVICE_CONTROL_NETBINDREMOVE
0x00000008
Notifica um serviço de rede de que um componente para associação foi removido. O identificador hService deve ter o direito de acesso SERVICE_PAUSE_CONTINUE . No entanto, esse código de controle foi preterido; use Plug and Play funcionalidade.
SERVICE_CONTROL_PARAMCHANGE
0x00000006
Notifica um serviço de que seus parâmetros de inicialização foram alterados. O identificador hService deve ter o direito de acesso SERVICE_PAUSE_CONTINUE .
SERVICE_CONTROL_PAUSE
0x00000002
Notifica um serviço de que ele deve pausar. O identificador hService deve ter o direito de acesso SERVICE_PAUSE_CONTINUE .
SERVICE_CONTROL_STOP
0x00000001
Notifica um serviço de que ele deve parar. O identificador hService deve ter o direito de acesso SERVICE_STOP .

Depois de enviar a solicitação de parada para um serviço, você não deve enviar outros controles para o serviço.

 

Esse valor também pode ser um código de controle definido pelo usuário, conforme descrito na tabela a seguir.

Código de controle Significado
Intervalo de 128 a 255
O serviço define a ação associada ao código de controle. O identificador hService deve ter o direito de acesso SERVICE_USER_DEFINED_CONTROL .

[out] lpServiceStatus

Um ponteiro para uma estrutura SERVICE_STATUS que recebe as informações de status de serviço mais recentes. As informações retornadas refletem as status mais recentes que o serviço relatou ao gerenciador de controle de serviço.

O gerenciador de controle de serviço preenche a estrutura somente quando GetLastError retorna um dos seguintes códigos de erro: NO_ERROR, ERROR_INVALID_SERVICE_CONTROL, ERROR_SERVICE_CANNOT_ACCEPT_CTRL ou ERROR_SERVICE_NOT_ACTIVE. Caso contrário, a estrutura não será preenchida.

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_ACCESS_DENIED
O identificador não tem o direito de acesso necessário.
ERROR_DEPENDENT_SERVICES_RUNNING
O serviço não pode ser interrompido porque outros serviços em execução dependem dele.
ERROR_INVALID_HANDLE
O identificador especificado não foi obtido usando CreateService ou OpenService ou o identificador não é mais válido.
ERROR_INVALID_PARAMETER
O código de controle solicitado é indefinido.
ERROR_INVALID_SERVICE_CONTROL
O código de controle pedido não é válido ou é inaceitável para o serviço.
ERROR_SERVICE_CANNOT_ACCEPT_CTRL
O código de controle solicitado não pode ser enviado ao serviço porque o estado do serviço é SERVICE_STOPPED, SERVICE_START_PENDING ou SERVICE_STOP_PENDING.
ERROR_SERVICE_NOT_ACTIVE
O serviço não foi iniciado.
ERROR_SERVICE_REQUEST_TIMEOUT
O processo para o serviço foi iniciado, mas não chamou StartServiceCtrlDispatcher ou o thread que chamou StartServiceCtrlDispatcher pode ser bloqueado em uma função de manipulador de controle.
ERROR_SHUTDOWN_IN_PROGRESS
O sistema está sendo desligado.

Comentários

A função ControlService solicita que o SCM (Service Control Manager) envie o código de controle solicitado para o serviço. O SCM envia o código se o serviço tiver especificado que aceitará o código e está em um estado no qual um código de controle pode ser enviado a ele.

O SCM processa as notificações de controle de serviço de maneira serial— ele aguardará até que um serviço conclua o processamento de uma notificação de controle de serviço antes de enviar a próxima. Por isso, uma chamada para ControlService será bloqueada por 30 segundos se algum serviço estiver ocupado manipulando 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, ControlService falhará com ERROR_SERVICE_REQUEST_TIMEOUT.

Para interromper e iniciar um serviço, é necessário um descritor de segurança que permita que você faça isso. O descritor de segurança padrão permite que a conta LocalSystem e os membros dos grupos Administradores e Usuários Avançados interrompam e iniciem serviços. Para alterar o descritor de segurança de um serviço, consulte Modificando a DACL para um serviço.

A função QueryServiceStatusEx retorna uma estrutura SERVICE_STATUS_PROCESS cujos membros dwCurrentState e dwControlsAccepted indicam o estado atual e os controles aceitos por um serviço em execução. Todos os serviços em execução aceitam o código de controle SERVICE_CONTROL_INTERROGATE por padrão. Os drivers não aceitam códigos de controle diferentes de SERVICE_CONTROL_STOP e SERVICE_CONTROL_INTERROGATE. Cada serviço especifica os outros códigos de controle que ele aceita quando chama a função SetServiceStatus para relatar seu status. Um serviço sempre deve aceitar esses códigos quando estiver em execução, independentemente do que estiver fazendo.

A tabela a seguir mostra a ação do SCM em cada um dos estados de serviço possíveis.

Estado do serviço Stop Outros controles
STOPPED (c) (c)
STOP_PENDING (b) (b)
START_PENDING (a) (b)
EXECUTANDO (a) (a)
CONTINUE_PENDING (a) (a)
PAUSE_PENDING (a) (a)
PAUSADO (a) (a)
(a)
Se o serviço aceitar esse código de controle, envie a solicitação para o serviço; caso contrário, ControlService retornará zero e GetLastError retornará ERROR_INVALID_SERVICE_CONTROL.
(b)
O serviço não está em um estado no qual um controle pode ser enviado para ele, portanto ControlService retorna zero e GetLastError retorna ERROR_SERVICE_CANNOT_ACCEPT_CTRL.
(c)
O serviço não está ativo, portanto , ControlService retorna zero e GetLastError retorna ERROR_SERVICE_NOT_ACTIVE.

Exemplos

Para obter um exemplo, consulte Parando um serviç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 (incluir Windows.h)
Biblioteca AdvApi32.lib
DLL AdvApi32.dll

Confira também

ControlServiceEx

CreateService

Openservice

QueryServiceStatusEx

SERVICE_STATUS

Solicitações de controle de serviço

Funções de serviço

SetServiceObjectSecurity

SetServiceStatus