EtwWrite-Funktion (wdm.h)

Artikel
03/08/2023

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 von EVENT_DATA_DESCRIPTOR Strukturen.

Rückgabewert

Wenn das Ereignis erfolgreich veröffentlicht wurde, gibt EtwWrite STATUS_SUCCESS zurück.

Wenn der Zeiger auf das Ereignisanbieterregistrierungshandle 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 EtwWrite STATUS_SUCCESS zurück, und die Ereignisse werden nicht protokolliert.

Ereignisse können aus verschiedenen Gründen verlorengehen; beispielsweise, wenn die Ereignisrate zu hoch ist oder die Ereignisgröße größer als die Puffergröße ist. In diesen Fällen wird der Ereignislost-Indikator , ein Element der EVENT_TRACE_PROPERTIES-Struktur für die entsprechende Protokollierung, mit der Anzahl von Ereignissen aktualisiert, die nicht aufgezeichnet wurden.

Hinweise

Die EtwWrite-Funktion ist die Kernelmodus-Entsprechung der EventWrite-Funktion im Benutzermodus. Um sicherzustellen, dass ein Consumer für das von Ihnen veröffentlichte Ereignis vorhanden ist, können Sie dem Aufruf von EtwWrite einen Aufruf von EtwEventEnabled oder EtwProviderEnabled vorangehen.

Bevor Sie die 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 durch die Funktionen EtwRegister und EtwUnregister begrenzt ist. Um eine optimale Leistung zu erzielen, können Sie die EtwRegister-Funktion in Ihrer DriverEntry-Routine und die EtwUnregister-Funktion in Ihrer DriverUnload-Routine aufrufen.

Wenn Sie den optionalen UserData-Parameter in der EtwWrite-Funktion verwenden, um zusätzliche Ereignisdaten zu protokollieren, können Sie das Makro EventDataDescCreate verwenden, um die Erstellung der EVENT_DATA_DESCRIPTOR Strukturen zu vereinfachen. Im folgenden Beispiel wird das Makro EventDataDescCreate 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. a. es werden keine Kopien der Daten gespeichert). Die Zeiger müssen gültig bleiben, bis der Aufruf von EtwWrite zurückgibt.

Sie können EtwWrite in jedem IRQL aufrufen. Wenn IRQL jedoch größer als APC_LEVEL ist, dürfen daten, die an die Funktionen EtwWrite, EtwWriteEx, EtwWriteString und EtwWriteTransfer übergeben werden, nicht ausgelagert werden können. Das heißt, jede Kernelmodusroutine, die bei IRQL ausgeführt wird, die größer als APC_LEVEL ist, kann nicht auf ausgelagerten Arbeitsspeicher zugreifen. Daten, die an die Funktionen EtwWrite, EtwWriteEx, EtwWriteString und EtwWriteTransfer übergeben werden, müssen sich im Speicher des Systemspeichers befinden, unabhängig davon, was 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	Universell
Header	wdm.h (include Wdm.h, Ntddk.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Beliebige Ebene (siehe Abschnitt "Kommentare".)