Função TraceMessageVa (evntrace.h)

  • Artigo

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

Sintaxe

ULONG TraceMessageVa(
  [in] TRACEHANDLE LoggerHandle,
  [in] ULONG       MessageFlags,
  [in] LPCGUID     MessageGuid,
  [in] USHORT      MessageNumber,
  [in] va_list     MessageArgList
);

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ífica do provedor do evento conterá dados somente para os sinalizadores 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_GUID: inclua o GUID da classe de rastreamento de evento 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 de sequência começa em um. Para usar esse sinalizador, o controlador deve ter definido o EVENT_TRACE_USE_GLOBAL_SEQUENCE ou EVENT_TRACE_USE_LOCAL_SEQUENCE modo de arquivo de log 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.

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

  • Número de sequência
  • GUID da classe de rastreamento de eventos
  • Carimbo de data/hora
  • Identificador de thread
  • Identificador de processo

[in] MessageGuid

GUID de classe que identifica a mensagem de rastreamento de evento.

[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.

[in] MessageArgList

Lista de argumentos variáveis a serem acrescentados à mensagem. 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. A tabela a seguir inclui alguns erros comuns e suas causas.

  • ERROR_INVALID_HANDLE

    O LoggerHandle é NULL ou especifica o identificador de sessão do Agente de 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ê não precisar acessar a funcionalidade de rastreamento de mensagens de uma função wrapper, poderá chamar a versão TraceMessage dessa função.

Os consumidores precisarão 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 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho evntrace.h
Biblioteca Advapi32.lib
DLL Advapi32.dll

Confira também

Traceevent

TraceEventInstance

TraceMessage