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

Функция EtwRegister (wdm.h)

  • Статья

Функция EtwRegister регистрирует поставщик событий и должна быть вызвана, прежде чем поставщик сможет начать трассировку. Функция EtwRegister является аналогом режима ядра функции EventRegister пользовательского режима. Функция также может предоставить указатель на необязательную функцию обратного вызова, которую можно использовать для предоставления дополнительных возможностей фильтрации событий.

Синтаксис

NTSTATUS EtwRegister(
  [in]           LPCGUID            ProviderId,
  [in, optional] PETWENABLECALLBACK EnableCallback,
  [in, optional] PVOID              CallbackContext,
  [out]          PREGHANDLE         RegHandle
);

Параметры

[in] ProviderId

Указатель на GUID поставщика событий.

[in, optional] EnableCallback

Указатель на необязательную функцию обратного вызова. Функция обратного вызова предоставляет дополнительные возможности фильтрации событий. Функция обратного вызова определяется пользователем.

[in, optional] CallbackContext

Функция передает необязательный контекст обратного вызова при выполнении обратного вызова. Необязательный контекст можно указать при регистрации поставщика. Параметр CallbackContext поддерживает сценарии, в которых один обратный вызов совместно используется несколькими поставщиками, как в классе C++. CallbackContext позволяет различать экземпляры целевого поставщика для включения обратного вызова.

[out] RegHandle

Указатель на переменную, которая получает дескриптор регистрации поставщика в случае успешного вызова функции.

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

Функция EtwRegister возвращает код состояния из следующего списка:

Код возврата Описание
STATUS_SUCCESS
Указывает, что поставщик событий успешно зарегистрирован в трассировки событий Windows.
STATUS_INVALID_PARAMETER
Указывает, что параметр был недопустим.
STATUS_Xxx
Указывает, что запрос завершился сбоем по причине, указанной значением NTSTATUS. Подробные сведения о фактическом коде возврата состояния см. в статье Ntstatus.h.

Комментарии

Прежде чем драйвер в режиме ядра сможет отслеживать события, драйвер должен зарегистрироваться в качестве поставщика событий с помощью функции EtwRegister . Когда драйвер режима ядра вызывает EtwRegister, функция возвращает дескриптор регистрации. Этот дескриптор регистрации можно использовать для проверки включения ключевое слово или уровня для конкретного поставщика, а также для вызова функций трассировки событий и ведения журнала. После завершения трассировки драйвер должен вызвать функцию EtwUnregister , чтобы отменить регистрацию поставщика. Для каждого вызова EtwRegister должен быть соответствующий вызов EtwUnregister. Сбой при отмене регистрации поставщика событий может привести к ошибкам при выгрузке процесса, так как функции обратного вызова, связанные с процессом, больше не являются допустимыми. Не следует выполнять вызовы трассировки, которые выходят за пределы кода, ограниченного функциями EtwRegister и EtwUnregister . Для достижения наилучшей производительности можно вызвать функцию EtwRegister в подпрограмме DriverEntry и функцию EtwUnregister в подпрограмме DriverUnload .

Вызывающие функции EtwRegister должны выполняться в IRQL = PASSIVE_LEVEL в контексте системного потока.

Требования

Требование Значение
Минимальная версия клиента Доступно в Windows Vista и более поздних версиях Windows.
Целевая платформа Универсальное
Верхняя часть wdm.h (включая Wdm.h, Ntddk.h)
Библиотека NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
Правила соответствия DDI HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)

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

EtwUnregister