TraceLoggingCustom マクロ (traceloggingprovider.h)
カスタム シリアライザーを使用してパックされたフィールドをイベントに追加する TraceLogging ラッパー マクロ。
ほとんどの TraceLogging イベントでは、カスタム シリアライザーを使用する必要はありません。また、TraceLoggingCustom を使用しないでください。
構文
void TraceLoggingCustom(
[in] pValue,
[in] cbValue,
[in] protocol,
[in] bSchema,
[in] cbSchema,
[in, optional] __VA_ARGS__
);
パラメーター
[in] pValue
指定したプロトコル ファミリのシリアライザーによって実行時にシリアル化される、フィールドのペイロードへのポインター。
[in] cbValue
フィールドのペイロードのサイズ (バイト単位) は、指定されたプロトコル ファミリのシリアライザーによって実行時にシリアル化されます。
[in] protocol
プロトコル ファミリ。0 から 4 の Microsoft 定義値、または 5 から 31 のユーザー定義値を指定できます。 Microsoft で定義された値は、 で始まる TRACELOGGING_PROTOCOL_マクロによって定義されます。
[in] bSchema
ペイロードをデコードするために必要な情報 (つまりスキーマ) をプロトコル定義形式で含むバイト値のコンマ区切りのリスト。 この一覧の値は、コンパイル時定数である必要があります。 例: (0x12、0x23、0x34)
[in] cbSchema
bSchema で指定されたバイト値の数。 この値はコンパイル時定数である必要があります。
[in, optional] __VA_ARGS__
フィールド定義の省略可能な 名前、 説明、 タグ パラメーター。
TraceLoggingCustom は、5、6、7、または 8 個のパラメーターで指定できます。 パラメーターが指定されていない場合は、既定値が使用されます。 たとえば、TraceLoggingCustom(&x.data, sizeof(x.data), p, (schema), cbSchema) は、TraceLoggingCustom(&x.data, sizeof(x.data), p, (schema), cbSchema, "&x.data", "", 0) と同じです。
[in, optional] nameイベント フィールドに使用する名前。 指定する場合、name パラメーターは文字列リテラル (変数ではない) であり、'\0' 文字を含めてはなりません。 指定しない場合、イベント フィールド名は pValue に基づいています。
[in, optional] descriptionイベント フィールドの値の説明。 指定した場合、description パラメーターは文字列リテラルである必要があり、 PDB に含まれます。
[in, optional] tagsコンパイル時の定数整数値。 値の下位 28 ビットは、フィールドのメタデータに含まれます。 この値のセマンティクスは、イベント コンシューマーによって定義されます。 イベント処理中に、この値は [EVENT_PROPERTY_INFO タグ] フィールドから取得できます。
戻り値
なし
解説
TraceLoggingCustom(pValue, cbValue, protocol, (schema...), cbSchema, ...)は、TraceLoggingWrite マクロの呼び出しのパラメーターとして使用できます。 各 TraceLoggingCustom パラメーターは、カスタム シリアル化されたフィールドをイベントに追加します。 ほとんどの TraceLogging イベントでは、カスタム シリアライザーは使用されず、TraceLoggingCustom を使用しないでください。 汎用 ETW デコーダーは、カスタム シリアル化を使用するフィールドをサポートせず、通常はフィールドをTDH_INTYPE_BINARYとして扱います。
デコーダーは、TDH API を使用して TraceLoggingCustom シリアル化されたフィールドにアクセスする必要があります。 TdhGetEventInformation によって返されるTRACE_EVENT_INFO構造体には、ログに記録された TraceLoggingCustom フィールドに関連する 2 つのEVENT_PROPERTY_INFO構造体が含まれます。 これらは、一般的な方法で、バイナリ フィールド (TDH_INTYPE_BINARY) のEVENT_RECORDの UserData BLOB にあるデータと関連付けます。
- 2 つのEVENT_PROPERTY_INFO構造体の 1 つ目は、シリアル化されたペイロードの長さ (cbValue) を表す "Length" プロパティです。
- 2 つ目は、ユーザーのペイロード (pbValue) を参照する プロパティです。 2 番目のプロパティには、PropertyParamLength ("Length" プロパティを参照) と PropertyHasCustomSchema が設定されます。
デコーダーは、PropertyHasCustomSchema が設定されていることを認識し、CustomSchemaOffset のEVENT_PROPERTY_INFOの customSchemaType メンバーを参照する必要があります。これは、プロトコルの種類とプロトコル メタデータが配置されているTRACE_EVENT_INFORMATION内のオフセットです。 そこでは、 (擬似構造体) の形式で渡されたメタデータを見つけることができます。
struct _CUSTOM_SCHEMA {
UINT16 protocolType;
UINT16 cbSchema;
BYTE bSchema[cbSchema];
};
PropertyHasCustomSchema フラグを認識するためにこれらの追加の手順を実行せず、代わりに EVENT_PROPERTY_INFO 共用体の nonStructType 部分を参照してイベントをデコードする既存のデコーダーは、ペイロードをTDH_INTYPE_BINARYされたかのようにシームレスに処理します。
例
// Value generated at runtime by serializer:
BYTE rgValue[] = {...};
TraceLoggingWrite(
g_hProvider,
"MyEventName",
TraceLoggingCustom(
rgValue,
sizeof(rgValue),
TRACELOGGING_PROTOCOL_MYPROTOCOL,
( 0x0, 0x1, 0x2 ), // Generated at compile-time
3,
"MyCustomField"),
TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
TraceLoggingKeyword(MyEventCategories)); // Provider-defined categories
要件
| サポートされている最小のクライアント | Windows Vista [デスクトップ アプリのみ | UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2008 [デスクトップ アプリ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | traceloggingprovider.h |