Функция TraceLoggingRegister (traceloggingprovider.h)

Регистрирует поставщик TraceLogging, чтобы его можно было использовать для регистрации событий. Регистрация действительна до тех пор, пока не будет отменена регистрация поставщика или пока процесс не завершится.

Синтаксис

TLG_STATUS TraceLoggingRegister(
  TraceLoggingHProvider hProvider
);

Параметры

hProvider

Дескриптор регистрируемого поставщика TraceLogging. Дескриптор еще не должен быть зарегистрирован.

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

При вызове этой функции из кода пользовательского режима функция возвращает .HRESULT Используйте макрос SUCCEEDED() , чтобы определить, успешно ли выполняется функция.

При вызове этой функции из кода в режиме ядра функция возвращает .NTSTATUS Используйте макрос NT_SUCCESS() , чтобы определить, успешно ли выполняется функция.

Примечание

Код ошибки, возвращаемый TraceLoggingRegister , в основном предназначен для использования в сценариях отладки и диагностики. Большая часть рабочего кода должна продолжать выполняться, даже если поставщику трассировки событий Windows не удалось зарегистрировать, поэтому сборки выпуска обычно должны игнорировать код ошибки, возвращенный TraceLoggingRegister.

Комментарии

При запуске компонента любой дескриптор поставщика TraceLogging в компоненте будет находиться в незарегистрированном состоянии, а любые попытки использовать дескриптор поставщика для создания событий будут игнорироваться автоматически. Прежде чем поставщик сможет записывать какие-либо события, необходимо зарегистрировать поставщик с помощью TraceLoggingRegister. Обычно это делается во время запуска компонента, например в main, wmain, WinMain, DllMain(DLL_PROCESS_ATTACH)или DriverEntry. При завершении работы компонента отмените регистрацию поставщика, вызвав TraceLoggingUnregister.

Не вызывайте TraceLoggingRegister для уже зарегистрированного дескриптора поставщика. Вы можете отменить регистрацию дескриптора, а затем при необходимости зарегистрировать его снова, хотя повторная регистрация и отмена регистрации дескриптора может привести к проблемам с производительностью и их следует избегать (т. е. не регистрируйте, не записывайте несколько событий, а затем отменяйте регистрацию; вместо этого зарегистрируйте один раз при запуске компонента и отмените регистрацию при завершении работы компонента).

TraceLoggingRegister не является потокобезопасной в отношении других вызовов TraceLoggingRegister или TraceLoggingUnregister в том же дескрипторе. Не вызывайте TraceLoggingRegister , если возможно, что другой поток может одновременно вызывать TraceLoggingRegister или TraceLoggingUnregister для того же дескриптора.

Если TraceLoggingRegister завершится сбоем, дескриптор поставщика останется незарегистрированным, а все способы использования дескриптора поставщика будут безопасены. В частности, вызов TraceLoggingWrite или TraceLoggingUnregister с незарегистрированным дескриптором поставщика является безопасным.

Важно!

Если библиотека DLL или драйвер вызывает TraceLoggingRegister в дескрипторе поставщика, он должен вызвать TraceLoggingUnregister для этого дескриптора поставщика перед выгрузкой библиотеки DLL или драйвера. Если библиотека DLL выгружается без вызова TraceLoggingUnregister, процесс может завершиться сбоем. Если драйвер выгружается без вызова TraceLoggingUnregister, система может впоследствии завершиться сбоем. Функция TraceLoggingRegister устанавливает обратный вызов конфигурации трассировки событий Windows, а TraceLoggingUnregister отменяет обратный вызов. Если обратный вызов не отменен и модуль выгрузится, при следующей попытке трассировки событий Windows вызвать обратный вызов произойдет сбой.

Предупреждение

Если драйвер вызывает TraceLoggingRegister , а затем обнаруживает ошибку во время DriverEntry, он должен вызвать TraceLoggingUnregister , прежде чем возвращать ошибку из DriverEntry. Обычные процедуры очистки драйвера не будут вызываться, если драйвер возвращает ошибку из DriverEntry, а сбой вызова TraceLoggingUnregister приведет к сбою системы.

TraceLoggingRegister выполняет следующие действия:

  • Вызывает EventRegister , чтобы открыть подключение к трассировки событий Windows.
  • Если EventRegister выполняется успешно, вызывает TraceLoggingSetInformation с InformationClassEventProviderSetTraits , чтобы настроить поставщик для поддержки TraceLogging.

Вызов TraceLoggingRegister совпадает с вызовом TraceLoggingRegisterEx со значением NULL для параметров обратного вызова и контекста . Используйте TraceLoggingRegisterEx, если вам нужно получить обратный вызов etw Enable, когда сеансы включают или отключают поставщика.

Требования

Требование Значение
Минимальная версия клиента Windows Vista [классические приложения | Приложения UWP]
Минимальная версия сервера Windows Server 2008 [классические приложения | Приложения UWP]
Верхняя часть traceloggingprovider.h
Библиотека Advapi32.lib

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

EventRegister

TraceLoggingRegisterEx

TraceLoggingUnregister

TraceLoggingWrite

TRACELOGGING_DEFINE_PROVIDER