Função TraceMessageVa (evntrace.h)
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 |