Макросы программы-оболочки 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 (None). Ключевое слово является важной частью маршрутизации событий EtW и фильтрации, поэтому все события должны иметь понятное ненулевое ключевое слово.
  • TraceLoggingOpcode задает код операции события. Код операции представляет собой 8-разрядное значение, указывающее специальную семантику для события, например, что событие записывает начало (WINEVENT_OPCODE_START) или конец (WINEVENT_OPCODE_STOP) действия ETW (группа связанных событий). Если значение не указано, событие по умолчанию использует код opcode 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, имя поля определяется на основе текста препроцессора значения макроса, pszValue, pchValue или pValue . Например, выражение TraceLoggingInt32(x[4] + y) будет эквивалентно TraceLoggingInt32(x[4] + y, "x[4] + y"). Оба типа добавляют в событие поле "x[4] + y" с именем со значением, определяемым вычислением выражения x[4] + y.
  • Описание: Строковый литерал (констант времени компиляции) с описанием, используемым для поля. В основном это удобное место для размещения комментария для поля, но описание также записывается как заметка в символах отладки компонента (PDB). Описание является необязательным. Если параметр описания опущен, описание поля по умолчанию равно "".
  • Тег: 28-разрядное целое число (константа времени компиляции) с семантикой, определенной поставщиком. Например, поставщик может определить тег 0x2, чтобы указать, что поле содержит номер телефона и должно получать специальное лечение от средств обработки событий конкретного поставщика. Если параметр тега опущен, по умолчанию тег поля имеет значение 0.

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

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

Скаляры

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

    Добавляет поле с типом, автоматически выведенным из типа параметра значения. (только для 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 (без знака длинное целое число, 32 бита на платформах 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, ...]):

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

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

    Добавляет поле со значением (16-разрядное char16_t целое число с указанием форматирования строки, обычно обрабатываемое как 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, ...]):

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

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

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

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

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

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

    Добавляет поле с 0-завершаемой wchar_t строкой (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, [имя, описание, тег]):

    Добавляет поле с подсчитываемой 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 и должен указывать на правильно инициализированный sid (Revision и SubAuthorityCount должен быть допустимым).

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

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

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

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

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

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

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

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

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

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

Структуры

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

Массивы

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

Примечание

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

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

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

Для всех макросов массива требуется указать параметры pValues и cValues , при этом pValues указывает на начало содержимого массива, а значения cValue — количество элементов в массиве. Значения 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) и метаданные поля (имя, inType).

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

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

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

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

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

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

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

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

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

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

  • TraceLoggingPackedData(pValue, cbValue):

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

  • TraceLoggingPackedDataEx(pValue, cbValue, dataDescType):

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