Функция EtwWrite (wdm.h)
Функция EtwWrite — это функция трассировки для публикации событий в коде драйвера в режиме ядра.
Синтаксис
NTSTATUS EtwWrite(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in, optional] LPCGUID ActivityId,
[in] ULONG UserDataCount,
[in, optional] PEVENT_DATA_DESCRIPTOR UserData
);
Параметры
[in] RegHandle
Указатель на дескриптор регистрации поставщика событий, который возвращается функцией EtwRegister в случае успешной регистрации поставщика событий.
[in] EventDescriptor
Указатель на структуру EVENT_DESCRIPTOR .
[in, optional] ActivityId
Идентификатор, указывающий действие, связанное с событием. ActivityID предоставляет способ группировки связанных событий и используется для сквозной трассировки.
[in] UserDataCount
Количество EVENT_DATA_DESCRIPTOR структур в UserData.
[in, optional] UserData
Указатель на массив EVENT_DATA_DESCRIPTOR структур.
Возвращаемое значение
Если событие было успешно опубликовано, функция EtwWrite возвращает STATUS_SUCCESS.
Если указатель на дескриптор регистрации поставщика событий недопустим, функция EtwWrite возвращает STATUS_INVALID_HANDLE. Поставщик событий должен быть зарегистрирован перед вызовом EtwWrite . EtwWrite также может возвращать STATUS_INVALID_HANDLE, если не удается записать событие в журнал.
Если число EVENT_DATA_DESCRIPTOR структур, указанных в UserDataCount , превышает максимально допустимое значение (128), функция EtwWrite возвращает STATUS_INVALID_PARAMETER.
Если параметр ActivityID указан, но доступной памяти для записи в журнал данных, связанных с событием, функция EtwWrite возвращает STATUS_NO_MEMORY.
Если поставщик не включен для какого-либо сеанса, функция EtwWrite возвращает STATUS_SUCCESS и события не регистрируются.
События могут быть потеряны по ряду причин; например, если частота событий слишком высока или размер события больше размера буфера. В таких случаях счетчик EventsLost , член структуры EVENT_TRACE_PROPERTIES для соответствующего средства ведения журнала, обновляется с учетом количества событий, которые не были записаны.
Комментарии
Функция EtwWrite является эквивалентом функции EventWrite в пользовательском режиме. Чтобы убедиться, что для публикуемого события есть потребитель, можно перед вызовом EtwWrite вызвать EtwEventEnabled или EtwProviderEnabled.
Перед вызовом функции EtwWrite для публикации события необходимо зарегистрировать поставщик в EtwRegister. Не следует выполнять вызовы трассировки, которые выходят за пределы кода, ограниченного функциями EtwRegister и EtwUnregister . Для достижения наилучшей производительности можно вызвать функцию EtwRegister в процедуре DriverEntry и функцию EtwUnregister в процедуре DriverUnload .
Если вы используете необязательный параметр UserData в функции EtwWrite для регистрации дополнительных данных событий, можно использовать макрос EventDataDescCreate , чтобы упростить создание структур EVENT_DATA_DESCRIPTOR. В следующем примере используется макрос EventDataDescCreate для инициализации EVENT_DATA_DESCRIPTOR структур с именем устройства и его состоянием. Макрос EventDataDescCreate хранит указатели на данные (то есть не хранит копии данных). Указатели должны оставаться действительными до тех пор, пока не будет возвращен вызов etwWrite .
EtwWrite можно вызвать в любом IRQL. Однако если значение IRQL больше APC_LEVEL, все данные, передаваемые в функции EtwWrite, EtwWriteEx, EtwWriteString, EtwWriteTransfer , не должны быть доступны для страниц. Это значит, что любая подпрограмма в режиме ядра, выполняющаяся в IRQL больше APC_LEVEL, не может получить доступ к памяти, доступной для страниц. Данные, передаваемые в функции EtwWrite, EtwWriteEx, EtwWriteString и EtwWriteTransfer , должны находиться в памяти системного пространства, независимо от того, что такое IRQL.
Пример
//
// Register the provider with ETW in DriverEntry
// Unregister the provider in DriverUnload
//
// Build the EVENT_DATA_DESCRIPTOR structures using
// the EventDataDescCreate macros
if (RegHandle != (REGHANDLE)NULL) {
//
// Log an Event with : DeviceNameLength
// DeviceName
// Status
//
EventDataDescCreate(&EventDataDescriptor[0],
(PVOID)&DeviceName.Length,
sizeof(USHORT));
EventDataDescCreate(&EventDataDescriptor[1],
(PVOID)DeviceName.Buffer,
DeviceName.Length);
EventDataDescCreate(&EventDataDescriptor[2],
(PVOID)&Status,
sizeof(ULONG));
EtwWrite(RegHandle, // Handle from EtwRegister
&StartEvent, // EventDescriptor
NULL, // Activity ID
3, // Number of data items
EventDataDescriptor); // Array of data descriptors
}
//
Требования
| Требование | Значение |
|---|---|
| Целевая платформа | Универсальное |
| Верхняя часть | wdm.h (включая Wdm.h, Ntddk.h) |
| Библиотека | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | Любой уровень (см. раздел Комментарии). |