Функция ControlTraceA (evntrace.h)
Функция ControlTrace сбрасывает, запрашивает, обновляет или останавливает указанный сеанс трассировки событий.
Синтаксис
ULONG WMIAPI ControlTraceA(
CONTROLTRACE_ID TraceId,
[in] LPCSTR InstanceName,
[in, out] PEVENT_TRACE_PROPERTIES Properties,
[in] ULONG ControlCode
);
Параметры
TraceId
[in] InstanceName
Имя сеанса трассировки событий или ЗНАЧЕНИЕ NULL. Если TraceHandle имеет значение 0, необходимо указать InstanceName.
Чтобы указать сеанс средства ведения журнала ядра NT, задайте для instanceNameзначение KERNEL_LOGGER_NAME.
[in, out] Properties
Указатель на инициализированную структуру EVENT_TRACE_PROPERTIES . Эта структура должна быть обнулена перед установкой полей.
Если ControlCode указывает EVENT_TRACE_CONTROL_STOP, EVENT_TRACE_CONTROL_QUERY или EVENT_TRACE_CONTROL_FLUSH, необходимо задать только элементы Wnode.BufferSize, Wnode.Guid, LoggerNameOffset и LogFileNameOffsetструктуры EVENT_TRACE_PROPERTIES . Если сеанс является частным, необходимо также задать LogFileMode. Вы можете использовать максимальную длину имени сеанса (1024 символа) и максимальную длину файла журнала (1024 символа), чтобы вычислить размер буфера и смещения, если они не известны.
Если ControlCode указывает EVENT_TRACE_CONTROL_UPDATE, при входе члены должны указать новые значения для обновляемых свойств. В выходных данных свойства содержат свойства и статистику для сеанса трассировки событий. Вы можете обновить следующие свойства.
EnableFlags: установите для этого элемента значение 0, чтобы отключить все системные поставщики. Присвойте этому параметру ненулевое значение, чтобы указать системных поставщиков, которые необходимо включить или сохранить включенными. Это может быть ненулевым только для системных средств ведения журнала.
FlushTimer: задайте этот элемент, если вы хотите изменить время ожидания перед очисткой буферов. Если этот элемент равен 0, элемент не обновляется.
LogFileNameOffset. Задайте этот элемент, если вы хотите переключиться на другой файл журнала или очистить трассировку в режиме буферизации до нового файла журнала. Если этот элемент равен 0, имя файла не обновляется. Если смещение не равно нулю и имя файла журнала не изменяется, функция возвращает ошибку.
LogFileMode: задайте этот элемент, если вы хотите включить и выключить EVENT_TRACE_REAL_TIME_MODE . Чтобы отключить режим реального времени, установите для этого элемента значение 0. Чтобы включить режим реального времени (создание сеанса, записывающего на диск, а также доставку событий в режиме реального времени), задайте для этого элемента значение EVENT_TRACE_REAL_TIME_MODE , и он будет иметь значение OR'd с текущими режимами.
MaximumBuffers: задайте этот элемент, если вы хотите изменить максимальное количество буферов, которые использует трассировка событий Windows. Если этот элемент равен 0, элемент не обновляется.
Для частных сеансов средства ведения журнала можно обновить только члены LogFileNameOffset и FlushTimer .
Если вы используете новую инициализированную структуру EVENT_TRACE_PROPERTIES , обнулите структуру, а затем задайте Wnode.BufferSize, Wnode.Guid и Wnode.Flags и значения, которые требуется обновить.
Если вы повторно используете структуру EVENT_TRACE_PROPERTIES (т. е. используете структуру, которая ранее была передана в StartTrace или ControlTrace), обязательно установите для элемента LogFileNameOffset значение 0, если вы не изменяете имя файла журнала, и не забудьте задать EVENT_TRACE_PROPERTIES. Wnode.Flags для WNODE_FLAG_TRACED_GUID.
Начиная с Windows 10 версии 1703: Для повышения производительности в сценариях перекрестного процесса теперь можно передать сведения о фильтрации в ControlTrace для частных средств ведения журнала на уровне системы. Для включения сведений о фильтрации необходимо использовать структуру EVENT_TRACE_PROPERTIES_V2 . Дополнительные сведения см. в статье Настройка и запуск сеанса частного средства ведения журнала .
[in] ControlCode
Запрошенная функция управления. Можно указать одно из следующих значений.
EVENT_TRACE_CONTROL_FLUSH: очищает активные буферы сеанса.
Его можно использовать с сеансом в памяти (сеансом, запущенным с флагом EVENT_TRACE_BUFFERING_MODE ) для записи данных из трассировки в файл.
Обычно очистка сеансов на основе файлов или сеансов в режиме реального времени не требуется, так как трассировка windows автоматически очищает буфер, когда он заполнен (т. е. если у него нет места для следующего события), когда истекает срок действия FlushTimer сеанса трассировки или когда сеанс трассировки закрыт.
Windows 2000: Это значение не поддерживается.
EVENT_TRACE_CONTROL_QUERY. Извлекает свойства сеанса и статистику.
EVENT_TRACE_CONTROL_STOP: останавливает сеанс. Дескриптор сеанса больше недействителен.
EVENT_TRACE_CONTROL_UPDATE: обновляет свойства сеанса.
EVENT_TRACE_CONTROL_INCREMENT_FILE. Если в сеансе есть
EVENT_TRACE_FILE_MODE_NEWFILE, обновляет сеанс, чтобы немедленно перейти к следующему файлу, а не ожидать заполнения предыдущего файла. Поддерживается начиная с обновления Windows 10 за октябрь 2018 г.EVENT_TRACE_CONTROL_CONVERT_TO_REALTIME. Изменяет сеанс файлового режима на сеанс в режиме реального времени (включает доставку в режиме реального времени и отключает запись событий в ETL-файл). Поддерживается начиная с обновления Windows 10 за октябрь 2020 г.
Примечание
Очистка буферов или остановка сеанса трассировки из DllMain небезопасно (это может привести к взаимоблокировкам).
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение будет ERROR_SUCCESS.
Если функция завершается сбоем, возвращаемое значение является одним из кодов системных ошибок. Ниже приведены некоторые распространенные ошибки и их причины.
ERROR_BAD_LENGTH
Выполняется одно из следующих условий.
- Элемент Wnode.BufferSizeсвойства указывает неправильный размер.
- В свойствах недостаточно места, выделенного для хранения копии имени сеанса и имени файла журнала (если используется).
ERROR_INVALID_PARAMETER
Выполняется одно из следующих условий.
- Свойство имеет значение NULL.
- InstanceName и TraceHandle имеют значение NULL.
- InstanceName имеет значение NULL , а TraceHandle — недопустимый дескриптор.
- Недопустимый элемент LogFileNameOffsetсвойства.
- Недопустимый элемент LoggerNameOffsetсвойства .
- Элемент LogFileModeсвойства задает недопустимое сочетание флагов.
- Элемент Wnode.Guidсвойства — SystemTraceControlGuid, но параметр InstanceName не
KERNEL_LOGGER_NAMEимеет значения .
ERROR_BAD_PATHNAME
В другом сеансе уже используется имя файла, указанное элементом LogFileNameOffset структуры Properties .
ERROR_MORE_DATA
Буфер для EVENT_TRACE_PROPERTIES слишком мал, чтобы вместить всю информацию для сеанса. Если вам не нужны сведения о свойстве сеанса, эту ошибку можно игнорировать. Если эта ошибка возникает при остановке сеанса, трассировка событий Windows уже остановит сеанс перед созданием этой ошибки.
ERROR_ACCESS_DENIED
Только пользователи с повышенными правами администратора, пользователи в группе Пользователи журнала производительности и службы под управлением LocalSystem, LocalService, NetworkService могут управлять сеансами трассировки событий. Чтобы предоставить пользователю с ограниченным доступом возможность управлять сеансами трассировки, добавьте его в группу Пользователи журнала производительности. Только пользователи с правами администратора и службами, работающими в качестве LocalSystem, могут управлять сеансом средства ведения журнала ядра NT.
Windows XP и Windows 2000: Любой пользователь может управлять сеансом трассировки.
ERROR_WMI_INSTANCE_NOT_FOUND
Данный сеанс не выполняется.
Комментарии
Контроллеры трассировки событий вызывают эту функцию.
Эта функция заменяет функции FlushTrace, QueryTrace, StopTrace и UpdateTrace .
Примечание
Заголовок evntrace.h определяет ControlTrace как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 2000 Профессиональная [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows 2000 Server [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | evntrace.h |
| Библиотека | Sechost.lib в Windows 8.1 и Windows Server 2012 R2; Advapi32.lib в Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista и Windows XP |
| DLL | Sechost.dll в Windows 8.1 и Windows Server 2012; Advapi32.dll в Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista и Windows XP |