EtwWrite-Funktion (wdm.h)
Die EtwWrite-Funktion ist eine Ablaufverfolgungsfunktion zum Veröffentlichen von Ereignissen im Kernelmodustreibercode.
Syntax
NTSTATUS EtwWrite(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in, optional] LPCGUID ActivityId,
[in] ULONG UserDataCount,
[in, optional] PEVENT_DATA_DESCRIPTOR UserData
);
Parameter
[in] RegHandle
Ein Zeiger auf das Ereignisanbieterregistrierungshandle, das von der EtwRegister--Funktion zurückgegeben wird, wenn die Ereignisanbieterregistrierung erfolgreich ist.
[in] EventDescriptor
Ein Zeiger auf die EVENT_DESCRIPTOR Struktur.
[in, optional] ActivityId
Der Bezeichner, der die dem Ereignis zugeordnete Aktivität angibt. Die ActivityID- bietet eine Möglichkeit zum Gruppieren verwandter Ereignisse und wird in der End-to-End-Ablaufverfolgung verwendet.
[in] UserDataCount
Die Anzahl der EVENT_DATA_DESCRIPTOR Strukturen in UserData-.
[in, optional] UserData
Ein Zeiger auf das Array EVENT_DATA_DESCRIPTOR Strukturen.
Rückgabewert
Wenn das Ereignis erfolgreich veröffentlicht wurde, gibt EtwWrite STATUS_SUCCESS zurück.
Wenn der Zeiger auf den Registrierungshandle des Ereignisanbieters ungültig ist, gibt EtwWrite STATUS_INVALID_HANDLE zurück. Der Ereignisanbieter muss registriert werden, bevor EtwWrite- aufgerufen wird. EtwWrite kann auch STATUS_INVALID_HANDLE zurückgeben, wenn das Ereignis nicht protokolliert werden kann.
Wenn die Anzahl der in UserDataCount- angegebenen EVENT_DATA_DESCRIPTOR Strukturen größer als der maximal zulässige Wert (128) ist, gibt EtwWrite STATUS_INVALID_PARAMETER zurück.
Wenn ActivityID- angegeben ist, aber nicht genügend Arbeitsspeicher verfügbar ist, um die dem Ereignis zugeordneten Daten zu protokollieren, gibt EtwWrite STATUS_NO_MEMORY zurück.
Wenn der Anbieter für keine Sitzung aktiviert ist, gibt Etwrite STATUS_SUCCESS zurück, und die Ereignisse werden nicht protokolliert.
Ereignisse können aus mehreren Gründen verlorengehen; Wenn die Ereignisrate beispielsweise zu hoch ist oder die Ereignisgröße größer als die Puffergröße ist. In diesen Fällen wird der EventsLost-Zähler, ein Mitglied der EVENT_TRACE_PROPERTIES-Struktur für den entsprechenden Logger, mit der Anzahl der Ereignisse aktualisiert, die nicht aufgezeichnet wurden.
Bemerkungen
Die EtwWrite-Funktion ist das Kernelmodus-Äquivalent des Benutzermodus EventWrite-Funktion. Um sicherzustellen, dass es einen Consumer für das Ereignis gibt, das Sie veröffentlichen, können Sie dem Aufruf von EtwWrite- einen Aufruf von EtwEventEnabled oder EtwProviderEnabledvorangehen.
Bevor Sie EtwWrite-Funktion aufrufen können, um ein Ereignis zu veröffentlichen, müssen Sie den Anbieter bei EtwRegister-registrieren. Es sollten keine Ablaufverfolgungsaufrufe ausgeführt werden, die außerhalb des Codes liegen, der von den funktionen EtwRegister und EtwUnregister begrenzt ist. Um optimale Leistung zu erzielen, können Sie die EtwRegister--Funktion in Ihrer DriverEntry- Routine und die funktion EtwUnregister in Ihrer DriverUnload- Routine aufrufen.
Wenn Sie den optionalen UserData-Parameter in der EtwWrite-Funktion zum Protokollieren zusätzlicher Ereignisdaten verwenden, können Sie das EventDataDescCreate Makro verwenden, um die Erstellung der EVENT_DATA_DESCRIPTOR Strukturen zu vereinfachen. Im folgenden Beispiel wird das EventDataDescCreate Makro verwendet, um EVENT_DATA_DESCRIPTOR Strukturen mit dem Namen des Geräts und dessen Status zu initialisieren. Das EventDataDescCreate Makro speichert Zeiger auf die Daten (d. h., es speichert keine Kopien der Daten). Die Zeiger müssen gültig bleiben, bis der Aufruf von EtwWrite zurückgegeben wird.
Sie können EtwWrite- bei jedem IRQL aufrufen. Wenn IRQL jedoch größer als APC_LEVEL ist, dürfen alle daten, die an die EtwWrite, EtwWriteEx, EtwWriteString, EtwWriteTransfer Funktionen nicht seitenfähig sein. Das heißt, jede Kernelmodusroutine, die bei IRQL ausgeführt wird, die größer als APC_LEVEL kann nicht auf den ausgelagerten Speicher zugreifen. Daten, die an die EtwWrite, EtwriteEx, EtwwriteStringund EtwWriteTransfer Funktionen gespeichert sein müssen, müssen sich unabhängig davon befinden, was die IRQL ist.
Beispiel
//
// 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
}
//
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform- | Universal |
| Header- | wdm.h (include Wdm.h, Ntddk.h) |
| Library | NtosKrnl.lib |
| DLL- | NtosKrnl.exe |
| IRQL- | Eine beliebige Ebene (Siehe Abschnitt "Kommentare".) |