次の方法で共有


TraceMessageVa 関数 (evntrace.h)

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

構文

ULONG TraceMessageVa(
  [in] TRACEHANDLE LoggerHandle,
  [in] ULONG       MessageFlags,
  [in] LPCGUID     MessageGuid,
  [in] USHORT      MessageNumber,
  [in] va_list     MessageArgList
);

パラメーター

[in] LoggerHandle

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

[in] MessageFlags

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

  • 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: メッセージにタイム スタンプを含めます。

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

  • Sequence number
  • イベント トレース クラス GUID
  • タイム スタンプ
  • スレッド識別子
  • プロセス識別子

[in] MessageGuid

イベント トレース メッセージを識別するクラス GUID。

[in] MessageNumber

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

[in] MessageArgList

メッセージに追加する変数引数の一覧。 リストは、次のように引数のペアで構成されている必要があります。

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

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

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

戻り値

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

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

  • ERROR_INVALID_HANDLE

    LoggerHandleNULL であるか、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 プロバイダーは、この関数を呼び出します。

注意

ほとんどの開発者は、この関数を直接呼び出しません。 WPP プロバイダーは、ETW API を呼び出す代わりに、tracewpp.exe によって生成されたラッパー関数を使用します。

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

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 フラグを指定した場合にのみ設定されます。

要件

   
サポートされている最小のクライアント Windows XP (デスクトップ アプリのみ)
サポートされている最小のサーバー Windows Server 2003 (デスクトップ アプリのみ)
対象プラットフォーム Windows
ヘッダー evntrace.h
Library Advapi32.lib
[DLL] Advapi32.dll

関連項目

TraceEvent

TraceEventInstance

TraceMessage