TraceEventInstance 関数 (evntrace.h)
RegisterTraceGuids ベース ("クラシック") イベント プロバイダーは、TraceEventInstance 関数を使用して、インスタンス識別子を使用して構造化イベントをイベント トレース セッションに送信します。
イベントでは、インスタンス識別子を使用してイベントをトランザクションに関連付けます。 この関数は、関連するイベント間の階層関係をトレースするためにも使用できます。
構文
ULONG WMIAPI TraceEventInstance(
[in] TRACEHANDLE TraceHandle,
[in] PEVENT_INSTANCE_HEADER EventTrace,
[in] PEVENT_INSTANCE_INFO InstInfo,
[in] PEVENT_INSTANCE_INFO ParentInstInfo
);
パラメーター
[in] TraceHandle
イベント インスタンスを記録するイベント トレース セッションを処理します。 プロバイダーは、ControlCallback 実装で GetTraceLoggerHandle 関数を呼び出すときにハンドルを取得します。
[in] EventTrace
EVENT_INSTANCE_HEADER構造体へのポインター。 イベント固有のデータは、必要に応じて 構造体に追加されます。 ログに記録できる最大のイベントは 64K です。 EVENT_INSTANCE_HEADER構造体の次のメンバーの値を指定する必要があります。
- [サイズ]
- Flags
- RegHandle
プロバイダーが提供する情報の複雑さに応じて、次のメンバーの値の指定も検討する必要があります。
- Class.Type
- Class.Level
関連するイベント間の階層関係をトレースするには、 ParentRegHandle メンバーも設定します。
[in] InstInfo
このイベント トレース クラスの登録ハンドルとインスタンス識別子を含む、 EVENT_INSTANCE_INFO 構造体へのポインター。 CreateTraceInstanceId 関数を使用して構造体を初期化します。
[in] ParentInstInfo
親イベント トレース クラスとそのインスタンス識別子の登録ハンドルを含む、 EVENT_INSTANCE_INFO 構造体へのポインター。 CreateTraceInstanceId 関数を使用して構造体を初期化します。 階層リレーションシップをトレースしない場合は 、NULL に設定します。
戻り値
関数が成功した場合、戻り値は ERROR_SUCCESS です。
関数が失敗した場合、戻り値は システム エラー コードの 1 つです。 一般的なエラーとその原因を次に示します。
ERROR_INVALID_FLAGS
EVENT_INSTANCE_HEADERの Flags メンバーにWNODE_FLAG_TRACED_GUIDが含まれていません。
ERROR_OUTOFMEMORY
関数呼び出しを完了するためのメモリが不足していました。 このエラー コードの原因については、次の「解説」セクションで説明します。
ERROR_INVALID_PARAMETER
次のいずれかが当てはまります。
- EventTrace は NULL です。
- pInstInfo は NULL です。
- pInstInfo のメンバーは NULL です。
- TraceHandle は NULL です。
- EVENT_INSTANCE_HEADERの Size メンバーが正しくありません。
ERROR_INVALID_HANDLE
TraceHandle が無効であるか、NT カーネル ロガー セッション ハンドルを指定します。
ERROR_NOT_ENOUGH_MEMORY
セッションの空きバッファーが不足していて書き込みができないことを示します。 これは、イベントの発生頻度が高いとき、ディスク サブシステムに過大な負荷がかかっているか、バッファー数が少なすぎるために発生します。 使用可能なバッファーが増えるまでブロックするのではなく、 TraceEvent によってイベントが破棄されます。
Windows 2000 および Windows XP: サポートされていません。
ERROR_OUTOFMEMORY
バッファー プールが最大サイズに達していないにもかかわらず、追加のバッファーを割り当てるために使用可能なメモリが不足しており、イベントを受信できるバッファーがないため、イベントは破棄されます。
ERROR_MORE_DATA
1 つのイベントのデータは、複数のバッファーにまたがることはできません。 トレース イベントは、イベント トレース セッションのバッファーのサイズから EVENT_INSTANCE_HEADER 構造体のサイズを引いた値に制限されます。
解説
MOF ベースの ETW プロバイダーは、この関数を呼び出します。
注意
ほとんどの開発者はこの関数を呼び出しません。 この API は MOF ベースの ETW をサポートしていますが、マニフェスト ベースの ETW を優先して MOF ベースの ETW は非推奨とされています。 さらに、ほとんどの MOF ベースのプロバイダーは、ETW API を直接呼び出す代わりに、MC.exe によって生成されたラッパー関数を使用します。
プロバイダーがこの関数を呼び出す前に、プロバイダーは
- RegisterTraceGuids 関数を呼び出して、それ自体とイベント トレース クラスを登録する必要があります。
- 登録されたイベント トレース クラスのインスタンス識別子を作成するには、 CreateTraceInstanceId 関数を呼び出す必要があります。
- 有効にする必要があります。 コントローラーは EnableTrace 関数を呼び出してプロバイダーを有効にします。
イベントは、ログ ファイルに書き込まれるか、リアルタイムでイベント トレース コンシューマーに送信されるか、またはその両方に書き込まれます。 StartTrace に渡されるEVENT_TRACE_PROPERTIES構造体の LogFileMode メンバーは、イベントの送信先を定義します。
トレース イベントは、発生した順序で書き込まれます。
関連のないイベントをトレースするには、 TraceEvent 関数を使用します。
Windows XP: 正しく機能しません。
例
CreateTraceInstanceId と TraceEventInstance を使用して関連するイベント セットを生成する例については、「イベント インスタンスのトレース」を参照してください。
要件
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | evntrace.h |
| Library | Advapi32.lib |
| [DLL] | Advapi32.dll |