EtwWriteEx-Funktion (wdm.h)

Die EtwWriteEx-Funktion ist eine Ablaufverfolgungsfunktion für die Veröffentlichung von Ereignissen, die die Filterung in Ihrem Kernelmodustreibercode unterstützen.

Syntax

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
);

Parameter

[in] RegHandle

Ein Zeiger auf das Registrierungshandle des Ereignisanbieters, das von der EtwRegister-Funktion zurückgegeben wird, wenn die Registrierung des Ereignisanbieters erfolgreich ist.

[in] EventDescriptor

Ein Zeiger auf die EVENT_DESCRIPTOR-Struktur .

[in] Filter

Die instance Bezeichner, die die Sitzung identifizieren, in die das Ereignis nicht geschrieben wird. Das heißt, der Wert ist eine Maske von Sitzungen, die von der Protokollierung ausgeschlossen (herausgefiltert) werden sollten. Verwenden Sie einen bitweisen OR, um mehrere Bezeichner anzugeben. Legen Sie auf Null fest, wenn Sie keine Filter unterstützen oder wenn das Ereignis in alle Sitzungen geschrieben wird (keine Filter fehlgeschlagen). Informationen zum Abrufen des Bezeichners für eine Sitzung finden Sie im FilterData-Parameter Ihres EtwEnableCallback-Rückrufs .

[in] Flags

Reserviert. Muss null (0) sein.

[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. Bei NULL ruft ETW den Bezeichner aus dem lokalen Threadspeicher ab. Ausführliche Informationen zum Abrufen dieses Bezeichners finden Sie unter EtwActivityIdControl.

[in, optional] RelatedActivityId

Aktivitätsbezeichner aus der vorherigen Komponente. Verwenden Sie diesen Parameter, um die Ereignisse der Komponente mit den Ereignissen der vorherigen Komponente zu verknüpfen. Informationen zum Abrufen des Aktivitätsbezeichners, der für die vorherige Komponente festgelegt wurde, finden Sie in den Beschreibungen für den ControlCode-Parameter der EtwActivityIdControl-Funktion .

[in] UserDataCount

Anzahl der EVENT_DATA_DESCRIPTOR Strukturen in UserData. Die maximale Zahl ist 128.

[in, optional] UserData

Ein Zeiger auf das Array von EVENT_DATA_DESCRIPTOR Strukturen. Legen Sie diesen Parameter auf NULL fest, wenn UserDataCount 0 ist. Die Daten müssen in der im Manifest angegebenen Reihenfolge angeordnet sein.

Rückgabewert

Gibt bei erfolgreicher Ausführung ERROR_SUCCESS oder einen der folgenden Werte bei Fehler zurück.

Hinweise

Die EtwWriteEx-Funktion ist das Kernelmodusäquivalent der EventWriteEx-Funktion im Benutzermodus. Ereignisdaten, die mit dieser Funktion geschrieben werden, erfordern ein Manifest. Das Manifest ist im Anbieter eingebettet, daher muss der Anbieter verfügbar sein, damit ein Consumer die Daten nutzen kann. Um sicherzustellen, dass es einen Consumer für das von Ihnen veröffentlichte Ereignis gibt, können Sie dem Aufruf von EtwWrite einen Aufruf von EtwEventEnabled oder EtwProviderEnabled vorangehen.

Verwenden Sie die Parameter ActivityId und RelatedActivityId , wenn Sie Ereignisse in verschiedenen Komponenten in einem End-to-End-Ablaufverfolgungsszenario verknüpfen möchten. Beispielsweise führen die Komponenten A, B und C Arbeiten an einer verwandten Aktivität aus und möchten deren Ereignisse verknüpfen, damit ein Consumer alle Ereignisse im Zusammenhang mit dieser Aktivität nutzen kann.

Sie können EtwWriteEx an einem beliebigen IRQL aufrufen. Wenn IRQL jedoch größer als APC_LEVEL ist, dürfen alle Daten, die an die Funktionen EtwWrite, EtwWriteEx, EtwWriteString, 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 unabhängig vom IRQL im Arbeitsspeicher des Systemspeichers befinden.

Anforderungen

Weitere Informationen

EtwWrite

EventWrite

EventWriteEx