TraceLoggingCustom 宏 (traceloggingprovider.h)

TraceLogging 包装器宏 ，用于将使用自定义序列化程序打包的字段添加到 事件。

大多数 TraceLogging 事件不需要使用自定义序列化程序，并且不应使用 TraceLoggingCustom。

语法

void TraceLoggingCustom(
  [in]            pValue,
  [in]            cbValue,
  [in]            protocol,
  [in]            bSchema,
  [in]            cbSchema,
  [in, optional]  __VA_ARGS__
);

参数

[in] pValue

指向字段有效负载的指针，在运行时由指定协议系列的序列化程序进行序列化。

[in] cbValue

字段有效负载的大小（以字节为单位），在运行时由指定协议系列的序列化程序序列化。

[in] protocol

协议系列，可以是 Microsoft 定义的 0-4 值，也可以是 5-31 中的用户定义的值。 Microsoft 定义的值由以 TRACELOGGING_PROTOCOL_开头的宏定义。

[in] bSchema

以逗号分隔的字节值列表，其中包含解码有效负载 (（即架构) ）所需的信息，采用协议定义的格式。 此列表中的值必须是编译时常量。 示例： (0x12、0x23、0x34)

[in] cbSchema

bSchema 中提供的字节值数。 此值必须是编译时常量。

[in, optional] __VA_ARGS__

字段定义的可选 名称、 说明和 标记 参数。

可以使用 5、6、7 或 8 个参数指定 TraceLoggingCustom。 如果未指定参数，将使用默认值。 例如，TraceLoggingCustom(&x.data, sizeof(x.data), p, (schema), cbSchema) 等效于 TraceLoggingCustom(&x.data, sizeof(x.data), p, (schema), cbSchema, "&x.data", "", 0)。

• [in, optional] name

  要用于事件字段的名称。 如果提供，则 name 参数必须是字符串文本 (不是) 变量，并且不得包含任何“\0”字符。 如果未提供，事件字段名称将基于 pValue。

• [in, optional] description

  事件字段值的说明。 如果提供说明参数，则说明参数必须是字符串文本，并且将包含在 PDB 中。

• [in, optional] tags

  编译时常量整数值。 该值的低 28 位将包含在字段的元数据中。 此值的语义由事件使用者定义。 在事件处理期间，可以从 “EVENT_PROPERTY_INFO 标记”字段检索此值。

返回值

无

备注

TraceLoggingCustom(pValue, cbValue, protocol, (schema...), cbSchema, ...) 可用作 TraceLoggingWrite 宏调用的参数。 每个 TraceLoggingCustom 参数都会向事件添加一个自定义序列化字段。 大多数 TraceLogging 事件不使用自定义序列化程序，并且不应使用 TraceLoggingCustom。 常规用途 ETW 解码器不支持使用自定义序列化的字段，通常将这些字段视为TDH_INTYPE_BINARY。

解码器应使用 TDH API 访问 TraceLoggingCustom 序列化字段。 TdhGetEventInformation 返回的 TRACE_EVENT_INFO 结构将包含两个与记录的 TraceLoggingCustom 字段相关的EVENT_PROPERTY_INFO结构。 它们以典型方式与二进制字段 (TDH_INTYPE_BINARY) EVENT_RECORD的 UserData Blob 中找到的数据相关联。

• 两个EVENT_PROPERTY_INFO结构中的第一个是“Length”属性，用于描述序列化有效负载 (的长度，即 cbValue) 。
• 第二个属性引用用户的有效负载 (pbValue) 。 第二个属性将具有 PropertyParamLength (引用“Length”属性) 和 PropertyHasCustomSchema 集。

解码器应识别已设置 PropertyHasCustomSchema，并查阅 customSchemaOffset EVENT_PROPERTY_INFO的 customSchemaType 成员，该成员是协议类型和协议元数据所在的TRACE_EVENT_INFORMATION中的偏移量。 在那里，他们可以找到传入的元数据，格式为 (伪结构) ：

struct _CUSTOM_SCHEMA {
    UINT16 protocolType;
    UINT16 cbSchema;
    BYTE bSchema[cbSchema];
};

不采取这些额外步骤来识别 PropertyHasCustomSchema 标志，而是引用EVENT_PROPERTY_INFO联合的 nonStructType 部分来解码事件的现有解码器将无缝地将有效负载视为TDH_INTYPE_BINARY。

示例

// Value generated at runtime by serializer:
BYTE rgValue[] = {...};

TraceLoggingWrite(
   g_hProvider,
   "MyEventName",
   TraceLoggingCustom(
      rgValue,
      sizeof(rgValue),
      TRACELOGGING_PROTOCOL_MYPROTOCOL,
      ( 0x0, 0x1, 0x2 ), // Generated at compile-time
      3,
      "MyCustomField"),
   TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
   TraceLoggingKeyword(MyEventCategories)); // Provider-defined categories

要求

另请参阅

TraceLoggingWrite

TraceLogging 包装宏