Função OpenTraceW (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

ETW_APP_DECLSPEC_DEPRECATED TRACEHANDLE WMIAPI OpenTraceW(
  [in, out] PEVENT_TRACE_LOGFILEW 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

EVENT_TRACE_LOGFILE

CloseTrace

ProcessTrace