È possibile personalizzare DoTraceMessage?

Sì, è possibile scrivere una versione personalizzata della macroDoTraceMessage. DoTraceMessage genera un messaggio di traccia.

Il driver di esempio TraceDrv fornisce un esempio dei metodi descritti in questo argomento. TraceDrv è disponibile negli esempi di driver di Windows repository su GitHub.

DoTraceMessage: versione predefinita

Per impostazione predefinita, la macro DoTraceMessage ha il formato seguente:

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

In questa versione predefinita, Flag rappresenta i flag di traccia , che sono le condizioni in cui viene generato il messaggio. MessageVariables contiene un elenco delimitato da virgole di variabili definite dal driver e visualizzate nel messaggio di traccia. Le variabili MessageVariables vengono formattate utilizzando gli elementi printf. Il preprocessore WPP crea una direttiva del compilatore dalla macro DoTraceMessage. Questa macro aggiunge le informazioni sulla definizione del messaggio e la formattazione al file PDB generato per il provider di traccia , ad esempio un driver in modalità kernel o un'applicazione in modalità utente.

La macro DoTraceMessage viene espansa, logicamente, nel modo seguente:

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

Si consideri l'esempio di codice seguente.

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

Questa chiamata genera il messaggio di traccia quando il flag ERROR è abilitato. Il messaggio è "IOCTL=%d" e il MessageVariables è il valore di ControlCode.

Se le macro PRE-logging e POST-logging sono state definite, verranno espanse anch'esse. Le macro PRE e post sono supportate nei sistemi operativi Microsoft Windows 2000 e versioni successive. Per usare le macro, è necessario compilare il driver usando wdk. Se si compila un driver usando una versione precedente di Windows Driver Development Kit (DDK), la funzionalità PRE e POST non è disponibile e le macro non verranno eseguite come parte dell'istruzione di traccia. La compilazione del driver usando una versione precedente di Windows DDK potrebbe non causare un'interruzione di compilazione, ma il codice non funzionerà come previsto.

DoTraceMessage: formato generale

Di seguito è riportato un formato generale di una funzione del messaggio di traccia valida:

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

I parametri visualizzati prima del messaggio vengono interpretati come condizioni. I parametri visualizzati dopo il messaggio vengono interpretati come variabili di messaggio.

Condizioni è un elenco delimitato da virgole di valori. Il messaggio di traccia viene generato solo se tutte le condizioni sono vere. È possibile specificare qualsiasi condizione supportata nel codice.

Esempio di : MyTrace

Di seguito è riportato un esempio di funzione di traccia. In questo esempio vengono aggiunte condizioni per il livello di traccia e il sottocomponente del provider che genera il messaggio di traccia.

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

Per esempio:

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

Il livello di traccia è il livello standard definito in Evntrace.h, un file header pubblico che si trova nella cartella 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

Come creare una funzione di traccia personalizzata

Per creare una funzione di traccia personalizzata, seguire questa procedura:

• Scrivere versioni alternative delle macro che supportano la macro DoTraceMessage.

• Aggiungere il parametro -func all'istruzione RUN_WPP che richiama il preprocessore WPP.

scrivere macro personalizzate

Per creare una funzione di traccia personalizzata che modifica le condizioni per un messaggio di traccia (i parametri visualizzati prima del messaggio), è necessario scrivere versioni alternative delle macro che supportano le funzioni di traccia, WPP_LEVEL_ENABLED e WPP_LEVEL_LOGGER.

• WPP_LEVEL_ENABLED(Flags) determina se la registrazione è abilitata con il valore del flag specificato. Restituisce TRUE o FALSE.

• WPP_LEVEL_LOGGER(Flags) trova la sessione di traccia in cui il provider è abilitato e restituisce un handle alla sessione di traccia.

Ad esempio, se si vuole includere il livello di traccia, oltre ai flag, come condizione, è necessario definire una nuova macro WPP_LEVEL_ENABLED che includa il livello di traccia. È possibile basare la definizione della nuova macro nella macro predefinita, come illustrato nell'esempio di codice seguente.

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

In genere, la macro WPP_LEVEL_LOGGER non è interessata. In questi casi, è possibile definire la nuova macro come macro predefinita. Per esempio:

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

Tuttavia, in alcuni casi, è necessario modificare la macro LOGGER. Ad esempio, è possibile scrivere una funzione di traccia che dipende solo dal livello di traccia e non dai flag.

Nell'esempio di codice seguente il valore dei flag nella macro viene sostituito da un valore fittizio. Non vengono definiti flag quando si dichiara la definizione del GUID del controllo.

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

Aggiungere la funzione a WPP

Per aggiungere la funzione di traccia personalizzata a WPP, aggiungere il parametro -func all'istruzione RUN_WPP con una dichiarazione della funzione, come illustrato nell'esempio di codice seguente.

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

Nota Non devi specificare l'opzione -km nella direttiva RUN_WPP per le applicazioni in modalità utente o le librerie a collegamento dinamico (DLL).

Per un elenco completo dei parametri facoltativi per RUN_WPP, vedere preprocessore WPP.