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

Статья
08/23/2023

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

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

Синтаксис

ULONG WMIAPI FlushTraceA(
  [in]      TRACEHANDLE             TraceHandle,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties
);

Параметры

[in] TraceHandle

Обработка сеанса трассировки событий для очистки или 0. Если instanceName имеет значение NULL, необходимо указать ненулевое значение TraceHandle. Этот параметр будет использоваться только в том случае, если instanceName имеет значение NULL. Дескриптор возвращается элементом StartTrace.

[in] InstanceName

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

Чтобы указать сеанс средства ведения журнала ядра 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

Share via