Compartilhar via


Função OpenTraceA (evntrace.h)

A função OpenTrace abre um identificador de processamento de rastreamento ETW para consumir eventos de uma sessão de rastreamento em tempo real do ETW ou de um arquivo de log ETW.

Sintaxe

PROCESSTRACE_HANDLE WMIAPI OpenTraceA(
  [in, out] PEVENT_TRACE_LOGFILEA Logfile
);

Parâmetros

[in, out] Logfile

Ponteiro para uma estrutura EVENT_TRACE_LOGFILE . A estrutura especifica a origem da qual consumir eventos (de um arquivo de log ETW ou de uma sessão ETW em tempo real) e especifica os retornos de chamada que o consumidor deseja usar para receber os eventos. Em caso de êxito, o OpenTrace atualizará a estrutura com informações do arquivo ou da sessão aberta.

Retornar valor

Se a função for bem-sucedida, ela retornará o identificador de processamento de rastreamento. O identificador deve ser fechado usando CloseTrace.

Se a função falhar, ela retornará INVALID_PROCESSTRACE_HANDLE. (INVALID_PROCESSTRACE_HANDLE é equivalente a (UINT64)UINTPTR_MAX.)

Observação

Antes do Windows Vista, o OpenTrace retornava UINT64_MAX em caso de falha. Se o código der suporte a sistemas operacionais mais antigos (Windows XP ou Windows Server 2003) e versões mais recentes do Windows (Windows Vista e posterior), você deverá determinar o sistema operacional no qual você está executando e comparar o valor retornado com o valor apropriado.

Sistema operacional Tipo de processo Valor que indica falha
Antes do Windows Vista 32 ou 64 bits 0XFFFFFFFFFFFFFFFF = UINT64_MAX
Windows Vista ou posterior 32 bits 0x00000000FFFFFFFF = (UINT64)UINTPTR_MAX
Windows Vista ou posterior 64 bits 0XFFFFFFFFFFFFFFFF = (UINT64)UINTPTR_MAX

Se a função falhar, você poderá usar a função GetLastError para obter informações de erro estendidas. Veja a seguir alguns erros comuns e suas causas.

  • ERROR_INVALID_PARAMETER

    O parâmetro Logfile é NULL.

  • ERROR_BAD_PATHNAME

    Se você não especificou o membro LoggerName do EVENT_TRACE_LOGFILE, especifique um nome de arquivo de log válido.

  • ERROR_ACCESS_DENIED

    Somente usuários com privilégios administrativos, usuários no grupo Usuários do Log de Desempenho e serviços em execução como LocalSystem, LocalService, NetworkService podem consumir eventos em tempo real. Para conceder a um usuário restrito a capacidade de consumir eventos em tempo real, adicione-os ao grupo Usuários do Log de Desempenho.

    Windows XP e Windows 2000: Qualquer pessoa pode consumir eventos em tempo real.

Comentários

Os consumidores de rastreamento chamam essa função para abrir uma sessão de processamento de rastreamento.

Depois de chamar OpenTrace, chame a função ProcessTrace para processar os eventos. Quando terminar de processar eventos, chame a função CloseTrace para fechar o identificador de processamento de rastreamento.

Exemplos

Para obter um exemplo que usa OpenTrace, consulte Usando TdhFormatProperty para consumir dados de evento.

Observação

O cabeçalho evntrace.h define OpenTrace 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 Sechost.lib em Windows 8.1 e Windows Server 2012 R2; Advapi32.lib em Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista e Windows XP
DLL Sechost.dll em Windows 8.1 e Windows Server 2012 R2; Advapi32.dll em Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista e Windows XP

Confira também

CloseTrace

EVENT_TRACE_LOGFILE

ProcessTrace