Formats a property value for display.
TDHSTATUS TdhFormatProperty( PTRACE_EVENT_INFO EventInfo, PEVENT_MAP_INFO MapInfo, ULONG PointerSize, USHORT PropertyInType, USHORT PropertyOutType, USHORT PropertyLength, USHORT UserDataLength, PBYTE UserData, PULONG BufferSize, PWCHAR Buffer, PUSHORT UserDataConsumed );
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.
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 is passed to your EventRecordCallback callback function.
The input type of the property. Use the InType member of the EVENT_PROPERTY_INFO structure to set this parameter.
The output type of the property. Use the OutType member of the EVENT_PROPERTY_INFO structure to set this parameter.
The length, in bytes, of the property. Use the Length member of the EVENT_PROPERTY_INFO structure to set this parameter.
The size, in bytes, of the UserData buffer. See Remarks.
The buffer that contains the event data. See Remarks.
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.
A caller-allocated buffer that contains the formatted property value. To determine the required buffer size, set this parameterto NULL and BufferSize to zero.
The length, in bytes, of the consumed event data. Use this value to adjust the values of the UserData and UserDataLength parameters. See Remarks.
Returns ERROR_SUCCESS if successful. Otherwise, this function returns one of the following return codes in addition to others.
||The size of the pBuffer buffer is too small. Use the required buffer size set in pBufferSize to allocate a new buffer.|
||One or more of the parameters is not valid.|
||The event data does not match the event definition in the manifest.|
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 EventRecordCallback 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:
- The InType member of EVENT_PROPERTY_INFO is TDH_INTYPE_BINARY
- The OutType member of EVENT_PROPERTY_INFO is TDH_OUTTYPE_IPV6
- The Length member of the EVENT_PROPERTY_INFO is 0
For an example that shows how to call this function , see Using TdhFormatProperty to Consume Event Data.
|Minimum supported client||Windows 7 [desktop apps only]|
|Minimum supported server||Windows Server 2008 R2 [desktop apps only]|