次の方法で共有

DoTraceMessage をカスタマイズできますか?

  • [アーティクル]

はい、独自のバージョンの DoTraceMessage マクロを作成できます。 DoTraceMessage はトレース メッセージを生成します。

TraceDrv サンプル ドライバーは、このトピックで説明するメソッドの例を提供します。 TraceDrv は、GitHub の Windows ドライバー サンプル リポジトリで入手できます。

DoTraceメッセージ: デフォルトのバージョン

デフォルトでは、DoTraceMessage マクロの形式は次のとおりです。

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

このデフォルト バージョンでは、Flag はメッセージが生成される条件であるトレース フラグを表します。 MessageVariables には、ドライバーが定義し、トレース メッセージに表示される変数のカンマ区切りのリストが含まれます。 MessageVariables 変数は、printf 要素を使用してフォーマットされます。 WPP プリプロセッサは、DoTraceMessage マクロからコンパイラ ディレクティブを作成します。 このマクロは、カーネル モード ドライバーやユーザー モード アプリケーションなどのトレース プロバイダー用に生成された PDB ファイルにメッセージ定義情報と形式情報を追加します。

DoTraceMessage マクロは、論理的に次のように展開されます。

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

次のコード例について考えます。

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

この呼び出しは、ERROR フラグが有効な場合にトレース メッセージを生成します。 メッセージは「IOCTL=%d」で、MessageVariables は ControlCode の値です。

PRE-logging マクロと POST-logging マクロが定義されている場合は、それらも展開されます。 PRE マクロと POST マクロは、Microsoft Windows 2000 以降のオペレーティング システムでサポートされています。 マクロを使用するには、WDK を使用してドライバーをビルドする必要があります。 以前のバージョンの Windows Driver Development Kit (DDK) を使用してドライバーをビルドする場合、PRE および POST 機能は使用できず、マクロはトレース ステートメントの一部として実行されません。 以前のバージョンの Windows DDK を使用してドライバーをビルドすると、ビルド ブレークが発生しない可能性がありますが、コードは期待どおりに動作しません。

DoTraceメッセージ: 一般的なフォーマット

以下は、有効なトレース メッセージ関数の一般的な形式です。

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

メッセージの前に表示されるパラメータは条件として解釈されます。 メッセージの後に表示されるパラメータは、メッセージ変数として解釈されます。

条件は、カンマで区切られた値のリストです。 トレース メッセージは、すべての条件が true の場合にのみ生成されます。 コードでサポートされている任意の条件を指定できます。

例マイトレース

以下はトレース機能のサンプルです。 この例では、トレース メッセージを生成するプロバイダーのトレース レベルとサブコンポーネントの条件を追加します。

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

次に例を示します。

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

トレース レベルは、WDK の Include サブディレクトリにあるパブリック ヘッダー ファイルである Evntrace.h で定義されている標準レベルです。

#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

カスタム トレース関数を作成する方法

カスタム トレース関数を作成するには、次の手順に従います。

  • DoTraceMessage マクロをサポートするマクロの代替バージョンを作成します。

  • WPP プリプロセッサを呼び出す RUN_WPP ステートメントに -func パラメータを追加します。

カスタムマクロの作成

トレース メッセージの条件 (メッセージの前に表示されるパラメーター) を変更するカスタム トレース関数を作成するには、トレース関数をサポートするマクロの代替バージョン、WPP_LEVEL_ENABLED および WPP_LEVEL_LOGGER を作成する必要があります。

  • WPP_LEVEL_ENABLED(Flags) は、指定されたフラグ値でログ記録が有効かどうかを決定します。 TRUE または FALSE を返します。

  • WPP_LEVEL_LOGGER(Flags) は、プロバイダーが有効になっているトレース セッションを検索し、トレース セッションへのハンドルを返します。

たとえば、フラグに加えてトレース レベルを条件として含める場合は、トレース レベルを含む新しい WPP_LEVEL_ENABLED マクロを定義します。 次のコード例に示すように、新しいマクロの定義はデフォルトのマクロに基づいて行うことができます。

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

通常、WPP_LEVEL_LOGGER マクロは影響を受けません。 このような場合、新しいマクロをデフォルトのマクロとして定義できます。 次に例を示します。

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

ただし、場合によっては、LOGGER マクロを変更する必要があります。 たとえば、フラグではなくトレース レベルのみに依存するトレース関数を作成することができます。

次のコード例では、マクロ内の flags 値がダミー値に置き換えられます。 コントロール GUID 定義を宣言するときにフラグは定義されません。

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

WPPに機能を追加する

カスタム トレース関数を WPP に追加するには、次のコード例に示すように、関数の宣言を含む RUN_WPP ステートメントに -func パラメーターを追加します。

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

注 ユーザー モード アプリケーションまたはダイナミック リンク ライブラリ (DLL) の RUN_WPP ディレクティブに -km スイッチを指定しないでください。

RUN_WPP のオプション パラメーターの完全なリストについては、「WPP プリプロセッサ」を参照してください。