Compartir a través de

¿Puedo personalizar DoTraceMessage?

  • Artículo

Sí, puede escribir su propia versión de la macro DoTraceMessage . DoTraceMessage genera un mensaje de seguimiento.

El controlador de ejemplo TraceDrv proporciona un ejemplo de los métodos que se describen en este tema. TraceDrv está disponible en el repositorio de ejemplos de controladores de Windows en GitHub.

DoTraceMessage: versión predeterminada

De forma predeterminada, la macro DoTraceMessage tiene el siguiente formato:

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

En esta versión predeterminada, Flag representa las marcas de seguimiento, que son las condiciones en las que se genera el mensaje. MessageVariables contiene una lista separada por comas de variables que define el controlador y que aparecen en el mensaje de seguimiento. Las variables MessageVariables tienen formato mediante los elementos printf . El preprocesador de WPP crea una directiva del compilador a partir de la macro DoTraceMessage. Esta macro agrega la información de definición de mensaje y la información de formato al archivo PDB que se generó para el proveedor de seguimiento, como un controlador en modo kernel o una aplicación en modo usuario.

La macro DoTraceMessage se expande, lógicamente, en lo siguiente:

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

Tenga en cuenta el siguiente código de ejemplo.

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

Esta llamada genera el mensaje de seguimiento cuando la marca ERROR está habilitada. El mensaje es "IOCTL=%d" y MessageVariables es el valor de ControlCode.

Si se han definido las macros REGISTRO PREVIO y REGISTRO POST, también se expandirán. Las macros PRE y las macros POST se admiten en sistemas operativos de Microsoft Windows 2000 y versiones posteriores. Para usar las macros, debe compilar el controlador mediante el WDK. Si compila un controlador con una versión anterior del Kit de desarrollo de controladores de Windows (DDK), la funcionalidad PRE y POST no está disponible y las macros no se ejecutarán como parte de la instrucción de seguimiento. La compilación del controlador mediante una versión anterior de Windows DDK podría no provocar un salto de compilación, pero el código no funcionará según lo previsto.

DoTraceMessage: formato general

A continuación se muestra un formato general de una función de mensaje de seguimiento válida:

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

Los parámetros que aparecen antes del mensaje se interpretan como condiciones. Los parámetros que aparecen después del mensaje se interpretan como variables de mensaje.

Las condiciones son una lista separada por comas de valores. El mensaje de seguimiento solo se genera si todas las condiciones son verdaderas. Puede especificar cualquier condición que se admita en el código.

Ejemplo: MyTrace

A continuación se muestra un ejemplo de una función de seguimiento. En este ejemplo se agregan condiciones para el nivel de seguimiento y el subcomponente del proveedor que genera el mensaje de seguimiento.

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

Por ejemplo:

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

El nivel de seguimiento es el nivel estándar que se define en Evntrace.h, un archivo de encabezado público que se encuentra en el subdirectorio Include del 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

Cómo crear una función de seguimiento personalizada

Para crear una función de seguimiento personalizada, siga estos pasos:

  • Escriba versiones alternativas de las macros que admiten la macro DoTraceMessage.

  • Agregue el parámetro -func a la instrucción RUN_WPP que invoca el preprocesador de WPP.

Escribir macros personalizadas

Para crear una función de seguimiento personalizada que cambie las condiciones de un mensaje de seguimiento (los parámetros que aparecen antes del mensaje), debe escribir versiones alternativas de las macros que admiten las funciones de seguimiento, WPP_LEVEL_ENABLED y WPP_LEVEL_LOGGER.

  • WPP_LEVEL_ENABLED(Flags) determina si el registro está habilitado con el valor de marca especificado. Devuelve TRUE o FALSE.

  • WPP_LEVEL_LOGGER(Flags) busca la sesión de seguimiento a la que está habilitado el proveedor y devuelve un identificador a la sesión de seguimiento.

Por ejemplo, si desea incluir el nivel de seguimiento, además de marcas, como condición, defina una nueva macro de WPP_LEVEL_ENABLED que incluya el nivel de seguimiento. Puede basar la definición de la nueva macro en la macro predeterminada, como se muestra en el ejemplo de código siguiente.

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

Normalmente, la macro WPP_LEVEL_LOGGER no se ve afectada. En estos casos, puede definir la nueva macro para que sea la macro predeterminada. Por ejemplo:

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

Sin embargo, en algunos casos, debe cambiar la macro LOGGER. Por ejemplo, es posible que desee escribir una función de seguimiento que dependa solo del nivel de seguimiento y no de las marcas.

En el ejemplo de código siguiente, el valor flags de la macro se reemplaza por un valor ficticio. No se definen marcas al declarar la definición del GUID de control.

#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)

Agregar la función a WPP

Para agregar la función de seguimiento personalizada a WPP, agregue el parámetro -func a la instrucción RUN_WPP con una declaración de la función, como se muestra en el ejemplo de código siguiente.

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

Nota No debe especificar el modificador -km en la directiva RUN_WPP para aplicaciones en modo de usuario o bibliotecas de vínculos dinámicos (DLL).

Para obtener una lista completa de los parámetros opcionales para RUN_WPP, consulte Preprocesador de WPP.