複合型定義の構文とは

[アーティクル]
03/20/2024

Event Tracing for Windows (ETW) では、トレース関数で使用する単純型と複合型がいくつか定義されています。これらの型は、Defaultwpp.ini ファイルで宣言されます。ただし、独自のカスタム構成ファイルを作成し、それを使用するように WPP に指示することができます。

複合データ型 (DEFINE_CPLX_TYPE) の形式は次のとおりです。

DEFINE_CPLX_TYPE(TypeName, HelperMacroName, ArgumentType, WppMofType,"WppMofFormat", TypeSignature, Priority, Slots);

次に例を示します。

DEFINE_CPLX_TYPE(.*ls, WPP_LOGXWCS, const xwcs_t&, ItemPWString,"s", _xwcs_t_, 0, 2);

Format 要素

TypeName
WPP では、このフィールドを使用して複合型を識別します。たとえば、 .*ls です。

HelperMacroName
引数を長さ/アドレスペアの形式で可変長配列に変換するヘルパーマクロ。この形式は、可変引数リスト内の各エントリに対して TraceMessage 関数で必要です。

引数を適切に書式設定するには、次の例に示すように、ヘルパーマクロの定義で WPP_LOGPAIR マクロを使用する必要があります。

#define HelperMacroName(x) WPP_LOGPAIR(length, x)

注: 実装するトレースロジックによっては、複数のWPP_LOGPAIR マクロを使用してマクロを定義することが必要な場合があります。

引数の型
TypeName 型の引数で受け入れられる値を示します。たとえば、 const xwcs_t&。

WppMofType
WPP プリプロセッサによって認識されるマネージドオブジェクト形式 (MOF) 型を指定します

WppMofFormat
WPP プリプロセッサによって認識される "s"などの書式指定子を指定します。

TypeSignature
関数名に追加して複合型に関連付ける文字列。アンダースコアの間には、1 文字または複数の文字が必要です。たとえば、 _xwcs_t_。

優先順位
この要素は予約済みであり、0に設定する必要があります。

スロット
WPP プリプロセッサがこの複合型の TraceMessage 関数に渡す可変長パラメーターの最大数を指定します。この format 要素は省略可能です。この要素が指定されていない場合、WPP は既定値の 1 を使用します。

例

複合型を定義するには、次の操作を行います。

ローカル構成ファイルを作成する。このファイルには、複合型を定義するDEFINE_CPLX_TYPE マクロが含まれている必要があります。
WPP プリプロセッサにローカル構成ファイルを指定します。プロジェクトのプロパティを開きます。 WPP トレース、 ファイルオプション で、 追加構成ファイル フィールドを使用して構成ファイルの名前 (-ini パラメーター) を指定します。。 WPP の実行 を [はい] に設定して、WPP トレースを有効にしてください。詳細については、WPP プリプロセッサーをご覧ください。

たとえば、 .*ls という名前の複合型を定義するローカル構成ファイル (Localwpp.ini) を作成できます。複合型は次のように定義します。

DEFINE_CPLX_TYPE(.*ls, WPP_LOGXWCS, const xwcs_t&, ItemPWString,"s", _xwcs_t_, 0, 2);

次に、WPP に次のような型 .*ls が表示されます。

printf("my string is %.*ls", value);

WPP は次のステージング関数を生成します。ここで、 SF は "ステージング関数" を表します。

WPP_SF__xwcs_t_(..., const xwcs_t& a1) {
    TraceMessage(..., WPP_LOGXWCS(a1) 0);
}

次に、次の文字列のように、 .*ls 型名が適切な MOF 形式 %s に置き換えられる MOF エントリが WPP によって生成されます。

"my string is %s"
{
    Value, ItemPWString
}

また、次のような型の構造体も生成されます。

struct xwcs_t {
      WCHAR*    _buf;
      short     _len;
      xwcs_t(short buf, short len):_buf(buf),_len(len){}
};

次に、次のように、データ型を xwstr_t型の文字列に結合するマクロを追加します。

#define WPP_LOGXWCS(x) WPP_LOGPAIR(2, &(x)._len) WPP_LOGPAIR((x)._len, (x)._buf)

ItemPWString は、WPP によって認識されるカウントされた Unicode 文字列型です。長さは 2 バイトとして指定されます。

ETW は、WPP_LOGXWCS定義を解釈するときに、最初の WPP_LOGPAIR マクロが解釈されるバッファーに 2 バイトの文字列を格納します。 ETW は、ETW が 2 番目の WPP_LOGPAIR マクロを解釈するときに、文字列のすべてのバイトをバッファーにコピーします。

データとは別の長さを指定したため、WPP_LOGXWCSは TraceMessage の 2 つのスロットを使用します。したがって、数値 2 は 8 番目の引数です。

WPP プリプロセッサを呼び出すときは、 [感嘆符を無視する] オプション (-noshrieks) を使用します。これにより、WPP は、感嘆符 (!) で囲まれていない名前を持つ複合型を認識するのに役立ちます。これは、"shrieks" とも呼ばれます。

WPP トレースオプションの完全な一覧と、プロジェクトプロパティページから設定する方法については、 WPP プリプロセッサを参照してください。

次の方法で共有

複合型定義の構文とは

Format 要素

例

フィードバック

その他のリソース