Макрос TraceLoggingCustom (traceloggingprovider.h)

Статья
08/26/2023

Макрос-оболочка 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

Семейство протоколов, которое может быть определяемым корпорацией Майкрософт значением от 0 до 4 или определяемым пользователем значением от 5 до 31. Значения, определяемые корпорацией Майкрософт, определяются макросами, начиная с TRACELOGGING_PROTOCOL_.

[in] bSchema

Разделенный запятыми список значений байтов, содержащий сведения, необходимые для декодирования полезных данных (т. е. схемы) в формате, определенном протоколом. Значения в этом списке должны быть константой времени компиляции. Пример: (0x12, 0x23, 0x34)

[in] cbSchema

Количество байтовых значений, указанных в bSchema. Это значение должно быть константой времени компиляции.

[in, optional] __VA_ARGS__

Необязательные параметры имени, описания и тегов для определения поля.

TraceLoggingCustom можно указать с 5, 6, 7 или 8 параметрами. Если параметр не указан, будет использоваться значение по умолчанию. Например, выражение 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

Описание значения поля события. Если он указан, параметр description должен быть строковым литералом и будет включен в PDB.
[in, optional] tags

Целочисленное значение константы времени компиляции. Низкие 28 бит значения будут включены в метаданные поля. Семантика этого значения определяется потребителем события. Во время обработки события это значение можно получить из поля EVENT_PROPERTY_INFO Теги.

Возвращаемое значение

None

Remarks

TraceLoggingCustom(pValue, cbValue, protocol, (schema...), cbSchema, ...) можно использовать в качестве параметра для вызова макроса TraceLoggingWrite . Каждый параметр TraceLoggingCustom добавляет в событие настраиваемое сериализованное поле. Большинство событий TraceLogging не используют пользовательские сериализаторы и не должны использовать TraceLoggingCustom. Декодеры трассировки событий Windows общего назначения не поддерживают поля, использующие настраиваемую сериализацию и обычно обрабатывают поля как TDH_INTYPE_BINARY.

Декодеры должны обращаться к сериализованным полям TraceLoggingCustom с помощью API TDH. Структура TRACE_EVENT_INFO, возвращаемая TdhGetEventInformation, будет содержать две структуры EVENT_PROPERTY_INFO, связанные с зарегистрированным полем TraceLoggingCustom. Они обычно коррелируют с данными, найденными в большом двоичном объекте UserData EVENT_RECORD для двоичного поля (TDH_INTYPE_BINARY).

Первая из двух EVENT_PROPERTY_INFO структур — это свойство Length, которое описывает длину сериализованных полезных данных (т. е. cbValue).
Второй — это свойство, которое ссылается на полезные данные пользователя (pbValue). Второе свойство будет иметь свойство PropertyParamLength (в ссылке на свойство Length) и PropertyHasCustomSchema.

Декодеры должны распознавать, что свойство PropertyHasCustomSchema задано, и обращаться к члену customSchemaType EVENT_PROPERTY_INFO для CustomSchemaOffset, который является смещением в TRACE_EVENT_INFORMATION, где находятся тип протокола и метаданные протокола. Там они могут найти метаданные, которые они передали в формате (псевдоструктура):

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

Существующие декодеры, которые не выполняют эти дополнительные действия для распознавания флага PropertyHasCustomSchema и вместо этого ссылаются на часть nonStructType объединения EVENT_PROPERTY_INFO для декодирования события, будут легко обрабатывать полезные данные, как если бы они были 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

Требования


Минимальная версия клиента	Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2008 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	traceloggingprovider.h

См. также раздел

TraceLoggingWrite

Макросы-оболочки TraceLogging

Поделиться через