ホーム › System.Diagnostics.Etw › EVENT_DATA_DESCRIPTOR

EVENT_DATA_DESCRIPTOR

構造体

サイズx64: 24 バイト / x86: 16 バイト

サイズ=各フィールドのバイト数(x64/x86 で異なる場合は x64/x86 と併記)。x64/x86 列=フィールドのバイトオフセット(HSPで dupptr / lpoke / wpoke 等に使用)。

フィールド

フィールド	型	サイズ	x64	x86	説明
Ptr	ULONGLONG	8	+0	+0	データへのポインターです。重要これは 32 ビットアーキテクチャと 64 ビットアーキテクチャのどちらにおいても 64 ビットの符号なし整数値です。この値を正しく設定するには、データのポインターを符号なし整数にキャストしてから `Ptr` フィールドに代入するか (例: `EventDataDescriptor.Ptr = (UINT_PTR)dataPointer;`)、 EventDataDescCreate 関数を使用してください。
Size	DWORD	4	+8	+8	データのサイズ (バイト単位) です。
Anonymous	_Anonymous_e__Union	8/4	+16	+12	予約・型情報を含む共用体。EventDataDescCreateで設定する。

共用体: _Anonymous_e__Union x64 8B / x86 4B

フィールド	型	サイズ	x64	x86	説明
Reserved	DWORD	4	+0	+0
Anonymous	_Anonymous_e__Struct	8/4	+0	+0	予約・型情報を含む共用体。EventDataDescCreateで設定する。

公式ドキュメント

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

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

解説(Remarks)

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

イベントデータを含むイベントを書き込むには、EVENT_DATA_DESCRIPTOR 構造体の配列を (データのかたまりごとに 1 要素) 作成し、 EventDataDescCreate 関数を呼び出して、イベントに含めるデータで各要素を初期化します。次に、この配列を EventWrite に渡して、データをイベントに含めます。例については、 Writing Manifest-based Events を参照してください。

イベントに書き込まれるデータは、EventWrite 関数に渡された EVENT_DATA_DESCRIPTOR 構造体が参照するデータのかたまりを連結したものになります。この連結にはパディングは含まれず、元のデータのかたまりの境界やサイズの情報も保持されません。

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

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

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での定義

#include <windows.h>

// EVENT_DATA_DESCRIPTOR  (x64 24 / x86 16 バイト)
typedef struct EVENT_DATA_DESCRIPTOR {
    ULONGLONG Ptr;
    DWORD Size;
    _Anonymous_e__Union Anonymous;
} EVENT_DATA_DESCRIPTOR;

using System;
using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct EVENT_DATA_DESCRIPTOR
{
    public ulong Ptr;
    public uint Size;
    public _Anonymous_e__Union Anonymous;
}

Imports System.Runtime.InteropServices

<StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Unicode)>
Public Structure EVENT_DATA_DESCRIPTOR
    Public Ptr As ULong
    Public Size As UInteger
    Public Anonymous As _Anonymous_e__Union
End Structure

import ctypes
from ctypes import wintypes

class EVENT_DATA_DESCRIPTOR(ctypes.Structure):
    _fields_ = [
        ("Ptr", ctypes.c_ulonglong),
        ("Size", wintypes.DWORD),
        ("Anonymous", _Anonymous_e__Union),
    ]

#[repr(C)]
pub struct EVENT_DATA_DESCRIPTOR {
    pub Ptr: u64,
    pub Size: u32,
    pub Anonymous: _Anonymous_e__Union,
}

import "golang.org/x/sys/windows"

type EVENT_DATA_DESCRIPTOR struct {
	Ptr uint64
	Size uint32
	Anonymous _Anonymous_e__Union
}

type
  EVENT_DATA_DESCRIPTOR = record
    Ptr: UInt64;
    Size: DWORD;
    Anonymous: _Anonymous_e__Union;
  end;

const EVENT_DATA_DESCRIPTOR = extern struct {
    Ptr: u64,
    Size: u32,
    Anonymous: _Anonymous_e__Union,
};

type
  EVENT_DATA_DESCRIPTOR {.bycopy.} = object
    Ptr: uint64
    Size: uint32
    Anonymous: _Anonymous_e__Union

struct EVENT_DATA_DESCRIPTOR
{
    ulong Ptr;
    uint Size;
    _Anonymous_e__Union Anonymous;
}

HSP用定義

HSP3.7/3.8 は構造体機能が無いため4byte整数配列(dim)+peek/poke で操作(32/64bitでサイズ・位置が異なる場合はタブで分割)。IronHSP は NSTRUCT(#defstruct/stdim/->)で32/64bit共通。

; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x86 レイアウト)
; EVENT_DATA_DESCRIPTOR サイズ: 16 バイト(x86)
dim st, 4    ; 4byte整数×4(構造体サイズ 16 / 4 切り上げ)
; Ptr : ULONGLONG (+0, 8byte)  qpoke st,0,値 / qpeek(st,0)  ※IronHSPのみ。3.7/3.8は lpoke st,0,下位 : lpoke st,4,上位
; Size : DWORD (+8, 4byte)  st.2 = 値  /  値 = st.2   (lpoke/lpeek も可)
; Anonymous : _Anonymous_e__Union (+12, 4byte)  varptr(st)+12 を基点に操作(4byte:入れ子/配列)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。

; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x64 レイアウト)
; EVENT_DATA_DESCRIPTOR サイズ: 24 バイト(x64)
dim st, 6    ; 4byte整数×6(構造体サイズ 24 / 4 切り上げ)
; Ptr : ULONGLONG (+0, 8byte)  qpoke st,0,値 / qpeek(st,0)  ※IronHSPのみ。3.7/3.8は lpoke st,0,下位 : lpoke st,4,上位
; Size : DWORD (+8, 4byte)  st.2 = 値  /  値 = st.2   (lpoke/lpeek も可)
; Anonymous : _Anonymous_e__Union (+16, 8byte)  varptr(st)+16 を基点に操作(8byte:入れ子/配列)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。

; IronHSP は NSTRUCT(構造体)をサポート。32bit/64bit どちらでも同じコードで動作します。
#defstruct global EVENT_DATA_DESCRIPTOR
    #field int64 Ptr
    #field int Size
    #field byte Anonymous 8
#endstruct

stdim st, EVENT_DATA_DESCRIPTOR        ; NSTRUCT 変数を確保
st->Ptr = 100
mes "Ptr=" + st->Ptr
; ※union フィールドは byte 列で確保(NSTRUCT は union 非対応)。必要に応じ手動でアクセス。