Funzione TdhCreatePayloadFilter (tdh.h)
La funzione TdhCreatePayloadFilter crea un singolo filtro per un singolo payload da usare con la funzione EnableTraceEx2 .
Sintassi
TDHSTATUS TdhCreatePayloadFilter(
[in] LPCGUID ProviderGuid,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in] BOOLEAN EventMatchANY,
[in] ULONG PayloadPredicateCount,
[in] PPAYLOAD_FILTER_PREDICATE PayloadPredicates,
[out] PVOID *PayloadFilter
);
Parametri
[in] ProviderGuid
GUID che identifica il provider manifesto del parametro EventDescriptor .
[in] EventDescriptor
Puntatore al descrittore dell'evento il cui payload verrà filtrato.
[in] EventMatchANY
Valore booleano che indica come vengono gestiti gli eventi quando vengono specificate più condizioni.
Quando questo parametro è TRUE, un evento verrà scritto in una sessione se una delle condizioni specificate nel filtro è TRUE.
Quando questo parametro è FALSE, un evento verrà scritto in una sessione solo se tutte le condizioni specificate specificate nel filtro sono TRUE.
[in] PayloadPredicateCount
Numero di condizioni specificate nel filtro. Questo valore deve essere minore o uguale alla costante ETW_MAX_PAYLOAD_PREDICATES definita nel file di intestazione Tdhh.h .
[in] PayloadPredicates
Puntatore a una matrice di strutture PAYLOAD_FILTER_PREDICATE che contengono le condizioni di elenco specificate dal filtro.
[out] PayloadFilter
In caso di esito positivo, questo parametro restituisce un puntatore a un singolo filtro payload che viene ridimensionato correttamente e compilato per le condizioni specificate.
Al termine dell'uso del filtro payload restituito con la funzione EnableTraceEx2 , la funzione TdhDeletePayloadFilter deve essere chiamata per liberare la memoria allocata.
Valore restituito
Restituisce ERROR_SUCCESS se riuscito. In caso contrario, questa funzione restituisce uno dei codici restituiti seguenti oltre ad altri.
| Codice restituito | Descrizione |
|---|---|
|
I metadati per il provider non sono stati trovati. |
|
Uno o più parametri non sono validi. |
|
Il filtro payload risultante non rientra nel limite MAX_EVENT_FILTER_PAYLOAD_SIZE imposto dalla funzione EnableTraceEx2nelle strutture EVENT_FILTER_DESCRIPTOR in un payload. |
|
Impossibile allocare memoria per creare il filtro del payload. |
|
Non sono state trovate le informazioni sullo schema per il GUID del provider fornito. |
Commenti
In Windows 8.1, Windows Server 2012 R2 e versioni successive, i filtri del payload degli eventi possono essere usati dalla funzione EnableTraceEx2 per filtrare il contenuto specifico dell'evento in una sessione del logger.
La funzione TdhCreatePayloadFilter viene usata per creare un singolo filtro payload per un singolo payload da usare con la funzione EnableTraceEx2 . TdhCreatePayloadFilter alloca e riempie una struttura di dati opaca per un singolo filtro payload. Quando il filtro del payload non è più necessario, la funzione TdhDeletePayloadFilter viene usata per liberare memoria allocata per un filtro payload.
Per un singolo provider, più eventi possono avere filtri payload distinti. Possono essere presenti anche più filtri per lo stesso evento, con un payload passato alla sessione se uno o tutti i filtri dell'evento lo passano.
La funzione EnableTraceEx2 accetta una matrice di strutture EVENT_FILTER_DESCRIPTOR nelle struttureENABLE_TRACE_PARAMETERS passate nel parametro EnableParameters. È possibile inserire una sola voce nella matrice per ogni tipo di filtro eventi. La funzione TdhAggregatePayloadFilters può essere usata per aggregare un elenco di filtri payload per un singolo provider creato usando TdhCreatePayloadFilter in una singola struttura di dati e restituire un EVENT_FILTER_DESCRIPTOR da usare con la funzione EnableTraceEx2 .
Esempio
Per un esempio che usa la funzione TdhCreatePayloadFilter per creare filtri payload da usare in condizioni specifiche in una sessione di logger, vedere l'esempio per la funzione EnableTraceEx2 .
Requisiti
| Client minimo supportato | Windows 8.1 [solo app desktop] |
| Server minimo supportato | Windows Server 2012 R2 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | tdh.h |
| Libreria | Tdh.lib |
| DLL | Tdh.dll |