EVENT_DATA_DESCRIPTOR 結構 (evntprov.h)

發行項
02/26/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 。相反地，大部分的事件提供者都是使用 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