evntprov.h) (EVENT_DATA_DESCRIPTOR 结构

  • 项目

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。 大于 64KB 的事件将由 ETW 运行时删除。

此外，无法放入跟踪会话缓冲区的 ETW 事件也将被删除。 每个缓冲区都有一个 72 字节标头，因此可以放入缓冲区的最大事件略小于缓冲区的大小。 例如，使用 32KB 缓冲区的跟踪会话将无法接受任何大于 32,696 字节的事件 (32,768 字节缓冲区减去 72 字节标头后 32,696 字节的事件) 。

要求

要求 值
最低受支持的客户端 Windows Vista [仅限桌面应用]
最低受支持的服务器 Windows Server 2008 [仅限桌面应用]
标头 evntprov.h

另请参阅

EVENT_HEADER

EVENT_HEADER_EXTENDED_DATA_ITEM

EventDataDescCreate

EventWrite

EventWriteTransfer

编写基于清单的事件