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

Статья
06/12/2024

Функция FlushTrace позволяет сеансу трассировки событий немедленно доставлять буферизированные события для указанного сеанса. По умолчанию сеанс трассировки событий будет доставлять события при заполнении буфера, истечении срока действия FlushTimer сеанса или закрытии сеанса.

Эта функция является устаревшей. Функция ControlTrace заменяет эту функцию.

Синтаксис

ULONG WMIAPI FlushTraceA(
            CONTROLTRACE_ID         TraceId,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties
);

Параметры

TraceId

[in] InstanceName

Имя сеанса трассировки событий, который требуется очистить, или NULL. Необходимо указать InstanceName , если TraceHandle имеет значение 0.

Чтобы указать сеанс средства ведения журнала ядра NT, задайте для instanceNameзначение KERNEL_LOGGER_NAME.

[in, out] Properties

Указатель на инициализированную структуру EVENT_TRACE_PROPERTIES .

Если вы используете новую инициализированную структуру, необходимо задать только члены структуры Wnode.BufferSize, Wnode.Guid, LoggerNameOffset и LogFileNameOffset . Вы можете использовать максимальное имя сеанса (1024 символа) и максимальное имя файла журнала (1024 символа) для вычисления размера буфера и смещения, если они не известны.

В выходных данных структура получает параметры свойств и статистику сеанса трассировки событий, которые отражают состояние сеанса после очистки.

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

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

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

ERROR_INVALID_PARAMETER

Выполняется одно из следующих условий.
- Свойство имеет значение NULL.
- InstanceName и TraceHandle имеют значение NULL.
- InstanceName имеет значение NULL , а TraceHandle не является допустимым дескриптором.
ERROR_BAD_LENGTH

Выполняется одно из следующих условий.
- Элемент Wnode.BufferSizeсвойства указывает неправильный размер.
- В свойствах недостаточно места, выделенного для хранения копии имени сеанса и имени файла журнала (если используется).
ERROR_ACCESS_DENIED

Только пользователи с правами администратора, пользователи в группе Пользователи журнала производительности и службы, работающие под управлением LocalSystem, LocalService, NetworkService, могут управлять сеансами трассировки событий. Чтобы предоставить ограниченному пользователю возможность управлять сеансами трассировки, добавьте его в группу Пользователи журнала производительности.

Windows XP и Windows 2000: Любой пользователь может управлять сеансом трассировки.

Обычно очистка сеансов на основе файлов или сеансов в режиме реального времени не требуется, так как трассировка событий Windows автоматически очищает буфер при его заполнении (т. е. если у него нет места для следующего события), по истечении срока действия FlushTimer сеанса трассировки или при закрытии сеанса трассировки.

Не вызывайте FlushTrace из DllMain (может привести к взаимоблокировке).

Примечание

Заголовок evntrace.h определяет FlushTrace в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

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

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

ControlTrace

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