EventWriteTransfer 関数 (evntprov.h)

  • [アーティクル]

アクティビティ ID とオプションの関連アクティビティ ID を使用して ETW イベントを書き込みます。

構文

ULONG EVNTAPI EventWriteTransfer(
  [in]           REGHANDLE              RegHandle,
  [in]           PCEVENT_DESCRIPTOR     EventDescriptor,
  [in, optional] LPCGUID                ActivityId,
  [in, optional] LPCGUID                RelatedActivityId,
  [in]           ULONG                  UserDataCount,
  [in, optional] PEVENT_DATA_DESCRIPTOR UserData
);

パラメーター

[in] RegHandle

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

[in] EventDescriptor

ID 、バージョン、レベル、キーワード、チャネル、オペコード、タスクなどのイベント情報 (メタデータ) を含むEVENT_DESCRIPTOR。

重要

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

[in, optional] ActivityId

このイベントの 128 ビット アクティビティ ID への省略可能なポインター。 これが NULL 以外の場合、 EventWriteTransfer はイベントのアクティビティ ID に指定された値を使用します。 これが NULL の場合、 EventWriteTransfer は現在のスレッドのアクティビティ ID を使用します。

トレース処理ツールでは、イベントのアクティビティ ID を使用して、イベントをアクティビティと呼ばれるグループに整理できます。 アクティビティ ID の詳細については、「 EventActivityIdControl」を参照してください。

[in, optional] RelatedActivityId

このイベントのアクティビティの親である 128 ビットアクティビティ ID へのオプションのポインター。 これが NULL 以外の場合、 EventWriteTransfer はイベントの関連するアクティビティ ID に指定された値を使用します。 これが NULL の場合、イベントには関連するアクティビティ ID はありません。 通常、関連するアクティビティ ID は、アクティビティの START イベント (Opcode = START でログに記録されるアクティビティの最初のイベント) に設定されます。

トレース処理ツールでは、イベントの関連アクティビティ ID を使用して、アクティビティ間のリレーションシップを決定できます。たとえば、関連アクティビティは新しく開始されたアクティビティの親です。 関連するアクティビティ ID の詳細については、「 EventActivityIdControl」を参照してください。

[in] UserDataCount

UserData 内のEVENT_DATA_DESCRIPTOR構造体の数。 最大数は 128 です。

[in, optional] UserData

イベントに含めるデータを記述する UserDataCountEVENT_DATA_DESCRIPTOR 構造体の配列。 UserDataCount が 0 の場合、UserData は NULL になります。

各 EVENT_DATA_DESCRIPTOR では、イベントに含める 1 つのメモリ ブロックについて説明します。 指定されたブロックは、埋め込みまたは配置なしで連結され、イベント コンテンツが形成されます。 マニフェストベースのデコードを使用する場合、イベント コンテンツは、マニフェスト内のイベントに関連付けられているテンプレートで指定されたレイアウトと一致する必要があります。

戻り値

成功 した場合 、またはエラー コード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 イベントを記述できなかった場合でも、ほとんどの運用コードは引き続き実行され、イベントを報告し続ける必要があるため、リリース ビルドでは通常、エラー コードを無視する必要があります。

注釈

ほとんどのイベント プロバイダーは、 EventWriteTransfer を 直接呼び出しません。 代わりに、ほとんどのイベント プロバイダーは、EventRegister、EventWriteTransfer、および EventUnregister の呼び出しをラップする ETW フレームワークを使用して実装されます。 たとえば、 イベント マニフェストを記述 し、 メッセージ コンパイラ を使用してイベントの C/C++ コードを生成したり、 TraceLogging を 使用してマニフェストの必要性を回避したりできます。

EventWriteTransfer は、ProviderId ( RegHandle から決定)、Level、Keyword、およびその他のイベント特性に基づいて、イベントを適切なトレース セッションにルーティングします。 このイベントを記録しているトレース セッションがない場合、この関数は何も実行せず、 ERROR_SUCCESSを返します。

トレース セッションによって記録されないイベントのパフォーマンスへの影響を軽減するには、 EventEnabled を呼び出して、データを準備して EventWriteTransfer を呼び出す前に、トレース セッションがイベントを記録しているかどうかを判断できます。

EventWriteTransfer は、 EventWriteEx と同じです。 フィルター の場合は 0、 フラグの場合は 0 です。

要件

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

こちらもご覧ください

EventActivityIdControl

EventRegister

EventWrite

EventWriteEx

マニフェストベースのイベントの記述。