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