通过

TdhFormatProperty 函数 (tdh.h)

  • 项目

设置用于显示的属性值的格式。

语法

TDHSTATUS TdhFormatProperty(
  [in]            PTRACE_EVENT_INFO EventInfo,
  [in, optional]  PEVENT_MAP_INFO   MapInfo,
  [in]            ULONG             PointerSize,
  [in]            USHORT            PropertyInType,
  [in]            USHORT            PropertyOutType,
  [in]            USHORT            PropertyLength,
  [in]            USHORT            UserDataLength,
  [in]            PBYTE             UserData,
  [in, out]       PULONG            BufferSize,
  [out, optional] PWCHAR            Buffer,
  [out]           PUSHORT           UserDataConsumed
);

参数

[in] EventInfo

包含事件信息的 TRACE_EVENT_INFO结构 。 若要获取此结构，请调用 TdhGetEventInformation 函数。

[in, optional] MapInfo

将整数和位值映射到字符串 的EVENT_MAP_INFO结构 。 若要获取此结构，请调用 TdhGetEventMapInformation 函数。 若要获取映射的名称，请使用 EVENT_PROPERTY_INFO 结构的MapNameOffset 成员。 如果未提供映射属性的映射信息，该函数将设置整数或位值的格式。

[in] PointerSize

事件数据中指针值的大小。 若要获取大小，请访问 EVENT_RECORD。EventHeader.Flags 成员。 如果设置了EVENT_HEADER_FLAG_32_BIT_HEADER标志，则指针大小为 4 个字节;否则，如果设置了EVENT_HEADER_FLAG_64_BIT_HEADER标志，则为 8 个字节。 EVENT_RECORD结构 (evntcons.h) 传递到 [PEVENT_RECORD_CALLBACK 回调函数]。

[in] PropertyInType

属性的输入类型。 使用 EVENT_PROPERTY_INFO 结构的InType 成员来设置此参数。

[in] PropertyOutType

属性的输出类型。 使用 EVENT_PROPERTY_INFO 结构的OutType 成员来设置此参数。

[in] PropertyLength

属性的长度（以字节为单位）。 使用 EVENT_PROPERTY_INFO 结构的Length 成员来设置此参数。

[in] UserDataLength

UserData 缓冲区的大小（以字节为单位）。 请参阅“备注”。

[in] UserData

包含事件数据的缓冲区。 请参阅“备注”。

[in, out] BufferSize

缓冲区的大小（以字节为单位）。 如果函数成功，此参数将接收所用缓冲区的大小。 如果缓冲区太小，函数将返回ERROR_INSUFFICIENT_BUFFER并将此参数设置为所需的缓冲区大小。 如果输入时缓冲区大小为零，则缓冲区中不返回任何数据，并且此参数接收所需的缓冲区大小。

[out, optional] Buffer

一个调用方分配的缓冲区，其中包含格式化的属性值。 若要确定所需的缓冲区大小，请将此参数设置为 NULL ， 并将 BufferSize 设置为零。

[out] UserDataConsumed

已使用事件数据的长度（以字节为单位）。 使用此值可以调整 UserData 和 UserDataLength 参数的值。 请参阅“备注”。

返回值

如果成功，则返回ERROR_SUCCESS。 否则，此函数除了返回其他返回代码外，还会返回以下返回代码之一。

返回代码 说明
ERROR_INSUFFICIENT_BUFFER pBuffer 缓冲区的大小太小。 使用 pBufferSize 中设置的所需缓冲区大小来分配新缓冲区。
ERROR_INVALID_PARAMETER 一个或多个参数无效。
ERROR_EVT_INVALID_EVENT_DATA 事件数据与清单中的事件定义不匹配。

注解

通常，在循环中调用此函数。 使用 TRACE_EVENT_INFO。用于控制循环的 TopLevelPropertyCount 成员 (TdhGetEventInformation 函数 返回 ) TRACE_EVENT_INFO结构 。 在进入循环之前，将 UserData 和 UserDataLength 参数分别设置为 EVENT_RECORD 结构的UserData 和 UserDataLength 成员的值。 EVENT_RECORD 结构将传递给 [PEVENT_RECORD_CALLBACK 回调函数]。

确定 属性是否为数组。 如果EVENT_PROPERTY_INFO，则 属性是数组 。Flags 成员设置为 PropertyParamCount 或 EVENT_PROPERTY_INFO.count 成员大于 1。 根据数组中的元素数在循环中调用 TdhFormatProperty 函数。

调用 TdhFormatProperty 函数后，使用 UserDataConsumed 参数值设置 UserData 和 UserDataLength 参数的新值， (从 UserDataLength 减去 UserDataConsumed，并使用 UserDataLength 递增 UserData 指针) 。

如果 属性是 IP V6 地址，则必须将 PropertyLength 参数设置为 IN6_ADDR 结构的大小。 如果满足以下条件，则 属性被视为 IP V6 地址：

示例

有关演示如何调用此函数 的示例，请参阅 使用 TdhFormatProperty 来使用事件数据。

要求

要求 值
最低受支持的客户端 Windows 7 [仅限桌面应用]
最低受支持的服务器 Windows Server 2008 R2 [仅限桌面应用]
目标平台 Windows
标头 tdh.h
Library Tdh.lib
DLL Tdh.dll