EVENT_DATA_DESCRIPTOR 結構 (evntprov.h)
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 。 相反地，大部分的事件提供者都是使用 ETW 架構來實作，以包裝 對 EventRegister、 EventWrite 和 EventUnregister 的呼叫。 例如，您可以 撰寫事件指令清單 ，然後使用 訊息編譯 程式為事件產生 C/C++ 程式代碼，或者您可以使用 TraceLogging 來避免指令清單的需求。
若要撰寫包含事件數據的事件，您會針對每個) 數據區塊建立EVENT_DATA_DESCRIPTOR結構的陣列 ( 一個專案，並呼叫 EventDataDescCreate 函式，以使用事件中包含的數據初始化每個元素。 接著，您會將此陣列傳遞至 EventWrite ，以將數據包含在事件中。 如需範例，請參閱 撰寫以指令清單為基礎的事件。
寫入事件的數據會是傳遞至EventWrite函式之EVENT_DATA_DESCRIPTOR結構所參考之數據區塊的串連。 此串連不包含填補，而且不會保留原始數據集中任何界限或大小資訊。
ETW 事件的大小總計 (使用者提供數據的總和、 EVENT_HEADER，以及事件) 可能需要的任何 EVENT_HEADER_EXTENDED_DATA_ITEM 不能超過 64KB。 ETW 運行時間將會卸除大於 64KB 的事件。
此外，也將會卸除無法放入追蹤會話緩衝區的 ETW 事件。 每個緩衝區都有 72 位元組的標頭，因此可以放入緩衝區的最大事件稍微小於緩衝區的大小。 例如，使用 32KB 緩衝區的追蹤會話將無法接受大於 32,696 個字節的任何事件 (32,768 位元組緩衝區減去 72 位元組標頭的 32,696 個字節，則事件) 。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows Vista [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2008 [僅限傳統型應用程式] |
| 標頭 | evntprov.h |