Função ControlServiceExA (winsvc.h)

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

Sintaxe

BOOL ControlServiceExA(
  [in]      SC_HANDLE hService,
  [in]      DWORD     dwControl,
  [in]      DWORD     dwInfoLevel,
  [in, out] PVOID     pControlParams
);

Parâmetros

[in] hService

Um identificador para o serviço. Esse identificador é retornado pela função do OpenService ou CreateService. Os direitos de acesso necessários para esse identificador dependem do código de 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 que ele deve ser retomado. O identificador hService deve ter o acesso SERVICE_PAUSE_CONTINUE correto.
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 acesso SERVICE_INTERROGATE correto. 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 acesso SERVICE_PAUSE_CONTINUE correto. No entanto, esse código de controle foi preterido; em vez disso, use a funcionalidade Plug and Play.
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 acesso SERVICE_PAUSE_CONTINUE correto. No entanto, esse código de controle foi preterido; em vez disso, use a funcionalidade Plug and Play.
SERVICE_CONTROL_NETBINDENABLE 0x00000009	Notifica um serviço de rede de que uma associação desabilitada foi habilitada. O identificador hService deve ter o acesso SERVICE_PAUSE_CONTINUE correto. No entanto, esse código de controle foi preterido; em vez disso, use a funcionalidade Plug and Play.
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 acesso SERVICE_PAUSE_CONTINUE correto. No entanto, esse código de controle foi preterido; em vez disso, use a funcionalidade Plug and Play.
SERVICE_CONTROL_PARAMCHANGE 0x00000006	Notifica um serviço de que seus parâmetros de inicialização foram alterados. O identificador hService deve ter o acesso SERVICE_PAUSE_CONTINUE correto.
SERVICE_CONTROL_PAUSE 0x00000002	Notifica um serviço de que ele deve pausar. O identificador hService deve ter o acesso SERVICE_PAUSE_CONTINUE correto.
SERVICE_CONTROL_STOP 0x00000001	Notifica um serviço que ele deve parar. O identificador hService deve ter o acesso SERVICE_STOP correto. Depois de enviar a solicitação de parada para um serviço, você não deve enviar outros controles para o serviço.

 

Esse parâmetro 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 de de hService deve ter o acesso SERVICE_USER_DEFINED_CONTROL correto.

[in] dwInfoLevel

O nível de informações para os parâmetros de controle de serviço. Esse parâmetro deve ser definido como SERVICE_CONTROL_STATUS_REASON_INFO (1).

[in, out] pControlParams

Um ponteiro para os parâmetros de controle de serviço. Se dwInfoLevel for SERVICE_CONTROL_STATUS_REASON_INFO, esse membro será um ponteiro para uma estrutura SERVICE_CONTROL_STATUS_REASON_PARAMS.

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. 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 no parâmetro dwControl é indefinido ou dwControl é SERVICE_CONTROL_STOP mas os membros dwReason ou pszComment da estrutura SERVICE_CONTROL_STATUS_REASON_PARAMS não são válidos.
ERROR_INVALID_SERVICE_CONTROL	O código de controle solicitado 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 ele não chamou StartServiceCtrlDispatcherou 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.

Observações

A função ControlServiceEx 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 ele 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 forma serial – ele aguarda 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 ControlServiceEx blocos por 30 segundos se algum 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, ControlServiceEx falhará com ERROR_SERVICE_REQUEST_TIMEOUT.

Para parar 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 LocalSysteme os membros dos grupos Administradores e Usuários Do Power interrompa e inicie os serviços. Para alterar o descritor de segurança de um serviço, consulte Modificando a DACL para umde serviço.

A função QueryServiceStatusEx retorna uma estrutura SERVICE_STATUS_PROCESS cujo dwCurrentState e membros de 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 aceita quando chama a função SetServiceStatus para relatar seu status. Um serviço sempre deve aceitar esses códigos quando ele estiver em execução, independentemente do que ele esteja 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	Parar	Outros controles
PARADO	(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, ControlServiceEx retorna zero e GetLastError retorna ERROR_INVALID_SERVICE_CONTROL.

(b)

O serviço não está em um estado no qual um controle pode ser enviado para ele, portanto, ControlServiceEx retorna zero e GetLastError retorna ERROR_SERVICE_CANNOT_ACCEPT_CTRL.

(c)

O serviço não está ativo, portanto, ControlServiceEx retorna zero e GetLastError retorna ERROR_SERVICE_NOT_ACTIVE.

Nota

O cabeçalho winsvc.h define ControlServiceEx 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 Vista [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2008 [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

CreateService

openservice

queryServiceStatusEx

SERVICE_CONTROL_STATUS_REASON_PARAMS

SERVICE_STATUS

solicitações de controle de serviço

Funções de serviço

SetServiceObjectSecurity

SetServiceStatus