Função QueryServiceStatusEx (winsvc.h)
Recupera o status atual do serviço especificado com base no nível de informações especificado.
Sintaxe
BOOL QueryServiceStatusEx(
[in] SC_HANDLE hService,
[in] SC_STATUS_TYPE InfoLevel,
[out, optional] LPBYTE lpBuffer,
[in] DWORD cbBufSize,
[out] LPDWORD pcbBytesNeeded
);
Parâmetros
[in] hService
Um identificador para o serviço. Esse identificador é retornado pela função CreateService ou OpenService e deve ter o acesso SERVICE_QUERY_STATUS correto. Para obter mais informações, consulte Segurança do serviço e Direitos de Acesso.
[in] InfoLevel
Os atributos de serviço a serem retornados. Use SC_STATUS_PROCESS_INFO para recuperar as informações de status de serviço. O parâmetro lpBuffer é um ponteiro para uma estrutura SERVICE_STATUS_PROCESS .
Atualmente, nenhum outro nível de informação é definido.
[out, optional] lpBuffer
Um ponteiro para o buffer que recebe as informações de status. O formato desses dados depende do valor do parâmetro InfoLevel .
O tamanho máximo dessa matriz é de 8K bytes. Para determinar o tamanho necessário, especifique NULL para esse parâmetro e 0 para o parâmetro cbBufSize . A função falhará e GetLastError retornará ERROR_INSUFFICIENT_BUFFER. O parâmetro pcbBytesNeeded receberá o tamanho necessário.
[in] cbBufSize
O tamanho do buffer apontado pelo parâmetro lpBuffer , em bytes.
[out] pcbBytesNeeded
Um ponteiro para uma variável que recebe o número de bytes necessários para armazenar todas as informações status, se a função falhar com ERROR_INSUFFICIENT_BUFFER.
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 erros a seguir podem ser retornados.
| Código de retorno | Descrição |
|---|---|
|
O manipulador é inválido. |
|
O identificador não tem o acesso de SERVICE_QUERY_STATUS correto. |
|
O buffer é muito pequeno para a estrutura de SERVICE_STATUS_PROCESS . Nada foi escrito na estrutura. |
|
O membro cbSize do SERVICE_STATUS_PROCESS não é válido. |
|
O parâmetro InfoLevel contém um valor sem suporte. |
|
O sistema está sendo desligado; essa função não pode ser chamada. |
Comentários
A função QueryServiceStatusEx retorna o serviço mais recente status informações relatadas ao gerenciador de controle de serviço. Se o serviço acabou de alterar seu status, talvez ele ainda não tenha atualizado o gerenciador de controle de serviço.
O identificador de processo retornado na estrutura SERVICE_STATUS_PROCESS é válido desde que o estado do serviço seja um dos SERVICE_RUNNING, SERVICE_PAUSE_PENDING, SERVICE_PAUSED ou SERVICE_CONTINUE_PENDING. Se o serviço estiver em um estado SERVICE_START_PENDING ou SERVICE_STOP_PENDING, no entanto, o identificador de processo poderá não ser válido e, se o serviço estiver no estado SERVICE_STOPPED, ele nunca será válido.
Exemplos
Para obter um exemplo, consulte Iniciando um serviço ou 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 (inclua Windows.h) |
| Biblioteca | Advapi32.lib |
| DLL | Advapi32.dll |