TraceMessage 関数 (evntrace.h)

RegisterTraceGuids ベース ("クラシック") イベント プロバイダーは、TraceMessage 関数を使用して、メッセージ ベース (TMF ベースの WPP) イベントをイベント トレース セッションに送信します。

構文

ULONG TraceMessage(
  [in] TRACEHANDLE LoggerHandle,
  [in] ULONG       MessageFlags,
  [in] LPCGUID     MessageGuid,
  [in] USHORT      MessageNumber,
       ...         
);

パラメーター

[in] LoggerHandle

イベントを記録するイベント トレース セッションを処理します。 プロバイダーは、ControlCallback 実装で GetTraceLoggerHandle 関数を呼び出すときにハンドルを取得します。

[in] MessageFlags

イベントのプロバイダー固有のデータ セクションの先頭に追加情報を追加します。 イベントのプロバイダー固有のデータ セクションには、設定されているフラグのデータのみが含まれます。 引数データの変数リストは、この情報に従います。 このパラメーターには、次の 1 つ以上の値を指定できます。

• TRACE_MESSAGE_COMPONENTID

  メッセージにコンポーネント識別子を含めます。 MessageGuid パラメーターには、コンポーネント識別子が含まれています。

• TRACE_MESSAGE_GUID

  メッセージにイベント トレース クラス GUID を含めます。 MessageGuid パラメーターには、イベント トレース クラス GUID が含まれています。

• TRACE_MESSAGE_SEQUENCE

  メッセージにシーケンス番号を含めます。 シーケンス番号は 1 から始まります。 このフラグを使用するには、コントローラーがセッションの作成時に EVENT_TRACE_USE_GLOBAL_SEQUENCE またはログ ファイル モード EVENT_TRACE_USE_LOCAL_SEQUENCE 設定している必要があります。

• TRACE_MESSAGE_SYSTEMINFO

  スレッド識別子とプロセス識別子をメッセージに含めます。

• TRACE_MESSAGE_TIMESTAMP

  メッセージにタイム スタンプを含めます。

TRACE_MESSAGE_COMPONENTID と TRACE_MESSAGE_GUID は相互に排他的です。

情報は、次の順序でイベント データに含まれます。

• Sequence number
• イベント トレース クラス GUID (またはコンポーネント識別子)
• タイム スタンプ
• スレッド識別子
• プロセス識別子

[in] MessageGuid

メッセージを識別するクラス GUID またはコンポーネント ID。 MessageFlags にTRACE_MESSAGE_COMPONENTIDフラグまたはTRACE_MESSAGE_GUID フラグが含まれているかどうかによって異なります。

[in] MessageNumber

メッセージの各出現箇所を一意に識別する番号。 このパラメーターに指定する値を定義する必要があります。値はアプリケーションにとって意味のあるものでなければなりません。

...

メッセージに追加する可変引数のリスト。 この一覧を使用して、プロバイダー固有のイベント データを指定します。 リストは、次のように引数のペアで構成されている必要があります。

• PVOID: 引数データへのポインター。
• size_t: 引数データのサイズ (バイト単位)。

NULL と 0 へのポインターで構成される引数ペアを使用して、リストを終了します。

呼び出し元は、引数 + 72 のサイズの合計がイベント トレース セッションのバッファーのサイズを超えないようにする必要があります。

戻り値

関数が成功した場合、戻り値は ERROR_SUCCESS です。

関数が失敗した場合、戻り値は システム エラー コードの 1 つです。 一般的なエラーとその原因を次に示します。

• ERROR_INVALID_HANDLE

  LoggerHandle が NULL であるか、NT カーネル ロガー セッション ハンドルを指定します。

• ERROR_NOT_ENOUGH_MEMORY

  セッションの空きバッファーが不足していて書き込みができないことを示します。 これは、イベントの発生頻度が高いとき、ディスク サブシステムに過大な負荷がかかっているか、バッファー数が少なすぎるために発生します。 使用可能なバッファーが増えるまでブロックするのではなく、 TraceMessage によって イベントが破棄されます。

  Windows 2000 および Windows XP: サポートされていません。

• ERROR_OUTOFMEMORY

  バッファー プールが最大サイズに達していないにもかかわらず、追加のバッファーを割り当てるために使用可能なメモリが不足しており、イベントを受信できるバッファーがないため、イベントは破棄されます。

• ERROR_INVALID_PARAMETER

  MessageFlags に無効な値が含まれています。

• ERROR_MORE_DATA

  1 つのイベントのデータは、複数のバッファーにまたがることはできません。 トレース イベントは、イベント トレース セッションのバッファーのサイズから EVENT_TRACE_HEADER 構造体のサイズを引いた値に制限されます。

解説

TMF ベースの WPP プロバイダーは、この関数を呼び出します。

ラッパー関数からメッセージ トレース機能にアクセスする必要がある場合は、この関数の TraceMessageVa バージョンを呼び出します。

MessageFlags パラメーターに TRACE_MESSAGE_GUID フラグが含まれていない場合、コンシューマーは EventCallback コールバックを使用してイベントを受信して処理する必要があります。 TRACE_MESSAGE_GUID フラグを指定しない場合、EVENT_TRACE構造体のHeader.Guid メンバーにイベント トレース クラス GUID が含まれていないため、コンシューマーは EventClassCallback を使用できません。

MessageFlags フラグに対応するEVENT_TRACEおよびEVENT_TRACE_HEADER構造体のメンバーは、対応するフラグが指定されている場合にのみ設定されることに注意してください。 たとえば、EVENT_TRACE_HEADERの ThreadId メンバーと ProcessId メンバーは、 TRACE_MESSAGE_SYSTEMINFO フラグを指定した場合にのみ設定されます。

要件

関連項目

TraceEvent

TraceEventInstance

TraceMessageVa