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


Функция TraceMessage (evntrace.h)

Поставщик событий на основе RegisterTraceGuids ("Классическая") использует функцию TraceMessage для отправки события на основе сообщений (WPP на основе TMF) в сеанс трассировки событий.

Синтаксис

ULONG TraceMessage(
  [in] TRACEHANDLE LoggerHandle,
  [in] ULONG       MessageFlags,
  [in] LPCGUID     MessageGuid,
  [in] USHORT      MessageNumber,
       ...         
);

Параметры

[in] LoggerHandle

Обработка сеанса трассировки событий, который записывает событие. Поставщик получает дескриптор при вызове функции GetTraceLoggerHandle в реализации ControlCallback .

[in] MessageFlags

Добавляет дополнительные сведения в начало раздела данных конкретного поставщика события. Раздел данных конкретного поставщика события будет содержать данные только для установленных флагов. Эти сведения будут отображаться в списке переменных с данными аргументов. Этот параметр может быть одним или несколькими из следующих значений.

  • TRACE_MESSAGE_COMPONENTID

    Включите идентификатор компонента в сообщение. Параметр MessageGuid содержит идентификатор компонента.

  • TRACE_MESSAGE_GUID

    Включите GUID класса трассировки событий в сообщение. Параметр MessageGuid содержит GUID класса трассировки событий.

  • TRACE_MESSAGE_SEQUENCE

    Включите порядковый номер в сообщение. Порядковый номер начинается с единицы. Чтобы использовать этот флаг, контроллер должен задать режим EVENT_TRACE_USE_GLOBAL_SEQUENCE или EVENT_TRACE_USE_LOCAL_SEQUENCE файла журнала при создании сеанса.

  • TRACE_MESSAGE_SYSTEMINFO

    Включите идентификатор потока и идентификатор процесса в сообщение.

  • TRACE_MESSAGE_TIMESTAMP

    Включите метку времени в сообщение.

TRACE_MESSAGE_COMPONENTID и TRACE_MESSAGE_GUID являются взаимоисключающими.

Сведения включаются в данные события в следующем порядке:

  • Порядковый номер
  • GUID класса трассировки событий (или идентификатор компонента)
  • Метка времени
  • Идентификатор потока
  • Идентификатор процесса

[in] MessageGuid

Идентификатор GUID класса или компонента, который идентифицирует сообщение. Зависит от того, содержит ли MessageFlags флаг TRACE_MESSAGE_COMPONENTID или TRACE_MESSAGE_GUID .

[in] MessageNumber

Число, однозначно определяющее каждое вхождение сообщения. Необходимо определить значение, указанное для этого параметра; значение должно быть значимым для приложения.

...

Список переменных аргументов, добавляемых в сообщение. Используйте этот список, чтобы указать данные о событиях, относящихся к поставщику. Список должен состоять из пар аргументов, как показано ниже.

  • PVOID: указатель на данные аргумента.
  • size_t: размер данных аргумента в байтах.

Завершите список, используя пару аргументов, состоящую из указателя на NULL и ноль.

Вызывающий объект должен убедиться, что сумма размеров аргументов + 72 не превышает размер буфера сеанса трассировки событий.

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

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

Если функция завершается сбоем, возвращаемое значение является одним из кодов системных ошибок. Ниже приведены некоторые распространенные ошибки и их причины.

  • ERROR_INVALID_HANDLE

    Параметр LoggerHandle имеет значение NULL или задает дескриптор сеанса средства ведения журнала ядра NT.

  • ERROR_NOT_ENOUGH_MEMORY

    Сеанс исчерпал свободные буфера для записи. Это может произойти при высокой частоте событий из-за перегрузки дисковой подсистемы или недостаточного количества буферов. Вместо того чтобы блокировать, пока не станет доступно больше буферов, TraceMessage отменяет событие.

    Windows 2000 и Windows XP: Не поддерживается.

  • ERROR_OUTOFMEMORY

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

  • ERROR_INVALID_PARAMETER

    MessageFlags содержит недопустимое значение.

  • ERROR_MORE_DATA

    Данные из одного события не могут охватывать несколько буферов. Событие трассировки ограничено размером буфера сеанса трассировки событий за вычетом размера структуры EVENT_TRACE_HEADER .

Комментарии

Поставщики WPP на основе TMF вызывают эту функцию.

Примечание

Большинство разработчиков не будут вызывать эту функцию напрямую. Поставщики WPP используют функции-оболочки, созданные tracewpp.exe, вместо вызова API трассировки событий Windows.

Если необходимо получить доступ к функциям трассировки сообщений из функции-оболочки, вызовите версию traceMessageVa этой функции.

Потребителям придется использовать обратный вызов EventCallback для получения и обработки событий, если параметр MessageFlags не содержит флаг TRACE_MESSAGE_GUID. Если не указать флаг TRACE_MESSAGE_GUID, потребитель не сможет использовать EventClassCallback , так как элемент Header.Guid структуры EVENT_TRACE не будет содержать GUID класса трассировки событий.

Обратите внимание, что члены EVENT_TRACE и EVENT_TRACE_HEADER структур, соответствующих флагам MessageFlags , задаются только в том случае, если указан соответствующий флаг. Например, элементы ThreadId и ProcessIdEVENT_TRACE_HEADER заполняются только при указании флага TRACE_MESSAGE_SYSTEMINFO.

Требования

   
Минимальная версия клиента Windows XP [классические приложения | Приложения UWP]
Минимальная версия сервера Windows Server 2003 [классические приложения | Приложения UWP]
Целевая платформа Windows
Header evntrace.h
Библиотека Advapi32.lib
DLL Advapi32.dll

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

Traceevent

TraceEventInstance

TraceMessageVa