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

  • Статья

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

Синтаксис

ULONG TraceMessageVa(
  [in] TRACEHANDLE LoggerHandle,
  [in] ULONG       MessageFlags,
  [in] LPCGUID     MessageGuid,
  [in] USHORT      MessageNumber,
  [in] va_list     MessageArgList
);

Параметры

[in] LoggerHandle

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

[in] MessageFlags

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

  • 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. Включите метку времени в сообщение.

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

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

[in] MessageGuid

GUID класса, идентифицирующий сообщение трассировки событий.

[in] MessageNumber

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

[in] MessageArgList

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

  • 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.

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

Потребители должны будут использовать обратный вызов 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 [только классические приложения]
Минимальная версия сервера Windows Server 2003 [только классические приложения]
Целевая платформа Windows
Header evntrace.h
Библиотека Advapi32.lib
DLL Advapi32.dll

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

Traceevent

TraceEventInstance

TraceMessage