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.
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 |
|---|---|
|
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 |
|---|---|
|
O identificador não tem o direito de acesso necessário. |
|
O serviço não pode ser interrompido porque outros serviços em execução dependem dele. |
|
O identificador especificado não foi obtido usando CreateService ou OpenService ou o identificador não é mais válido. |
|
O código de controle solicitado é indefinido. |
|
O código de controle pedido não é válido ou é inaceitável para o serviço. |
|
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. |
|
O serviço não foi iniciado. |
|
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. |
|
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 |