Функция EventRegister (evntprov.h)

Статья
08/23/2023

Регистрирует поставщик событий ETW, создавая дескриптор, который можно использовать для записи событий трассировки событий Windows.

Синтаксис

ULONG EVNTAPI EventRegister(
  [in]           LPCGUID         ProviderId,
  [in, optional] PENABLECALLBACK EnableCallback,
  [in, optional] PVOID           CallbackContext,
  [out]          PREGHANDLE      RegHandle
);

Параметры

[in] ProviderId

GUID, который однозначно идентифицирует поставщика, иногда называемый GUID элемента управления. Это должен быть стабильный идентификатор, чтобы контроллеры трассировки могли использовать GUID для подписки на события от этого поставщика.

[in, optional] EnableCallback

Необязательный параметр EnableCallback , который будет вызываться трассировкой событий Windows, когда сеанс трассировки включает или отключает этот поставщик. Используйте , NULL если обратный вызов не требуется.

[in, optional] CallbackContext

Необязательные данные контекста, которые etw будет предоставлять при вызове EnableCallback. Используйте , NULL если контекст обратного вызова не требуется.

[out] RegHandle

Получает дескриптор регистрации поставщика событий. Дескриптор используется в последующих вызовах API поставщика, таких как EventWrite, EventProviderEnabled и EventRegister.

Перед тем как поставщик выгрузит или завершит работу, освободите дескриптор регистрации поставщика, вызвав EventUnregister. Библиотека DLL, которая выгружается без освобождения всех зарегистрированных дескрипторов поставщика, может привести к сбою процесса.

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

В случае успешного выполнения возвращает ERROR_SUCCESS.

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

Большинство поставщиков событий не вызывают EventRegister напрямую. Вместо этого большинство поставщиков событий реализуются с помощью платформы трассировки событий Windows, которая заключает вызовы в EventRegister, EventWrite и EventUnregister. Например, можно написать манифест события , а затем использовать компилятор сообщений для создания кода C/C++ для событий, или использовать TraceLogging , чтобы избежать необходимости в манифесте.

Регистрацию поставщика событий не следует путать с установкой манифеста поставщика событий.

API EventRegister выполняет регистрацию поставщика событий для создания дескриптора поставщика. Это операция область процесса (дескриптор действителен только внутри процесса). Дескриптор можно использовать для записи событий трассировки событий Windows. Все события, написанные с помощью дескриптора, будут помечены идентификатором поставщика, указанным во время регистрации поставщика. Нет необходимости устанавливать манифест для записи событий или отслеживания трассировок (хотя установка манифеста может потребоваться для декодирования событий поставщика или для работы поставщика с журналом событий).
Средство wevtutil.exe используется для установки или удаления манифеста поставщика событий. Установка манифеста поставщика событий означает, что сведения из манифеста записываются в систему. Записанные сведения являются системными и сохраняются до удаления манифеста. Записанные сведения включают имена, идентификаторы GUID, каналы и пути DLL ресурсов поставщиков, определенных в манифесте. Сведения из манифеста используются средствами декодирования трассировки и журналом событий.

Большинство компонентов регистрируют поставщик событий при инициализации компонента и отменяют регистрацию поставщика событий при завершении работы компонента. Например, приложение (EXE) может регистрироваться во время запуска приложения и отменять регистрацию во время завершения работы приложения. Динамическая библиотека (DLL) может зарегистрироваться во DllMain время присоединения процесса и отменить регистрацию DllMain во время отсоединения процесса.

Так как трассировка событий является задачей отладки и диагностики и обычно не является критически важной для приложения функциональностью, большинство розничных приложений должны автоматически игнорировать ошибки, возвращаемые EventRegister. В случае сбоя EventRegister установит для параметра RegHandle нулевое значение, чтобы последующие использование RegHandle (т. е. в вызовах EventWrite и EventUnregister) не влияло.

Каждый процесс может зарегистрировать до 1024 поставщиков. Однако следует ограничить количество поставщиков, зарегистрированных компонентом, одним или двумя. Это ограничение включает поставщиков, зарегистрированных с помощью этой функции, и поставщиков, зарегистрированных с помощью RegisterTraceGuids.

До Windows Vista: Определенного ограничения на количество поставщиков, которые может зарегистрировать процесс, не существует.

Требования


Минимальная версия клиента	Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2008 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	evntprov.h
Библиотека	Advapi32.lib
DLL	Advapi32.dll

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

EnableCallback

EventWrite

EventUnregister