TdhCreatePayloadFilter-Funktion (tdh.h)

Artikel
08/26/2023

Die TdhCreatePayloadFilter-Funktion erstellt einen einzelnen Filter für eine einzelne Nutzlast, die mit der EnableTraceEx2-Funktion verwendet werden soll.

Syntax

TDHSTATUS TdhCreatePayloadFilter(
  [in]  LPCGUID                   ProviderGuid,
  [in]  PCEVENT_DESCRIPTOR        EventDescriptor,
  [in]  BOOLEAN                   EventMatchANY,
  [in]  ULONG                     PayloadPredicateCount,
  [in]  PPAYLOAD_FILTER_PREDICATE PayloadPredicates,
  [out] PVOID                     *PayloadFilter
);

Parameter

[in] ProviderGuid

Eine GUID, die den Manifestanbieter des EventDescriptor-Parameters identifiziert.

[in] EventDescriptor

Ein Zeiger auf den Ereignisdeskriptor, dessen Nutzlast gefiltert wird.

[in] EventMatchANY

Ein boolescher Wert, der angibt, wie Ereignisse behandelt werden, wenn mehrere Bedingungen angegeben werden.

Wenn dieser Parameter TRUE ist, wird ein Ereignis in eine Sitzung geschrieben, wenn eine der im Filter angegebenen Bedingungen TRUE ist.

Wenn dieser Parameter FALSE ist, wird ein Ereignis nur dann in eine Sitzung geschrieben, wenn alle im Filter angegebenen Bedingungen TRUE sind.

[in] PayloadPredicateCount

Die Anzahl der im Filter angegebenen Bedingungen. Dieser Wert muss kleiner oder gleich der in der Tdh.h-Headerdatei definierten ETW_MAX_PAYLOAD_PREDICATES Konstanten sein.

[in] PayloadPredicates

Ein Zeiger auf ein Array von PAYLOAD_FILTER_PREDICATE Strukturen, die die vom Filter angegebenen Listenbedingungen enthalten.

[out] PayloadFilter

Bei Erfolg gibt dieser Parameter einen Zeiger auf einen einzelnen Nutzlastfilter zurück, der ordnungsgemäß dimensioniert und für die angegebenen Bedingungen erstellt wurde.

Wenn der Aufrufer den zurückgegebenen Nutzlastfilter mit der EnableTraceEx2-Funktion verwendet, sollte die TdhDeletePayloadFilter-Funktion aufgerufen werden, um den zugeordneten Arbeitsspeicher freizugeben.

Rückgabewert

Gibt bei erfolgreicher Ausführung ERROR_SUCCESS zurück. Andernfalls gibt diese Funktion zusätzlich zu anderen einen der folgenden Rückgabecodes zurück.

Rückgabecode	Beschreibung
ERROR_FILE_NOT_FOUND	Die Metadaten für den Anbieter wurden nicht gefunden.
ERROR_INVALID_PARAMETER	Mindestens einer der Parameter ist ungültig.
ERROR_INSUFFICIENT_BUFFER	Der resultierende Nutzlastfilter würde nicht innerhalb des MAX_EVENT_FILTER_PAYLOAD_SIZE Grenzwerts passen, der von der EnableTraceEx2-Funktion für die EVENT_FILTER_DESCRIPTOR-Strukturen in einer Nutzlast festgelegt wird.
ERROR_NOT_ENOUGH_MEMORY	Speicher zum Erstellen des Nutzlastfilters kann nicht zugeordnet werden.
ERROR_NOT_FOUND	Die Schemainformationen für die angegebene Anbieter-GUID wurden nicht gefunden.

Hinweise

Unter Windows 8.1, Windows Server 2012 R2 und höher können Ereignisnutzlastfilter von der EnableTraceEx2-Funktion verwendet werden, um nach dem spezifischen Inhalt des Ereignisses in einer Protokollierungssitzung zu filtern.

Die TdhCreatePayloadFilter-Funktion wird verwendet, um einen einzelnen Nutzlastfilter für eine einzelne Nutzlast zu erstellen, die mit der EnableTraceEx2-Funktion verwendet werden soll. Der TdhCreatePayloadFilter ordnet eine undurchsichtige Datenstruktur für einen einzelnen Nutzlastfilter zu und füllt sie aus. Wenn der Nutzlastfilter nicht mehr benötigt wird, wird die TdhDeletePayloadFilter-Funktion verwendet, um den für einen Nutzlastfilter zugewiesenen Arbeitsspeicher freizugeben.

Bei einem einzelnen Anbieter können mehrere Ereignisse über unterschiedliche Nutzlastfilter verfügen. Es kann auch mehrere Filter für dasselbe Ereignis geben, wobei eine Nutzlast an die Sitzung übergeben wird, wenn ein oder alle Filter des Ereignisses sie übergeben.

Die EnableTraceEx2-Funktion verwendet ein Array von EVENT_FILTER_DESCRIPTOR Strukturen in den ENABLE_TRACE_PARAMETERS Strukturen, die im EnableParameters-Parameter übergeben werden. Für jeden Ereignisfiltertyp kann nur ein Eintrag im Array vorhanden sein. Die TdhAggregatePayloadFilters-Funktion kann verwendet werden, um eine Liste von Nutzlastfiltern für einen einzelnen Anbieter, der mit TdhCreatePayloadFilter erstellt wurde, in einer einzelnen Datenstruktur zu aggregieren und einen EVENT_FILTER_DESCRIPTOR für die Verwendung mit der EnableTraceEx2-Funktion zurückzugeben.

Beispiele

Ein Beispiel, das die TdhCreatePayloadFilter-Funktion zum Erstellen von Nutzlastfiltern verwendet, die zum Filtern nach bestimmten Bedingungen in einer Protokollierungssitzung verwendet werden, finden Sie im Beispiel für die EnableTraceEx2-Funktion .

Anforderungen


Unterstützte Mindestversion (Client)	Windows 8.1 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 R2 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	tdh.h
Bibliothek	Tdh.lib
DLL	Tdh.dll