Função QueryTraceA (evntrace.h)
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(
CONTROLTRACE_ID TraceId,
LPCSTR InstanceName,
PEVENT_TRACE_PROPERTIES Properties
);
Parâmetros
TraceId
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.
A partir do Windows 10, versão 1703: Para obter um 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 |