TdhAggregatePayloadFilters-Funktion (tdh.h)

Artikel
08/26/2023

Die TdhAggregatePayloadFilters-Funktion aggregiert mehrere Nutzlastfilter für einen einzelnen Anbieter in einer einzelnen Datenstruktur zur Verwendung mit der EnableTraceEx2-Funktion .

Syntax

TDHSTATUS TdhAggregatePayloadFilters(
                 ULONG                    PayloadFilterCount,
                 PVOID                    *PayloadFilterPtrs,
  [in, optional] PBOOLEAN                 EventMatchALLFlags,
  [out]          PEVENT_FILTER_DESCRIPTOR EventFilterDescriptor
);

Parameter

PayloadFilterCount

Die Anzahl der Nutzlastfilter.

PayloadFilterPtrs

Ein Array von einzelnen Ereignisnutzlastfiltern, die jeweils durch einen Aufruf der TdhCreatePayloadFilter-Funktion erstellt wurden.

[in, optional] EventMatchALLFlags

Ein Array boolescher Werte, die den einzelnen Nutzlastfiltern entsprechen, die im PayloadFilterPtrs-Parameter übergeben werden, und gibt an, wie Ereignisse behandelt werden, wenn mehrere Bedingungen angegeben werden. Dieser Parameter wirkt sich nur auf Situationen aus, in denen für dasselbe Ereignis mehrere Nutzlastfilter angegeben werden.

Wenn ein boolescher Wert TRUE ist, wird ein Ereignis in eine Sitzung geschrieben, wenn eine der im Filter angegebenen Bedingungen TRUE ist. Wenn dieses Flag für einen oder mehrere Filter für dieselbe Ereignis-ID oder Ereignisversion auf TRUE festgelegt ist, wird das Ereignis nur geschrieben, wenn alle gekennzeichneten Filter für das Ereignis erfüllt sind.

Wenn ein boolescher Wert FALSE ist, wird ein Ereignis nur dann in eine Sitzung geschrieben, wenn alle im Filter angegebenen Bedingungen TRUE sind. Wenn dieses Flag für einen oder mehrere Filter für dieselbe Ereignis-ID oder Ereignisversion auf FALSE festgelegt ist, wird das Ereignis geschrieben, wenn einer der nicht gekennzeichneten Filter erfüllt ist.

[out] EventFilterDescriptor

Ein Zeiger auf eine EVENT_FILTER_DESCRIPTOR Struktur, die mit der EnableTraceEx2-Funktion verwendet werden soll. Die EVENT_FILTER_DESCRIPTOR-Struktur enthält einen Zeiger auf die aggregierten Nutzlastfilter, die von dieser Funktion zugeordnet wurden.

Wenn der Aufrufer mit der Verwendung dieser EVENT_FILTER_DESCRIPTOR Struktur mit der EnableTraceEx2-Funktion fertig ist, sollte die TdhCleanupPayloadEventFilterDescriptor-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_INVALID_PARAMETER	Mindestens einer der Parameter ist ungültig.
ERROR_NOT_ENOUGH_MEMORY	Speicher kann nicht zugeordnet werden, um den aggregierten Nutzlastfilter zu erstellen.

Hinweise

Auf 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 TdhAggregatePayloadFilters-Funktion aggregiert Nutzlastfilter für einen einzelnen Anbieter in einer einzelnen Datenstruktur zur Verwendung mit der EnableTraceEx2-Funktion . TdhAggregatePayloadFilters ordnet eine undurchsichtige Datenstruktur für einen aggregierten Nutzlastfilter zu und füllt sie aus. Wenn der aggregierte Nutzlastfilter nicht mehr benötigt wird, wird die TdhCleanupPayloadEventFilterDescriptor-Funktion verwendet, um Arbeitsspeicher freizugeben, der für den aggregierten Nutzlastfilter in der zurückgegebenen EVENT_FILTER_DESCRIPTOR-Struktur zugeordnet ist.

Beispiele

Ein Beispiel, das die TdhAggregatePayloadFilters-Funktion zum Aggregieren von Nutzlastfiltern verwendet, die bei der Filterung für bestimmte Bedingungen in einer Protokollierungssitzung verwendet werden, finden Sie im Beispiel für die EnableTraceEx2-Funktion .

Anforderungen

Anforderung	Wert
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