Função TraceMessage (evntrace.h)

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.

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

Confira também

Traceevent

TraceEventInstance

TraceMessageVa