Функция 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 |