Функция 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. Чтобы получить имя карты, используйте элемент MapNameOffsetструктуры EVENT_PROPERTY_INFO. Если данные карты для сопоставленного свойства не указаны, функция форматирует целое число или битовое значение.

[in] PointerSize

Размер значения указателя в данных события. Чтобы получить размер, получите доступ к EVENT_RECORD. Элемент EventHeader.Flags . Размер указателя составляет 4 байта, если установлен флаг EVENT_HEADER_FLAG_32_BIT_HEADER; В противном случае значение равно 8 байтам, если установлен флаг EVENT_HEADER_FLAG_64_BIT_HEADER. Структура EVENT_RECORD (evntcons.h) передается в [функцию обратного вызова PEVENT_RECORD_CALLBACK].

[in] PropertyInType

Тип входных данных свойства . Используйте элемент InTypeструктуры EVENT_PROPERTY_INFO , чтобы задать этот параметр.

[in] PropertyOutType

Тип выходных данных свойства . Используйте элемент OutTypeструктуры EVENT_PROPERTY_INFO , чтобы задать этот параметр.

[in] PropertyLength

Длина свойства в байтах. Используйте элемент Lengthструктуры EVENT_PROPERTY_INFO , чтобы задать этот параметр.

[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 значение элементов UserData и UserDataLengthструктуры EVENT_RECORD соответственно. Структура EVENT_RECORD передается в [функцию обратного вызова PEVENT_RECORD_CALLBACK].

Определите, является ли свойство массивом. Свойство является массивом, если EVENT_PROPERTY_INFO. Элемент Flags имеет значение PropertyParamCount или член EVENT_PROPERTY_INFO.count больше 1. Вызовите функцию TdhFormatProperty в цикле на основе количества элементов в массиве.

После вызова функции TdhFormatProperty используйте значение параметра UserDataConsumed , чтобы задать новые значения параметров UserData и UserDataLength (вычитайте UserDataConsumed из UserDataLength и используйте UserDataLength для увеличения указателя UserDataData ).

Если свойство является IP-адресом версии 6, необходимо задать для параметра PropertyLength размер структуры IN6_ADDR . Свойство считается IP-адресом версии 6 при выполнении следующих условий:

Примеры

Пример вызова этой функции см. в разделе Использование TdhFormatProperty для использования данных о событиях.

Требования

Требование Значение
Минимальная версия клиента Windows 7 [только классические приложения]
Минимальная версия сервера Windows Server 2008 R2 [только классические приложения]
Целевая платформа Windows
Header tdh.h
Библиотека Tdh.lib
DLL Tdh.dll