TraceMessageVa 関数 (evntrace.h)

[アーティクル]
03/11/2023

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

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

注意

ほとんどの開発者は、この関数を直接呼び出しません。 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

次の方法で共有

TraceMessageVa 関数 (evntrace.h)

構文

パラメーター

戻り値

解説

要件

関連項目

フィードバック

その他のリソース