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

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

  • Статья

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

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

Синтаксис

ULONG WMIAPI StopTraceW(
  TRACEHANDLE             TraceHandle,
  LPCWSTR                 InstanceName,
  PEVENT_TRACE_PROPERTIES Properties
);

Параметры

TraceHandle

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

InstanceName

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

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

Properties

Указатель на структуру EVENT_TRACE_PROPERTIES , которая получает окончательные свойства и статистику для сеанса.

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

Начиная с Windows 10 версии 1703: Для повышения производительности в сценариях перекрестных процессов теперь можно передать фильтрацию в StopTrace для системных частных средств ведения журнала. Вам потребуется передать новую структуру EVENT_TRACE_PROPERTIES_V2 , чтобы включить сведения о фильтрации. Дополнительные сведения см. в разделе Настройка и запуск сеанса частного средства ведения журнала .

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

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

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

  • ERROR_BAD_LENGTH

    Выполняется одно из следующих условий.

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

  • ERROR_INVALID_PARAMETER

    Выполняется одно из следующих условий.

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

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

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

Комментарии

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

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

Если LogFileMode содержит EVENT_TRACE_FILE_MODE_PREALLOCATE, StartTrace расширяет файл журнала до максимального значения байтовFileSize . Файл занимает все пространство во время ведения журнала как для циклических, так и для последовательных журналов. При остановке средства ведения журнала файл журнала уменьшается до необходимого размера.

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

Примечание

Заголовок evntrace.h определяет StopTrace как псевдоним, который автоматически выбирает версию 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 R2; Advapi32.dll в Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista и Windows XP

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

ControlTrace

StartTrace