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 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 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 |
|---|---|
|
O serviço define a ação associada ao código de controle. O identificador hService deve ter o acesso de 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 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 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. |
|
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 ele 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 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 aos blocos ControlServiceEx 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 LocalSystem e os membros dos grupos Administradores e Usuários de Energia 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) |
| RUNNING | (a) | (a) |
| CONTINUE_PENDING | (a) | (a) |
| PAUSE_PENDING | (a) | (a) |
| PAUSED | (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 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 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.
Observação
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 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 Vista [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2008 [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
SERVICE_CONTROL_STATUS_REASON_PARAMS