EventWriteString 関数 (evntprov.h)

[アーティクル]
08/23/2023

文字列をデータとして含む ETW イベントを書き込みます。この関数は使用しないでください。

構文

ULONG EVNTAPI EventWriteString(
  [in] REGHANDLE RegHandle,
  [in] UCHAR     Level,
  [in] ULONGLONG Keyword,
  [in] PCWSTR    String
);

パラメーター

[in] RegHandle

プロバイダーの登録ハンドル。ハンドルは EventRegister から取得されます。生成されたイベントでは、ハンドルに関連付けられている ProviderId が使用されます。

[in] Level

イベントの重大度または重要度を表すために使用される 8 ビットの数値。

重要

ProviderId、Level、Keyword は、イベントをフィルター処理するための主要な手段です。他の種類のフィルター処理も可能ですが、オーバーヘッドははるかに高くなります。常に 0 以外のレベルを割り当て、すべてのイベントにキーワード (keyword)します。

イベントレベルの詳細については、「 EVENT_DESCRIPTOR 」を参照してください。

[in] Keyword

一連のイベントカテゴリ内のイベントのメンバーシップを示すために使用される 64 ビットビットマスク。

重要

イベントキーワード (keyword)の詳細については、「EVENT_DESCRIPTOR」を参照してください。

[in] String

イベントデータとして書き込む NUL で終わる文字列。

戻り値

成功した場合 、または エラーコードERROR_SUCCESSを返します。考えられるエラーコードは次のとおりです。

ERROR_INVALID_PARAMETER: 1 つ以上のパラメーターが無効です。
ERROR_INVALID_HANDLE: プロバイダーの登録ハンドルが無効です。
ERROR_ARITHMETIC_OVERFLOW: イベントサイズが許容最大値 (64 KB - ヘッダー) を超えています。
ERROR_MORE_DATA: セッションバッファーサイズがイベントに対して小さすぎます。
ERROR_NOT_ENOUGH_MEMORY: 塗りつぶされたバッファーがディスクにフラッシュしようとしているが、ディスク IO が十分な速度で実行されていない場合に発生します。これは、ディスクが低速で、イベントトラフィックが多い場合に発生します。最終的には、空の (空の) バッファーがなくなり、イベントが削除されます。
STATUS_LOG_FILE_FULL: リアルタイム再生ファイルがいっぱいです。リアルタイムコンシューマーが再生ファイルからイベントを使用するまで、イベントはセッションに記録されません。

エラーコードは、主にデバッグと診断のシナリオで使用することを目的としています。 ETW イベントを記述できなかった場合でも、ほとんどの運用コードは引き続き実行され、イベントを報告し続ける必要があるため、リリースビルドでは通常、エラーコードを無視する必要があります。

解説

この API は役に立たず、使用しないでください。

ほとんどの ETW 分析ツールは、マニフェストのない文字列のみのイベントを正しくサポートしていません。
マニフェストがないと、イベントに関する重要な情報 (プロバイダー名、イベント ID、イベント名など) は使用できないため、分析ツールで文字列のみのイベントがサポートされている場合でも、結果のイベントは使用しにくくなります。
マニフェストを使用すると、この関数は、1 つの文字列フィールドを持つマニフェストベースのイベントのコードとほぼ同じように動作します。ただし、マニフェストベースのイベントは、トレース分析ツールによってより適切にサポートされています。さらに、1 つの文字列フィールドを持つイベントの MC.exe によって生成されるコードは、 EventWriteString 関数よりも効率的です。

この API を使用する代わりに、次の代替手段を検討してください。

TraceLoggingProvider.h を使用して、ETW 分析ツールで適切にサポートされているイベントを書き込み、マニフェストなしで作業し、プロバイダー名やイベント名などのメタデータを含めます。
インストルメンテーションマニフェストを記述します。単一の NUL で終わる文字列値を持つ単純なイベントを作成します。マニフェストがなくても、イベントを書き込んで収集できます。必要なのは、収集されたトレースをデコードするためのマニフェストのみです。

EventWriteString は、指定された文字列で構成されるデータペイロードを含むイベントを書き込みます。この API は、次のコードとほぼ同じです。

EVENT_DESCRIPTOR eventDescriptor;
EVENT_DATA_DESCRIPTOR dataDescriptor;
EventDescCreate(&eventDescriptor, 0, 0, 0, Level, 0, 0, Keyword);
EventDataDescCreate(&dataDescriptor, String, (wcslen(String) + 1) * sizeof(WCHAR));
return EventWrite(RegHandle, &eventDescriptor, 1, &dataDescriptor);

結果のイベントは、 EventWrite によって生成される他のイベントと同じですが、結果のイベントに EVENT_HEADER_FLAG_STRING_ONLY フラグが設定されている点が除きます (イベントフラグの詳細については、「EVENT_HEADER 」を参照してください)。

イベントは、ID、バージョン、オペコード、タスク、チャネルが 0 に設定されて書き込まれます。

イベントでは、現在のスレッドのアクティビティ ID が使用されることに注意してください。

EVENT_HEADER_FLAG_STRING_ONLY フラグを認識する ETW 分析ツールでは、デコーダーがイベントプロバイダーの他のデコード情報を見つけられない場合でも、文字列値を抽出できます。ただし、マニフェストがないと、ツールはイベントのプロバイダー名を特定できません。

要件


サポートされている最小のクライアント	Windows Vista [デスクトップアプリのみ \| UWP アプリ]
サポートされている最小のサーバー	Windows Server 2008 [デスクトップアプリ \| UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	evntprov.h
Library	Advapi32.lib
[DLL]	Advapi32.dll

次の方法で共有

EventWriteString 関数 (evntprov.h)

構文

パラメーター

戻り値

解説

要件

関連項目

フィードバック

その他のリソース