EVENT_DATA_DESCRIPTOR 構造体 (evntprov.h)

[アーティクル]
03/05/2024

EVENT_DATA_DESCRIPTOR構造体は、ETW イベントで使用されるデータブロックを定義します。

通常、この構造体は EventDataDescCreate 関数を使用して初期化されます。

構文

typedef struct _EVENT_DATA_DESCRIPTOR {
  ULONGLONG Ptr;
  ULONG     Size;
  union {
    ULONG Reserved;
    struct {
      UCHAR  Type;
      UCHAR  Reserved1;
      USHORT Reserved2;
    } DUMMYSTRUCTNAME;
  } DUMMYUNIONNAME;
} EVENT_DATA_DESCRIPTOR, *PEVENT_DATA_DESCRIPTOR;

メンバー

Ptr

データへのポインター。

重要

これは、32 ビットアーキテクチャと 64 ビットアーキテクチャの両方の 64 ビット符号なし整数値です。この値を適切に設定するには、データポインターをフィールドに割り当てるPtr前に符号なし整数にキャストするか、EventDataDescriptor.Ptr = (UINT_PTR)dataPointer;EventDataDescCreate 関数を使用します。

Size

データのサイズ (バイト単位)。

DUMMYUNIONNAME

DUMMYUNIONNAME.Reserved

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Type

イベントでのこのデータの使用を指定します。次のいずれかの値を指定できます。

EVENT_DATA_DESCRIPTOR_TYPE_NONE (0)

通常のイベントデータ。
EVENT_DATA_DESCRIPTOR_TYPE_EVENT_METADATA (1)

TraceLogging イベントのデコード情報。
EVENT_DATA_DESCRIPTOR_TYPE_PROVIDER_METADATA (2)

手動で接続されたプロバイダーの特徴。 EventSetInformation を介したプロバイダー特性のアタッチをサポートしていないオペレーティングシステムで使用する場合。プロバイダーの特性がを使用して EventSetInformation構成されている場合、このデータは無視されます。
EVENT_DATA_DESCRIPTOR_TYPE_TIMESTAMP_OVERRIDE (3)

64 ビットのイベントタイムスタンプのオーバーライド。再ログ記録時に使用します。タイムスタンプ順にイベントをログに記録すると、トレース処理中にイベントの順序付けの問題が発生する可能性があることに注意してください。

イベントプロバイダーがまたは EventProviderUseDescriptorType 操作で EventSetInformation API EventProviderSetTraits を呼び出してフィールドを尊重Typeするように構成されていない限り、このフィールドは無視されることに注意してください。

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Reserved1

使用しません。 0 に設定されます。

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Reserved2

使用しません。 0 に設定されます。

注釈

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

イベントデータを含むイベントを書き込むには、 EVENT_DATA_DESCRIPTOR 構造体の配列 (データのチャンクごとに 1 つの要素) を作成し、 EventDataDescCreate 関数を呼び出して、イベントに含めるデータを使用して各要素を初期化します。次に、この配列を EventWrite に渡して、イベントにデータを含めます。例については、「マニフェストベースのイベントの記述」を参照してください。

イベントに書き込まれるデータは、関数に渡される EVENT_DATA_DESCRIPTOR 構造体によって参照されるデータチャンクの EventWrite 連結になります。この連結にはパディングが含まれていないので、元のデータチャンクのセットの境界またはサイズ情報は保持されません。

ETW イベントの合計サイズ (ユーザーが指定したデータ、 EVENT_HEADER、およびイベントに必要な可能性のあるEVENT_HEADER_EXTENDED_DATA_ITEM の合計) は、64 KB を超えることはできません。 64 KB を超えるイベントは、ETW ランタイムによって削除されます。

さらに、トレースセッションバッファーに収まらない ETW イベントも削除されます。各バッファーには 72 バイトのヘッダーがあるため、バッファーに収まる最大のイベントはバッファーのサイズよりも若干小さくなります。たとえば、32 KB のバッファーを使用するトレースセッションでは、32,696 バイトを超えるイベントを受け入れることができません (32,768 バイトのバッファーから 72 バイトのヘッダーを差し引いた 32,696 バイトのイベントは残ります)。

要件

要件	値
サポートされている最小のクライアント	Windows Vista [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2008 [デスクトップアプリのみ]
Header	evntprov.h

こちらもご覧ください

EVENT_HEADER

EVENT_HEADER_EXTENDED_DATA_ITEM

EVENT_DATA_DESCRIPTOR 構造体 (evntprov.h)

構文

メンバー

注釈

要件

こちらもご覧ください

フィードバック

フィードバック

その他のリソース