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.
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 de de |
[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 |
|---|---|
|
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 solicitado 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 StartServiceCtrlDispatcherou o thread que chamou StartServiceCtrlDispatcher pode ser bloqueado em uma função de manipulador de controle. |
|
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
SERVICE_CONTROL_STATUS_REASON_PARAMS