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

Функция 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: Любой пользователь может управлять сеансом трассировки.

Комментарии

Контроллеры трассировки событий вызывают эту функцию.

Эта функция является устаревшей. Вместо этого используйте ControlTrace с параметромControlCode, для EVENT_TRACE_CONTROL_FLUSH.

Эту функцию можно использовать с сеансом в памяти (сеанс, запущенный с флагом EVENT_TRACE_BUFFERING_MODE ) для записи данных из трассировки в файл.

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

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

Требования

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

ControlTrace