Função QueryTraceA (evntrace.h)

  • Artigo

A função QueryTrace recupera as configurações de propriedade e as estatísticas de sessão para a sessão de rastreamento de eventos especificada.

Essa função está obsoleta. A função ControlTrace substitui essa função.

Sintaxe

ULONG WMIAPI QueryTraceA(
  TRACEHANDLE             TraceHandle,
  LPCSTR                  InstanceName,
  PEVENT_TRACE_PROPERTIES Properties
);

Parâmetros

TraceHandle

Manipule para a sessão de rastreamento de eventos a ser consultada ou 0. Você deve especificar um TraceHandle diferente de zero se InstanceName for NULL. Esse parâmetro será usado somente se InstanceName for NULL. O identificador é retornado pelo StartTrace.

InstanceName

Nome da sessão de rastreamento de eventos a ser consultada ou NULL. Você deve especificar InstanceName se TraceHandle for 0.

Para especificar a sessão do Agente do Kernel NT, defina InstanceNamecomo KERNEL_LOGGER_NAME.

Properties

Ponteiro para uma estrutura de EVENT_TRACE_PROPERTIES inicializada.

Você só precisa definir o membro Wnode.BufferSize da estrutura EVENT_TRACE_PROPERTIES . Você pode usar o nome máximo da sessão (1024 caracteres) e os comprimentos máximos do nome do arquivo de log (1024 caracteres) para calcular o tamanho e os deslocamentos do buffer, se não forem conhecidos.

Na saída, os membros da estrutura contêm as configurações de propriedade e as estatísticas de sessão para a sessão de rastreamento de eventos.

Começando com Windows 10, versão 1703: para obter melhor desempenho em cenários de processo cruzado, agora você pode passar a filtragem para QueryTrace para agentes privados de todo o sistema. Você precisará passar a nova estrutura de EVENT_TRACE_PROPERTIES_V2 para incluir informações de filtragem. Consulte Configurando e iniciando uma sessão de agente privado para obter mais detalhes.

Retornar valor

Se a função obtiver êxito, o valor retornado será ERROR_SUCCESS.

Se a função falhar, o valor retornado será um dos códigos de erro do sistema. Veja a seguir alguns erros comuns e suas causas.

  • ERROR_BAD_LENGTH

    Uma das seguintes condições é verdadeira:

    • O membro Wnode.BufferSize de Properties especifica um tamanho incorreto.
    • As propriedades não têm espaço suficiente alocado para manter uma cópia do nome da sessão e do nome do arquivo de log (se usado).

  • ERROR_INVALID_PARAMETER

    Uma das seguintes condições é verdadeira:

    • As propriedades são NULL.
    • InstanceName e TraceHandle são NULL.
    • InstanceName é NULL e TraceHandle não é um identificador válido.

  • ERROR_ACCESS_DENIED

    Somente usuários em execução com privilégios administrativos elevados, usuários no grupo Usuários do Log de Desempenho e serviços em execução como LocalSystem, LocalService, NetworkService podem consultar sessões de rastreamento de eventos. Para conceder a um usuário restrito a capacidade de consultar sessões de rastreamento, adicione-as ao grupo Usuários do Log de Desempenho ou consulte EventAccessControl.

    Windows XP e Windows 2000: Qualquer pessoa pode controlar uma sessão de rastreamento.

  • ERROR_WMI_INSTANCE_NOT_FOUND

    A sessão fornecida não está em execução.

Comentários

Os controladores de rastreamento de eventos chamam essa função.

Essa função está obsoleta. Em vez disso, use ControlTrace com ControlCode definido como EVENT_TRACE_CONTROL_QUERY.

Observação

O cabeçalho evntrace.h define QueryTrace 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

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho evntrace.h
Biblioteca Advapi32.lib
DLL Advapi32.dll

Confira também

ControlTrace

QueryAllTraces