EventWriteString 関数 (evntprov.h)

  • [アーティクル]

文字列をデータとして含む 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 ビット ビットマスク。

重要

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

イベント キーワード (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

関連項目

EventWrite

TraceLoggingProvider.h