TdhCreatePayloadFilter-Funktion (tdh.h)
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 |
|---|---|
|
Die Metadaten für den Anbieter wurden nicht gefunden. |
|
Mindestens einer der Parameter ist ungültig. |
|
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. |
|
Speicher zum Erstellen des Nutzlastfilters kann nicht zugeordnet werden. |
|
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 |