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 |