Função TraceMessage (evntrace.h)

  • Artigo

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

Sintaxe

ULONG TraceMessage(
  [in] TRACEHANDLE LoggerHandle,
  [in] ULONG       MessageFlags,
  [in] LPCGUID     MessageGuid,
  [in] USHORT      MessageNumber,
       ...         
);

Parâmetros

[in] LoggerHandle

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] MessageFlags

Adiciona informações adicionais ao início da seção de dados específicos do provedor do evento. A seção de dados específicos do provedor do evento conterá dados somente para os sinalizadores que estão definidos. A lista variável de dados de argumento seguirá essas informações. Esse parâmetro pode usar um dos valores a seguir.

  • TRACE_MESSAGE_COMPONENTID

    Inclua o identificador de componente na mensagem. O parâmetro MessageGuid contém o identificador de componente.

  • TRACE_MESSAGE_GUID

    Inclua o GUID da classe de rastreamento de eventos na mensagem. O parâmetro MessageGuid contém o GUID da classe de rastreamento de eventos.

  • TRACE_MESSAGE_SEQUENCE

    Inclua um número de sequência na mensagem. O número da sequência começa em um. Para usar esse sinalizador, o controlador deve ter definido o modo de arquivo de log EVENT_TRACE_USE_GLOBAL_SEQUENCE ou EVENT_TRACE_USE_LOCAL_SEQUENCE ao criar a sessão.

  • TRACE_MESSAGE_SYSTEMINFO

    Inclua o identificador de thread e o identificador de processo na mensagem.

  • TRACE_MESSAGE_TIMESTAMP

    Inclua um carimbo de data/hora na mensagem.

TRACE_MESSAGE_COMPONENTID e TRACE_MESSAGE_GUID são mutuamente exclusivos.

As informações são incluídas nos dados do evento na seguinte ordem:

  • Número de sequência
  • GUID da classe de rastreamento de evento (ou identificador de componente)
  • Carimbo de data/hora
  • Identificador de thread
  • Identificador de processo

[in] MessageGuid

GUID de classe ou ID de componente que identifica a mensagem. Depende se MessageFlags contiver o sinalizador TRACE_MESSAGE_COMPONENTID ou TRACE_MESSAGE_GUID .

[in] MessageNumber

Número que identifica exclusivamente cada ocorrência da mensagem. Você deve definir o valor especificado para esse parâmetro; o valor deve ser significativo para o aplicativo.

...

Uma lista de argumentos variáveis a serem acrescentados à mensagem. Use esta lista para especificar os dados de evento específicos do provedor. A lista deve ser composta por pares de argumentos da seguinte maneira.

  • PVOID: ponteiro para os dados do argumento.
  • size_t: o tamanho dos dados do argumento, em bytes.

Encerre a lista usando um par de argumentos que consiste em um ponteiro para NULL e zero.

O chamador deve garantir que a soma dos tamanhos dos argumentos + 72 não exceda o tamanho do buffer da sessão de rastreamento de eventos.

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_HANDLE

    O LoggerHandle é NULL 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, TraceMessage descarta o evento.

    Windows 2000 e Windows XP: 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

    MessageFlags contém um valor que não é válido.

  • 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 WPP baseados em TMF chamam essa função.

Observação

A maioria dos desenvolvedores não chamará essa função diretamente. Os provedores WPP usam funções wrapper geradas por tracewpp.exe em vez de chamar APIs ETW.

Se você precisar acessar a funcionalidade de rastreamento de mensagens de uma função wrapper, chame a versão TraceMessageVa dessa função.

Os consumidores terão que usar o retorno de chamada EventCallback para receber e processar os eventos se o parâmetro MessageFlags não contiver o sinalizador TRACE_MESSAGE_GUID. Se você não especificar o sinalizador TRACE_MESSAGE_GUID, o consumidor não poderá usar EventClassCallback porque o membro Header.Guid da estrutura EVENT_TRACE não conterá o GUID da classe de rastreamento de eventos.

Observe que os membros das estruturas EVENT_TRACE e EVENT_TRACE_HEADER que correspondem aos sinalizadores MessageFlags serão definidos somente se o sinalizador correspondente for especificado. Por exemplo, os membros ThreadId e ProcessId de EVENT_TRACE_HEADER serão preenchidos somente se você especificar o sinalizador TRACE_MESSAGE_SYSTEMINFO.

Requisitos

   
Cliente mínimo com suporte Windows XP [aplicativos da área de trabalho | aplicativos UWP]
Servidor mínimo com suporte Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho evntrace.h
Biblioteca Advapi32.lib
DLL Advapi32.dll

Confira também

Traceevent

TraceEventInstance

TraceMessageVa