Função TraceEvent (evntrace.h)

Um provedor de eventos baseado em RegisterTraceGuids ("Clássico") usa a função TraceEvent para enviar um evento estruturado para uma sessão de rastreamento de eventos.

Sintaxe

ULONG WMIAPI TraceEvent(
  [in] TRACEHANDLE         TraceHandle,
  [in] PEVENT_TRACE_HEADER EventTrace
);

Parâmetros

[in] TraceHandle

Manipule para a sessão de rastreamento de eventos que registra o evento. O provedor obtém o identificador quando chama a função GetTraceLoggerHandle em sua implementação ControlCallback .

[in] EventTrace

Ponteiro para uma estrutura EVENT_TRACE_HEADER . Opcionalmente, os dados específicos do evento são acrescentados à estrutura. O maior evento que você pode registrar é um pouco menor que 64K. Você deve especificar valores para os seguintes membros da estrutura EVENT_TRACE_HEADER .

  • Tamanho
  • Guid ou GuidPtr
  • Sinalizadores

Dependendo da complexidade das informações fornecidas pelo provedor, você também deve considerar a especificação de valores para os membros a seguir.

  • Class.Type
  • Class.Level

Valor retornado

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_INVALID_FLAG_NUMBER

    O membro Flags da estrutura EVENT_TRACE_HEADER está incorreto.

  • ERROR_INVALID_HANDLE

    TraceHandle não é válido ou especifica o identificador de sessão do Agente do Kernel NT.

  • ERROR_NOT_ENOUGH_MEMORY

    A sessão ficou sem buffers livres para gravação. Isso pode ocorrer durante as altas taxas de eventos porque o subsistema do disco está sobrecarregado ou o número de buffers é muito pequeno. Em vez de bloquear até que mais buffers fiquem disponíveis, TraceEvent descarta o evento.

    Considere aumentar o número e o tamanho dos buffers para a sessão ou reduzir o número de eventos gravados ou o tamanho dos eventos.

    Windows 2000: Sem suporte.

  • ERROR_OUTOFMEMORY

    O evento é descartado porque, embora o pool de buffers não tenha atingido seu tamanho máximo, não há memória disponível suficiente para alocar um buffer adicional e não há nenhum buffer disponível para receber o evento.

  • ERROR_INVALID_PARAMETER

    Uma das seguintes condições é verdadeira:

    • TraceHandle é NULL.
    • EventTrace é NULL.
    • O membro Size da estrutura EVENT_TRACE_HEADER está incorreto.
  • ERROR_MORE_DATA

    Os dados de um único evento não podem abranger vários buffers. Um evento de rastreamento é limitado ao tamanho do buffer da sessão de rastreamento de eventos menos o tamanho da estrutura EVENT_TRACE_HEADER .

Comentários

Os provedores ETW baseados em MOF chamam essa função.

Observação

A maioria dos desenvolvedores não chamará essa função. Essa API dá suporte ao ETW baseado em MOF, mas o ETW baseado em MOF foi preterido em favor do ETW baseado em manifesto. Além disso, a maioria dos provedores baseados em MOF usa funções wrapper geradas por MC.exe em vez de chamar diretamente APIs ETW.

Antes que o provedor possa chamar essa função, o provedor

  • Deve chamar a função RegisterTraceGuids para se registrar e a classe de rastreamento de evento.
  • Deve estar habilitado. Um controlador chama a função EnableTrace para habilitar um provedor.

O evento é gravado em um arquivo de log, enviado para consumidores de rastreamento de eventos em tempo real ou ambos. O membro LogFileMode da estrutura EVENT_TRACE_PROPERTIES passada para o StartTrace define para onde o evento é enviado.

Os eventos de rastreamento são gravados na ordem em que ocorrem.

Para rastrear um conjunto de eventos relacionados, use a função TraceEventInstance .

No Windows Vista, você deve usar a função EventWrite para registrar eventos.

Exemplos

Para obter um exemplo que usa TraceEvent, consulte Eventos de rastreamento.

Requisitos

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

Confira também

EVENT_TRACE_HEADER

EnableTrace

RegisterTraceGuids

TraceEventInstance