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

  • Статья

Макросы TraceLoggingWrite и TraceLoggingWriteActivity выдают события TraceLogging, настроенные в соответствии с параметрами макроса. Каждый из этих макросов принимает набор обязательных параметров, за которыми следует до 99 необязательных параметров. Каждый необязательный параметр либо настраивает событие, либо добавляет в событие поле. Каждый необязательный параметр должен быть одним из макросов оболочки TraceLogging, описанных на этой странице.

Пример:

TraceLoggingWrite(
    g_hProvider,
    "MyEvent1",
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyNetworkingKeyword),
    TraceLoggingString(operationName), // Adds an "operationName" field.
    TraceLoggingHResult(hr, "NetStatus")); // Adds a "NetStatus" field.

В этом примере g_hProvider и "MyEvent1" являются обязательными параметрами. Они указывают поставщика, который будет использоваться для события, и имя события. Каждый из оставшихся параметров является макросом-оболочкой. Параметры TraceLoggingLevel и TraceLoggingKeyword настраивают событие. Параметры TraceLoggingString и TraceLoggingHResult добавляют поля в событие .

Макросы конфигурации событий

Следующие макросы настраивают событие.

Если определенный макрос конфигурации не указан в TraceLoggingWrite, для этого события используется значение по умолчанию. Например, если для события не используется параметр TraceLoggingLevel , событие использует уровень по умолчанию 5 (VERBOSE).

  • TraceLoggingLevel задает уровень события. Уровень — это 8-битовое значение, указывающее серьезность события. Уровни от 1 (WINEVENT_LEVEL_CRITICAL) до 5 (WINEVENT_LEVEL_VERBOSE) определяются в <winmeta.h>. Если значение не указано, событие по умолчанию использует уровень 5 (VERBOSE). Уровень является важной частью маршрутизации и фильтрации событий ETW, поэтому все события должны иметь значимый уровень, отличный от нуля.
  • TraceLoggingKeyword задает ключевое слово события. Ключевое слово — это 64-разрядное значение, каждый бит которого указывает категорию, к которой относится событие. Низкие 48 бит ключевое слово определяются владельцем поставщика, а высокие 16 бит ключевое слово определяются корпорацией Майкрософт. Например, вы можете решить, что все поставщики с именем MyCompany.MyComponent будут использовать ключевое слово 0x1 для обозначения "Сеть". Если значение не указано, событие по умолчанию ключевое слово 0x0 (Нет). Ключевое слово является важной частью маршрутизации и фильтрации событий ETW, поэтому все события должны иметь значимую ненулевую ключевое слово.
  • TraceLoggingOpcode задает код операции события. Код операции — это 8-битовое значение, указывающее специальную семантику события, например, то, что событие записывает начало (WINEVENT_OPCODE_START) или конец (WINEVENT_OPCODE_STOP) действия ETW (группа связанных событий). Если значение не указано, событие по умолчанию использует код операции 0 (WINEVENT_OPCODE_INFO), указывая, что специальная семантика не требуется.
  • TraceLoggingChannel задает канал события. Канал — это 8-битовое значение, которое используется для различных целей. Если значение не указано, событие по умолчанию использует канал 11 (WINEVENT_CHANNEL_TRACELOGGING). Большинству событий не требуется изменять канал события и не следует использовать TraceLoggingChannel.
  • TraceLoggingEventTag задает тег события. Тег является 28-разрядным значением с семантикой, определяемой поставщиком. Например, поставщик может определить бит тега 0x1000000, чтобы указать, что событие потенциально содержит личные сведения и должно получать специальный режим от средств обработки событий, относящихся к конкретному поставщику. Если этот тег не указан, по умолчанию используется значение 0.
  • TraceLoggingDescription задает описание события. Описание — это строковый литерал с понятным для человека описанием события. Он служит комментарием о назначении события, а описание также записывается в виде заметки в отладочных символах компонента (PDB). Если значение не указано, по умолчанию используется ""описание .
  • TraceLoggingCustomAttribute добавляет заметку "ключ-значение" к отладочным символам компонента (PDB).

Макросы полей

TraceLogging поддерживает множество макросов-оболочек для добавления полей в событие. Каждое поле является парой "имя-значение". Например, TraceLoggingInt32(argc, "ArgCount") добавит поле INT32 с именем "ArgCount" со значением argc.

Большинство макросов-оболочек полей принимают аналогичные параметры:

  • Значение: Выражение, которое будет вычисляться во время выполнения для определения данных для включения в поле. Большинство макросов-оболочки полей используют один параметр для указания значения, но для некоторых макросов требуется несколько параметров для значения поля, например указатель и длина. Параметры значений всегда являются обязательными.
    • В некоторых случаях значение поля указывается как pszValue, в этом случае оно является указателем на строку символов с 0-символами, включаемую в поле. PszValue может иметь значение NULL, в этом случае значение поля будет пустой строкой "".
    • В некоторых случаях значение поля указывается как pchValue, в этом случае оно является указателем на строку символов cchValue для включения в поле. Значение pchValue может иметь значение NULL, только если значение cchValue равно 0.
    • В некоторых случаях значение поля указывается как pValue с автоматически определенным размером (без параметра cbValue ), в этом случае оно является указателем на значение, включаемое в поле. Значение pValue не может иметь значение NULL.
    • В некоторых случаях значение поля указывается как pValue с параметром cbValue , чтобы указать размер (в байтах) данных для включения в поле. Значение pValue может иметь значение NULL, только если cbValue равно 0.
  • Имя: Строковый литерал (констант времени компиляции) с именем, используемым для поля. Для большинства макросов-оболочек полей параметр name не требуется. Если опустить параметр name, имя поля определяется на основе текста препроцессора значения макроса, pszValue, pchValue или pValue . Например, выражение TraceLoggingInt32(x[4] + y) будет эквивалентно TraceLoggingInt32(x[4] + y, "x[4] + y"). В обоих случаях к событию добавляется поле "x[4] + y" со значением, определяемым путем вычисления выражения x[4] + y.
  • Описание: Строковый литерал (констант времени компиляции) с описанием, используемым для поля. В основном это удобное место для размещения комментария к полю, но описание также записывается в виде заметки в отладочных символах компонента (PDB). Описание является необязательным. Если параметр description опущен, описание поля по умолчанию имеет значение "".
  • Тег: 28-разрядное целое число (константа времени компиляции) с семантикой, определяемой поставщиком. Например, поставщик может определить 0x2 тегов, чтобы указать, что поле содержит номер телефона и должно получать специальную обработку от средств обработки событий, относящихся к конкретному поставщику. Если параметр тега опущен, тег поля по умолчанию имеет значение 0.

Например, следующие макрокоманды оболочки имеют одинаковый эффект:

  • TraceLoggingInt32(argc)
  • TraceLoggingInt32(argc, "argc")
  • TraceLoggingInt32(argc, "argc", "")
  • TraceLoggingInt32(argc, "argc", "", 0)

Скаляры

  • TraceLoggingValue(value, [name, ...]):

    Добавляет поле с типом, который автоматически выводится из типа параметра value. (только C++)

  • TraceLoggingInt8(value, [name, ...]):

    Добавляет поле со значением INT8.

  • TraceLoggingUInt8(value, [name, ...]):

    Добавляет поле со значением UINT8.

  • TraceLoggingInt16(value, [name, ...]):

    Добавляет поле со значением INT16.

  • TraceLoggingUInt16(value, [name, ...]):

    Добавляет поле со значением UINT16.

  • TraceLoggingInt32(value, [name, ...]):

    Добавляет поле со значением INT32.

  • TraceLoggingUInt32(value, [name, ...]):

    Добавляет поле со значением UINT32.

  • TraceLoggingInt64(value, [name, ...]):

    Добавляет поле со значением INT64.

  • TraceLoggingUInt64(value, [name, ...]):

    Добавляет поле со значением UINT64.

  • TraceLoggingIntPtr(value, [name, ...]):

    Добавляет поле со значением INT_PTR (целое число со знаком с тем же размером, что и указатель).

  • TraceLoggingUIntPtr(value, [name, ...]):

    Добавляет поле со значением UINT_PTR (целое число без знака с тем же размером, что и указатель).

  • TraceLoggingLong(value, [name, ...]):

    Добавляет поле со значением LONG (со знаком long int, 32-разрядные значения на платформах Windows).

  • TraceLoggingULong(value, [name, ...]):

    Добавляет поле со значением ULONG (unsigned long int, 32-bits на платформах Windows).

  • TraceLoggingHexInt8(value, [name, ...]):

    Добавляет поле со значением INT8 с указанием шестнадцатеричного форматирования.

  • TraceLoggingHexUInt8(value, [name, ...]):

    Добавляет поле со значением UINT8 с шестнадцатеричным указанием форматирования.

  • TraceLoggingHexInt16(value, [name, ...]):

    Добавляет поле со значением INT16 с указанием шестнадцатеричного форматирования.

  • TraceLoggingHexUInt16(value, [name, ...]):

    Добавляет поле со значением UINT16 с шестнадцатеричным указанием форматирования.

  • TraceLoggingHexInt32(value, [name, ...]):

    Добавляет поле со значением INT32 с шестнадцатеричным указанием форматирования.

  • TraceLoggingHexUInt32(value, [name, ...]):

    Добавляет поле со значением UINT32 с шестнадцатеричным указанием форматирования.

  • TraceLoggingHexInt64(value, [name, ...]):

    Добавляет поле со значением INT64 с шестнадцатеричным указанием форматирования.

  • TraceLoggingHexUInt64(value, [name, ...]):

    Добавляет поле со значением UINT64 с шестнадцатеричным указанием форматирования.

  • TraceLoggingHexIntPtr(value, [name, ...]):

    Добавляет поле с INT_PTR значением с шестнадцатеричным указанием форматирования.

  • TraceLoggingHexUIntPtr(value, [name, ...]):

    Добавляет поле с UINT_PTR значением с шестнадцатеричным указанием форматирования.

  • TraceLoggingHexLong(value, [name, ...]):

    Добавляет поле со значением LONG с указанием шестнадцатеричного форматирования.

  • TraceLoggingHexULong(value, [name, ...]):

    Добавляет поле со значением ULONG с шестнадцатеричным указанием форматирования.

  • TraceLoggingFloat32(value, [name, ...]):

    Добавляет поле со значением FLOAT (32-разрядной плавающей запятой).

  • TraceLoggingFloat64(value, [name, ...]):

    Добавляет поле со значением DOUBLE (64-разрядная плавающая запятая).

  • TraceLoggingBoolean(value, [name, ...]):

    Добавляет поле с 8-разрядным логическим значением (Win32 BOOLEAN или C++ bool).

  • TraceLoggingBool(value, [name, ...]):

    Добавляет поле с 32-разрядным логическим значением (Win32 BOOL).

  • TraceLoggingChar(value, [name, ...]):

    Добавляет поле со значением char (8-битовое целое число с указанием форматирования строки, которое обычно рассматривается как кодовая страница 1252).

  • TraceLoggingChar16(value, [name, ...]):

    Добавляет поле со значением char16_t (16-битовое целое число с указанием форматирования строки, которое обычно обрабатывается как UCS-2).

  • TraceLoggingWChar(value, [name, ...]):

    Добавляет поле со значением wchar_t (то же, что и char16_t на платформах Windows).

  • TraceLoggingPointer(value, [name, ...]):

    Добавляет поле со значением void* (значение размера указателя с указанием шестнадцатеричного форматирования).

  • TraceLoggingCodePointer(value, [name, ...]):

    Добавляет поле со значением void* (значение размера указателя с указанием форматирования указателя кода).

  • TraceLoggingPid(value, [name, ...]):

    Добавляет поле со значением INT32 с указанием форматирования идентификатора процесса.

  • TraceLoggingTid(value, [name, ...]):

    Добавляет поле со значением INT32 с указанием форматирования идентификатора потока.

  • TraceLoggingIPv4Address(value, [name, ...]):

    Добавляет поле со значением UINT32 с указанием форматирования IPv4 (порядок сетевых байтов).

  • TraceLoggingIPv6Address(pValue, [name, ...]):

    Добавляет поле с 16-байтным двоичным значением с указанием форматирования IPv6.

  • TraceLoggingPort(value, [name, ...]):

    Добавляет поле со значением UINT16 с указанием форматирования IP-порта (порядок сетевых байтов).

  • TraceLoggingSocketAddress(pValue, cbValue, [name, ...]):

    Добавляет поле со значением SOCKADDR .

  • TraceLoggingWinError(value, [name, ...]):

    Добавляет поле со значением UINT32 с указанием форматирования кода ошибки Win32.

  • TraceLoggingNTStatus(value, [name, ...]):

    Добавляет поле со значением NTSTATUS (LONG) с указанием форматирования кода ошибки WinNT.

  • TraceLoggingHResult(value, [name, ...]):

    Добавляет поле со значением HRESULT (LONG) с указанием форматирования Windows HRESULT.

  • TraceLoggingFileTime(value, [name, ...]):

    Добавляет поле со значением FILETIME . При использовании в коде value C параметр должен быть выражением lvalue.

  • TraceLoggingFileTimeUtc(value, [name, ...]):

    Добавляет поле со значением FILETIME с указанием форматирования часового пояса UTC. При использовании в коде value C параметр должен быть выражением lvalue.

  • TraceLoggingSystemTime(value, [name, ...]):

    Добавляет поле со значением SYSTEMTIME . При использовании в коде value C параметр должен быть выражением lvalue.

  • TraceLoggingSystemTimeUtc(value, [name, ...]):

    Добавляет поле со значением SYSTEMTIME с указанием форматирования часового пояса UTC. При использовании в коде value C параметр должен быть выражением lvalue.

  • TraceLoggingGuid(value, [name, ...]):

    Добавляет поле со значением GUID . При использовании в коде value C параметр должен быть выражением lvalue.

  • TraceLoggingString(pszValue, [name, ...]):

    Добавляет поле со строкой с символом char 0 (обычно это кодовая страница 1252). Если значение pszValue равно NULL, в качестве значения поля используется пустая строка "" .

  • TraceLoggingUtf8String(pszValue, [name, ...]):

    Добавляет поле со строкой, заканчивающейся char 0, с указанием форматирования UTF-8. Если значение pszValue равно NULL, в качестве значения поля используется пустая строка "" .

  • TraceLoggingString16(pszValue, [name, ...]):

    Добавляет поле со строкой, заканчивающейся char16_t 0 (UTF-16). Если значение pszValue равно NULL, в качестве значения поля используется пустая строка u"" .

  • TraceLoggingWideString(pszValue, [name, ...]):

    Добавляет поле со строкой, заканчивающейся wchar_t 0 (UTF-16 в Windows). Если значение pszValue равно NULL, в качестве значения поля используется пустая строка L"" .

  • TraceLoggingCountedString(pchValue, cchValue, [name, ...]):

    Добавляет поле с подсчитываемой char строкой (обычно обрабатывается как кодовая страница 1252). Значение pchValue может иметь значение NULL, только если значение cchValue равно 0.

  • TraceLoggingCountedUtf8String(pchValue, cchValue, [имя, описание, тег]):

    Добавляет поле с подсчитываемой char строкой с указанием форматирования UTF-8. Значение pchValue может иметь значение NULL, только если значение cchValue равно 0.

  • TraceLoggingCountedString16(pchValue, cchValue, [name, ...]):

    Добавляет поле с подсчитываемой строкой char16_t (UTF-16). Значение pchValue может иметь значение NULL, только если значение cchValue равно 0.

  • TraceLoggingCountedWideString(pchValue, cchValue, [name, description, tag]):

    Добавляет поле с подсчитываемой wchar_t строкой (UTF-16 в Windows). Значение pchValue может иметь значение NULL, только если значение cchValue равно 0.

  • TraceLoggingAnsiString(pValue, [name, ...]):

    Добавляет поле со значением ANSI_STRING . Указатель pValue не должен иметь значение NULL.

  • TraceLoggingUnicodeString(pValue, [name, ...]):

    Добавляет поле со значением UNICODE_STRING . Указатель pValue не должен иметь значение NULL.

  • TraceLoggingSid(pValue, [name, ...]):

    Добавляет поле со значением SID . Указатель pValue не должен иметь значение NULL и должен указывать на правильно инициализированный идентификатор безопасности (значение Revision и SubAuthorityCount должно быть допустимым).

  • TraceLoggingBinary(pValue, cbValue, [name, ...]):

    Добавляет поле с двоичными данными.

  • TraceLoggingBinaryEx(pValue, cbValue, outType, [name, ...]):

    Добавляет поле с двоичными данными с указанием форматирования, заданным параметром outType.

  • TraceLoggingBinaryBuffer(pValue, StructType, [name, ...]):

    Добавляет поле с двоичными данными. pValue должен быть ненулевым указателем на структуру StructType . pValue->Buffer значение должно указывать на начало данных и pValue->Length должно быть числом байтов данных, которые должны быть включены в поле.

  • TraceLoggingBinaryBufferEx(pValue, StructType, outType, name, description, tag):

    Добавляет поле с двоичными данными с указанием форматирования, заданным параметром outType. pValue должен быть ненулевым указателем на структуру StructType . pValue->Buffer значение должно указывать на начало данных и pValue->Length должно быть числом байтов данных, которые должны быть включены в поле.

  • TraceLoggingCustom(pValue, cbValue, protocol, bSchema, cbSchema, [name, ...]):

    Добавляет поле с двоичными данными, сериализованным в соответствии с протоколом сериализации. Сведения о декодирования констант времени компиляции будут включены вместе с событием, чтобы разрешить десериализацию декодером событий.

Структуры

Для создания именованной структуры (группы полей) можно использовать макрос TraceLoggingStruct(fieldCount, name, [...] ). Параметр fieldCount указывает, сколько последующих полей должно быть учтено как часть структуры. Структуры могут быть вложенными. В этом случае каждая вложенная структура и содержащиеся в ней поля считаются одним полем для определения родительской структуры.

Массивы

Можно создать поле, содержащее массив скалярных (одиночных) значений. Например, вы добавляете массив идентификаторов GUID в качестве одного поля в событие.

Примечание

Хотя протокол TraceLogging поддерживает массивы всех типов, TraceLoggingProvider.h предоставляет только макросы-оболочки для массивов простых значений, например он предоставляет макросы для массивов INT32 и GUID, но не предоставляет макросы для массивов String или массивов структур. Можно создавать события с массивами сложных значений путем маршалинга данных в буфер, а затем с помощью TraceLoggingPacked макросов, описанных ниже.

TraceLogging поддерживает массивы фиксированной и переменной длины.

  • Используйте макрос Array в случаях, когда длина массива не известна во время компиляции и может отличаться при каждом создании события.
  • Используйте макрос FixedArray в случаях, когда длина массива известна во время компиляции (т. е. если длина массива является константой). Это сообщает потребителю события о том, что все события с определенным именем события будут иметь одинаковое количество элементов в поле массива.

Все макросы массива требуют указания параметров pValues и cValues , при этом значение pValues указывает на начало содержимого массива, а значение cValues — количество элементов в массиве. Значение pValue может иметь значение NULL, только если значение cValues равно 0.

Все макросы массива при необходимости принимают параметры имени, описания и тега , как описано для макросов Scalar. Если имя не указано, имя поля определяется из текста препроцессора pValues. Если описание не указано, то описание поля будет иметь значение "". Если тег не указан, тег поля будет иметь значение 0.

Примечание

Чтобы трассировка событий Windows не отбрасывала события, избегайте создания событий с большими массивами. Трассировка событий Windows не поддерживает события размером более 64 КБ. Все такие события будут автоматически удалены трассировой событий Windows. Кроме того, события, которые больше , чем BufferSize сеанса потребителя, также будут удалены трассировой событий Windows. Размер события зависит от суммы заголовков события, метаданных (поставщиков, событий и имен полей) и данных (значений полей).

  • TraceLoggingInt8Array(pValues, cValues, [name, ...])
  • TraceLoggingInt8FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingUInt8Array(pValues, cValues, [name, ...])
  • TraceLoggingUInt8FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingInt16Array(pValues, cValues, [name, ...])
  • TraceLoggingInt16FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingUInt16Array(pValues, cValues, [name, ...])
  • TraceLoggingUInt16FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingInt32Array(pValues, cValues, [name, ...])
  • TraceLoggingInt32FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingUInt32Array(pValues, cValues, [name, ...])
  • TraceLoggingUInt32FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingInt64Array(pValues, cValues, [name, ...])
  • TraceLoggingInt64FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingUInt64Array(pValues, cValues, [name, ...])
  • TraceLoggingUInt64FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingIntPtrArray(pValues, cValues, [name, ...])
  • TraceLoggingIntPtrFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingUIntPtrArray(pValues, cValues, [name, ...])
  • TraceLoggingUIntPtrFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingLongArray(pValues, cValues, [name, ...])
  • TraceLoggingLongFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingULongArray(pValues, cValues, [name, ...])
  • TraceLoggingULongFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexInt8Array(pValues, cValues, [name, ...])
  • TraceLoggingHexInt8FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt8Array(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt8FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexInt16Array(pValues, cValues, [name, ...])
  • TraceLoggingHexInt16FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt16Array(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt16FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexInt32Array(pValues, cValues, [name, ...])
  • TraceLoggingHexInt32FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt32Array(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt32FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexInt64Array(pValues, cValues, [name, ...])
  • TraceLoggingHexInt64FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt64Array(pValues, cValues, [name, ...])
  • TraceLoggingHexUInt64FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexIntPtrArray(pValues, cValues, [name, ...])
  • TraceLoggingHexIntPtrFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexUIntPtrArray(pValues, cValues, [name, ...])
  • TraceLoggingHexUIntPtrFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexLongArray(pValues, cValues, [name, ...])
  • TraceLoggingHexLongFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingHexULongArray(pValues, cValues, [name, ...])
  • TraceLoggingHexULongFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingFloat32Array(pValues, cValues, [name, ...])
  • TraceLoggingFloat32FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingFloat64Array(pValues, cValues, [name, ...])
  • TraceLoggingFloat64FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingBooleanArray(pValues, cValues, [name, ...])
  • TraceLoggingBooleanFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingBoolArray(pValues, cValues, [name, ...])
  • TraceLoggingBoolFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingCharArray(pValues, cValues, [name, ...])
  • TraceLoggingCharFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingChar16Array(pValues, cValues, [name, ...])
  • TraceLoggingChar16FixedArray(pValues, cValues, [name, ...])
  • TraceLoggingWCharArray(pValues, cValues, [name, ...])
  • TraceLoggingWCharFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingPointerArray(pValues, cValues, [name, ...])
  • TraceLoggingPointerFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingCodePointerArray(pValues, cValues, [name, ...])
  • TraceLoggingCodePointerFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingFileTimeArray(pValues, cValues, [name, ...])
  • TraceLoggingFileTimeFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingFileTimeUtcArray(pValues, cValues, [name, ...])
  • TraceLoggingFileTimeUtcFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingSystemTimeArray(pValues, cValues, [name, ...])
  • TraceLoggingSystemTimeFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingSystemTimeUtcArray(pValues, cValues, [name, ...])
  • TraceLoggingSystemTimeUtcFixedArray(pValues, cValues, [name, ...])
  • TraceLoggingGuidArray(pValues, cValues, [name, ...])
  • TraceLoggingGuidFixedArray(pValues, cValues, [name, ...])

Упакованные макросы

TraceLoggingProvider.h предоставляет только макросы полей для непреобразуемых типов полей, т. е. полей, где каждый макрос поля соответствует одному полю и одной смежным областям памяти со значением поля.

TraceLoggingProvider.h не обеспечивает прямую поддержку более сложных случаев, таких как:

  • Ведение журнала массива типа переменной длины, например массива строк.
  • Ведение журнала массива структур.
  • Передача нескольких полей в трассировку событий Windows через один буфер для сокращения затрат на ведение журнала событий.

Для поддержки этих сценариев TraceLoggingProvider.h определяет несколько TraceLoggingPacked макросов, которые позволяют напрямую управлять определением события (метаданными) и значениями полей (данными) события.

Предупреждение

Макросы TraceLoggingPacked сложно использовать правильно и требуют хорошего понимания того, как создаются события TraceLogging. При неправильном использовании они приведут к повреждению событий, которые не декодируются правильно.

Дополнительные сведения об использовании этих макросов см. в комментариях в заголовке TraceLoggingProvider.h.

  • TraceLoggingPackedField(pValue, cbValue, inType, [имя, описание, теги]):

    Добавляет данные поля (pValue, cbValue) и метаданные поля (name, inType).

  • TraceLoggingPackedFieldEx(pValue, cbValue, inType, outType, [name, ...]):

    Добавляет данные поля (pValue, cbValue) и метаданные поля (name, inType) вместе с указанием форматирования (outType).

  • TraceLoggingPackedMetadata(inType, [name, ...]):

    Добавляет метаданные поля (name, inType) без добавления данных поля. Соответствующие данные полей должны быть добавлены с помощью TraceLoggingPackedData.

  • TraceLoggingPackedMetadataEx(inType, outType, [name, ...]):

    Добавляет метаданные поля (name, inType) и указание форматирования (outType) без добавления данных поля. Соответствующие данные полей должны быть добавлены с помощью TraceLoggingPackedData.

  • TraceLoggingPackedStruct(fieldCount, name, [...]):

    Добавляет метаданные поля (name, fieldCount) для структуры.

  • TraceLoggingPackedStructArray(fieldCount, [name, ...]):

    Добавляет метаданные поля (name, fieldCount) для массива структуры переменной длины. Длина массива должна быть указана с помощью TraceLoggingPackedData.

  • TraceLoggingPackedData(pValue, cbValue):

    Добавляет данные поля в событие без добавления метаданных поля. Соответствующие метаданные необходимо добавить с помощью макросов метаданных.

  • TraceLoggingPackedDataEx(pValue, cbValue, dataDescType):

    Добавляет данные поля в событие без добавления метаданных поля, используя определенный Type в EVENT_DATA_DESCRIPTOR для данных. Соответствующие метаданные необходимо добавить с помощью макросов метаданных.