Posso personalizar o DoTraceMessage?

Artigo
06/15/2023

Sim, você pode escrever sua própria versão da macro DoTraceMessage . DoTraceMessage gera uma mensagem de rastreamento.

O driver de exemplo TraceDrv fornece um exemplo dos métodos descritos neste tópico. TraceDrv está disponível no repositório de exemplos de driver do Windows no GitHub.

DoTraceMessage: versão padrão

Por padrão, a macro DoTraceMessage tem o seguinte formato:

DoTraceMessage(Flag,"Message",MessageVariables...);

Nesta versão padrão, Sinalizador representa os sinalizadores de rastreamento, que são as condições sob as quais a mensagem é gerada. MessageVariables contém uma lista separada por vírgulas de variáveis que o driver define e que aparecem na mensagem de rastreamento. As variáveis MessageVariables são formatadas usando os elementos printf . O pré-processador WPP cria uma diretiva do compilador da macro DoTraceMessage. Essa macro adiciona as informações de definição de mensagem e as informações de formatação ao arquivo PDB que foi gerado para o provedor de rastreamento, como um driver de modo kernel ou um aplicativo de modo de usuário.

A macro DoTraceMessage é expandida, logicamente, para o seguinte:

PRE macro // If defined
If (WPP_CHECK_INIT && Flag is enabled) {
 ....Call WmiTraceMessage;
}
POST macro // If defined

Considere o exemplo de código a seguir.

DoTraceMessage(ERROR, "IOCTL = %d", ControlCode);

Essa chamada gera a mensagem de rastreamento quando o sinalizador ERROR está habilitado. A mensagem é "IOCTL=%d" e MessageVariables é o valor de ControlCode.

Se as macros pré-registro em log e POST-logging tiverem sido definidas, elas também serão expandidas. As macros PRE e POST têm suporte nos sistemas operacionais Microsoft Windows 2000 e posterior. Para usar as macros, você deve criar o driver usando o WDK. Se você criar um driver usando uma versão anterior do DDK (Kit de Desenvolvimento de Driver do Windows), a funcionalidade PRE e POST não estará disponível e as macros não serão executadas como parte da instrução de rastreamento. Criar o driver usando uma versão anterior do DDK do Windows pode não causar uma quebra de build, mas o código não funcionará conforme o esperado.

DoTraceMessage: Formato Geral

Veja a seguir um formato geral de uma função de mensagem de rastreamento válida:

FunctionName(Conditions...,"Message",MessageVariables...);

Parâmetros que aparecem antes da mensagem são interpretados como condições. Parâmetros que aparecem após a mensagem são interpretados como variáveis de mensagem.

As condições são uma lista separada por vírgulas de valores. A mensagem de rastreamento será gerada somente se todas as condições forem verdadeiras. Você pode especificar qualquer condição com suporte no código.

Exemplo: MyTrace

Veja a seguir um exemplo de uma função de rastreamento. Este exemplo adiciona condições para o nível de rastreamento e o subcomponente do provedor que está gerando a mensagem de rastreamento.

MyDoTrace(Level, Flag, Subcomponent,"Message",MessageVariables...);

Por exemplo:

MyDoTrace(TRACE_LEVEL_ERROR, VERBOSE, Network,"IOCTL = %d", ControlCode);

O nível de rastreamento é o nível padrão definido em Evntrace.h, um arquivo de cabeçalho público que está no subdiretório Include do WDK.

#define TRACE_LEVEL_NONE        0   // Tracing is not on
#define TRACE_LEVEL_FATAL       1   // Abnormal exit or termination
#define TRACE_LEVEL_ERROR       2   // Severe errors that need logging
#define TRACE_LEVEL_WARNING     3   // Warnings such as allocation failure
#define TRACE_LEVEL_INFORMATION 4   // Includes non-error cases(for example, Entry-Exit)
#define TRACE_LEVEL_VERBOSE     5   // Detailed traces from intermediate steps
#define TRACE_LEVEL_RESERVED6   6
#define TRACE_LEVEL_RESERVED7   7
#define TRACE_LEVEL_RESERVED8   8
#define TRACE_LEVEL_RESERVED9   9

Como criar uma função de rastreamento personalizada

Para criar uma função de rastreamento personalizada, siga estas etapas:

Escreva versões alternativas das macros que dão suporte à macro DoTraceMessage.
Adicione o parâmetro -func à instrução RUN_WPP que invoca o pré-processador WPP.

Gravar macros personalizadas

Para criar uma função de rastreamento personalizada que altera as condições de uma mensagem de rastreamento (os parâmetros que aparecem antes da mensagem), você deve escrever versões alternativas das macros que dão suporte às funções de rastreamento, WPP_LEVEL_ENABLED e WPP_LEVEL_LOGGER.

WPP_LEVEL_ENABLED(Flags) determina se o registro em log está habilitado com o valor do sinalizador especificado. Ele retorna TRUE ou FALSE.
WPP_LEVEL_LOGGER(Flags) localiza a sessão de rastreamento para a qual o provedor está habilitado e retorna um identificador para a sessão de rastreamento.

Por exemplo, se você quiser incluir o nível de rastreamento, além de sinalizadores, como uma condição, defina uma nova macro WPP_LEVEL_ENABLED que inclui o nível de rastreamento. Você pode basear a definição da nova macro na macro padrão, como mostra o exemplo de código a seguir.

#define WPP_LEVEL_FLAGS_ENABLED(lvl, flags) (WPP_LEVEL_ENABLED(flags) && WPP_CONTROL(WPP_BIT_ ## flags).Level >=lvl

Normalmente, a macro WPP_LEVEL_LOGGER não é afetada. Nesses casos, você pode definir a nova macro como macro padrão. Por exemplo:

#define WPP_LEVEL_FLAGS_LOGGER(lvl,flags) WPP_LEVEL_LOGGER(flags)

No entanto, em alguns casos, você precisa alterar a macro LOGGER. Por exemplo, talvez você queira escrever uma função de rastreamento que dependa apenas do nível de rastreamento e não dos sinalizadores.

No exemplo de código a seguir, o valor de sinalizadores na macro é substituído por um valor fictício. Nenhum sinalizador é definido ao declarar a definição de GUID de controle.

#define WPP_CONTROL_GUIDS \
   WPP_DEFINE_CONTROL_GUID(CtlGuid,(a044090f,3d9d,48cf,b7ee,9fb114702dc1),  \
        WPP_DEFINE_BIT(DUMMY))

#define WPP_LEVEL_LOGGER(lvl) (WPP_CONTROL(WPP_BIT_ ## DUMMY).Logger)

Adicionar a função ao WPP

Para adicionar a função de rastreamento personalizada ao WPP, adicione o parâmetro -func à instrução RUN_WPP com uma declaração da função, como mostra o exemplo de código a seguir.

RUN_WPP=$(SOURCES) -km -func:DoTraceLevelMessage(LEVEL,FLAGS,MSG,...)

Nota Você não deve especificar a opção -km na diretiva RUN_WPP para aplicativos de modo de usuário ou DLLs (bibliotecas de vínculo dinâmico).

Para obter uma lista completa dos parâmetros opcionais para RUN_WPP, consulte Pré-processador WPP.

Compartilhar via