Edit

TdhFormatProperty function (tdh.h)

  • Article

Formats a property value for display.

Syntax

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
);

Parameters

[in] EventInfo

A TRACE_EVENT_INFO structure that contains the event information. To get this structure, call the TdhGetEventInformation function.

[in, optional] MapInfo

An EVENT_MAP_INFO structure that maps integer and bit values to strings. To get this structure, call the TdhGetEventMapInformation function. To get the name of the map, use the MapNameOffset member of the EVENT_PROPERTY_INFO structure. If you do not provide the map information for a mapped property, the function formats the integer or bit value.

[in] PointerSize

The size of a pointer value in the event data. To get the size, access the EVENT_RECORD.EventHeader.Flags member. The pointer size is 4 bytes if the EVENT_HEADER_FLAG_32_BIT_HEADER flag is set; otherwise, it is 8 bytes if the EVENT_HEADER_FLAG_64_BIT_HEADER flag is set. The EVENT_RECORD structure (evntcons.h) is passed to your [PEVENT_RECORD_CALLBACK callback function].

[in] PropertyInType

The input type of the property. Use the InType member of the EVENT_PROPERTY_INFO structure to set this parameter.

[in] PropertyOutType

The output type of the property. Use the OutType member of the EVENT_PROPERTY_INFO structure to set this parameter.

[in] PropertyLength

The length, in bytes, of the property. Use the Length member of the EVENT_PROPERTY_INFO structure to set this parameter.

[in] UserDataLength

The size, in bytes, of the UserData buffer. See Remarks.

[in] UserData

The buffer that contains the event data. See Remarks.

[in, out] BufferSize

The size, in bytes, of the Buffer buffer. If the function succeeds, this parameter receives the size of the buffer used. If the buffer is too small, the function returns ERROR_INSUFFICIENT_BUFFER and sets this parameter to the required buffer size. If the buffer size is zero on input, no data is returned in the buffer and this parameter receives the required buffer size.

[out, optional] Buffer

A caller-allocated buffer that contains the formatted property value. To determine the required buffer size, set this parameterto NULL and BufferSize to zero.

[out] UserDataConsumed

The length, in bytes, of the consumed event data. Use this value to adjust the values of the UserData and UserDataLength parameters. See Remarks.

Return value

Returns ERROR_SUCCESS if successful. Otherwise, this function returns one of the following return codes in addition to others.

Return code Description
ERROR_INSUFFICIENT_BUFFER The size of the pBuffer buffer is too small. Use the required buffer size set in pBufferSize to allocate a new buffer.
ERROR_INVALID_PARAMETER One or more of the parameters is not valid.
ERROR_EVT_INVALID_EVENT_DATA The event data does not match the event definition in the manifest.

Remarks

Typically, you call this function in a loop. Use the TRACE_EVENT_INFO.TopLevelPropertyCount member to control the loop (the TdhGetEventInformation function returns the TRACE_EVENT_INFO structure). Before entering the loop, you set the UserData and UserDataLength parameters to the value of the UserData and UserDataLength members of the EVENT_RECORD structure, respectively. The EVENT_RECORD structure is passed to your [PEVENT_RECORD_CALLBACK callback function].

Determine whether the property is an array. The property is an array if the EVENT_PROPERTY_INFO.Flags member is set to PropertyParamCount or the EVENT_PROPERTY_INFO.count member is greater than 1. Call the TdhFormatProperty function in a loop based on the number of elements in the array.

After calling the TdhFormatProperty function, use the UserDataConsumed parameter value to set the new values of the UserData and UserDataLength parameters (Subtract UserDataConsumed from UserDataLength and use UserDataLength to increment the UserData pointer).

If the property is an IP V6 address, you must set the PropertyLength parameter to the size of the IN6_ADDR structure. The property is considered an IP V6 address if the following conditions are met:

Examples

For an example that shows how to call this function , see Using TdhFormatProperty to Consume Event Data.

Requirements

Requirement Value
Minimum supported client Windows 7 [desktop apps only]
Minimum supported server Windows Server 2008 R2 [desktop apps only]
Target Platform Windows
Header tdh.h
Library Tdh.lib
DLL Tdh.dll