Partilhar via

Posso personalizar DoTraceMessage?

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. O TraceDrv está disponível no repositório de exemplos de drivers 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, Flag 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 de compilador a partir da macro DoTraceMessage. Essa macro adiciona as informações de definição de mensagem e informações de formatação ao arquivo PDB que foi gerado para o provedor de rastreamento, como um driver de modo kernel ou 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);

Esta 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 PRE-logging e POST-logging tiverem sido definidas, elas também serão expandidas. As macros PRE e POST são suportadas no Microsoft Windows 2000 e sistemas operacionais posteriores. Para usar as macros, você deve criar o driver usando o WDK. Se você criar um driver usando uma versão anterior do Windows Driver Development Kit (DDK), 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. Compilar o driver usando uma versão anterior do DDK do Windows pode não causar uma quebra de compilação, mas o código não funcionará conforme o esperado.

DoTraceMessage: Formato geral

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

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

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

Condições é uma lista de valores separada por vírgula. A mensagem de rastreamento é gerada somente se todas as condições forem verdadeiras. Você pode especificar qualquer condição suportada no código.

Exemplo: MyTrace

Segue-se um exemplo de uma função de rastreio. 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 suportam a macro DoTraceMessage.

  • Adicione o parâmetro -func à instrução RUN_WPP que invoca o pré-processador WPP.

Escrever macros personalizadas

Para criar uma função de rastreamento personalizada que altere 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 suportam as funções de rastreamento, WPP_LEVEL_ENABLED e WPP_LEVEL_LOGGER.

  • WPP_LEVEL_ENABLED(Flags) determina se o registo 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 de WPP_LEVEL_ENABLED que inclua 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 de sinalizadores.

No exemplo de código a seguir, o valor flags 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,...)

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

Para obter uma lista completa dos parâmetros opcionais do RUN_WPP, consulte WPP Preprocessor.

  • Last updated on