Функция EtwWriteEx (wdm.h)
Функция EtwWriteEx — это функция трассировки для публикации событий, поддерживающих фильтрацию в коде драйвера в режиме ядра.
Синтаксис
NTSTATUS EtwWriteEx(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in] ULONG64 Filter,
[in] ULONG Flags,
[in, optional] LPCGUID ActivityId,
[in, optional] LPCGUID RelatedActivityId,
[in] ULONG UserDataCount,
[in, optional] PEVENT_DATA_DESCRIPTOR UserData
);
Параметры
[in] RegHandle
Указатель на дескриптор регистрации поставщика событий, который возвращается функцией EtwRegister в случае успешной регистрации поставщика событий.
[in] EventDescriptor
Указатель на структуру EVENT_DESCRIPTOR .
[in] Filter
Идентификаторы экземпляра, определяющие сеанс, в который не будет записано событие. То есть значение представляет собой маску сеансов, которые должны быть исключены из журнала (отфильтрованы). Используйте побитовое ИЛИ, чтобы указать несколько идентификаторов. Установите значение 0, если фильтры не поддерживаются или событие записывается во все сеансы (сбой фильтров не выполнен). Сведения о получении идентификатора для сеанса см. в параметре FilterData обратного вызова EtwEnableCallback .
[in] Flags
Зарезервировано. Значение должно быть равно нулю (0).
[in, optional] ActivityId
Идентификатор, указывающий действие, связанное с событием. ActivityID предоставляет способ группировки связанных событий и используется для сквозной трассировки. Если значение РАВНО NULL, etW получает идентификатор из локального хранилища потока. Дополнительные сведения о получении этого идентификатора см. в разделе EtwActivityIdControl.
[in, optional] RelatedActivityId
Идентификатор действия от предыдущего компонента. Этот параметр используется для связи событий компонента с событиями предыдущего компонента. Чтобы получить идентификатор действия, который был задан для предыдущего компонента, см. описание параметра ControlCode функции EtwActivityIdControl .
[in] UserDataCount
Количество структур EVENT_DATA_DESCRIPTOR в UserData. Максимальное число — 128.
[in, optional] UserData
Указатель на массив EVENT_DATA_DESCRIPTOR структур. Присвойте этому параметру значение NULL, если UserDataCount равно нулю. Объекты должны быть в том порядке, который указан в манифесте.
Возвращаемое значение
Возвращает ERROR_SUCCESS в случае успешного выполнения или одно из следующих значений при ошибке.
Комментарии
Функция EtwWriteEx является эквивалентом режима ядра функции EventWriteEx в пользовательском режиме. Для данных событий, записанных с помощью этой функции, требуется манифест. Манифест внедряется в поставщик, поэтому поставщик должен быть доступен потребителю для использования данных. Чтобы убедиться, что для публикуемого события есть потребитель, можно перед вызовом EtwWrite вызвать EtwEventEnabled или EtwProviderEnabled.
Используйте параметры ActivityId и RelatedActivityId , если требуется связать события в разных компонентах в сценарии сквозной трассировки. Например, компоненты A, B и C выполняют работу над связанным действием и хотят связать свои события, чтобы потребитель смог использовать все события, связанные с этим действием.
EtwWriteEx можно вызвать в любом IRQL. Однако если значение IRQL больше APC_LEVEL, все данные, передаваемые в функции EtwWrite, EtwWriteEx, EtwWriteString, EtwWriteTransfer , не должны быть доступны для страниц. Это значит, что любая подпрограмма в режиме ядра, выполняющаяся в IRQL больше APC_LEVEL, не может получить доступ к памяти, доступной для страниц. Данные, передаваемые в функции EtwWrite, EtwWriteEx, EtwWriteString и EtwWriteTransfer , должны находиться в памяти системного пространства, независимо от того, что такое IRQL.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 7 |
| Минимальная версия сервера | Windows Server 2008 R2 |
| Целевая платформа | Универсальное |
| Верхняя часть | wdm.h |
| Библиотека | NtosKrnl.lib |
| DLL | NtosKrnl.exe |