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

Статья
02/29/2024

Функция UpdateTrace обновляет значение свойства указанного сеанса трассировки событий.

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

Синтаксис

ULONG WMIAPI UpdateTraceA(
  CONTROLTRACE_ID         TraceId,
  LPCSTR                  InstanceName,
  PEVENT_TRACE_PROPERTIES Properties
);

Параметры

TraceId

InstanceName

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

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

Properties

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

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

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

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

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

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

ERROR_BAD_LENGTH

Элемент BufferSize элемента Wnodeсвойства указывает неправильный размер.
ERROR_INVALID_PARAMETER

Выполняется одно из следующих условий.
- Свойство имеет значение NULL.
- InstanceName и TraceHandle имеют значение NULL.
- InstanceName имеет значение NULL , а TraceHandle не является допустимым дескриптором.
- Недопустимый элемент LogFileNameOffsetсвойства.
- Недопустимый элемент LoggerNameOffsetсвойства .
Windows Server 2003 и Windows XP: Элемент Guid структуры Wnode — SystemTraceControlGuid, но параметр InstanceName не KERNEL_LOGGER_NAME.
ERROR_ACCESS_DENIED

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

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

EnableFlags. Установите для этого элемента значение 0, чтобы отключить все поставщики ядра. В противном случае необходимо указать поставщиков ядра, которые необходимо включить или оставить включенными. Применяется только к сеансам системного средства ведения журнала.
FlushTimer: задайте этот элемент, если вы хотите изменить время ожидания перед очисткой буферов. Если этот элемент равен 0, он не обновляется.
LogFileNameOffset: задайте этот член, если вы хотите переключиться на другой файл журнала. Если этот элемент равен 0, имя файла не обновляется. Если смещение не равно нулю и имя файла журнала не изменяется, функция возвращает ошибку.
LogFileMode: задайте этот элемент, если вы хотите включить и выключить EVENT_TRACE_REAL_TIME_MODE . Чтобы отключить режим реального времени, установите для этого элемента значение 0. Чтобы включить режим реального времени, установите для этого элемента значение EVENT_TRACE_REAL_TIME_MODE , и он будет иметь значение ИЛИ с текущими режимами.
MaximumBuffers. Установите этот элемент, если вы хотите изменить максимальное число буферов, которые использует трассировка событий Windows. Если этот элемент равен 0, он не обновляется.

Для сеансов частного средства ведения журнала можно обновить только LogFileNameOffset и FlushTimer.

Если вы используете новую инициализированную структуру EVENT_TRACE_PROPERTIES , единственными элементами, которые необходимо указать, кроме обновляемых элементов, являются Wnode.BufferSize, Wnode.Guid и Wnode.Flags.

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

Если вы вызываете функцию ControlTrace для запроса свойств текущего сеанса, а затем обновляете эти свойства для обновления сеанса, убедитесь, что для параметра LogFileNameOffset задано значение 0 (если вы не изменяете имя файла журнала) и EVENT_TRACE_PROPERTIES. Wnode.Flags для WNODE_FLAG_TRACED_GUID.

Чтобы получить параметры свойств и статистику сеанса для сеанса трассировки событий, вызовите функцию ControlTrace .

Примеры

Пример использования UpdateTrace см. в разделе Обновление сеанса трассировки событий.

Примечание

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

Требования

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

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

ControlTrace

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