Função QueryServiceStatusEx (winsvc.h)

  • Artigo

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
ERROR_INVALID_HANDLE
 O manipulador é inválido.
ERROR_ACCESS_DENIED
 O identificador não tem o acesso de SERVICE_QUERY_STATUS correto.
ERROR_INSUFFICIENT_BUFFER
 O buffer é muito pequeno para a estrutura de SERVICE_STATUS_PROCESS . Nada foi escrito na estrutura.
ERROR_INVALID_PARAMETER
 O membro cbSize do SERVICE_STATUS_PROCESS não é válido.
ERROR_INVALID_LEVEL
 O parâmetro InfoLevel contém um valor sem suporte.
ERROR_SHUTDOWN_IN_PROGRESS
 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

Confira também

SERVICE_STATUS_PROCESS

Funções de serviço

Inicialização de serviço