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

Статья
08/23/2023

Поставщик событий на основе 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 используют функции-оболочки, созданные 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

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